rapidoc 12.0.0 → 12.1.0

package/src/rapidoc-mini.ts

@@ -89,7 +89,10 @@ export default class RapiDocMini extends LitElement {
 
   // Mock Server
   @property({ type: String, attribute: "mock-server" }) mockServer = "false";
-  @property({ type: String, attribute: "mock-server-status-code" }) mockServerStatusCode = "200";
+  // A string of codes for every operation, or a map by operation (`{ "POST /orders": "503, 200", "*": "200" }`)
+  @property({ type: String, attribute: "mock-server-status-code" }) mockServerStatusCode:
+    | string
+    | Record<string, string> = "200";
   @property({ type: String, attribute: "mock-server-status-strategy" }) mockServerStatusStrategy =
     "example";
   @property({ type: Number, attribute: "mock-server-delay" }) mockServerDelay = 0;
@@ -120,6 +123,7 @@ export default class RapiDocMini extends LitElement {
   @property({ type: Boolean }) loading = false;
 
   isMini: boolean;
+  _specLoadSeq: number;
   updateRoute: string;
   renderStyle: string;
   showHeader: string;
@@ -135,6 +139,8 @@ export default class RapiDocMini extends LitElement {
   constructor() {
     super();
     this.isMini = true;
+    // Spec loads carry a token; only the latest load may apply its result (see loadSpec)
+    this._specLoadSeq = 0;
     this.updateRoute = "false";
     this.renderStyle = "view";
     this.showHeader = "false";
@@ -312,7 +318,7 @@ export default class RapiDocMini extends LitElement {
 
   disconnectedCallback() {
     if (this.mockServer === "true") {
-      disableMockServer();
+      disableMockServer(this);
     }
     super.disconnectedCallback();
   }
@@ -364,13 +370,14 @@ export default class RapiDocMini extends LitElement {
     if (changedProperties.has("mockServer")) {
       if (this.mockServer === "true" && this.resolvedSpec) {
         enableMockServer(this.resolvedSpec, {
+          owner: this,
           statusCode: this.mockServerStatusCode,
           statusStrategy: this.mockServerStatusStrategy,
           delay: this.mockServerDelay,
           log: this.mockServerLog,
         });
       } else if (this.mockServer !== "true") {
-        disableMockServer();
+        disableMockServer(this);
       }
     }
     if (
@@ -380,6 +387,7 @@ export default class RapiDocMini extends LitElement {
       changedProperties.has("mockServerLog")
     ) {
       updateMockConfig({
+        owner: this,
         statusCode: this.mockServerStatusCode,
         statusStrategy: this.mockServerStatusStrategy,
         delay: this.mockServerDelay,
@@ -438,7 +446,8 @@ export default class RapiDocMini extends LitElement {
       }
 
       if (updateSelectedApiKey) {
-        if (this.resolvedSpec) {
+        // While the spec is loading, resolvedSpec is a placeholder without securitySchemes
+        if (this.resolvedSpec?.securitySchemes) {
           const rapiDocApiKey = this.resolvedSpec.securitySchemes.find(
             (v: any) => v.securitySchemeId === rapidocApiKey,
           );
@@ -474,6 +483,8 @@ export default class RapiDocMini extends LitElement {
     if (!specUrl) {
       return;
     }
+    // Each load gets a token; a load whose token is no longer current never applies its result
+    const token = ++this._specLoadSeq;
     try {
       this.resolvedSpec = {
         specLoadError: false,
@@ -498,9 +509,15 @@ export default class RapiDocMini extends LitElement {
         this.matchType,
         this.removeEndpointsWithBadgeLabelAs,
       );
+      if (token !== this._specLoadSeq) {
+        return; // a newer load started while this one was parsing
+      }
       this.loading = false;
-      this.afterSpecParsedAndValidated(spec);
+      this.afterSpecParsedAndValidated(spec, token);
     } catch (err: any) {
+      if (token !== this._specLoadSeq) {
+        return;
+      }
       this.loading = false;
       this.loadFailed = true;
       this.resolvedSpec = null;
@@ -530,7 +547,7 @@ export default class RapiDocMini extends LitElement {
     return setApiServer.call(this, apiServerUrl);
   }
 
-  async afterSpecParsedAndValidated(spec) {
+  async afterSpecParsedAndValidated(spec, token = this._specLoadSeq) {
     this.resolvedSpec = spec;
     this.selectedServer = undefined;
     if (this.defaultApiServerUrl) {
@@ -553,11 +570,15 @@ export default class RapiDocMini extends LitElement {
     this.requestUpdate();
 
     while (!(await this.updateComplete));
+    if (token !== this._specLoadSeq) {
+      return; // a newer load took over while this one was rendering; it fires its own spec-loaded
+    }
     const specLoadedEvent = new CustomEvent("spec-loaded", { detail: spec });
     this.dispatchEvent(specLoadedEvent);
 
     if (this.mockServer === "true") {
       enableMockServer(this.resolvedSpec, {
+        owner: this,
         statusCode: this.mockServerStatusCode,
         statusStrategy: this.mockServerStatusStrategy,
         delay: this.mockServerDelay,

package/src/rapidoc.ts

@@ -41,9 +41,10 @@ import { applyApiKey, onClearAllApiKeys } from "~/templates/security-scheme-temp
 import { setApiServer } from "~/templates/server-template";
 import {
   generateMcpServer as mcpServerGenerator,
-  extractMcpOperations,
+  buildMcpManifest,
   estimateTokenCost,
-  parseMcpTargets,
+  parseMcpEnabled,
+  createZip,
 } from "~/utils/mcp-generator";
 import { bindNavBar } from "~/utils/bind-navbar";
 import { methodPathSlug } from "~/utils/slugger";
@@ -91,6 +92,11 @@ export default class RapiDoc extends LitElement {
     // Set on the reader's first pointer, key, wheel or touch input (see getContentScrollBehavior)
     this._readerHasInteracted = false;
     this._onFirstInteraction = null;
+    this._onHashChange = null;
+    // Spec loads carry a token; only the latest load may apply its result (see loadSpec)
+    this._specLoadSeq = 0;
+    // The spec-url attribute value whose load has been handled, or that an inlined spec superseded
+    this._lastSpecUrlRequested = null;
     this.initIntersectionObserver();
   }
 
@@ -104,6 +110,7 @@ export default class RapiDoc extends LitElement {
   @property({ type: String, attribute: "sort-tags" }) sortTags = "false";
   @property({ type: String, attribute: "sort-schemas" }) sortSchemas = "false";
   @property({ type: String, attribute: "generate-missing-tags" }) generateMissingTags = "false";
+  @property({ type: String, attribute: "show-unused-tags" }) showUnusedTags = "false";
   @property({ type: String, attribute: "sort-endpoints-by" }) sortEndpointsBy = "path";
   @property({ type: String, attribute: false }) specFile: any;
 
@@ -138,7 +145,10 @@ export default class RapiDoc extends LitElement {
 
   // Mock Server
   @property({ type: String, attribute: "mock-server" }) mockServer = "false";
-  @property({ type: String, attribute: "mock-server-status-code" }) mockServerStatusCode = "200";
+  // A string of codes for every operation, or a map by operation (`{ "POST /orders": "503, 200", "*": "200" }`)
+  @property({ type: String, attribute: "mock-server-status-code" }) mockServerStatusCode:
+    | string
+    | Record<string, string> = "200";
   @property({ type: String, attribute: "mock-server-status-strategy" }) mockServerStatusStrategy =
     "example";
   @property({ type: Number, attribute: "mock-server-delay" }) mockServerDelay = 0;
@@ -160,7 +170,8 @@ export default class RapiDoc extends LitElement {
   @property({ type: String, attribute: "allow-server-selection" }) allowServerSelection = "true";
   @property({ type: String, attribute: "allow-schema-description-expand-toggle" })
   allowSchemaDescriptionExpandToggle = "true";
-  @property({ type: String, attribute: "mcp" }) mcp = "true";
+  // "true" shows the Export MCP Server button; "none" or "false" hides it
+  @property({ type: String, attribute: "mcp" }) mcp = "false";
   @property({ type: String, attribute: "mcp-server-name" }) mcpServerName = "";
   @property({ type: String, attribute: "show-components" }) showComponents = "false";
   @property({ type: String, attribute: "page-direction" }) pageDirection = "ltr";
@@ -388,6 +399,9 @@ export default class RapiDoc extends LitElement {
     if (!this.generateMissingTags || !"true, false,".includes(`${this.generateMissingTags},`)) {
       this.generateMissingTags = "false";
     }
+    if (!this.showUnusedTags || !"true, false,".includes(`${this.showUnusedTags},`)) {
+      this.showUnusedTags = "false";
+    }
     if (
       !this.sortEndpointsBy ||
       !"method, path, summary, none,".includes(`${this.sortEndpointsBy},`)
@@ -472,13 +486,12 @@ export default class RapiDoc extends LitElement {
       this.mcp = "none";
     }
 
-    window.addEventListener(
-      "hashchange",
-      () => {
+    if (!this._onHashChange) {
+      this._onHashChange = () => {
         this.scrollToPath(this.getElementIDFromURL());
-      },
-      true,
-    );
+      };
+      window.addEventListener("hashchange", this._onHashChange, true);
+    }
 
     if (!this._readerHasInteracted && !this._onFirstInteraction) {
       this._onFirstInteraction = () => {
@@ -490,7 +503,9 @@ export default class RapiDoc extends LitElement {
       );
     }
 
-    // Auto-hydrate from inlined spec or spec-url attribute if not already loaded
+    // Auto-hydrate from inlined spec or spec-url attribute if not already loaded. This block owns
+    // the initial load; the deferred spec-url path in attributeChangedCallback skips the value
+    // recorded in _lastSpecUrlRequested so one <rapi-doc spec-url> loads once.
     if (!this.resolvedSpec) {
       const inlinedSpecEl = this.querySelector(
         'script[type="application/json"][slot="rapidoc-spec"]',
@@ -498,6 +513,8 @@ export default class RapiDoc extends LitElement {
       if (inlinedSpecEl?.textContent) {
         try {
           const parsed = JSON.parse(inlinedSpecEl.textContent);
+          // The inlined spec wins over a spec-url attribute present at connect
+          this._lastSpecUrlRequested = this.getAttribute("spec-url");
           this.loadSpec(parsed);
         } catch {
           // ignore parse error
@@ -524,9 +541,13 @@ export default class RapiDoc extends LitElement {
     if (this.intersectionObserver) {
       this.intersectionObserver.disconnect();
     }
+    if (this._onHashChange) {
+      window.removeEventListener("hashchange", this._onHashChange, true);
+      this._onHashChange = null;
+    }
     this.removeFirstInteractionListeners();
     if (this.mockServer === "true") {
-      disableMockServer();
+      disableMockServer(this);
     }
     super.disconnectedCallback();
   }
@@ -595,11 +616,12 @@ export default class RapiDoc extends LitElement {
     }
     this._clearDsdIfNeeded();
 
-    // return render(mainBodyTemplate(this), this.shadowRoot, { eventContext: this });
-    const cssLinkEl = document.querySelector(`link[href*="${this.cssFile}"]`);
-    // adding custom style for RapiDoc
-    if (cssLinkEl) {
-      this.shadowRoot.appendChild(cssLinkEl.cloneNode());
+    // adding custom style for RapiDoc: the page's <link> whose href contains the css-file value
+    if (this.cssFile) {
+      const cssLinkEl = document.querySelector(`link[href*="${CSS.escape(this.cssFile)}"]`);
+      if (cssLinkEl) {
+        this.shadowRoot.appendChild(cssLinkEl.cloneNode());
+      }
     }
     return mainBodyTemplate.call(this);
   }
@@ -662,13 +684,14 @@ export default class RapiDoc extends LitElement {
     if (changedProperties.has("mockServer")) {
       if (this.mockServer === "true" && this.resolvedSpec) {
         enableMockServer(this.resolvedSpec, {
+          owner: this,
           statusCode: this.mockServerStatusCode,
           statusStrategy: this.mockServerStatusStrategy,
           delay: this.mockServerDelay,
           log: this.mockServerLog,
         });
       } else if (this.mockServer !== "true") {
-        disableMockServer();
+        disableMockServer(this);
       }
     }
     if (
@@ -678,6 +701,7 @@ export default class RapiDoc extends LitElement {
       changedProperties.has("mockServerLog")
     ) {
       updateMockConfig({
+        owner: this,
         statusCode: this.mockServerStatusCode,
         statusStrategy: this.mockServerStatusStrategy,
         delay: this.mockServerDelay,
@@ -702,6 +726,10 @@ export default class RapiDoc extends LitElement {
       if (oldVal !== newVal) {
         // put it at the end of event-loop to load all the attributes
         window.setTimeout(async () => {
+          // Already loaded by connectedCallback (or superseded by an inlined spec there)
+          if (newVal === this._lastSpecUrlRequested) {
+            return;
+          }
           await this.loadSpec(newVal);
           // If goto-path is provided and no location-hash is present then try to scroll there
           if (this.gotoPath && !window.location.hash) {
@@ -894,6 +922,11 @@ export default class RapiDoc extends LitElement {
     if (!specUrl) {
       return;
     }
+    if (typeof specUrl === "string") {
+      this._lastSpecUrlRequested = specUrl;
+    }
+    // Each load gets a token; a load whose token is no longer current never applies its result
+    const token = ++this._specLoadSeq;
     this.searchVal = "";
     try {
       if (!this._hasDsd) {
@@ -919,10 +952,17 @@ export default class RapiDoc extends LitElement {
         this.matchPaths,
         this.matchType,
         this.removeEndpointsWithBadgeLabelAs,
+        this.showUnusedTags === "true",
       );
+      if (token !== this._specLoadSeq) {
+        return; // a newer load started while this one was parsing
+      }
       this.loading = false;
-      this.afterSpecParsedAndValidated(spec);
+      this.afterSpecParsedAndValidated(spec, token);
     } catch (err) {
+      if (token !== this._specLoadSeq) {
+        return;
+      }
       this.loading = false;
       this._clearDsdIfNeeded();
       this.loadFailed = true;
@@ -931,7 +971,7 @@ export default class RapiDoc extends LitElement {
     }
   }
 
-  async afterSpecParsedAndValidated(spec) {
+  async afterSpecParsedAndValidated(spec, token = this._specLoadSeq) {
     this._clearDsdIfNeeded();
     this.resolvedSpec = spec;
     this.selectedServer = undefined;
@@ -954,11 +994,15 @@ export default class RapiDoc extends LitElement {
     }
     this.requestUpdate();
     while (!(await this.updateComplete));
+    if (token !== this._specLoadSeq) {
+      return; // a newer load took over while this one was rendering; it fires its own spec-loaded
+    }
     const specLoadedEvent = new CustomEvent("spec-loaded", { detail: spec });
     this.dispatchEvent(specLoadedEvent);
 
     if (this.mockServer === "true") {
       enableMockServer(this.resolvedSpec, {
+        owner: this,
         statusCode: this.mockServerStatusCode,
         statusStrategy: this.mockServerStatusStrategy,
         delay: this.mockServerDelay,
@@ -973,6 +1017,9 @@ export default class RapiDoc extends LitElement {
     }
     if (this.renderStyle === "read") {
       await sleep(100);
+      if (token !== this._specLoadSeq) {
+        return;
+      }
       this.observeExpandedContent(); // This will auto-highlight the selected nav-item in read-mode
     }
 
@@ -993,7 +1040,9 @@ export default class RapiDoc extends LitElement {
       // If goto-path is provided and no location-hash is present then try to scroll to default element
       if (!this.gotoPath) {
         const defaultElementId =
-          this.showInfo === "true" ? "overview" : this.resolvedSpec.tags[0]?.paths[0]?.elementId;
+          this.showInfo === "true"
+            ? "overview"
+            : this.resolvedSpec.tags.find((t) => t.paths.length > 0)?.paths[0]?.elementId;
         if (defaultElementId) {
           this.scrollToPath(defaultElementId);
         }
@@ -1721,53 +1770,51 @@ export default class RapiDoc extends LitElement {
     return setApiServer.call(this, apiServerUrl);
   }
 
-  // Getter for normalized active MCP targets
-  get mcpTargets() {
-    return parseMcpTargets(this.mcp);
+  // True when the `mcp` attribute asks for the Export MCP Server button
+  get mcpEnabled() {
+    return parseMcpEnabled(this.mcp);
   }
 
-  // Public Method - Generates MCP Server code and configuration in memory
-  generateMcpServer(target, options = {}) {
-    const spec = this.resolvedSpec || this.openApiSpec;
-    if (!spec) return null;
-    const defaultTarget = this.mcpTargets[0] || "typescript";
-    return mcpServerGenerator(spec, {
-      target: target || defaultTarget,
+  /**
+   * The <rapi-flow> on the page whose Arazzo document the export takes workflow tools from: the
+   * one whose `for` names this element, else one without `for`. Nothing when rapi-flow is not
+   * loaded.
+   */
+  private findArazzoDocument() {
+    if (typeof customElements === "undefined" || !customElements.get("rapi-flow")) return undefined;
+    const flows = [...document.querySelectorAll("rapi-flow")] as any[];
+    return (
+      flows.find((f) => this.id && f.getAttribute("for") === this.id && f.arazzoDocument) ||
+      flows.find((f) => !f.getAttribute("for") && f.arazzoDocument)
+    );
+  }
+
+  private mcpOptions(options) {
+    const flow = this.findArazzoDocument();
+    return {
       serverName: this.mcpServerName,
+      arazzo: flow?.arazzoDocument,
+      // <rapi-flow> carries the workflow runtime; this bundle does not
+      workflowRuntime: flow?.workflowRuntimeSource,
       ...options,
-    });
+    };
+  }
+
+  // Public Method - Builds the MCP manifest and the files of the exported project in memory
+  generateMcpServer(options = {}) {
+    const spec = this.resolvedSpec || this.openApiSpec;
+    if (!spec) return null;
+    return mcpServerGenerator(spec, this.mcpOptions(options));
   }
 
-  // Public Method - Triggers browser download of generated MCP server file
-  downloadMcpServer(target, options = {}) {
-    const defaultTarget = this.mcpTargets[0] || "typescript";
-    const result = this.generateMcpServer(target || defaultTarget, options);
-    if (!result || !result.serverCode) return;
-    const t = result.target;
-    let filename = "server.ts";
-    let mime = "text/typescript";
-
-    if (t === "python") {
-      filename = "server.py";
-      mime = "text/x-python";
-    } else if (t === "go") {
-      filename = "main.go";
-      mime = "text/x-go";
-    } else if (t === "csharp" || t === "c#") {
-      filename = "Program.cs";
-      mime = "text/plain";
-    } else if (t === "rust") {
-      filename = "main.rs";
-      mime = "text/x-rust";
-    } else if (t === "java") {
-      filename = "RapiDocMcpServer.java";
-      mime = "text/x-java-source";
-    }
-
-    const blob = new Blob([result.serverCode], { type: mime });
+  // Public Method - Downloads the exported MCP project as a zip
+  downloadMcpServer(options = {}) {
+    const result = this.generateMcpServer(options);
+    if (!result) return;
+    const blob = new Blob([createZip(result.files)], { type: "application/zip" });
     const link = document.createElement("a");
     link.href = URL.createObjectURL(blob);
-    link.download = filename;
+    link.download = `${result.manifest.server.name.replace(/_/g, "-")}-mcp.zip`;
     document.body.appendChild(link);
     link.click();
     document.body.removeChild(link);
@@ -1778,8 +1825,7 @@ export default class RapiDoc extends LitElement {
   getMcpBudget(options = {}) {
     const spec = this.resolvedSpec || this.openApiSpec;
     if (!spec) return null;
-    const extracted = extractMcpOperations(spec, options);
-    return estimateTokenCost(extracted.tools, extracted.resources, extracted.workflows);
+    return estimateTokenCost(buildMcpManifest(spec, this.mcpOptions(options)));
   }
 
   // Event handler for Advanced Search text-inputs and checkboxes

package/src/styles/README.md

@@ -0,0 +1,96 @@
+# `src/styles` — RapiDoc Stylesheets and Theme Tokens
+
+## Overview
+
+The CSS of `<rapi-doc>` and `<rapi-doc-mini>`, written as Lit `css` templates (one default export
+per stylesheet file), plus the theming helpers that turn the `theme` attribute into CSS custom
+properties, and string transforms that reuse the same CSS outside a shadow root.
+
+- `theme-tokens.js` defines the custom properties (shadcn/ui names such as `--background`,
+  `--primary`, `--radius`; `--sidebar-*` for navigation; `--h1-font-size`… and `--heading-*`) and
+  switches them on host attributes (`theme`, `color-scheme`, `radius`, `scale`,
+  `nav-item-spacing`). The other stylesheets read those tokens and style component class names.
+- `css-bundle.js` composes every stylesheet into `allStyles` and rewrites `:host` selectors for
+  Light DOM use.
+
+Not owned here: which attributes exist (`src/rapidoc.ts`), the documented token list
+(`docs/src/page-data/styling-data.yaml`), and the portal's own layout CSS.
+
+Dependents: `src/rapidoc.ts`, `src/rapidoc-mini.ts` and the shadow-root components in
+`src/components/` list the stylesheets they need in `static get styles()`; `packages/rapidoc-prerender/src/index.js`
+re-exports `getBundledCss`, `getNavCss` and `getThemeTokensCss` as `@rapidoc/prerender`, and
+`packages/rapidoc-prerender/src/render.js` uses `getBundledCss` for Declarative Shadow DOM output; `@rapidoc/portal`
+(`src/pages/api-reference.astro`) uses `getNavCss` and `getThemeTokensCss`.
+
+## Interface
+
+`theme-tokens.js`:
+
+- `DEFAULT_THEME` (`"ember"`), `THEMES` (preset name to `{ dark, light }` declaration strings),
+  `THEME_PRESETS` (its keys).
+- `isValidHexColor`, `isValidTheme`, `isCustomColor`, `isLightColor`: theme value checks.
+- `normalizeTheme(theme) -> { theme }`: presets lower-cased, hex kept, anything else becomes
+  `DEFAULT_THEME`.
+- `applyCustomTheme(element, themeVal)`: sets inline `--primary` and `--primary-foreground` on
+  the host for a valid hex string, and removes them for anything else (presets, non-strings).
+- default export: the token stylesheet (defaults, geometry switches, color schemes, presets).
+
+`css-bundle.js`:
+
+- `allStyles`: every stylesheet in cascade order, `ThemeTokens` first, `CustomStyles` last.
+- `getBundledCss({ scope })` (also the default export): `allStyles` as one string; with a scope
+  other than `:host`, rewrites `:host(X)` to `<scope>X`, `:host` to `<scope>` and `::slotted(X)` to
+  `X`. Only `scope` is read, although the JSDoc also lists `theme` and `colorScheme`.
+- `getNavCss(scope)`: `nav-styles.js` with the same rewrites, wrapped in a `<scope> { ... }` block
+  that also sets a compact `--sidebar-item-padding`, for the portal sidebar.
+- `getThemeTokensCss(theme, scope = ":root")`: the token stylesheet with `theme` / `color-scheme`
+  host rules rewritten to `[data-theme='dark'|'light'|'system']` selectors (other presets keyed by
+  `[data-theme-preset='<name>']`).
+
+Every other file default-exports one stylesheet named after what it styles (`nav-styles.js`,
+`endpoint-styles.js`, `schema-styles.js`, ...); `custom-styles.js` is an empty slot kept last.
+`flow-styles.js` styles the Arazzo diagram for `<rapi-flow>` and `@rapidoc/prerender` `getFlowCss()`; it
+uses plain class selectors (no `:host`) and is not part of `allStyles`.
+
+The custom properties themselves are not listed here: `theme-tokens.js` is the source of truth and
+`docs/src/page-data/styling-data.yaml` is the documented list (`packages/rapidoc/AGENTS.md` §5,
+rule 6).
+
+## Invariants
+
+- Every custom property RapiDoc reads is defined somewhere in `src`; public tokens are defined
+  with a default in `theme-tokens.js`. `tests/unit/css-variables.test.js` enforces this, forbids
+  the removed v11 names and requires the shadcn/ui core tokens.
+- Tokens are read as plain `var(--x)`, without a fallback. The one exception is the local
+  `--method-color` in `endpoint-styles.js`, which `.m-endpoint` and the verb classes set and which
+  is read with a fallback to `--method-default` or `--primary`.
+- Adding, renaming or removing a token also updates `docs/src/page-data/styling-data.yaml` and the
+  current migration guide.
+- Dark is the default scheme: the dark block matches `:host`, `[color-scheme='dark']`,
+  `[color-scheme='system']` and no `color-scheme`; `system` turns light only under
+  `@media (prefers-color-scheme: light)`. `DEFAULT_THEME` also applies with no `theme` attribute.
+- `--primary` and `--primary-foreground` have no `:host` default; they come from a preset rule or
+  from `applyCustomTheme`. `--ring` follows `--primary`.
+- The `:host(...)` selector shapes written by `presetCss` and the color-scheme block are exactly
+  what `getThemeTokensCss` and `getNavCss` match with regular expressions; change both together.
+  `getThemeTokensCss` rewrites only `theme` / `color-scheme` rules, so the `radius`, `scale` and
+  `nav-item-spacing` rules come out as unusable `<scope>([...])` selectors.
+- `ThemeTokens` is first in `allStyles` and in both components' `static get styles()`.
+  `CustomStyles` is last in `allStyles` and in `rapidoc.ts`; `rapidoc-mini.ts` does not load it
+  and ends with its own inline `css` block.
+- Lit templates are not reformatted by oxfmt; keep the CSS text inside `css` templates as written.
+
+## Side Effects
+
+- Each stylesheet file creates a Lit `CSSResult` at import; `theme-tokens.js` also builds the
+  preset CSS from `THEMES` once.
+- `applyCustomTheme` mutates the element's inline style. Everything else is pure; nothing touches
+  the network or disk.
+
+## Verification
+
+- `npm run test:unit` from the repo root. Suites: `tests/unit/css-variables.test.js` (defined
+  tokens, no undefined reads), `tests/unit/theme-validation.test.js` (`theme-tokens.js` helpers,
+  `nav-styles.js`), `tests/unit/static-renderer.test.js` (`getBundledCss`, `getNavCss`,
+  `getThemeTokensCss` output).
+- After editing, `npm run lint`, `npm run format-fix` and `npm run build:rapidoc`.

package/src/styles/css-bundle.js

@@ -51,7 +51,7 @@ export function getBundledCss(options = {}) {
   // If rendering in Light DOM without Shadow DOM, adapt :host selectors to the container
   if (scope && scope !== ":host") {
     combinedCss = combinedCss
-      .replace(/:host\(([^)]+)\)/g, `${scope}$1`)
+      .replace(/:host\(((?:[^()]|\([^()]*\))+)\)/g, `${scope}$1`)
       .replace(/:host\b/g, scope)
       .replace(/::slotted\(([^)]+)\)/g, `$1`);
   }
@@ -73,7 +73,7 @@ export function getNavCss(scope = "") {
         /:host\(\[color-scheme='([^']+)'\]\)/g,
         `[data-theme='$1'] ${scope}, ${scope}[color-scheme='$1']`,
       )
-      .replace(/:host\(([^)]+)\)/g, `${scope}$1`)
+      .replace(/:host\(((?:[^()]|\([^()]*\))+)\)/g, `${scope}$1`)
       .replace(/:host\b/g, scope)
       .replace(/::slotted\(([^)]+)\)/g, `$1`)
       .replace(/^\s*\.nav-bar\s*\{/gm, "&.nav-bar, & {");

package/src/styles/endpoint-styles.js

@@ -51,14 +51,18 @@ export default css`
     gap: 4px;
   }
 
+  /* a block, so it fills the callback box less its indent; width: 100% plus the margin overflowed the box */
   .callback-operation-list {
     margin-left: 16px;
-    width: 100%;
   }
 
   .callback-operation-item {
     margin-top: 12px;
   }
+  /* a callback sits in the request column, too narrow to put its request and response side by side in row layout */
+  .callback-operation-item > .expanded-req-resp-container {
+    flex-direction: column !important;
+  }
 
   .callback-operation-header {
     display: flex;
@@ -257,6 +261,7 @@ export default css`
 
   .endpoint-head .method {
     padding: 2px 5px;
+    box-sizing: border-box;
     vertical-align: middle;
     font-size: var(--font-size-small);
     height: calc(var(--font-size-small) + 16px);