rapidoc 12.0.0 → 12.1.0

package/src/templates/expanded-endpoint-template.js

@@ -171,7 +171,7 @@ export function expandedEndpointBodyTemplate(
             schema-hide-write-only="${this.schemaHideWriteOnly === "never" ? "false" : path.isWebhook ? "true" : "false"}"
             fetch-credentials="${this.fetchCredentials}"
             exportparts="section-request-title:section-request-title, heading:heading, heading-4:heading-4, heading-5:heading-5, heading-6:heading-6,
-            wrap-request-btn:wrap-request-btn, btn:btn, btn-fill:btn-fill, btn-outline:btn-outline, btn-try:btn-try, btn-clear:btn-clear, btn-clear-resp:btn-clear-resp,
+            wrap-request-btn:wrap-request-btn, btn:btn, btn-fill:btn-fill, btn-outline:btn-outline, btn-try:btn-try, btn-clear:btn-clear, btn-fill-example:btn-fill-example, btn-clear-resp:btn-clear-resp,
             tab-panel:tab-panel, tab-btn:tab-btn, tab-btn-row:tab-btn-row, tab-content:tab-content, 
             file-input:file-input, textbox:textbox, textbox-param:textbox-param, textarea:textarea, textarea-param:textarea-param, 
             anchor:anchor, anchor-param-example:anchor-param-example, anchor-param-constraint:anchor-param-constraint, param-list:param-list, param:param, param-label:param-label, param-name:param-name, param-type:param-type, param-input:param-input, param-constraint:param-constraint, param-constraint-label:param-constraint-label, param-details:param-details, param-example-list:param-example-list, value-list:value-list, value-list-label:value-list-label, value-list-items:value-list-items, schema-description:schema-description, schema-multiline-toggle:schema-multiline-toggle"
@@ -228,9 +228,13 @@ export default function expandedEndpointTemplate() {
           )}
         </div>`)}
     </section>
-    <section class="regular-font section-gap--read-mode" part="section-operations-in-tag">
-      ${tag.paths.map((path, idx) => expandedEndpointBodyTemplate.call(this, path, tag.name, tag.description, idx === 0))}
-    </section>
+    ${
+      tag.paths.length > 0
+        ? html`<section class="regular-font section-gap--read-mode" part="section-operations-in-tag">
+            ${tag.paths.map((path, idx) => expandedEndpointBodyTemplate.call(this, path, tag.name, tag.description, idx === 0))}
+          </section>`
+        : ""
+    }
   `;
 
   if (this.resolvedSpec.tagGroups && this.resolvedSpec.tagGroups.length > 0) {

package/src/templates/focused-endpoint-template.js

@@ -36,8 +36,9 @@ function defaultContentTemplate() {
   if (this.showInfo === "true") {
     return wrapFocusedTemplate(html`${overviewTemplate.call(this)}${downloadsTemplate.call(this)}`);
   }
-  const selectedTagObj = this.resolvedSpec.tags[0];
-  const selectedPathObj = this.resolvedSpec.tags[0]?.paths[0];
+  // the first tag with operations: a description-only tag (show-unused-tags) has none
+  const selectedTagObj = this.resolvedSpec.tags.find((t) => t.paths.length > 0);
+  const selectedPathObj = selectedTagObj?.paths[0];
   return selectedTagObj && selectedPathObj
     ? wrapFocusedTemplate(
         expandedEndpointBodyTemplate.call(
@@ -79,7 +80,7 @@ export default function focusedEndpointTemplate() {
   if (!this.focusedElementId && this.resolvedSpec) {
     this.focusedElementId =
       this.showInfo === "false" || this.showInfo === false
-        ? this.resolvedSpec.tags?.[0]?.paths?.[0]?.elementId || ""
+        ? this.resolvedSpec.tags?.find((t) => t.paths.length > 0)?.paths[0]?.elementId || ""
         : "overview";
   }
   if (!this.focusedElementId || !this.resolvedSpec) {

package/src/templates/navbar-template.js

@@ -7,19 +7,13 @@ import { getMatchedPaths, isInternalOrHidden } from "~/utils/common-utils";
 
 export function expandCollapseNavBarTag(navLinkEl, action = "toggle") {
   const tagAndPathEl = navLinkEl?.closest(".nav-bar-tag-and-paths");
-  const pathsUnderTagEl = tagAndPathEl?.querySelector(".nav-bar-paths-under-tag");
   if (tagAndPathEl) {
     const isExpanded = tagAndPathEl.classList.contains("expanded");
     if (isExpanded && (action === "toggle" || action === "collapse")) {
-      if (pathsUnderTagEl) pathsUnderTagEl.style.maxHeight = 0;
       tagAndPathEl.classList.replace("expanded", "collapsed");
       tagAndPathEl.querySelector(".nav-bar-tag")?.setAttribute("aria-expanded", "false");
     } else if (!isExpanded && (action === "toggle" || action === "expand")) {
       tagAndPathEl.classList.replace("collapsed", "expanded");
-      if (pathsUnderTagEl)
-        pathsUnderTagEl.style.maxHeight = pathsUnderTagEl.scrollHeight
-          ? `${pathsUnderTagEl.scrollHeight}px`
-          : null;
       tagAndPathEl.querySelector(".nav-bar-tag")?.setAttribute("aria-expanded", "true");
     }
   }
@@ -61,6 +55,10 @@ export function isNavTagVisible(tag, searchVal) {
   if (isInternalOrHidden(tag)) {
     return false;
   }
+  // A description-only tag (show-unused-tags) has no operations to match, so the filter hides it
+  if (tag.descriptionOnly) {
+    return !searchVal;
+  }
   return (tag.paths || []).some((path) => isNavPathVisible(path, searchVal, tag.name));
 }
 
@@ -91,16 +89,11 @@ export function expandCollapseAll(event, action = "expand-all") {
   const elList = [...navEl.querySelectorAll(".nav-bar-tag-and-paths")];
   if (action === "expand-all") {
     elList.forEach((el) => {
-      const navBarPathsUnderTagEl = el.querySelector(".nav-bar-paths-under-tag");
       el.classList.replace("collapsed", "expanded");
-      if (navBarPathsUnderTagEl) {
-        navBarPathsUnderTagEl.style.maxHeight = `${navBarPathsUnderTagEl?.scrollHeight}px`;
-      }
     });
   } else {
     elList.forEach((el) => {
       el.classList.replace("expanded", "collapsed");
-      // el.querySelector('.nav-bar-paths-under-tag').style.maxHeight = 0;
     });
   }
 }
@@ -338,6 +331,22 @@ export default function navbarTemplate() {
         <!-- TAGS AND PATHS (3-tier if tagGroups exist, else 2-tier) -->
         ${(() => {
           const renderNavTagItem = (tag) => {
+            // A description-only tag is a link to its section: no operations to expand or collapse
+            if (tag.descriptionOnly) {
+              if (!isNavTagVisible(tag, this.searchVal)) return "";
+              return html` <div class="nav-bar-tag-and-paths description-only">
+                <div
+                  class="nav-bar-tag"
+                  part="section-navbar-item section-navbar-tag"
+                  id="link-${tag.elementId}"
+                  data-action="navigate"
+                  data-content-id="${tag.elementId}"
+                  tabindex="0"
+                >
+                  <div class="nav-bar-tag-title">${tag.displayName || tag.name}</div>
+                </div>
+              </div>`;
+            }
             const visiblePaths = (tag.paths || []).filter((p) =>
               isNavPathVisible(p, this.searchVal, tag.name),
             );

package/src/templates/request-body-template.js

@@ -18,6 +18,7 @@ import {
   EMPTY_ARRAY,
   getMergedProperties,
   getMergedRequired,
+  exampleLabel,
 } from "~/utils/schema-utils";
 import "~/components/schema-tree";
 import "~/components/schema-table";
@@ -28,8 +29,14 @@ import {
   examplesBesideConstraints,
   renderExample,
 } from "~/templates/request-params-template";
+import { multipartPartContentType } from "~/utils/request-utils";
 
-export function formDataParamAsObjectTemplate(fieldName, fieldSchema, mimeType) {
+export function formDataParamAsObjectTemplate(
+  fieldName,
+  fieldSchema,
+  mimeType,
+  partContentType = "",
+) {
   // This template is used when form-data param should be send as a object (application/json, application/xml)
   const formdataPartSchema = schemaToAST(fieldSchema);
   const formdataPartExample = generateExample(
@@ -95,6 +102,7 @@ export function formDataParamAsObjectTemplate(fieldName, fieldSchema, mimeType)
           data-array="false"
           data-ptype="${mimeType.includes("form-urlencode") ? "form-urlencode" : "form-data"}"
           data-pname="${fieldName}"
+          data-content-type="${partContentType}"
           data-example="${formdataPartExample[0]?.exampleValue || ""}"
           .value="${live(this.fillRequestFieldsWithExample === "true" ? formdataPartExample[0]?.exampleValue || "" : "")}"
           spellcheck="false"
@@ -133,7 +141,7 @@ export function formDataParamAsObjectTemplate(fieldName, fieldSchema, mimeType)
   `;
 }
 
-export function formDataTemplate(schema, mimeType, exampleValue = "") {
+export function formDataTemplate(schema, mimeType, exampleValue = "", encoding = {}) {
   const formFieldItems = [];
   const properties = getMergedProperties(schema);
   const required = getMergedRequired(schema);
@@ -145,6 +153,10 @@ export function formDataTemplate(schema, mimeType, exampleValue = "") {
       }
       const fieldExamples = fieldSchema.examples || fieldSchema.example || "";
       const fieldType = fieldSchema.type;
+      // multipart parts are sent with this Content-Type (application/json for objects); empty means text/plain
+      const partContentType = mimeType.includes("form-data")
+        ? multipartPartContentType(fieldSchema, encoding?.[fieldName])
+        : "";
       const paramSchema = getTypeInfo(fieldSchema);
       const example = normalizeExamples(
         paramSchema.examples || paramSchema.example,
@@ -169,7 +181,7 @@ export function formDataTemplate(schema, mimeType, exampleValue = "") {
         >
           <div class="param-label" part="param-label">
             <div class="param-name ${fieldSchema.deprecated ? "deprecated" : ""}" part="param-name">
-              ${fieldName}${required.includes(fieldName) || fieldSchema.required ? html`<span class="param-required" title="Required">*</span>` : ""}
+              ${fieldName}${required.includes(fieldName) ? html`<span class="param-required" title="Required">*</span>` : ""}
             </div>
             <div class="param-type" part="param-type">
               ${
@@ -227,6 +239,7 @@ export function formDataTemplate(schema, mimeType, exampleValue = "") {
                               style="width:100%"
                               data-ptype="${mimeType.includes("form-urlencode") ? "form-urlencode" : "form-data"}"
                               data-pname="${fieldName}"
+                              data-content-type="${partContentType}"
                               data-example="${Array.isArray(fieldExamples) ? fieldExamples.join("~|~") : fieldExamples}"
                               data-array="true"
                               placeholder="add-multiple &#x21a9;"
@@ -247,6 +260,7 @@ export function formDataTemplate(schema, mimeType, exampleValue = "") {
                                 fieldName,
                                 fieldSchema,
                                 mimeType,
+                                partContentType,
                               )
                             : html`
                                 ${
@@ -259,6 +273,7 @@ export function formDataTemplate(schema, mimeType, exampleValue = "") {
                                         style="width:100%"
                                         data-ptype="${mimeType.includes("form-urlencode") ? "form-urlencode" : "form-data"}"
                                         data-pname="${fieldName}"
+                                        data-content-type="${partContentType}"
                                         data-example="${Array.isArray(fieldExamples) ? fieldExamples[0] : fieldExamples}"
                                         data-array="false"
                                       />`
@@ -379,6 +394,7 @@ export default function requestBodyTemplate() {
       schema: content[mimeType].schema,
       example: content[mimeType].example,
       examples: content[mimeType].examples,
+      encoding: content[mimeType].encoding,
     });
     // Fallback guard: If selectedRequestBodyType was cleared (e.g., after focused-mode navigation),
     // automatically latch onto the first available MIME type (e.g., application/json).
@@ -436,11 +452,16 @@ export default function requestBodyTemplate() {
               reqBodyExamples.length === 1
                 ? ""
                 : html`
-                    <select class="select-sm example-select" aria-label="request body examples" @change="${(e) => this.onSelectExample(e)}">
+                    <select
+                      class="select-sm example-select"
+                      aria-label="request body examples"
+                      title="${exampleLabel(reqBodyExamples.find((v) => v.exampleId === this.selectedRequestBodyExample))}"
+                      @change="${(e) => this.onSelectExample(e)}"
+                    >
                       ${reqBodyExamples.map(
                         (v) =>
-                          html`<option value="${v.exampleId}" ?selected=${v.exampleId === this.selectedRequestBodyExample}>
-                            ${v.exampleSummary.length > 80 ? v.exampleId : v.exampleSummary ? v.exampleSummary : v.exampleId}
+                          html`<option value="${v.exampleId}" title="${exampleLabel(v)}" ?selected=${v.exampleId === this.selectedRequestBodyExample}>
+                            ${exampleLabel(v)}
                           </option>`,
                       )}
                     </select>
@@ -454,7 +475,7 @@ export default function requestBodyTemplate() {
                     class="example ${v.exampleId === this.selectedRequestBodyExample ? "example-selected" : ""}"
                     data-example="${v.exampleId}"
                   >
-                    ${v.exampleSummary && v.exampleSummary.length > 80 ? html`<div style="padding: 4px 0">${v.exampleSummary}</div>` : ""}
+                    ${reqBodyExamples.length === 1 && v.exampleSummary && v.exampleSummary.length > 80 ? html`<div style="padding: 4px 0">${v.exampleSummary}</div>` : ""}
                     ${
                       v.exampleDescription
                         ? html`<div class="m-markdown-small" style="padding: 4px 0">
@@ -524,6 +545,7 @@ ${v.exampleFormat === "text" ? v.exampleValue : JSON.stringify(v.exampleValue, n
             reqBody.schema,
             reqBody.mimeType,
             ex[0] ? ex[0].exampleValue : "",
+            reqBody.encoding,
           );
         }
       }

package/src/templates/request-params-template.js

@@ -148,6 +148,12 @@ export function exampleListTemplate(paramName, paramType, exampleList = []) {
   }`;
 }
 
+// A singular `example` is the value itself, even an object; only an `examples` map wraps its values in { value }
+const singleExample = (ex) =>
+  ex !== null && typeof ex === "object" && !Array.isArray(ex)
+    ? { Example: { value: ex } }
+    : standardizeExample(ex);
+
 export function inputParametersTemplate(paramType) {
   const filteredParams = this.parameters
     ? this.parameters.filter((param) => param.in === paramType)
@@ -196,8 +202,8 @@ export function inputParametersTemplate(paramType) {
     // openapi 3.1.0 spec based examples (which must be Object(string : { value:any, summary?: string, description?: string})
     const example = normalizeExamples(
       standardizeExample(param.examples) ||
-        standardizeExample(param.example) ||
-        standardizeExample(mimeTypeElem?.example) ||
+        singleExample(param.example) ||
+        singleExample(mimeTypeElem?.example) ||
         standardizeExample(mimeTypeElem?.examples) ||
         standardizeExample(paramSchema.examples) ||
         standardizeExample(paramSchema.example),
@@ -263,6 +269,7 @@ export function inputParametersTemplate(paramType) {
                         style="width:100%"
                         data-ptype="${paramType}"
                         data-pname="${param.name}"
+                        data-item-type="${declaredParamSchema.items?.type || ""}"
                         data-example="${Array.isArray(example.exampleVal) ? example.exampleVal.join("~|~") : example.exampleVal}"
                         data-param-serialize-style="${paramStyle}"
                         data-param-serialize-explode="${paramExplode}"
@@ -337,7 +344,11 @@ export function inputParametersTemplate(paramType) {
                               part="textarea textarea-param"
                               data-ptype="${paramType}-object"
                               data-pname="${param.name}"
-                              data-example="${example.exampleVal}"
+                              data-example="${
+                                typeof example.exampleVal === "object"
+                                  ? JSON.stringify(example.exampleVal, null, 2)
+                                  : example.exampleVal
+                              }"
                               data-param-serialize-style="${paramStyle}"
                               data-param-serialize-explode="${paramExplode}"
                               data-param-allow-reserved="${paramAllowReserved}"
@@ -380,7 +391,7 @@ export function inputParametersTemplate(paramType) {
                               allow-schema-description-expand-toggle="${this.allowSchemaDescriptionExpandToggle}"
                               schema-hide-read-only="${this.schemaHideReadOnly.includes(this.method)}"
                               schema-hide-write-only="${this.schemaHideWriteOnly.includes(this.method)}"
-                              exportparts="wrap-request-btn:wrap-request-btn, btn:btn, btn-fill:btn-fill, btn-outline:btn-outline, btn-try:btn-try, btn-clear:btn-clear, btn-clear-resp:btn-clear-resp,
+                              exportparts="wrap-request-btn:wrap-request-btn, btn:btn, btn-fill:btn-fill, btn-outline:btn-outline, btn-try:btn-try, btn-clear:btn-clear, btn-fill-example:btn-fill-example, btn-clear-resp:btn-clear-resp,
                           file-input:file-input, textbox:textbox, textbox-param:textbox-param, textarea:textarea, textarea-param:textarea-param, 
                           anchor:anchor, anchor-param-example:anchor-param-example"
                             >

package/src/templates/security-scheme-template.js

@@ -119,6 +119,9 @@ export function onClearAllApiKeys() {
     v.finalKeyValue = "";
     v.hostNote = "";
   });
+  if (this.persistAuth === "true") {
+    setPersistedApiKeys.call(this, {});
+  }
   this.requestUpdate();
 }
 
@@ -133,7 +136,7 @@ function setPersistedApiKeys(obj) {
 export function recoverPersistedApiKeys() {
   const rapidocLs = getPersistedApiKeys.call(this);
   Object.values(rapidocLs).forEach((p) => {
-    applyApiKey.call(this, p.securitySchemeId, p.username, p.password, p.value);
+    applyApiKey.call(this, p.securitySchemeId, "", "", p.value);
   });
 }
 
@@ -159,8 +162,14 @@ function onApiKeyChange(securitySchemeId) {
         applyApiKey.call(this, securitySchemeId, "", "", apiKeyValue);
       }
       if (this.persistAuth === "true") {
+        // Only what recoverPersistedApiKeys restores: the apiKey / bearer value. Basic credentials
+        // (and the derived Authorization header) are never written to localStorage.
         const rapidocLs = getPersistedApiKeys.call(this);
-        rapidocLs[securitySchemeId] = securityObj;
+        if (securityObj.value) {
+          rapidocLs[securitySchemeId] = { securitySchemeId, value: securityObj.value };
+        } else {
+          delete rapidocLs[securitySchemeId];
+        }
         setPersistedApiKeys.call(this, rapidocLs);
       }
     }

package/src/templates/server-template.js

@@ -26,7 +26,8 @@ export function setApiServer(serverUrl) {
 }
 
 function onApiServerVarChange(e, serverObj) {
-  const inputEls = [...e.currentTarget.closest("table").querySelectorAll("input, select")];
+  // The variables render as a list, <ul class="server-vars">
+  const inputEls = [...e.currentTarget.closest(".server-vars").querySelectorAll("input, select")];
   let tempUrl = serverObj.url;
   inputEls.forEach((v) => {
     const regex = new RegExp(`{${v.dataset.var}}`, "g");
@@ -134,7 +135,7 @@ export default function serverTemplate() {
                       .checked="${this.selectedServer.url === server.url}"
                     />
                     <label for="srvr-opt-${i}">
-                      ${server.url} ${server.description ? html`- <span class="regular-font">${server.description} </span>` : ""}
+                      ${server.url} ${server.description ? html`- <span class="regular-font">${unsafeHTML(sanitizeHTML(marked.parseInline(server.description)))} </span>` : ""}
                     </label>
                   </div>
                 `,

package/src/utils/README.md

@@ -0,0 +1,146 @@
+# RapiDoc Utilities
+
+## Overview
+
+Framework-free helpers behind the `<rapi-doc>` component (`src/rapidoc.ts`), its templates and
+the static renderer (`@rapidoc/prerender`, `packages/rapidoc-prerender`). `utils/` owns the spec pipeline (load,
+dereference, group, anchor), schema rendering and example generation, request/response/mock
+helpers, and UI helpers (highlighting, Markdown, sanitizing, navbar binding, color, OAuth). It
+does not own rendering (`templates/`, `components/`) or styles. The MCP manifest, runtime and
+project writer are documented in [`./mcp/README.md`](./mcp/README.md); Arazzo parsing and workflow diagrams in
+[`./arazzo/README.md`](./arazzo/README.md).
+
+Everything except `arazzo/` is bundled into `dist/rapidoc-min.js`; `arazzo/` goes into
+`dist/rapidoc-flow-min.js` and `@rapidoc/prerender`. `@rapidoc/portal` depends on this folder
+indirectly through `@rapidoc/prerender` (`methodPathSlug`, `operationAnchorSource`, `toKebabCase`)
+and the anchors `<rapi-doc>` emits, so anchor generation is public behavior.
+Several modules run in Node (static renderer, unit tests) and must guard `window`/`document`.
+
+## Interface
+
+Spec pipeline:
+
+- `spec-parser.js`: default `ProcessSpec` (spec URL, text or object to the render model of
+  tags, tag groups, components, security schemes, servers); `isTagExpanded`, `groupByTagGroups`.
+- `slugger.js`: `OperationSlugger` (`slug`, `slugOp`, `slugTag`, `slugTagGroup`, `reset`),
+  `operationAnchorSource`, `methodPathSlug`, `toKebabCase`, `clampWordBoundary`, `createSlugger`.
+- `common-utils.js`: search (`advancedSearch`, `getMatchedPaths`), `debounce`, `sleep`,
+  clipboard and download helpers, `rapidocApiKey`.
+
+Schema rendering:
+
+- `schema-utils.js`: `getTypeInfo`, `schemaToAST` (schema tree for renderers),
+  `schemaInObjectNotation` (older tree format), `schemaToSampleObj` and `generateExample`
+  (examples), `json2xml`, `getMergedProperties`/`getMergedRequired`.
+
+Request, response, mock:
+
+- `url-utils.js`: path/query serialization, `constructFetchURL`, `oauthReceiverUrl`.
+- `request-utils.js`: headers, url-encoded and multipart bodies.
+- `response-utils.js`: `processFetchResponse` (decode a `Response`),
+  `prepareResponseDefinitions`.
+- `curl-utils.js`: `generateCurlCommand`.
+- `mock-interceptor.js`: `enableMockServer`, `disableMockServer`, `updateMockConfig`,
+  `isMockServerActive`, `compileRoutes` (from a `ProcessSpec` result).
+
+UI helpers:
+
+- `highlighter.js`: `highlightAllCode`, `scheduleHighlight` (CSS Custom Highlight API).
+- `markdown-utils.js`: `configureMarkdown` and token helpers for the global `marked`.
+- `sanitize.js`: `sanitizeHTML`.
+- `bind-navbar.js`: `bindNavBar` ties a static `getNavBarHtml` sidebar to `<rapi-doc>`.
+- `auto-color-scheme.js`: `AutoColorSchemeController`, `resolvePageColorScheme`.
+- `oauth-utils.js`: PKCE (`randomUrlSafe`, `pkceChallenge`), `readOAuthReply`,
+  `isExpectedOAuthReply`.
+- `color-utils.js`, `xml-utils.js` (`formatXml`): pure helpers.
+- `mcp-generator.js`: `generateMcpServer(spec, options) -> { manifest, files, budget, hostConfig }`,
+  re-exporting `./mcp` (`buildMcpManifest`, `createMcpRuntime`, `writeMcpProject`, `createZip`,
+  `parseMcpEnabled`, ...).
+
+## Invariants
+
+- **`ProcessSpec` never rejects** (`[spec-parser.js:ProcessSpec]`). Loading and post-load
+  processing are each wrapped in `try/catch`. Every failure resolves to
+  `{ specLoadError: true, isSpecLoading: false, info: { title, description, version }, tags: [],
+  tagGroups: [] }`, where `description` is `"<url> ┃ Not Found (404)"`,
+  `"Unable to load <url> ┃ <status|message>"`, `"Invalid Spec Definition"`, or
+  `"Unable to process the spec ┃ <message>"` for failures after loading. Callers check
+  `specLoadError`, not exceptions. It uses an optional `this` (`requestUpdate`,
+  `before-render` event), so the component calls it with `.call(element, ...)`.
+- **Webhooks** (`[spec-parser.js:groupByTags]`) are grouped after paths and flagged
+  `isWebhook`; they are never written into the spec's `paths`, so a webhook named like a path
+  does not replace it.
+- **Stable anchors** (`[slugger.js:operationAnchorSource]`, `[slugger.js:OperationSlugger.slug]`):
+  - Source priority: `operationId` (trimmed, 1-45 chars, not a placeholder like `operation12`),
+    then `summary` (the parser passes `summary || description`; clamped to 40 chars at a word
+    boundary), then `methodPathSlug(method, path)`.
+  - Memoized per method + path (and tag slug), so one operation keeps one `elementId` per run.
+  - Tag prefix `<tagSlug>--` is applied only when the spec has non-empty `x-tagGroups` or
+    `x-tag-groups` (`[spec-parser.js:ProcessSpec]`), and never for the tag `general`.
+  - Collisions try `<prefix><method>-<slug>` first, then `github-slugger`'s `-1`, `-2` suffixes,
+    which depend on encounter order (paths, then webhooks; methods in `supportedMethods` order).
+  - Tag and tag-group ids (`tag--<kebab>`, `tag-group--<kebab>`) are not deduplicated.
+  - The portal links to these ids and checks them with `operationAnchorSource`/`methodPathSlug`;
+    changing any rule above is a breaking change for published portals.
+- **Circular references** (`[spec-parser.js:breakCircularRefs]`): after dereferencing, the tree
+  is cloned without `x-ref` keys and each cycle becomes `{ $ref }` (fallback
+  `#/components/schemas/Circular`); shared non-cyclic nodes stay shared. Schema code treats a
+  remaining `$ref` as the cycle marker, so renderers must not recurse into it.
+- **Schema depth limits** (`[schema-utils.js]`): `schemaToSampleObj` returns `undefined` and
+  `schemaInObjectNotation` returns a `::type` stub when `level > 8`. `schemaToAST` expands to
+  `MAX_SCHEMA_DEPTH` (8) and, while the tree exceeds `SCHEMA_NODE_BUDGET` (8000 nodes), retries
+  with a smaller depth down to `MIN_SCHEMA_DEPTH` (4); cut containers become nodes with
+  `truncated: true`. Its module state makes it synchronous and non-reentrant.
+- **Sanitization** (`[sanitize.js:sanitizeHTML]`): non-strings return `""`. The native
+  `Sanitizer` path allows all attributes; the fallback removes only `<script>`, `on*` attributes
+  and `javascript:` / `data:text/html` in `href`/`src`. Without `DOMParser` (Node) the input is
+  returned unchanged, so server-side output is not sanitized.
+- **Mock server** (`[mock-interceptor.js:enableMockServer]`): one mock per `options.owner` (the
+  element; omitted, a page-wide default), so several `<rapi-doc>` / `<rapi-doc-mini>` on a page
+  mock their own APIs with their own status codes, delay and cycle positions. Repeated calls for an
+  owner refresh its routes and config but never stack wrappers; `disableMockServer(owner)` drops
+  that mock and restores the originals once none is left. A request is answered by the most
+  specific match across the mocks (server origin and base path, then base path, then bare path;
+  ties to the mock enabled first); unmatched requests fall through to the real `fetch`/XHR. Mock
+  responses carry `X-Mock-Server: RapiDoc`.
+- **Highlighter** (`[highlighter.js]`): `highlightAllCode` and `scheduleHighlight` are no-ops
+  without `window` and `CSS.highlights`; highlighting never mutates the DOM.
+- **Headless boundary**: `spec-parser.js`, `schema-utils.js`, `slugger.js`, `mcp-generator.js`,
+  `mcp/`, `arazzo/` and everything they import are shared with the Node builds (`@rapidoc/prerender`,
+  `@rapidoc/mcp`). They never import Lit, elements, `components/`, `templates/`, `styles/` or
+  `static/`, and use only the third-party packages allowed in `tests/unit/headless-boundary.test.js`.
+  DOM calls inside functions are allowed (Node never calls them); DOM access at import time is not.
+
+## Side Effects
+
+- `ProcessSpec` fetches the spec and external `$ref`s, logs load errors with `console.info`, and
+  mutates the spec it processes: `x-ref` during dereference, `paths` replaced by `filterPaths`,
+  `callbacks` filtered, relative `servers[*].url` prefixed with `location.origin`,
+  `computedUrl` added.
+- `mock-interceptor.js` replaces `window.fetch` and `XMLHttpRequest.prototype` methods while
+  active and keeps routes and config in module state.
+- `markdown-utils.js` configures the global `marked` at import time.
+- `highlighter.js` writes the global `CSS.highlights` registry and schedules
+  `requestAnimationFrame`.
+- `bind-navbar.js` adds DOM and `window` listeners, writes `history`; some timers and the
+  `spec-loaded` listener outlive `unbind()`.
+- `auto-color-scheme.js` observes `<html>`/`<body>` attributes and `prefers-color-scheme`.
+- `response-utils.js` creates object URLs it does not revoke; `common-utils.js` clipboard and
+  download helpers create temporary elements.
+
+## Verification
+
+Run `npm run test:unit` from the repo root before and after changing `spec-parser.js` or
+`schema-utils.js`, then `npm run lint` and `npm run format-fix`. Files in `tests/unit/`:
+
+- `spec-parser.js`: `spec-parser-relative-url`, `spec-parser-security`,
+  `spec-parser-tag-groups`, `spec-parser-webhooks`, `unused-tags`, `openapi-3-2-bookstore`.
+- `slugger.js`: `slugger`.
+- `schema-utils.js`: `schema-utils`, `schema-ast`, `schema-in-object-notation`,
+  `schema-nullable`, `schema-modernization`, `multipart-form-curl`.
+- `url-utils.js`: `query-param-serialization`, `oauth-receiver-url`.
+- `request-utils.js`, `curl-utils.js`: `request-utils`, `multipart-part-types`, `curl-command`.
+- `response-utils.js`: `api-request-response`.
+- `mock-interceptor.js`, `oauth-utils.js`, `markdown-utils.js`, `mcp-generator.js`: the
+  test file of the same name.
+- Headless boundary (imports of the modules above, transitively): `headless-boundary`.

package/src/utils/arazzo/README.md

@@ -0,0 +1,119 @@
+# Arazzo Workflow Diagrams
+
+## Overview
+
+Reads Arazzo 1.x documents and draws one workflow as an SVG string: the workflow's inputs and
+outputs, its steps in order, the values passed between steps, and each step's success and failure
+actions. The inputs box (each input's type, required flag, default and enum values; a string enum's type
+reads `enum`, as `<rapi-doc>` labels it) and the
+outputs table are the same in both views, which differ in the step boxes: `expanded` (the
+default) lists each step's values with a keyword for where they come from (`input`, `step`,
+`fixed`, `expr`), its checks (the success criteria, unnumbered), its actions as "condition →
+what happens" under "On success · first match runs" / "On failure · first match runs", and the
+outputs something reads; `compact` shows each step's name, method, path and number of checks,
+with labelled value lines and no actions. Used by `<rapi-flow>` (`src/rapi-flow.ts`, bundled as `dist/rapidoc-flow-min.js`) and by
+the build-time renderer (`@rapidoc/prerender`: `renderArazzoWorkflow`, `getFlowCss`).
+
+Not owned here: running workflows (nothing here makes a request), the element's loading and
+events (`src/rapi-flow.ts`), and the diagram's look (`src/styles/flow-styles.js`). `dist/rapidoc-min.js`
+imports only the YAML-free modules `components.js`, `operations.js` and `refs.js`, through
+`utils/mcp/workflows.js`, which compiles workflows into the MCP manifest; `parse.js` (the `yaml`
+package) stays out of it.
+
+## Interface
+
+- `parseDocument(input)` [parse.js]: JSON or YAML text to an object; an object passes through.
+  Throws on empty input or a non-object.
+- `validateArazzo(doc) -> { level, path, message }[]` [parse.js]: structural checks the diagram
+  relies on; an empty list means valid.
+- `resolveComponentRef(doc, obj, kind)` [components.js, re-exported by parse.js]: `{ reference: "$components.<kind>.<name>" }`
+  to the component, or null.
+- `collectRefs(value)` [refs.js]: `$inputs`, `$steps` and `$workflows` expressions anywhere in a
+  JSON value, distinct, in first-seen order.
+- `indexOperations(openapi)`, `indexResolvedSpec(resolvedSpec)` (the same index from
+  `<rapi-doc>`'s processed `tags[].paths[]`, webhooks skipped, the first entry kept for an
+  operation with several tags), `resolveOperation(step, sources)` [operations.js]: operation lookup
+  by operationId (plain or `$sourceDescriptions.<name>.` qualified) and by `operationPath`.
+- `buildFlowGraph(doc, workflowId?, { sources })` [graph.js]: the graph the SVG draws; null when
+  the workflow does not exist.
+- `renderFlowDiagram(graph, { view, idPrefix, interactive }) -> { svg, legend }` [svg.js]:
+  `legend` names the kinds of lines drawn (`seq`, `data`, `output`, `success`, `failure`);
+  `renderFlowSvg` returns only the SVG. `actionLabel` (short: "✗ retry 3× after 2s (if)"),
+  `actionSentence` (with criteria), `describeAction(action, checks, index)` (`{ when, does, name, tag }`, the
+  wording of the expanded boxes; an action without criteria reads "checks
+  fail" / "check fails" / "request fails" by the step's number of checks, or "otherwise" after
+  other actions) and `escapeXml` are exported too.
+- `renderArazzoWorkflow(arazzo, options)` [index.js]: parse, validate, index `options.sources`,
+  build and draw in one call; returns `{ svg, legend, graph, problems, workflowIds }`.
+
+## Invariants
+
+- **No DOM, no network.** Text widths are estimated from character counts, so output is the same
+  in Node and the browser and long labels are cut with `…` rather than measured.
+- **OpenAPI is not dereferenced.** Only `paths.<path>.<method>.operationId` and `summary` are read,
+  so an operation reached through a path-item `$ref` is not found.
+- **Validation is structural.** It checks required fields, duplicate ids, exactly one of
+  `operationId` / `operationPath` / `workflowId` per step, action types (retry only on failure),
+  goto and `dependsOn` targets, and `$steps.<id>` references. It does not check expression syntax,
+  `inputs` JSON Schema, or criteria.
+- **Edges.** A data edge goes from a step to a later step (or to the outputs box) whenever a
+  `$steps.<id>.outputs.<name>` expression appears in the later step's `parameters` or
+  `requestBody` (or a workflow output). References to the same or an earlier step are not drawn.
+  Edges into the outputs box are drawn gray, the others in the primary color. Compact: edges from
+  one step with the same labels share a lane and arrive at the middle of the target step; edges
+  into the outputs box carry no label and arrive at the step's group, as in expanded. Expanded: one lane per source step, starting at each of its Outputs rows
+  that is read and branching to each line (a step binding, or the step's group heading in the
+  outputs box) that reads one; no labels, since the lines name the value.
+- **Step outputs.** Each step's `usedOutputs` are its outputs that a later step or the workflow
+  reads. Expanded boxes end with an Outputs section listing them, the source shortened
+  (`$response.body#/status` reads `response body /status`, the full expression a tooltip), and
+  "+N unused" for the rest.
+- **Outputs box.** A table in both views: the output names in one flat column (the workflow's
+  result is a flat object), and on the right, under "From step", the step each group comes from,
+  once per group, with a rule between groups. Groups follow the order each step first appears;
+  outputs not taken from a step come last, their source kind (`input`, `fixed`, `expr`) in the
+  step column. A step output whose name differs from the workflow output's follows as
+  `← <name>`. A step's line arrives at its group's first row, beside the step name.
+- **Step names** (box titles, the step in `step` value lines, the From step column) share one
+  color, `--primary` mixed toward the text color so it passes 4.5:1 on light cards; variable
+  names keep the text color.
+- **Linking.** Step boxes carry `data-step-id`; output rows and value lines carry
+  `data-from-step`, so a caller can highlight a step with everything it feeds (`<rapi-flow>` does
+  on hover, with the `rf-linked` class). With `interactive`, those rows are also `rf-jump` links
+  (the outputs box's step names focusable, `role="link"`) for a caller to scroll to the step.
+- **Actions.** A step's actions are its own `onSuccess` / `onFailure`, then the workflow's
+  `successActions` / `failureActions` (marked `inherited`) minus any the step overrides by `name`.
+  The graph also lists the workflow's actions once as `workflowActions`. Compact shows no
+  actions; expanded lists a step's own actions and the inherited ones in one list per outcome, in merge order, each with its name in parentheses after
+  what it does; inherited ones also carry a `workflow` tag on the right. A runner takes the first action whose criteria match, so every action after
+  one without criteria is marked `shadowed` (it never runs). Shadowed actions are left out of the
+  boxes and draw no goto line; the graph's `warnings` (`{ level, path,
+  message }`, one per step and outcome) name them, for author tooling;
+  `<rapi-flow>` does not show them. Only `goto` with a `stepId` in the same workflow draws a line, from its action line
+  (expanded) or the box's left edge (compact); `end`, `retry` and goto to a workflow draw none.
+- **Details.** The graph carries more than the boxes show, for callers that render their own
+  documentation: `inputDetails` (type,
+  format, required, default, enum, description, from `inputs` or a `$ref` to
+  `#/components/inputs/<name>`), each step's `parameters` (component references resolved, their
+  `value` overriding), `requestBody`, `criteria` and `outputExprs`, and each output's `expr`.
+  Each step's `bindings` are the values it sends: parameters by name and request body fields as
+  `body.<path>` (objects flattened, arrays kept whole), each with a `source` (`input`, `step`,
+  `expression` or `value`) and the steps it reads (`fromSteps`). Expanded boxes show at most ten.
+  Input descriptions and step descriptions are tooltips (`<title>`) on their lines and boxes.
+- **Next-step arrows.** A step falls through to the next one unless it has a success action of type
+  `end` or `goto` without `criteria`; then no arrow is drawn into the next step, which is reached
+  only through goto lines. The last step always gets an arrow into the outputs box.
+- **Ids.** Marker ids are `<idPrefix>-<name>`; pages with several diagrams pass distinct prefixes.
+  Steps carry `data-step-id`; with `interactive`, steps whose operation or workflow is known get
+  `tabindex="0" role="button"` and the `rf-clickable` class.
+
+## Side Effects
+
+- None. `parseDocument` uses the `yaml` package, which is why `dist/rapidoc-flow-min.js` carries it.
+
+## Verification
+
+- `npm run test:unit` from the repo root; `tests/unit/arazzo-flow.test.js` covers parsing,
+  validation, lookup, the graph and the SVG, using `docs/public/specs/petstore.arazzo.yaml`.
+- The docs page `/examples/arazzo-flow` shows `<rapi-flow>` tied to a `<rapi-doc>`.
+- After editing, `npm run lint` and `npm run format-fix`.

package/src/utils/arazzo/components.js

@@ -0,0 +1,15 @@
+/**
+ * Arazzo reusable components. Kept apart from parse.js so the MCP manifest builder can compile
+ * workflows inside dist/rapidoc-min.js without pulling in the YAML parser.
+ */
+
+/**
+ * Resolves `{ reference: "$components.<kind>.<name>" }` against the document's components.
+ */
+export function resolveComponentRef(doc, obj, kind) {
+  if (!obj || typeof obj.reference !== "string") return obj;
+  const m = obj.reference.match(/^\$components\.([A-Za-z]+)\.([A-Za-z0-9_.-]+)$/);
+  if (!m || m[1] !== kind) return null;
+  const target = doc?.components?.[kind]?.[m[2]];
+  return target ? { ...target, ...(obj.value !== undefined ? { value: obj.value } : {}) } : null;
+}