sourcey 3.6.2 → 3.6.4

package/README.md

@@ -2,18 +2,14 @@
 
 > Docs straight from the source.
 
-Sourcey tells the whole product story. It turns specs, code, rich guides, changelog, roadmap pages, examples, and portable context files from your project into static HTML you can deploy anywhere.
+Sourcey turns OpenAPI, MCP, Doxygen XML, godoc, rustdoc, and Markdown into one static HTML site you own: reference, guides, changelog, roadmap, and llms.txt from the same build, deployable anywhere.
 
-No dashboard. No runtime. No API calls to render your own documentation.
+Everything renders at build time: no dashboard, no runtime, no API calls to render your own documentation.
 
 [![npm](https://img.shields.io/npm/v/sourcey)](https://www.npmjs.com/package/sourcey)
 [![build](https://img.shields.io/github/actions/workflow/status/sourcey/sourcey/ci.yml?branch=main)](https://github.com/sourcey/sourcey/actions)
 [![node](https://img.shields.io/node/v/sourcey)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/sourcey)](LICENSE)
-[![Go Reference](https://pkg.go.dev/badge/github.com/sourcey/sourcey/go/sourcey-godoc.svg)](https://pkg.go.dev/github.com/sourcey/sourcey/go/sourcey-godoc)
-[![Go Report Card](https://goreportcard.com/badge/github.com/sourcey/sourcey/go/sourcey-godoc)](https://goreportcard.com/report/github.com/sourcey/sourcey/go/sourcey-godoc)
-[![crates.io](https://img.shields.io/crates/v/sourcey.svg)](https://crates.io/crates/sourcey)
-[![docs.rs](https://docs.rs/sourcey/badge.svg)](https://docs.rs/sourcey)
 
 ```bash
 npx sourcey init
@@ -60,6 +56,9 @@ Then `sourcey init` to scaffold a new project, or `sourcey build` against an exi
 
 ### Standalone Go docs generator
 
+[![Go Reference](https://pkg.go.dev/badge/github.com/sourcey/sourcey/go/sourcey-godoc.svg)](https://pkg.go.dev/github.com/sourcey/sourcey/go/sourcey-godoc)
+[![Go Report Card](https://goreportcard.com/badge/github.com/sourcey/sourcey/go/sourcey-godoc)](https://goreportcard.com/report/github.com/sourcey/sourcey/go/sourcey-godoc)
+
 For Go-only consumers without a JavaScript toolchain, `sourcey-godoc` ships as a separate native binary. It produces static Go docs sites or portable `godoc.json` snapshots.
 
 | Path     | Command                                                                                           |
@@ -68,19 +67,31 @@ For Go-only consumers without a JavaScript toolchain, `sourcey-godoc` ships as a
 | Homebrew | `brew install sourcey/tap/sourcey-godoc`                                                          |
 | Scoop    | `scoop bucket add sourcey https://github.com/sourcey/scoop-bucket && scoop install sourcey-godoc` |
 
+### Rust snapshot converter
+
+[![crates.io](https://img.shields.io/crates/v/sourcey.svg)](https://crates.io/crates/sourcey)
+[![docs.rs](https://docs.rs/sourcey/badge.svg)](https://docs.rs/sourcey)
+
+The `rustdoc()` adapter consumes nightly rustdoc JSON through the [`sourcey`](https://crates.io/crates/sourcey) companion crate and its `sourcey-rustdoc` converter, so CI can build Rust API docs from a committed snapshot on a stable toolchain. See [docs/adapters/rustdoc.md](docs/adapters/rustdoc.md).
+
 ## Quick start
 
 ```bash
-# From a single OpenAPI spec
-sourcey build api.yaml -o docs/
-
-# Multi-page site (reads sourcey.config.ts)
-sourcey build -o docs/
+# Scaffold a project (detects OpenAPI specs and Doxyfiles)
+npx sourcey init
 
 # Dev server with hot reload
 sourcey dev
+
+# Build static HTML to dist/
+sourcey build
+
+# Quick build from a single OpenAPI spec
+sourcey build api.yaml -o dist/
 ```
 
+In CI, the [`sourcey/build-docs`](https://github.com/sourcey/build-docs) GitHub Action runs the build and deploys to GitHub Pages; see [deploying](https://sourcey.com/docs/deploying).
+
 ## Configuration
 
 Create `sourcey.config.ts` in your project root:
@@ -168,8 +179,8 @@ cd sourcey && npm install
 npm run build && npm test
 cd go/sourcey-godoc && go test ./... && go vet ./...
 
-# Run the demo site
-cd demo && npx tsx ../src/cli.ts dev
+# Run the in-repo docs site against your working copy
+cd docs && npx tsx ../src/cli.ts dev
 ```
 
 ## License

package/dist/client/scroll-tracker.js

@@ -1,12 +1,12 @@
 // Scroll tracker — highlights the active sidebar nav link as user scrolls.
 //
 // Observes [data-traverse-target] section anchors and toggles .active
-// on the matching #nav .nav-link. All visual styling is in sourcey.css;
+// on the matching #nav fragment link. All visual styling is in sourcey.css;
 // this file only manages the class.
 (function () {
   function init() {
     var navbar = document.getElementById('navbar');
-    var navLinks = document.querySelectorAll('#nav .nav-link');
+    var navLinks = document.querySelectorAll('#nav .nav-link, #nav .nav-group-link');
     var targets = document.querySelectorAll('[data-traverse-target]');
 
     // For prose pages, also track heading elements that TOC links point to
@@ -113,7 +113,7 @@
     if (tocEl) tocEl.addEventListener('click', function (e) { handleAnchorClick(e, '.toc-item'); });
 
     var navEl = document.getElementById('nav');
-    if (navEl) navEl.addEventListener('click', function (e) { handleAnchorClick(e, '.nav-link'); });
+    if (navEl) navEl.addEventListener('click', function (e) { handleAnchorClick(e, '.nav-link, .nav-group-link'); });
 
     // Use scroll event for reliable activation at all positions.
     function onScroll() {

package/dist/client/tabs.js

@@ -34,13 +34,13 @@
       trigger.setAttribute('aria-expanded', isOpen ? 'false' : 'true');
     });
 
-    // Select a language from the dropdown
+    // Select a language / example variant from the dropdown
     document.addEventListener('click', function (e) {
       var option = e.target.closest('.code-lang-option');
       if (!option) return;
 
-      var container = option.closest('.code-group');
-      var index = option.getAttribute('data-lang-index');
+      var dropdown = option.closest('.code-lang-dropdown');
+      var canSync = !!(dropdown && dropdown.hasAttribute('data-lang-sync'));
       var lang = option.textContent.trim();
 
       // Close the menu
@@ -52,17 +52,16 @@
       }
 
       var scrollY = window.scrollY;
-      activateLang(container, index);
+      activateLang(option);
 
-      // Sync language across all code-sample groups
-      if (lang !== selectedLang) {
+      // Sync language across code-sample groups only (not example variants).
+      if (canSync && lang !== selectedLang) {
         selectedLang = lang;
+        var ownGroup = option.closest('.code-group');
         document.querySelectorAll('.code-group').forEach(function (group) {
-          if (group === container || !group.querySelector('.code-lang-dropdown')) return;
+          if (group === ownGroup || !group.querySelector('.code-lang-dropdown[data-lang-sync]')) return;
           group.querySelectorAll('.code-lang-option').forEach(function (opt) {
-            if (opt.textContent.trim() === lang) {
-              activateLang(group, opt.getAttribute('data-lang-index'));
-            }
+            if (opt.textContent.trim() === lang) activateLang(opt);
           });
         });
       }
@@ -70,32 +69,51 @@
       window.scrollTo(0, scrollY);
     });
 
-    function activateLang(container, index) {
-      // Update dropdown label
-      var options = container.querySelectorAll('.code-lang-option');
-      var label = container.querySelector('.code-lang-label');
-      options.forEach(function (opt) {
-        var isActive = opt.getAttribute('data-lang-index') === index;
-        opt.setAttribute('aria-selected', isActive ? 'true' : 'false');
-        opt.className = opt.className.replace(/(dark:)?text-\[rgb\([^\]]+\)\]/g, '').trim();
-        if (isActive) {
-          opt.classList.add('text-[rgb(var(--color-primary))]', 'dark:text-[rgb(var(--color-primary-light))]');
-          if (label) label.textContent = opt.textContent.trim();
-          // Update trigger icon to match selected language
-          var triggerIcon = container.querySelector('.code-lang-trigger .code-lang-icon');
-          var optIcon = opt.querySelector('.lang-icon');
-          if (triggerIcon && optIcon) {
-            triggerIcon.innerHTML = optIcon.outerHTML;
+    // The panels a dropdown controls. A header variant dropdown (in the shared
+    // card header) drives the matching response status panel; otherwise panels
+    // live in the dropdown's own `.code-lang-scope` or `.code-group`.
+    function panelScopeForOption(option) {
+      var headerWrap = option.closest('[data-response-dropdown]');
+      if (headerWrap) {
+        var idx = headerWrap.getAttribute('data-response-dropdown');
+        var group = headerWrap.closest('.code-group');
+        var panel = group && group.querySelector('.response-panel[data-response-panel="' + idx + '"]');
+        if (panel) return panel;
+      }
+      return option.closest('.code-lang-scope') || option.closest('.code-group');
+    }
+
+    function activateLang(option) {
+      var dropdown = option.closest('.code-lang-dropdown');
+      var scope = panelScopeForOption(option);
+      var index = option.getAttribute('data-lang-index');
+
+      // Update the dropdown label + options (label/trigger live in the dropdown,
+      // which for a header variant switcher is separate from the panel scope).
+      if (dropdown) {
+        var label = dropdown.querySelector('.code-lang-label');
+        dropdown.querySelectorAll('.code-lang-option').forEach(function (opt) {
+          var isActive = opt.getAttribute('data-lang-index') === index;
+          opt.setAttribute('aria-selected', isActive ? 'true' : 'false');
+          opt.className = opt.className.replace(/(dark:)?text-\[rgb\([^\]]+\)\]/g, '').trim();
+          if (isActive) {
+            opt.classList.add('text-[rgb(var(--color-primary))]', 'dark:text-[rgb(var(--color-primary-light))]');
+            if (label) label.textContent = opt.textContent.trim();
+            var triggerIcon = dropdown.querySelector('.code-lang-trigger .code-lang-icon');
+            var optIcon = opt.querySelector('.lang-icon');
+            if (triggerIcon && optIcon) triggerIcon.innerHTML = optIcon.outerHTML;
+          } else {
+            opt.classList.add('text-[rgb(var(--color-stone-600))]', 'dark:text-[rgb(var(--color-stone-400))]');
           }
-        } else {
-          opt.classList.add('text-[rgb(var(--color-stone-600))]', 'dark:text-[rgb(var(--color-stone-400))]');
-        }
-      });
+        });
+      }
 
-      // Update panels
-      container.querySelectorAll('.code-lang-panel').forEach(function (p) {
-        p.classList.toggle('active', p.getAttribute('data-lang-panel') === index);
-      });
+      // Update panels within the controlled scope.
+      if (scope) {
+        scope.querySelectorAll('.code-lang-panel').forEach(function (p) {
+          p.classList.toggle('active', p.getAttribute('data-lang-panel') === index);
+        });
+      }
     }
 
     // ── Response Tabs ──────────────────────────────────────────────────
@@ -120,6 +138,11 @@
         p.classList.toggle('active', p.getAttribute('data-response-panel') === index);
       });
 
+      // Show only the active status's variant switcher in the header.
+      container.querySelectorAll('[data-response-dropdown]').forEach(function (d) {
+        d.classList.toggle('hidden', d.getAttribute('data-response-dropdown') !== index);
+      });
+
       window.scrollTo(0, scrollY);
     });
 
@@ -132,8 +155,11 @@
       var container = btn.closest('.code-group') || btn.closest('.prose-code-block');
       if (!container) return;
 
-      // Find the active panel's code, or the nearest code element
-      var activePanel = container.querySelector('.code-lang-panel.active, .response-panel.active');
+      // Find the active panel's code, or the nearest code element. With nested
+      // panels (a variant switcher inside a response tab), prefer the deepest
+      // active panel, which is last in document order.
+      var activePanels = container.querySelectorAll('.code-lang-panel.active, .response-panel.active');
+      var activePanel = activePanels.length ? activePanels[activePanels.length - 1] : null;
       var codeEl = activePanel
         ? activePanel.querySelector('code, .code-block, .font-mono')
         : container.querySelector('code, .code-block, .font-mono');

package/dist/components/layout/Sidebar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Sidebar.d.ts","sourceRoot":"","sources":["../../../src/components/layout/Sidebar.tsx"],"names":[],"mappings":"AA+FA;;GAEG;AACH,wBAAgB,OAAO,wCA2GtB"}
+{"version":3,"file":"Sidebar.d.ts","sourceRoot":"","sources":["../../../src/components/layout/Sidebar.tsx"],"names":[],"mappings":"AAsGA;;GAEG;AACH,wBAAgB,OAAO,wCA2GtB"}

package/dist/components/layout/Sidebar.js

@@ -32,7 +32,7 @@ function MethodPill({ method }) {
  * Shared nav group rendering used by both desktop sidebar and mobile drawer.
  */
 function NavGroups({ groups, activePageSlug, base }) {
-    return (_jsx(_Fragment, { children: groups.map((group, gi) => (_jsxs("div", { class: gi > 0 ? "mt-6 lg:mt-8" : "", children: [group.label && (_jsx("h5", { class: "nav-group-label", children: group.label })), _jsx("ul", { class: "space-y-px", children: group.items.map((item) => {
+    return (_jsx(_Fragment, { children: groups.map((group, gi) => (_jsxs("div", { class: gi > 0 ? "mt-6 lg:mt-8" : "", children: [group.label && (group.href ? (_jsx("a", { href: `${base}${group.href}`, class: `nav-group-label nav-group-link${group.id === activePageSlug ? " active" : ""}`, children: group.label })) : (_jsx("h5", { class: "nav-group-label", children: group.label }))), _jsx("ul", { class: "space-y-px", children: group.items.map((item) => {
                         const isActive = item.id === activePageSlug;
                         return (_jsx("li", { children: _jsxs("a", { href: `${base}${item.href}`, class: `nav-link${isActive ? " active" : ""}`, children: [item.method && _jsx(MethodPill, { method: item.method }), _jsx("span", { class: "flex-1 break-words [word-break:break-word]", children: item.label })] }) }, item.id));
                     }) })] }, group.label))) }));

package/dist/components/openapi/CodeSamples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CodeSamples.d.ts","sourceRoot":"","sources":["../../../src/components/openapi/CodeSamples.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAM/D,UAAU,gBAAgB;IACxB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,EAAE,gBAAgB,uCAuE9F"}
+{"version":3,"file":"CodeSamples.d.ts","sourceRoot":"","sources":["../../../src/components/openapi/CodeSamples.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAM/D,UAAU,gBAAgB;IACxB,SAAS,EAAE,mBAAmB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,EAAE,gBAAgB,uCAyE9F"}

package/dist/components/openapi/CodeSamples.js

@@ -12,8 +12,8 @@ export function CodeSamplesExamples({ operation, serverUrl, codeSampleLangs }) {
     if (!samples.length)
         return null;
     const title = operation.summary ?? `${operation.method.toUpperCase()} ${operation.path}`;
-    return (_jsxs("div", { class: "code-group not-prose", children: [_jsxs("div", { class: "relative flex items-center justify-between gap-2 px-3", children: [_jsx("div", { class: "flex min-w-0 items-center gap-1.5 font-medium text-xs leading-6 my-1 mb-1.5", children: _jsx("span", { class: "truncate text-[rgb(var(--color-stone-950))] dark:text-[rgb(var(--color-stone-50))]", children: title }) }), _jsxs("div", { class: "flex shrink-0 items-center justify-end gap-1.5", children: [_jsxs("div", { class: "code-lang-dropdown relative", children: [_jsx("button", { type: "button", class: "code-lang-trigger group relative my-1 mb-1.5 flex items-center whitespace-nowrap font-medium leading-6 outline-0 text-[rgb(var(--color-stone-500))] dark:text-[rgb(var(--color-stone-400))] cursor-pointer text-xs", "aria-expanded": "false", "aria-haspopup": "listbox", children: _jsxs("div", { class: "z-10 flex items-center gap-1 rounded-lg px-1.5 group-hover:bg-[rgb(var(--color-stone-200)/0.5)] group-hover:text-[rgb(var(--color-primary))] dark:group-hover:bg-[rgb(var(--color-stone-700)/0.7)] dark:group-hover:text-[rgb(var(--color-primary-light))]", children: [_jsx("span", { class: "code-lang-icon", dangerouslySetInnerHTML: { __html: langIcon(samples[0].lang) } }), _jsx("span", { class: "code-lang-label truncate", children: samples[0].label ?? samples[0].lang }), _jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", class: "size-3.5 shrink-0", children: [_jsx("path", { d: "m7 15 5 5 5-5" }), _jsx("path", { d: "m7 9 5-5 5 5" })] })] }) }), _jsx("div", { class: "code-lang-menu hidden absolute right-0 top-full mt-1 z-20 min-w-[120px] rounded-lg border border-[rgb(var(--color-stone-200))] dark:border-[rgb(255_255_255/0.1)] bg-[rgb(var(--color-background-light))] dark:bg-[rgb(var(--color-stone-900))] shadow-lg py-1", role: "listbox", children: samples.map((sample, i) => (_jsxs("button", { role: "option", "aria-selected": i === 0 ? "true" : "false", class: `code-lang-option w-full text-left px-3 py-1.5 text-xs font-medium flex items-center gap-1.5 hover:bg-[rgb(var(--color-stone-100))] dark:hover:bg-[rgb(255_255_255/0.05)] ${i === 0 ? "text-[rgb(var(--color-primary))] dark:text-[rgb(var(--color-primary-light))]" : "text-[rgb(var(--color-stone-600))] dark:text-[rgb(var(--color-stone-400))]"}`, "data-lang-index": String(i), children: [_jsx("span", { dangerouslySetInnerHTML: { __html: langIcon(sample.lang) } }), sample.label ?? sample.lang] }, i))) })] }), _jsx(CopyButton, {})] })] }), samples.map((sample, i) => {
-                const html = highlightCode(sample.source, sample.lang);
-                return (_jsx("div", { class: `code-lang-panel${i === 0 ? " active" : ""}`, "data-lang-panel": String(i), children: _jsx("div", { class: "relative w-full px-4 py-3.5 text-sm leading-6 bg-[rgb(var(--color-code-block-light))] dark:bg-[rgb(var(--color-code-block-dark))] overflow-x-auto", style: "font-variant-ligatures: none", children: _jsx("div", { class: "font-mono whitespace-pre text-xs leading-[1.35rem] code-block", dangerouslySetInnerHTML: { __html: html } }) }) }, i));
-            })] }));
+    return (_jsxs("div", { class: "code-group not-prose", children: [_jsxs("div", { class: "relative flex items-center justify-between gap-2 px-3", children: [_jsx("div", { class: "flex min-w-0 items-center gap-1.5 font-medium text-xs leading-6 my-1 mb-1.5", children: _jsx("span", { class: "truncate text-[rgb(var(--color-stone-950))] dark:text-[rgb(var(--color-stone-50))]", children: title }) }), _jsxs("div", { class: "flex shrink-0 items-center justify-end gap-1.5", children: [_jsxs("div", { class: "code-lang-dropdown relative", "data-lang-sync": true, children: [_jsx("button", { type: "button", class: "code-lang-trigger group relative my-1 mb-1.5 flex items-center whitespace-nowrap font-medium leading-6 outline-0 text-[rgb(var(--color-stone-500))] dark:text-[rgb(var(--color-stone-400))] cursor-pointer text-xs", "aria-expanded": "false", "aria-haspopup": "listbox", children: _jsxs("div", { class: "z-10 flex items-center gap-1 rounded-lg px-1.5 group-hover:bg-[rgb(var(--color-stone-200)/0.5)] group-hover:text-[rgb(var(--color-primary))] dark:group-hover:bg-[rgb(var(--color-stone-700)/0.7)] dark:group-hover:text-[rgb(var(--color-primary-light))]", children: [_jsx("span", { class: "code-lang-icon", dangerouslySetInnerHTML: { __html: langIcon(samples[0].lang) } }), _jsx("span", { class: "code-lang-label truncate", children: samples[0].label ?? samples[0].lang }), _jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", class: "size-3.5 shrink-0", children: [_jsx("path", { d: "m7 15 5 5 5-5" }), _jsx("path", { d: "m7 9 5-5 5 5" })] })] }) }), _jsx("div", { class: "code-lang-menu hidden absolute right-0 top-full mt-1 z-20 min-w-[120px] rounded-lg border border-[rgb(var(--color-stone-200))] dark:border-[rgb(255_255_255/0.1)] bg-[rgb(var(--color-background-light))] dark:bg-[rgb(var(--color-stone-900))] shadow-lg py-1", role: "listbox", children: samples.map((sample, i) => (_jsxs("button", { role: "option", "aria-selected": i === 0 ? "true" : "false", class: `code-lang-option w-full text-left px-3 py-1.5 text-xs font-medium flex items-center gap-1.5 hover:bg-[rgb(var(--color-stone-100))] dark:hover:bg-[rgb(255_255_255/0.05)] ${i === 0 ? "text-[rgb(var(--color-primary))] dark:text-[rgb(var(--color-primary-light))]" : "text-[rgb(var(--color-stone-600))] dark:text-[rgb(var(--color-stone-400))]"}`, "data-lang-index": String(i), children: [_jsx("span", { dangerouslySetInnerHTML: { __html: langIcon(sample.lang) } }), sample.label ?? sample.lang] }, i))) })] }), _jsx(CopyButton, {})] })] }), _jsx("div", { class: "code-card-body", children: samples.map((sample, i) => {
+                    const html = highlightCode(sample.source, sample.lang);
+                    return (_jsx("div", { class: `code-lang-panel${i === 0 ? " active" : ""}`, "data-lang-panel": String(i), children: _jsx("div", { class: "relative w-full px-4 py-3.5 text-sm leading-6 bg-[rgb(var(--color-code-block-light))] dark:bg-[rgb(var(--color-code-block-dark))] overflow-x-auto", style: "font-variant-ligatures: none", children: _jsx("div", { class: "font-mono whitespace-pre text-xs leading-[1.35rem] code-block", dangerouslySetInnerHTML: { __html: html } }) }) }, i));
+                }) })] }));
 }

package/dist/components/openapi/Operation.js

@@ -26,7 +26,7 @@ export function Operation({ operation: op, serverUrl }) {
     const hasParams = op.parameters.length > 0;
     const hasBody = !!op.requestBody;
     const mcp = op.mcpExtras;
-    return (_jsxs("div", { id: id, class: "py-8 border-t border-[rgb(var(--color-gray-100))] dark:border-[rgb(var(--color-gray-800))]", "data-traverse-target": id, children: [_jsx("header", { class: "mb-6", children: op.summary && (_jsxs("div", { class: "flex items-baseline gap-2 flex-wrap", children: [_jsx("h2", { class: "text-2xl sm:text-3xl text-[rgb(var(--color-gray-900))] dark:text-[rgb(var(--color-gray-200))] tracking-tight font-bold mb-2", children: _jsx(Markdown, { content: op.summary, inline: true }) }), op.deprecated && _jsx(DeprecatedBadge, {}), mcp?.annotations && _jsx(AnnotationBadges, { annotations: mcp.annotations })] })) }), mcp ? (_jsx(McpEndpointBar, { method: op.method, path: op.path })) : (_jsx(EndpointBar, { method: op.method, path: op.path, serverUrl: serverUrl })), _jsxs("div", { class: `flex flex-col ${apiFirst ? "lg:flex-row" : "xl:flex-row"} gap-8`, children: [_jsxs("div", { class: "flex-1 min-w-0", children: [op.description && (_jsx(Markdown, { content: op.description, class: "mb-6" })), hasBody && (_jsxs("div", { class: "mt-6", children: [_jsx(SectionLabel, { meta: bodyMediaType(op.requestBody), children: "Body" }), _jsx(RequestBody, { body: op.requestBody })] })), hasParams && (_jsxs("div", { class: "mt-6", children: [_jsx(SectionLabel, { children: "Parameters" }), _jsx(Parameters, { parameters: op.parameters })] })), mcp ? (_jsx(McpReturnsCopy, { schema: mcp.outputSchema })) : (op.responses.length > 0 && (_jsxs("div", { class: "mt-6", children: [_jsx(SectionLabel, { children: "Response" }), _jsx(ResponsesCopy, { responses: op.responses })] }))), !mcp && _jsx(SecurityCopy, { security: op.security })] }), _jsxs("aside", { class: `hidden ${apiFirst ? "lg:block" : "xl:block"} w-[28rem] shrink-0 sticky self-start overflow-y-auto space-y-4`, style: "top: calc(var(--header-height) + 2.5rem); max-height: calc(100vh - var(--header-height) - 5rem)", children: [_jsx(CodeSamplesExamples, { operation: op, serverUrl: serverUrl, codeSampleLangs: site.codeSamples }), hasBody && _jsx(RequestBodyExample, { body: op.requestBody }), mcp ? (_jsx(McpReturnsExample, { schema: mcp.outputSchema })) : (_jsx(ResponsesExamples, { responses: op.responses }))] })] }), _jsxs("div", { class: `${apiFirst ? "lg:hidden" : "xl:hidden"} mt-8 space-y-4`, children: [_jsx(CodeSamplesExamples, { operation: op, serverUrl: serverUrl, codeSampleLangs: site.codeSamples }), hasBody && _jsx(RequestBodyExample, { body: op.requestBody }), mcp ? (_jsx(McpReturnsExample, { schema: mcp.outputSchema })) : (_jsx(ResponsesExamples, { responses: op.responses }))] })] }));
+    return (_jsxs("div", { id: id, class: "py-8 border-t border-[rgb(var(--color-gray-100))] dark:border-[rgb(var(--color-gray-800))]", "data-traverse-target": id, children: [_jsx("header", { class: "mb-6", children: op.summary && (_jsxs("div", { class: "flex items-baseline gap-2 flex-wrap", children: [_jsx("h2", { class: "text-2xl sm:text-3xl text-[rgb(var(--color-gray-900))] dark:text-[rgb(var(--color-gray-200))] tracking-tight font-bold mb-2", children: _jsx(Markdown, { content: op.summary, inline: true }) }), op.deprecated && _jsx(DeprecatedBadge, {}), mcp?.annotations && _jsx(AnnotationBadges, { annotations: mcp.annotations })] })) }), mcp ? (_jsx(McpEndpointBar, { method: op.method, path: op.path })) : (_jsx(EndpointBar, { method: op.method, path: op.path, serverUrl: serverUrl })), _jsxs("div", { class: `flex flex-col ${apiFirst ? "lg:flex-row" : "xl:flex-row"} gap-8`, children: [_jsxs("div", { class: "flex-1 min-w-0", children: [op.description && (_jsx(Markdown, { content: op.description, class: "mb-6 max-w-none" })), hasBody && (_jsxs("div", { class: "mt-6", children: [_jsx(SectionLabel, { meta: bodyMediaType(op.requestBody), children: "Body" }), _jsx(RequestBody, { body: op.requestBody })] })), hasParams && (_jsxs("div", { class: "mt-6", children: [_jsx(SectionLabel, { children: "Parameters" }), _jsx(Parameters, { parameters: op.parameters })] })), mcp ? (_jsx(McpReturnsCopy, { schema: mcp.outputSchema })) : (op.responses.length > 0 && (_jsxs("div", { class: "mt-6", children: [_jsx(SectionLabel, { children: "Response" }), _jsx(ResponsesCopy, { responses: op.responses })] }))), !mcp && _jsx(SecurityCopy, { security: op.security })] }), _jsxs("aside", { class: `hidden ${apiFirst ? "lg:block" : "xl:block"} w-[28rem] shrink-0 sticky self-start overflow-y-auto space-y-4`, style: "top: calc(var(--header-height) + 2.5rem); max-height: calc(100vh - var(--header-height) - 5rem)", children: [_jsx(CodeSamplesExamples, { operation: op, serverUrl: serverUrl, codeSampleLangs: site.codeSamples }), hasBody && _jsx(RequestBodyExample, { body: op.requestBody }), mcp ? (_jsx(McpReturnsExample, { schema: mcp.outputSchema })) : (_jsx(ResponsesExamples, { responses: op.responses }))] })] }), _jsxs("div", { class: `${apiFirst ? "lg:hidden" : "xl:hidden"} mt-8 space-y-4`, children: [_jsx(CodeSamplesExamples, { operation: op, serverUrl: serverUrl, codeSampleLangs: site.codeSamples }), hasBody && _jsx(RequestBodyExample, { body: op.requestBody }), mcp ? (_jsx(McpReturnsExample, { schema: mcp.outputSchema })) : (_jsx(ResponsesExamples, { responses: op.responses }))] })] }));
 }
 function bodyMediaType(body) {
     const types = Object.keys(body.content);

package/dist/components/openapi/RequestBody.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RequestBody.d.ts","sourceRoot":"","sources":["../../../src/components/openapi/RequestBody.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAMjE,UAAU,gBAAgB;IACxB,IAAI,EAAE,qBAAqB,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,gBAAgB,uCA4BrD;AAED,UAAU,uBAAuB;IAC/B,IAAI,EAAE,qBAAqB,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,EAAE,uBAAuB,uCAQnE"}
+{"version":3,"file":"RequestBody.d.ts","sourceRoot":"","sources":["../../../src/components/openapi/RequestBody.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAOjE,UAAU,gBAAgB;IACxB,IAAI,EAAE,qBAAqB,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,IAAI,EAAE,EAAE,gBAAgB,uCA4BrD;AAED,UAAU,uBAAuB;IAC/B,IAAI,EAAE,qBAAqB,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,EAAE,uBAAuB,uCAKnE"}

package/dist/components/openapi/RequestBody.js

@@ -1,8 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
 import { SchemaView } from "../schema/SchemaView.js";
-import { ExampleView } from "../schema/ExampleView.js";
+import { ExampleVariantsCard } from "../schema/ExampleView.js";
 import { Markdown } from "../ui/Markdown.js";
 import { MediaTypeDetails } from "./MediaTypeDetails.js";
+import { buildExampleVariants } from "../../utils/example-variants.js";
 /**
  * Request body content (rendered in the main content column).
  */
@@ -19,11 +20,8 @@ export function RequestBody({ body }) {
  * Request body example (rendered in the sticky code panel).
  */
 export function RequestBodyExample({ body }) {
-    const mediaTypes = Object.entries(body.content);
-    if (!mediaTypes.length)
-        return null;
-    const [, content] = mediaTypes[0];
-    if (!content.schema)
+    const variants = buildExampleVariants(body.content);
+    if (!variants.length)
         return null;
-    return _jsx(ExampleView, { schema: content.schema, title: "Request Body" });
+    return _jsx(ExampleVariantsCard, { variants: variants, title: "Request Body" });
 }

package/dist/components/openapi/Responses.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Responses.d.ts","sourceRoot":"","sources":["../../../src/components/openapi/Responses.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAS9D,UAAU,cAAc;IACtB,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAUD;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,SAAS,EAAE,EAAE,cAAc,uCAoC1D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,SAAS,EAAE,EAAE,cAAc,uCAiE9D"}
+{"version":3,"file":"Responses.d.ts","sourceRoot":"","sources":["../../../src/components/openapi/Responses.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAQ9D,UAAU,cAAc;IACtB,SAAS,EAAE,kBAAkB,EAAE,CAAC;CACjC;AAUD;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAAE,SAAS,EAAE,EAAE,cAAc,uCAoC1D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,SAAS,EAAE,EAAE,cAAc,uCAkF9D"}

package/dist/components/openapi/Responses.js

@@ -1,11 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
 import { httpStatusText } from "../../utils/http.js";
 import { SchemaDatatype } from "../schema/SchemaDatatype.js";
-import { ExampleView } from "../schema/ExampleView.js";
+import { ExampleVariantsCard, VariantBody, VariantDropdown } from "../schema/ExampleView.js";
 import { Markdown } from "../ui/Markdown.js";
 import { CopyButton } from "../ui/CopyButton.js";
-import { generateExample } from "../../utils/example-generator.js";
-import { highlightCode } from "../../utils/highlighter.js";
+import { buildExampleVariants } from "../../utils/example-variants.js";
 function statusColorClass(code) {
     if (code.startsWith("2"))
         return "bg-green-100 text-green-800 dark:bg-green-400/20 dark:text-green-300";
@@ -32,29 +31,20 @@ export function ResponsesCopy({ responses }) {
 export function ResponsesExamples({ responses }) {
     if (!responses.length)
         return null;
-    const examples = responses
-        .map((r) => {
-        const schema = getResponseSchema(r);
-        if (!schema)
-            return null;
-        const example = schema.example ?? generateExample(schema);
-        if (example === undefined)
-            return null;
-        const json = JSON.stringify(example, null, 2);
-        const html = highlightCode(json, "json");
-        return { statusCode: r.statusCode, html };
-    })
-        .filter(Boolean);
-    if (!examples.length)
+    const groups = responses
+        .map((r) => ({ statusCode: r.statusCode, variants: buildExampleVariants(r.content) }))
+        .filter((g) => g.variants.length > 0);
+    if (!groups.length)
         return null;
-    // Single response: use plain ExampleView
-    if (examples.length === 1) {
-        const r = responses.find((r) => r.statusCode === examples[0].statusCode);
-        const schema = getResponseSchema(r);
-        return _jsx(ExampleView, { schema: schema, title: `${examples[0].statusCode}` });
+    // Single status code: a standalone card, with a variant switcher when the
+    // response carries more than one example (named examples / content types).
+    if (groups.length === 1) {
+        return _jsx(ExampleVariantsCard, { variants: groups[0].variants, title: groups[0].statusCode });
     }
-    // Multiple responses: tabbed code block with status code tabs in the header
-    return (_jsxs("div", { class: "response-tabs code-group not-prose", children: [_jsxs("div", { class: "relative flex items-center justify-between gap-2 px-3", children: [_jsx("div", { class: "response-tab-list flex gap-1 overflow-x-auto text-xs leading-6", role: "tablist", children: examples.map((ex, i) => (_jsx("button", { type: "button", role: "tab", "aria-selected": i === 0 ? "true" : "false", class: `response-tab group relative my-1 mb-1.5 flex items-center gap-1.5 whitespace-nowrap font-medium outline-0${i === 0 ? " active" : ""}`, "data-response-index": String(i), children: _jsx("div", { class: "z-10 flex items-center gap-1.5 rounded-lg px-1.5 group-hover:bg-[rgb(var(--color-stone-200)/0.5)] group-hover:text-[rgb(var(--color-primary))] dark:group-hover:bg-[rgb(var(--color-stone-700)/0.7)] dark:group-hover:text-[rgb(var(--color-primary-light))]", children: ex.statusCode }) }, ex.statusCode))) }), _jsx("div", { class: "flex shrink-0 items-center justify-end gap-1.5", children: _jsx(CopyButton, {}) })] }), examples.map((ex, i) => (_jsx("div", { class: `response-panel${i === 0 ? " active" : ""}`, role: "tabpanel", "data-response-panel": String(i), children: _jsx("div", { class: "relative w-full px-4 py-3.5 text-sm leading-6 bg-[rgb(var(--color-code-block-light))] dark:bg-[rgb(var(--color-code-block-dark))] overflow-x-auto", style: "font-variant-ligatures: none", children: _jsx("div", { class: "font-mono whitespace-pre text-xs leading-[1.35rem]", dangerouslySetInnerHTML: { __html: ex.html } }) }) }, ex.statusCode)))] }));
+    // Multiple status codes: status tabs on the left of the header; on the right,
+    // a per-status variant switcher (shown for the active status) next to copy,
+    // matching the language select. Panels live in the clipped card body.
+    return (_jsxs("div", { class: "response-tabs code-group not-prose", children: [_jsxs("div", { class: "relative flex items-center justify-between gap-2 px-3", children: [_jsx("div", { class: "response-tab-list flex gap-1 overflow-x-auto text-xs leading-6", role: "tablist", children: groups.map((g, i) => (_jsx("button", { type: "button", role: "tab", "aria-selected": i === 0 ? "true" : "false", class: `response-tab group relative my-1 mb-1.5 flex items-center gap-1.5 whitespace-nowrap font-medium outline-0${i === 0 ? " active" : ""}`, "data-response-index": String(i), children: _jsx("div", { class: "z-10 flex items-center gap-1.5 rounded-lg px-1.5 group-hover:bg-[rgb(var(--color-stone-200)/0.5)] group-hover:text-[rgb(var(--color-primary))] dark:group-hover:bg-[rgb(var(--color-stone-700)/0.7)] dark:group-hover:text-[rgb(var(--color-primary-light))]", children: g.statusCode }) }, g.statusCode))) }), _jsxs("div", { class: "flex shrink-0 items-center justify-end gap-1.5", children: [groups.map((g, i) => g.variants.length > 1 ? (_jsx("div", { "data-response-dropdown": String(i), class: i === 0 ? undefined : "hidden", children: _jsx(VariantDropdown, { variants: g.variants }) }, g.statusCode)) : null), _jsx(CopyButton, {})] })] }), _jsx("div", { class: "code-card-body", children: groups.map((g, i) => (_jsx("div", { class: `response-panel${i === 0 ? " active" : ""}`, role: "tabpanel", "data-response-panel": String(i), children: g.variants.length > 1 ? (g.variants.map((v, j) => (_jsx("div", { class: `code-lang-panel${j === 0 ? " active" : ""}`, "data-lang-panel": String(j), children: _jsx(VariantBody, { variant: v }) }, j)))) : (_jsx(VariantBody, { variant: g.variants[0] })) }, g.statusCode))) })] }));
 }
 function renderResponseType(r) {
     const schema = getResponseSchema(r);

package/dist/components/schema/ExampleView.d.ts

@@ -1,10 +1,33 @@
 import type { NormalizedSchema } from "../../core/types.js";
+import type { ExampleVariant } from "../../utils/example-variants.js";
+/** Render one example body (highlighted JSON or an external-example link). */
+export declare function VariantBody({ variant, showCopy }: {
+    variant: ExampleVariant;
+    showCopy?: boolean;
+}): import("preact").JSX.Element;
+/**
+ * Variant switcher reusing the code-sample language dropdown markup/JS, minus
+ * the cross-group language sync (no `data-lang-sync`). Sits in the card header
+ * to the left of the copy button, identical to the language select.
+ */
+export declare function VariantDropdown({ variants }: {
+    variants: ExampleVariant[];
+}): import("preact").JSX.Element;
+interface ExampleVariantsCardProps {
+    variants: ExampleVariant[];
+    title?: string;
+}
+/**
+ * Standalone example card: a `.code-group` with an optional title, a variant
+ * switcher when more than one example exists, and a copy button.
+ */
+export declare function ExampleVariantsCard({ variants, title }: ExampleVariantsCardProps): import("preact").JSX.Element | null;
 interface ExampleViewProps {
     schema: NormalizedSchema;
     title?: string;
 }
 /**
- * Renders a JSON example in a stone-themed code card with copy button.
+ * Renders a schema-derived JSON example in a stone-themed code card.
  */
 export declare function ExampleView({ schema, title }: ExampleViewProps): import("preact").JSX.Element | null;
 export {};

package/dist/components/schema/ExampleView.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExampleView.d.ts","sourceRoot":"","sources":["../../../src/components/schema/ExampleView.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAK5D,UAAU,gBAAgB;IACxB,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,gBAAgB,uCA8B9D"}
+{"version":3,"file":"ExampleView.d.ts","sourceRoot":"","sources":["../../../src/components/schema/ExampleView.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAQtE,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE;IAAE,OAAO,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,gCA8BjG;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,cAAc,EAAE,CAAA;CAAE,gCAgC3E;AAED,UAAU,wBAAwB;IAChC,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,wBAAwB,uCAsChF;AAED,UAAU,gBAAgB;IACxB,MAAM,EAAE,gBAAgB,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,gBAAgB,uCAI9D"}

package/dist/components/schema/ExampleView.js

@@ -1,15 +1,36 @@
 import { jsx as _jsx, jsxs as _jsxs } from "preact/jsx-runtime";
-import { generateExample } from "../../utils/example-generator.js";
-import { highlightCode } from "../../utils/highlighter.js";
+import { variantFromSchema } from "../../utils/example-variants.js";
 import { CopyButton } from "../ui/CopyButton.js";
+const BODY_WRAP = "relative w-full px-4 py-3.5 text-sm leading-6 bg-[rgb(var(--color-code-block-light))] dark:bg-[rgb(var(--color-code-block-dark))] overflow-x-auto";
+const BODY_CODE = "font-mono whitespace-pre text-xs leading-[1.35rem]";
+/** Render one example body (highlighted JSON or an external-example link). */
+export function VariantBody({ variant, showCopy }) {
+    return (_jsxs("div", { class: BODY_WRAP, style: "font-variant-ligatures: none", children: [showCopy && (_jsx("div", { class: "absolute top-3 right-4 z-10", children: _jsx(CopyButton, {}) })), variant.summary && (_jsx("p", { class: "mb-2 text-xs text-[rgb(var(--color-gray-500))] dark:text-[rgb(var(--color-gray-400))]", children: variant.summary })), variant.externalValue ? (_jsxs("p", { class: "text-xs", children: [_jsx("span", { class: "text-[rgb(var(--color-gray-500))]", children: "External example: " }), _jsx("a", { href: variant.externalValue, target: "_blank", rel: "noopener noreferrer", class: "break-all text-[rgb(var(--color-primary))] hover:underline", children: variant.externalValue })] })) : (_jsx("div", { class: BODY_CODE, dangerouslySetInnerHTML: { __html: variant.html } }))] }));
+}
+/**
+ * Variant switcher reusing the code-sample language dropdown markup/JS, minus
+ * the cross-group language sync (no `data-lang-sync`). Sits in the card header
+ * to the left of the copy button, identical to the language select.
+ */
+export function VariantDropdown({ variants }) {
+    return (_jsxs("div", { class: "code-lang-dropdown relative", children: [_jsx("button", { type: "button", class: "code-lang-trigger group relative my-1 mb-1.5 flex items-center whitespace-nowrap font-medium leading-6 outline-0 text-[rgb(var(--color-stone-500))] dark:text-[rgb(var(--color-stone-400))] cursor-pointer text-xs", "aria-expanded": "false", "aria-haspopup": "listbox", children: _jsxs("div", { class: "z-10 flex items-center gap-1 rounded-lg px-1.5 group-hover:bg-[rgb(var(--color-stone-200)/0.5)] group-hover:text-[rgb(var(--color-primary))] dark:group-hover:bg-[rgb(var(--color-stone-700)/0.7)] dark:group-hover:text-[rgb(var(--color-primary-light))]", children: [_jsx("span", { class: "code-lang-label truncate", children: variants[0].label }), _jsxs("svg", { xmlns: "http://www.w3.org/2000/svg", width: "14", height: "14", viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", class: "size-3.5 shrink-0", children: [_jsx("path", { d: "m7 15 5 5 5-5" }), _jsx("path", { d: "m7 9 5-5 5 5" })] })] }) }), _jsx("div", { class: "code-lang-menu hidden absolute right-0 top-full mt-1 z-20 min-w-[140px] rounded-lg border border-[rgb(var(--color-stone-200))] dark:border-[rgb(255_255_255/0.1)] bg-[rgb(var(--color-background-light))] dark:bg-[rgb(var(--color-stone-900))] shadow-lg py-1", role: "listbox", children: variants.map((v, i) => (_jsx("button", { role: "option", "aria-selected": i === 0 ? "true" : "false", class: `code-lang-option w-full text-left px-3 py-1.5 text-xs font-medium flex items-center gap-1.5 hover:bg-[rgb(var(--color-stone-100))] dark:hover:bg-[rgb(255_255_255/0.05)] ${i === 0 ? "text-[rgb(var(--color-primary))] dark:text-[rgb(var(--color-primary-light))]" : "text-[rgb(var(--color-stone-600))] dark:text-[rgb(var(--color-stone-400))]"}`, "data-lang-index": String(i), children: v.label }, i))) })] }));
+}
+/**
+ * Standalone example card: a `.code-group` with an optional title, a variant
+ * switcher when more than one example exists, and a copy button.
+ */
+export function ExampleVariantsCard({ variants, title }) {
+    if (!variants.length)
+        return null;
+    const multi = variants.length > 1;
+    return (_jsxs("div", { class: "code-group not-prose", children: [(title || multi) && (_jsxs("div", { class: "relative flex items-center justify-between gap-2 px-3", children: [_jsx("div", { class: "flex min-w-0 items-center gap-1.5 font-medium text-xs leading-6 my-1 mb-1.5", children: title && (_jsx("span", { class: "truncate text-[rgb(var(--color-stone-950))] dark:text-[rgb(var(--color-stone-50))]", children: title })) }), _jsxs("div", { class: "flex shrink-0 items-center justify-end gap-1.5", children: [multi && _jsx(VariantDropdown, { variants: variants }), _jsx(CopyButton, {})] })] })), _jsx("div", { class: "code-card-body", children: multi ? (variants.map((v, i) => (_jsx("div", { class: `code-lang-panel${i === 0 ? " active" : ""}`, "data-lang-panel": String(i), children: _jsx(VariantBody, { variant: v }) }, i)))) : (_jsx(VariantBody, { variant: variants[0], showCopy: !title })) })] }));
+}
 /**
- * Renders a JSON example in a stone-themed code card with copy button.
+ * Renders a schema-derived JSON example in a stone-themed code card.
  */
 export function ExampleView({ schema, title }) {
-    const example = schema.example ?? generateExample(schema);
-    if (example === undefined)
+    const variant = variantFromSchema(schema, title ?? "Example");
+    if (!variant)
         return null;
-    const json = JSON.stringify(example, null, 2);
-    const html = highlightCode(json, "json");
-    return (_jsxs("div", { class: "code-group not-prose", children: [title && (_jsxs("div", { class: "relative flex items-center justify-between gap-2 px-3", children: [_jsx("div", { class: "flex min-w-0 items-center gap-1.5 font-medium text-xs leading-6 my-1 mb-1.5", children: _jsx("span", { class: "truncate text-[rgb(var(--color-stone-950))] dark:text-[rgb(var(--color-stone-50))]", children: title }) }), _jsx("div", { class: "flex shrink-0 items-center justify-end gap-1.5", children: _jsx(CopyButton, {}) })] })), _jsxs("div", { class: "relative w-full px-4 py-3.5 text-sm leading-6 bg-[rgb(var(--color-code-block-light))] dark:bg-[rgb(var(--color-code-block-dark))] overflow-x-auto", style: "font-variant-ligatures: none", children: [!title && (_jsx("div", { class: "absolute top-3 right-4 z-10", children: _jsx(CopyButton, {}) })), _jsx("div", { class: "font-mono whitespace-pre text-xs leading-[1.35rem]", dangerouslySetInnerHTML: { __html: html } })] })] }));
+    return _jsx(ExampleVariantsCard, { variants: [variant], title: title });
 }

package/dist/core/navigation.d.ts

@@ -17,6 +17,10 @@ export interface SiteTab {
 }
 export interface SiteNavGroup {
     label: string;
+    /** Optional section link for generated groups such as OpenAPI tag intros. */
+    href?: string;
+    /** Unique ID for section-level active-state matching. */
+    id?: string;
     items: SiteNavItem[];
 }
 export interface SiteNavItem {

package/dist/core/navigation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/core/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAgB/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,UAAkB,GAC7B,OAAO,CAiDT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAClC,UAAU,GAAE,UAAkB,GAC7B,OAAO,CA8BT;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CASnE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,cAAc,CAEhB"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/core/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErD,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAgB/D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,UAAU,GAAE,UAAkB,GAC7B,OAAO,CAuDT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,EAClC,UAAU,GAAE,UAAkB,GAC7B,OAAO,CA8BT;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CASnE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,cAAc,CAEhB"}

package/dist/core/navigation.js

@@ -40,6 +40,7 @@ export function buildNavFromSpec(spec, tabSlug, prettyUrls = false) {
     for (const tag of spec.tags) {
         if (tag.hidden)
             continue;
+        const tagId = `tag-${htmlId(tag.name)}`;
         const items = tag.operations.map((op) => ({
             label: op.summary ?? `${op.method.toUpperCase()} ${op.path}`,
             href: `${basePath}#operation-${htmlId(op.path)}-${htmlId(op.method)}`,
@@ -48,7 +49,12 @@ export function buildNavFromSpec(spec, tabSlug, prettyUrls = false) {
         }));
         if (!items.length)
             continue;
-        groups.push({ label: tagNavigationLabel(tag, tagsByName), items });
+        groups.push({
+            label: tagNavigationLabel(tag, tagsByName),
+            href: `${basePath}#${tagId}`,
+            id: tagId,
+            items,
+        });
     }
     // Models group
     const schemaNames = Object.keys(spec.schemas);

package/dist/core/sourcey-rustdoc/Cargo.lock

@@ -66,15 +66,15 @@ checksum = "7f202df86484c868dbad7eaa557ef785d5c66295e41b460ef922eca0723b842c"
 
 [[package]]
 name = "bitflags"
-version = "2.11.1"
+version = "2.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
+checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
 
 [[package]]
 name = "camino"
-version = "1.2.2"
+version = "1.2.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e629a66d692cb9ff1a1c664e41771b3dcaf961985a9774c0eb0bd1b51cf60a48"
+checksum = "b4ce8d3bd5823c7504d3f579f13e7b2f3da252fcb938c594d5680ee508bf846f"
 dependencies = [
  "serde_core",
 ]
@@ -180,9 +180,6 @@ name = "deranged"
 version = "0.5.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7cd812cc2bc1d69d4764bd80df88b4317eaef9e773c75226407d9bc0876b211c"
-dependencies = [
- "powerfmt",
-]
 
 [[package]]
 name = "equivalent"
@@ -245,9 +242,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
 
 [[package]]
 name = "memchr"
-version = "2.8.1"
+version = "2.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6b947ae49db0d222b1dbc6b113ce7248a3fc3a6ca21b696717bfc000ba4484d8"
+checksum = "88904434abc2901f197fe8cc55f0445e7ded921dba5911dad2e2b39b48e663c4"
 
 [[package]]
 name = "miniz_oxide"
@@ -452,9 +449,9 @@ checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
 
 [[package]]
 name = "syn"
-version = "2.0.117"
+version = "2.0.118"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99"
+checksum = "1b9ae57f904213ebb649ce6895b8a66c66f0203b9319718f69a5612a065b1422"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -503,12 +500,11 @@ dependencies = [
 
 [[package]]
 name = "time"
-version = "0.3.47"
+version = "0.3.49"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "743bd48c283afc0388f9b8827b976905fb217ad9e647fae3a379a9283c4def2c"
+checksum = "711a53c2d47bbd818258c498c8dbfe186a2526c631495cfe7e078567f86b8469"
 dependencies = [
  "deranged",
- "itoa",
  "num-conv",
  "powerfmt",
  "serde_core",
@@ -518,15 +514,15 @@ dependencies = [
 
 [[package]]
 name = "time-core"
-version = "0.1.8"
+version = "0.1.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7694e1cfe791f8d31026952abf09c69ca6f6fa4e1a1229e18988f06a04a12dca"
+checksum = "9e1c906769ad99c88eaa54e728060edef082f8e358ff32030cb7c7d315e81109"
 
 [[package]]
 name = "time-macros"
-version = "0.2.27"
+version = "0.2.29"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e70e4c5a0e0a8a4823ad65dfe1a6930e4f4d756dcd9dd7939022b5e8c501215"
+checksum = "71c652a3727a9cbb9a02f707f530b618ce00d0ccd762009c8c23bd191df3c17d"
 dependencies = [
  "num-conv",
  "time-core",

package/dist/core/sourcey-rustdoc/Cargo.toml

@@ -6,7 +6,7 @@ description = "Convert nightly rustdoc JSON into a stable RustdocSpec snapshot.
 license = "AGPL-3.0-only"
 repository = "https://github.com/sourcey/sourcey"
 homepage = "https://sourcey.com"
-documentation = "https://sourcey.com/docs/adapters/rustdoc"
+documentation = "https://sourcey.com/docs/rustdoc-integration"
 readme = "README.md"
 keywords = ["rustdoc", "documentation", "json", "rust-api"]
 categories = ["development-tools", "command-line-utilities"]

package/dist/core/sourcey-rustdoc/README.md

@@ -16,7 +16,7 @@ this crate directly. It is published for:
 - CI tools that drive snapshot generation from Rust
 
 If you just want sourcey for your project, see
-[sourcey.com/docs/adapters/rustdoc](https://sourcey.com/docs/adapters/rustdoc).
+[sourcey.com/docs/rustdoc-integration](https://sourcey.com/docs/rustdoc-integration).
 
 ## CLI
 

package/dist/themes/default/sourcey.css

@@ -218,6 +218,7 @@ h1[id], h2[id], h3[id], h4[id], h5[id], h6[id] {
 /* ── Nav Links ────────────────────────────────────────────────────── */
 
 #sourcey .nav-group-label {
+  display: block;
   padding: 0 0.75rem 0.25rem 1rem;
   margin-bottom: 0.625rem;
   font-size: inherit;
@@ -227,6 +228,24 @@ h1[id], h2[id], h3[id], h4[id], h5[id], h6[id] {
 .dark #sourcey .nav-group-label {
   color: rgb(var(--color-gray-200));
 }
+#sourcey .nav-group-link {
+  cursor: pointer;
+  border-radius: 0.75rem;
+  text-decoration: none;
+  transition: color 0.15s, background-color 0.15s;
+}
+#sourcey .nav-group-link:hover {
+  color: rgb(var(--color-primary-ink));
+}
+.dark #sourcey .nav-group-link:hover {
+  color: rgb(var(--color-primary-light));
+}
+#sourcey .nav-group-link.active {
+  color: rgb(var(--color-primary-ink));
+}
+.dark #sourcey .nav-group-link.active {
+  color: rgb(var(--color-primary-light));
+}
 
 #sourcey .nav-tab-label {
   display: block;
@@ -1425,7 +1444,9 @@ h1[id], h2[id], h3[id], h4[id], h5[id], h6[id] {
   position: relative;
   display: flex;
   flex-direction: column;
-  overflow: hidden;
+  /* Visible so an open header dropdown menu is not clipped by the card; the
+     code body's rounded corners are clipped by .code-card-body instead. */
+  overflow: visible;
   border-radius: var(--radius);
   border: 1px solid rgb(var(--color-stone-950) / 0.1);
 }
@@ -1435,11 +1456,21 @@ h1[id], h2[id], h3[id], h4[id], h5[id], h6[id] {
 
 #sourcey .code-group > div:first-child {
   background: rgb(var(--color-stone-50));
+  border-top-left-radius: var(--radius);
+  border-top-right-radius: var(--radius);
 }
 .dark #sourcey .code-group > div:first-child {
   background: rgb(255 255 255 / 0.03);
 }
 
+/* Clips the code panels' rounded bottom corners now that the card itself does
+   not clip. Horizontal code scrolling stays on the inner body element. */
+#sourcey .code-card-body {
+  overflow: hidden;
+  border-bottom-left-radius: var(--radius);
+  border-bottom-right-radius: var(--radius);
+}
+
 /* ── Selection ─────────────────────────────────────────────────────── */
 
 #sourcey ::selection { background: rgb(var(--color-primary) / 0.12); }

package/dist/utils/example-variants.d.ts

@@ -0,0 +1,31 @@
+import type { MediaTypeContent, NormalizedSchema } from "../core/types.js";
+/**
+ * A single, render-ready example. One media type can contribute several
+ * (named `examples`); each becomes its own variant so the UI can offer a
+ * switcher between them.
+ */
+export interface ExampleVariant {
+    /** Label shown in the variant switcher (example name, media type, or "Example"). */
+    label: string;
+    /** Optional caption from a named example's `summary`/`description`. */
+    summary?: string;
+    /** Media type the example came from (e.g. `application/json`). */
+    mediaType: string;
+    /** Syntax-highlighted HTML body, empty when the example is external-only. */
+    html: string;
+    /** Raw text body (for copy + tests), or the URL for an external example. */
+    raw: string;
+    /** Set when the example is referenced via `externalValue` rather than inline. */
+    externalValue?: string;
+}
+/** Build a single variant from a schema, falling back to a generated example. */
+export declare function variantFromSchema(schema: NormalizedSchema, label?: string, mediaType?: string): ExampleVariant | null;
+/**
+ * Collect every render-ready example for a content map (a response, request
+ * body, or parameter). Provided examples win over the schema: named `examples`
+ * first, then a single `example`, and only then a schema-generated fallback.
+ * Every media type contributes, so multi-content-type responses surface them
+ * all rather than just the first.
+ */
+export declare function buildExampleVariants(content?: Record<string, MediaTypeContent>): ExampleVariant[];
+//# sourceMappingURL=example-variants.d.ts.map

package/dist/utils/example-variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"example-variants.d.ts","sourceRoot":"","sources":["../../src/utils/example-variants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAI1F;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,oFAAoF;IACpF,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;IAClB,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AA2DD,iFAAiF;AACjF,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,gBAAgB,EACxB,KAAK,SAAY,EACjB,SAAS,SAAqB,GAC7B,cAAc,GAAG,IAAI,CAIvB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GACzC,cAAc,EAAE,CAiClB"}

package/dist/utils/example-variants.js

@@ -0,0 +1,99 @@
+import { generateExample } from "./example-generator.js";
+import { highlightCode } from "./highlighter.js";
+/** Map a media type to a highlighter language, defaulting to JSON. */
+function langForMediaType(mediaType) {
+    const m = mediaType.toLowerCase();
+    if (m.includes("xml"))
+        return "xml";
+    if (m.includes("yaml") || m.includes("yml"))
+        return "yaml";
+    if (m.includes("html"))
+        return "html";
+    if (m.includes("json"))
+        return "json";
+    if (m.startsWith("text/"))
+        return "text";
+    return "json";
+}
+/** Build a variant from a concrete example value. */
+function variantFromValue(value, opts) {
+    const lang = langForMediaType(opts.mediaType);
+    // JSON media encodes any value (a bare string "hi" renders as "hi"); other
+    // media types keep a provided string body verbatim (pre-formatted XML/text).
+    const raw = typeof value === "string" && lang !== "json"
+        ? value
+        : JSON.stringify(value, null, 2);
+    return {
+        label: opts.label,
+        summary: opts.summary,
+        mediaType: opts.mediaType,
+        raw,
+        html: highlightCode(raw, lang),
+    };
+}
+/** Build a variant from a named OpenAPI example object. */
+function variantFromExample(name, example, mediaType) {
+    if (example.value !== undefined) {
+        return variantFromValue(example.value, {
+            label: example.summary ?? name,
+            summary: example.description,
+            mediaType,
+        });
+    }
+    if (example.externalValue) {
+        return {
+            label: example.summary ?? name,
+            summary: example.description,
+            mediaType,
+            raw: example.externalValue,
+            html: "",
+            externalValue: example.externalValue,
+        };
+    }
+    return null;
+}
+/** Build a single variant from a schema, falling back to a generated example. */
+export function variantFromSchema(schema, label = "Example", mediaType = "application/json") {
+    const value = schema.example ?? generateExample(schema);
+    if (value === undefined)
+        return null;
+    return variantFromValue(value, { label, mediaType });
+}
+/**
+ * Collect every render-ready example for a content map (a response, request
+ * body, or parameter). Provided examples win over the schema: named `examples`
+ * first, then a single `example`, and only then a schema-generated fallback.
+ * Every media type contributes, so multi-content-type responses surface them
+ * all rather than just the first.
+ */
+export function buildExampleVariants(content) {
+    if (!content)
+        return [];
+    const entries = Object.entries(content);
+    const multiMedia = entries.length > 1;
+    const variants = [];
+    for (const [mediaType, media] of entries) {
+        const named = media.examples ? Object.entries(media.examples) : [];
+        if (named.length) {
+            for (const [name, example] of named) {
+                const variant = variantFromExample(name, example, mediaType);
+                if (variant)
+                    variants.push(variant);
+            }
+            continue;
+        }
+        if (media.example !== undefined) {
+            variants.push(variantFromValue(media.example, {
+                label: multiMedia ? mediaType : "Example",
+                mediaType,
+            }));
+            continue;
+        }
+        if (media.schema) {
+            const variant = variantFromSchema(media.schema, multiMedia ? mediaType : "Example", mediaType);
+            if (variant)
+                variants.push(variant);
+        }
+    }
+    return variants;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sourcey",
-  "version": "3.6.2",
+  "version": "3.6.4",
   "description": "Precision documentation from OpenAPI, MCP, Doxygen, godoc, rustdoc, and Markdown. Static HTML you own.",
   "type": "module",
   "engines": {