rapidoc 11.0.1 → 12.1.0

package/src/templates/server-template.js

@@ -0,0 +1,153 @@
+/**
+ * Renders the API server selector dropdown and server variable configuration form.
+ */
+import { html } from "lit";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";
+import { sanitizeHTML } from "../utils/sanitize.js";
+import { marked } from "marked";
+
+export function setApiServer(serverUrl) {
+  const serverObj = this.resolvedSpec?.servers.find((s) => s.url === serverUrl);
+  if (!serverObj) {
+    return false;
+  }
+  this.selectedServer = serverObj;
+  this.requestUpdate();
+  this.dispatchEvent(
+    new CustomEvent("api-server-change", {
+      bubbles: true,
+      composed: true,
+      detail: {
+        selectedServer: serverObj,
+      },
+    }),
+  );
+  return true;
+}
+
+function onApiServerVarChange(e, serverObj) {
+  // 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");
+    tempUrl = tempUrl.replace(regex, v.value);
+  });
+  serverObj.computedUrl = tempUrl;
+  this.requestUpdate();
+}
+
+function serverVarsTemplate() {
+  // const selectedServerObj = this.resolvedSpec.servers.find((v) => (v.url === this.selectedServer));
+  return this.selectedServer && this.selectedServer.variables
+    ? html`
+        <h3 class="rapidoc-heading label-heading table-title" part="heading heading-3">Server variables</h3>
+        <div class="param-list-container">
+          <ul class="param-list server-vars" part="param-list" role="list">
+            ${Object.entries(this.selectedServer.variables).map(
+              (kv) => html`
+                <li class="param" part="param">
+                  <div class="param-label" part="param-label">
+                    <div class="param-name" part="param-name">${kv[0]}</div>
+                  </div>
+                  <div class="param-input" part="param-input">
+                    ${
+                      kv[1].enum
+                        ? html` <select
+                            data-var="${kv[0]}"
+                            @input=${(e) => {
+                              onApiServerVarChange.call(this, e, this.selectedServer);
+                            }}
+                          >
+                            ${Object.entries(kv[1].enum).map((e) =>
+                              kv[1].default === e[1]
+                                ? html`<option selected label=${e[1]} value=${e[1]}></option>`
+                                : html`<option label=${e[1]} value=${e[1]}></option>`,
+                            )}
+                          </select>`
+                        : html` <input
+                            type="text"
+                            part="textbox textbox-server-var"
+                            spellcheck="false"
+                            data-var="${kv[0]}"
+                            value="${kv[1].default}"
+                            @input=${(e) => {
+                              onApiServerVarChange.call(this, e, this.selectedServer);
+                            }}
+                          />`
+                    }
+                  </div>
+                  ${
+                    kv[1].description
+                      ? html`<div class="param-details" part="param-details">
+                          <div class="m-markdown-small">${unsafeHTML(sanitizeHTML(marked(kv[1].description)))}</div>
+                        </div>`
+                      : ""
+                  }
+                </li>
+              `,
+            )}
+          </ul>
+        </div>
+      `
+    : "";
+}
+
+export default function serverTemplate() {
+  if (!this.resolvedSpec || this.resolvedSpec.specLoadError) {
+    return "";
+  }
+  return html`<section
+    id="servers"
+    part="section-servers"
+    style="text-align:left; direction:ltr; margin-top:24px; margin-bottom:24px;"
+    class="regular-font observe-me ${"read focused".includes(this.renderStyle) ? "section-gap--read-mode" : "section-gap"}"
+  >
+    <h2 part="section-servers-title heading heading-2" class="rapidoc-heading sub-title" style="display:flex; align-items:center; gap:8px;">
+      API Server
+      ${
+        this.mockServer === "true"
+          ? html`<span
+              style="font-size:var(--font-size-small); font-weight:bold; color:var(--green); border:1px solid var(--green); border-radius:var(--radius); padding:1px 6px; letter-spacing:0.5px;"
+              title="In-browser mock server is active"
+            >
+              MOCK ACTIVE
+            </span>`
+          : ""
+      }
+    </h2>
+    <div class="mono-font" style="margin: 12px 0; font-size:calc(var(--font-size-small) + 1px);">
+      ${
+        !this.resolvedSpec.servers || this.resolvedSpec.servers?.length === 0
+          ? ""
+          : html`
+              ${this.resolvedSpec?.servers.map(
+                (server, i) => html`
+                  <div class="server-opt-row">
+                    <input
+                      type="radio"
+                      name="api_server"
+                      id="srvr-opt-${i}"
+                      value="${server.url}"
+                      @change=${() => {
+                        setApiServer.call(this, server.url);
+                      }}
+                      .checked="${this.selectedServer.url === server.url}"
+                    />
+                    <label for="srvr-opt-${i}">
+                      ${server.url} ${server.description ? html`- <span class="regular-font">${unsafeHTML(sanitizeHTML(marked.parseInline(server.description)))} </span>` : ""}
+                    </label>
+                  </div>
+                `,
+              )}
+            `
+      }
+      <div class="table-title primary-text" part="label-selected-server">
+        SELECTED: ${this.selectedServer?.computedUrl || "none"}
+        ${this.mockServer === "true" ? html`<span style="color:var(--green); margin-left:6px;">(Mocked)</span>` : ""}
+      </div>
+    </div>
+    <slot name="servers"></slot>
+    ${serverVarsTemplate.call(this)}
+  </section>`;
+}

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;
+}