raffel 1.1.59 → 1.1.60-next.edcf9f3

package/dist/docs/ui/assets/raffel-docs.css

@@ -1483,6 +1483,114 @@
       color: var(--text-color);
     }
 
+    /* ========== ROOT OVERVIEW (OpenAPI landing) ========== */
+    .docs-overview {
+      max-width: 820px;
+      margin-bottom: 8px;
+    }
+
+    .docs-overview-header {
+      margin: 0 0 12px 0;
+    }
+
+    .docs-overview-title {
+      display: flex;
+      align-items: baseline;
+      flex-wrap: wrap;
+      gap: 12px;
+      font-size: 32px;
+      font-weight: 700;
+      line-height: 1.2;
+      margin: 0;
+      color: var(--text-color);
+    }
+
+    .docs-overview-version {
+      font-size: 13px;
+      font-weight: 600;
+      letter-spacing: 0.02em;
+      padding: 3px 10px;
+      border-radius: 999px;
+      color: var(--accent, var(--primary-color));
+      background: color-mix(in srgb, var(--accent, var(--primary-color)) 14%, transparent);
+      border: 1px solid color-mix(in srgb, var(--accent, var(--primary-color)) 35%, transparent);
+    }
+
+    .docs-overview-meta {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: 10px;
+      font-size: 14px;
+      color: var(--text-muted);
+      margin: 0 0 24px 0;
+    }
+
+    .docs-overview-meta a {
+      color: var(--accent, var(--primary-color));
+      text-decoration: none;
+    }
+
+    .docs-overview-meta a:hover {
+      text-decoration: underline;
+    }
+
+    .docs-overview-meta-sep {
+      color: var(--border-color);
+    }
+
+    .docs-overview-servers {
+      margin: 0 0 28px 0;
+    }
+
+    .docs-overview-subtitle {
+      font-size: 13px;
+      font-weight: 700;
+      text-transform: uppercase;
+      letter-spacing: 0.06em;
+      color: var(--text-muted);
+      margin: 0 0 12px 0;
+    }
+
+    .docs-overview-server-list {
+      list-style: none;
+      margin: 0;
+      padding: 0;
+      display: flex;
+      flex-direction: column;
+      gap: 8px;
+    }
+
+    .docs-overview-server {
+      display: flex;
+      align-items: center;
+      flex-wrap: wrap;
+      gap: 12px;
+      padding: 12px 16px;
+      border: 1px solid var(--border-color);
+      border-radius: 10px;
+      background: var(--surface-color);
+    }
+
+    .docs-overview-server-url {
+      font-family: 'SF Mono', Monaco, Consolas, monospace;
+      font-size: 14px;
+      color: var(--text-color);
+      background: var(--code-bg);
+      padding: 4px 10px;
+      border-radius: 6px;
+      word-break: break-all;
+    }
+
+    .docs-overview-server-desc {
+      font-size: 14px;
+      color: var(--text-muted);
+    }
+
+    .docs-overview-description {
+      max-width: 820px;
+    }
+
     /* ========== ENDPOINT SECTIONS (Redoc-style) ========== */
     .endpoint-section {
       padding: 32px 0;

package/dist/docs/ui/assets/raffel-docs.js

@@ -42,7 +42,15 @@ const xUsd = spec['x-usd'] ?? {};
 const { websocket: wsSpec = {}, graphql: graphqlSpec = {}, streams: streamsSpec = {}, jsonrpc: jsonrpcSpec = {}, grpc: grpcSpec = {}, tcp: tcpSpec = {}, udp: udpSpec = {} } = xUsd;
 const docsRouteBase = String(xUsd.documentation?.routeBase ?? '').replace(/^#/, '').replace(/\/+$/, '');
 const protocolData = detectProtocols();
-const protocols = Object.keys(protocolData);
+// Logical priority for which protocol the docs open on (and the tab order):
+// what a consumer of *this* API most likely came to read first. HTTP wins
+// when present, then GraphQL, then realtime/RPC, then raw sockets.
+const PROTOCOL_PRIORITY = ['http', 'graphql', 'websocket', 'jsonrpc', 'grpc', 'streams', 'tcp', 'udp'];
+const protocolRank = (name) => {
+    const i = PROTOCOL_PRIORITY.indexOf(name);
+    return i === -1 ? PROTOCOL_PRIORITY.length : i;
+};
+const protocols = Object.keys(protocolData).sort((a, b) => protocolRank(a) - protocolRank(b));
 let activeProtocol = protocols[0] ?? 'http';
 let searchQuery = '';
 let routeState = parseRouteHash();
@@ -922,9 +930,10 @@ function renderProtocolTabs() {
     if (!container)
         return;
     container.textContent = '';
+    const isRoot = !activePagePath || activePagePath === '/';
     for (const protocol of protocols) {
         const button = doc.createElement('button');
-        button.className = `protocol-tab${!activePagePath && protocol === activeProtocol ? ' active' : ''}`;
+        button.className = `protocol-tab${isRoot && protocol === activeProtocol ? ' active' : ''}`;
         button.innerHTML = `${esc(protocol.charAt(0).toUpperCase() + protocol.slice(1))}${sidebarConfig.showCounts !== false ? `<span class="count">${protocolData[protocol]}</span>` : ''}`;
         button.onclick = () => {
             activeProtocol = protocol;
@@ -1044,7 +1053,14 @@ function renderSidebar() {
         return;
     nav.textContent = '';
     renderDocsPagesNav(nav);
-    if (activePagePath)
+    // A real doc page (or a genuine non-root 404) shows the docs nav only.
+    // The docs root (`/`) is NOT a page — it's the overview, so it must list
+    // the active protocol's endpoints, expanded, like the old empty-path state.
+    const matchedPage = activePagePath
+        ? getDocsPageViews().some((p) => p.path === activePagePath)
+        : false;
+    const isRoot = !activePagePath || activePagePath === '/';
+    if (matchedPage || !isRoot)
         return;
     const endpoints = getEndpointsForProtocol(activeProtocol).filter(endpoint => !searchQuery ||
         endpoint.path.toLowerCase().includes(searchQuery) ||
@@ -1803,16 +1819,19 @@ function renderContent() {
         scrollToActiveHeading();
         return;
     }
-    if (activePagePath) {
+    // The docs root (`/`) is ours to define — never a "not found". Only a
+    // non-root path with no matching page is a genuine 404.
+    const isRoot = !activePagePath || activePagePath === '/';
+    if (activePagePath && !isRoot) {
         renderMissingDocsPage(main);
         renderToc(main);
         return;
     }
-    if (!searchQuery && spec.info?.description) {
-        const intro = doc.createElement('div');
-        intro.className = 'intro-section';
-        intro.innerHTML = `<div class="markdown-content">${parseMarkdown(spec.info.description)}</div>`;
-        main.appendChild(intro);
+    // Root landing: an OpenAPI-driven overview (title, version, servers,
+    // description) followed by the endpoint list — unless the user is
+    // mid-search, in which case the search results take the surface.
+    if (!searchQuery) {
+        main.appendChild(renderDocsOverview());
     }
     if (searchQuery)
         renderDocsSearch(main);
@@ -1829,6 +1848,67 @@ function renderContent() {
     }
     renderToc(main);
 }
+function renderDocsOverview() {
+    const info = (spec.info ?? {});
+    const container = doc.createElement('div');
+    container.className = 'docs-overview';
+    const title = String(info.title ?? 'API');
+    const versionBadge = info.version
+        ? `<span class="docs-overview-version">${esc(String(info.version))}</span>`
+        : '';
+    const header = doc.createElement('header');
+    header.className = 'docs-overview-header';
+    header.innerHTML = `<h1 class="docs-overview-title" id="overview">${esc(title)}${versionBadge}</h1>`;
+    container.appendChild(header);
+    // Contact / license line (ReDoc-style).
+    const contact = (info.contact ?? {});
+    const license = (info.license ?? {});
+    const metaBits = [];
+    if (contact.email) {
+        const label = esc(String(contact.name ?? contact.email));
+        metaBits.push(`E-mail: <a href="mailto:${esc(String(contact.email))}">${label}</a>`);
+    }
+    if (contact.url) {
+        metaBits.push(`URL: <a href="${esc(String(contact.url))}" target="_blank" rel="noopener">${esc(String(contact.url))}</a>`);
+    }
+    if (license.name) {
+        const lic = license.url
+            ? `<a href="${esc(String(license.url))}" target="_blank" rel="noopener">${esc(String(license.name))}</a>`
+            : esc(String(license.name));
+        metaBits.push(`License: ${lic}`);
+    }
+    if (metaBits.length) {
+        const meta = doc.createElement('div');
+        meta.className = 'docs-overview-meta';
+        meta.innerHTML = metaBits.join('<span class="docs-overview-meta-sep">·</span>');
+        container.appendChild(meta);
+    }
+    // Servers — straight from `spec.servers`.
+    const servers = Array.isArray(spec.servers) ? spec.servers : [];
+    if (servers.length) {
+        const section = doc.createElement('section');
+        section.className = 'docs-overview-servers';
+        const rows = servers
+            .map((s) => {
+            const url = esc(String(s?.url ?? ''));
+            const desc = s?.description
+                ? `<span class="docs-overview-server-desc">${esc(String(s.description))}</span>`
+                : '';
+            return `<li class="docs-overview-server"><code class="docs-overview-server-url">${url}</code>${desc}</li>`;
+        })
+            .join('');
+        section.innerHTML = `<h2 class="docs-overview-subtitle">${servers.length > 1 ? 'Servers' : 'Server'}</h2><ul class="docs-overview-server-list">${rows}</ul>`;
+        container.appendChild(section);
+    }
+    // Description (markdown).
+    if (info.description) {
+        const description = doc.createElement('div');
+        description.className = 'docs-overview-description markdown-content';
+        description.innerHTML = parseMarkdown(String(info.description));
+        container.appendChild(description);
+    }
+    return container;
+}
 function renderMissingDocsPage(main) {
     const notFound = getDocsPageViews().find(page => page.path === '/404' || page.path.endsWith('/404'));
     const article = doc.createElement('article');

package/dist/docs/ui/runtime/index.js

@@ -42,7 +42,15 @@ const xUsd = spec['x-usd'] ?? {};
 const { websocket: wsSpec = {}, graphql: graphqlSpec = {}, streams: streamsSpec = {}, jsonrpc: jsonrpcSpec = {}, grpc: grpcSpec = {}, tcp: tcpSpec = {}, udp: udpSpec = {} } = xUsd;
 const docsRouteBase = String(xUsd.documentation?.routeBase ?? '').replace(/^#/, '').replace(/\/+$/, '');
 const protocolData = detectProtocols();
-const protocols = Object.keys(protocolData);
+// Logical priority for which protocol the docs open on (and the tab order):
+// what a consumer of *this* API most likely came to read first. HTTP wins
+// when present, then GraphQL, then realtime/RPC, then raw sockets.
+const PROTOCOL_PRIORITY = ['http', 'graphql', 'websocket', 'jsonrpc', 'grpc', 'streams', 'tcp', 'udp'];
+const protocolRank = (name) => {
+    const i = PROTOCOL_PRIORITY.indexOf(name);
+    return i === -1 ? PROTOCOL_PRIORITY.length : i;
+};
+const protocols = Object.keys(protocolData).sort((a, b) => protocolRank(a) - protocolRank(b));
 let activeProtocol = protocols[0] ?? 'http';
 let searchQuery = '';
 let routeState = parseRouteHash();
@@ -922,9 +930,10 @@ function renderProtocolTabs() {
     if (!container)
         return;
     container.textContent = '';
+    const isRoot = !activePagePath || activePagePath === '/';
     for (const protocol of protocols) {
         const button = doc.createElement('button');
-        button.className = `protocol-tab${!activePagePath && protocol === activeProtocol ? ' active' : ''}`;
+        button.className = `protocol-tab${isRoot && protocol === activeProtocol ? ' active' : ''}`;
         button.innerHTML = `${esc(protocol.charAt(0).toUpperCase() + protocol.slice(1))}${sidebarConfig.showCounts !== false ? `<span class="count">${protocolData[protocol]}</span>` : ''}`;
         button.onclick = () => {
             activeProtocol = protocol;
@@ -1044,7 +1053,14 @@ function renderSidebar() {
         return;
     nav.textContent = '';
     renderDocsPagesNav(nav);
-    if (activePagePath)
+    // A real doc page (or a genuine non-root 404) shows the docs nav only.
+    // The docs root (`/`) is NOT a page — it's the overview, so it must list
+    // the active protocol's endpoints, expanded, like the old empty-path state.
+    const matchedPage = activePagePath
+        ? getDocsPageViews().some((p) => p.path === activePagePath)
+        : false;
+    const isRoot = !activePagePath || activePagePath === '/';
+    if (matchedPage || !isRoot)
         return;
     const endpoints = getEndpointsForProtocol(activeProtocol).filter(endpoint => !searchQuery ||
         endpoint.path.toLowerCase().includes(searchQuery) ||
@@ -1803,16 +1819,19 @@ function renderContent() {
         scrollToActiveHeading();
         return;
     }
-    if (activePagePath) {
+    // The docs root (`/`) is ours to define — never a "not found". Only a
+    // non-root path with no matching page is a genuine 404.
+    const isRoot = !activePagePath || activePagePath === '/';
+    if (activePagePath && !isRoot) {
         renderMissingDocsPage(main);
         renderToc(main);
         return;
     }
-    if (!searchQuery && spec.info?.description) {
-        const intro = doc.createElement('div');
-        intro.className = 'intro-section';
-        intro.innerHTML = `<div class="markdown-content">${parseMarkdown(spec.info.description)}</div>`;
-        main.appendChild(intro);
+    // Root landing: an OpenAPI-driven overview (title, version, servers,
+    // description) followed by the endpoint list — unless the user is
+    // mid-search, in which case the search results take the surface.
+    if (!searchQuery) {
+        main.appendChild(renderDocsOverview());
     }
     if (searchQuery)
         renderDocsSearch(main);
@@ -1829,6 +1848,67 @@ function renderContent() {
     }
     renderToc(main);
 }
+function renderDocsOverview() {
+    const info = (spec.info ?? {});
+    const container = doc.createElement('div');
+    container.className = 'docs-overview';
+    const title = String(info.title ?? 'API');
+    const versionBadge = info.version
+        ? `<span class="docs-overview-version">${esc(String(info.version))}</span>`
+        : '';
+    const header = doc.createElement('header');
+    header.className = 'docs-overview-header';
+    header.innerHTML = `<h1 class="docs-overview-title" id="overview">${esc(title)}${versionBadge}</h1>`;
+    container.appendChild(header);
+    // Contact / license line (ReDoc-style).
+    const contact = (info.contact ?? {});
+    const license = (info.license ?? {});
+    const metaBits = [];
+    if (contact.email) {
+        const label = esc(String(contact.name ?? contact.email));
+        metaBits.push(`E-mail: <a href="mailto:${esc(String(contact.email))}">${label}</a>`);
+    }
+    if (contact.url) {
+        metaBits.push(`URL: <a href="${esc(String(contact.url))}" target="_blank" rel="noopener">${esc(String(contact.url))}</a>`);
+    }
+    if (license.name) {
+        const lic = license.url
+            ? `<a href="${esc(String(license.url))}" target="_blank" rel="noopener">${esc(String(license.name))}</a>`
+            : esc(String(license.name));
+        metaBits.push(`License: ${lic}`);
+    }
+    if (metaBits.length) {
+        const meta = doc.createElement('div');
+        meta.className = 'docs-overview-meta';
+        meta.innerHTML = metaBits.join('<span class="docs-overview-meta-sep">·</span>');
+        container.appendChild(meta);
+    }
+    // Servers — straight from `spec.servers`.
+    const servers = Array.isArray(spec.servers) ? spec.servers : [];
+    if (servers.length) {
+        const section = doc.createElement('section');
+        section.className = 'docs-overview-servers';
+        const rows = servers
+            .map((s) => {
+            const url = esc(String(s?.url ?? ''));
+            const desc = s?.description
+                ? `<span class="docs-overview-server-desc">${esc(String(s.description))}</span>`
+                : '';
+            return `<li class="docs-overview-server"><code class="docs-overview-server-url">${url}</code>${desc}</li>`;
+        })
+            .join('');
+        section.innerHTML = `<h2 class="docs-overview-subtitle">${servers.length > 1 ? 'Servers' : 'Server'}</h2><ul class="docs-overview-server-list">${rows}</ul>`;
+        container.appendChild(section);
+    }
+    // Description (markdown).
+    if (info.description) {
+        const description = doc.createElement('div');
+        description.className = 'docs-overview-description markdown-content';
+        description.innerHTML = parseMarkdown(String(info.description));
+        container.appendChild(description);
+    }
+    return container;
+}
 function renderMissingDocsPage(main) {
     const notFound = getDocsPageViews().find(page => page.path === '/404' || page.path.endsWith('/404'));
     const article = doc.createElement('article');