From 32e486c6f8db8eb8f52352698c7641732dd9338e Mon Sep 17 00:00:00 2001
From: Scott George <sgeorge74@gmail.com>
Date: Thu, 18 Dec 2025 18:41:34 -0500
Subject: [PATCH] Enhance API docs landing page styling and resilience

---
 docs/index.html | 124 ++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 116 insertions(+), 8 deletions(-)

diff --git a/docs/index.html b/docs/index.html
index 09f451b..a90d632 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -3,14 +3,39 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <meta
+      name="description"
+      content="Paywaz documentation hub with API reference, SDK links, and runnable samples."
+    />
+    <meta name="theme-color" content="#0b57d0" />
     <title>Paywaz Docs</title>
     <style>
-      body { font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial; margin: 0; }
-      header { padding: 24px; border-bottom: 1px solid #eee; }
+      body {
+        font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, Arial;
+        margin: 0;
+        background: #fafafa;
+        color: #111;
+      }
+      header {
+        padding: 24px;
+        border-bottom: 1px solid #eee;
+        background: #fff;
+      }
+      main {
+        display: block;
+        background: #fff;
+        border-top: 1px solid #f3f4f6;
+        border-bottom: 1px solid #f3f4f6;
+      }
       .wrap { max-width: 1050px; margin: 0 auto; padding: 0 16px; }
       h1 { margin: 0 0 8px; font-size: 28px; }
       p { margin: 0; color: #444; }
-      .grid { display: grid; gap: 12px; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); margin: 18px 0 8px; }
+      .grid {
+        display: grid;
+        gap: 12px;
+        grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
+        margin: 18px 0 8px;
+      }
       .card { border: 1px solid #eee; border-radius: 14px; padding: 14px; background: #fff; }
       .card h2 { margin: 0 0 6px; font-size: 16px; }
       .card a { color: #0b57d0; text-decoration: none; }
@@ -18,6 +43,54 @@
       .muted { color: #666; font-size: 13px; line-height: 1.35; }
       .divider { height: 1px; background: #eee; margin: 16px 0; }
       .footer { padding: 18px 0 28px; color: #666; font-size: 12px; }
+      .pill {
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+        background: #0b57d0;
+        color: #fff;
+        border-radius: 999px;
+        padding: 6px 12px;
+        font-size: 13px;
+        font-weight: 600;
+      }
+      .status-dot {
+        width: 8px;
+        height: 8px;
+        border-radius: 50%;
+        background: #4ade80;
+        box-shadow: 0 0 0 4px rgba(74, 222, 128, 0.25);
+      }
+      .api-panel {
+        padding: 10px 16px 30px;
+      }
+      .api-heading {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+        margin: 0 0 12px;
+      }
+      .inline-link { color: #0b57d0; }
+      .inline-link:hover { text-decoration: underline; }
+      .callout {
+        margin: 12px 0 20px;
+        padding: 12px 14px;
+        background: #f8fafc;
+        border: 1px solid #e5e7eb;
+        border-radius: 10px;
+        color: #374151;
+        font-size: 14px;
+      }
+      #api-error {
+        margin-top: 10px;
+        padding: 12px 14px;
+        border-radius: 10px;
+        border: 1px solid #fcd34d;
+        background: #fffbeb;
+        color: #92400e;
+        font-size: 14px;
+        display: none;
+      }
     </style>
   </head>
 
@@ -62,9 +135,30 @@ <h2>3) Samples</h2>
       </div>
     </header>
 
-    <div class="wrap" id="api" style="padding: 10px 16px 30px;">
-      <div id="redoc-container"></div>
-    </div>
+    <main>
+      <div class="wrap api-panel" id="api">
+        <div class="api-heading">
+          <div class="pill">
+            <span class="status-dot" aria-hidden="true"></span>
+            Live API docs
+          </div>
+          <a class="inline-link" href="https://github.com/hellopaywaz/paywaz-public-api" aria-label="Open API repository">
+            OpenAPI source
+          </a>
+        </div>
+
+        <div class="callout">
+          Embedded Redoc powered by the latest public spec.
+          If the embed fails to load, you can access the raw OpenAPI file at
+          <a class="inline-link" href="https://raw.githubusercontent.com/hellopaywaz/paywaz-public-api/main/openapi/openapi.yaml">
+            openapi/openapi.yaml
+          </a>.
+        </div>
+
+        <div id="redoc-container" role="region" aria-label="Paywaz API reference"></div>
+        <div id="api-error" role="alert"></div>
+      </div>
+    </main>
 
     <script>
       // IMPORTANT: adjust if your OpenAPI file lives somewhere else.
@@ -72,9 +166,23 @@ <h2>3) Samples</h2>
       const SPEC_URL = "https://raw.githubusercontent.com/hellopaywaz/paywaz-public-api/main/openapi/openapi.yaml";
       window.__PAYWAZ_SPEC_URL__ = SPEC_URL;
     </script>
-    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js"></script>
+    <script src="https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js" defer></script>
     <script>
-      Redoc.init(window.__PAYWAZ_SPEC_URL__, { scrollYOffset: 0 }, document.getElementById("redoc-container"));
+      const redocContainer = document.getElementById("redoc-container");
+      const errorContainer = document.getElementById("api-error");
+
+      function renderDocs() {
+        Redoc.init(window.__PAYWAZ_SPEC_URL__, { scrollYOffset: 0 }, redocContainer).catch((error) => {
+          errorContainer.style.display = "block";
+          errorContainer.textContent = `Unable to load the API reference. Please open the spec directly: ${window.__PAYWAZ_SPEC_URL__}. Error: ${error}`;
+        });
+      }
+
+      if (window.Redoc) {
+        renderDocs();
+      } else {
+        window.addEventListener("load", renderDocs);
+      }
     </script>
 
     <div class="wrap footer">