@dogsbay/format-openapi 0.2.0-beta.13 → 0.2.0-beta.131

package/dist/core.js

@@ -0,0 +1,1224 @@
+/**
+ * The OpenAPI conversion with no file or network access, and no Node
+ * built-ins: it runs in a Cloudflare Worker (dogsbay-ssg) as well as in
+ * the CLI. A spec comes in as text (or an already-parsed object) and goes
+ * out as `endpoint` TreeNodes; finding and reading the file is the
+ * caller's (parse.ts for the CLI, a build's file map for dogsbay-ssg).
+ *
+ *   text ─ parseSpecText ─▶ object ─ prepareSpec ─▶ spec ─┬ embedSpec    (one page's body)
+ *                                                         └ specToPages  (a page per operation)
+ *
+ * `prepareSpec` is the expensive step (upgrade, dereference); `createSpecCache`
+ * runs it once per spec file per build. `findSpec` holds the rules for which
+ * file a page's `:::openapi{spec}` may name.
+ */
+import { dereference, upgrade } from "@scalar/openapi-parser";
+import MarkdownIt from "markdown-it";
+import { operationToSlug, slugifyTag } from "./slug.js";
+import { resolveCodeSamples } from "./code-samples.js";
+export { findSpec, specCandidates } from "./spec-path.js";
+const HTTP_METHODS = [
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete",
+    "head",
+    "options",
+];
+/**
+ * A dereferenced spec (`prepareSpec`) as a page per operation, a page per tag
+ * and an info page, with their nav: for a spec that IS the source.
+ */
+export function specToPages(spec, options = {}) {
+    const hrefPrefix = normalisePrefix(options.hrefPrefix);
+    const operations = collectOperations(spec);
+    const { groups, ungrouped } = groupOperations(spec, operations);
+    const slugs = pageSlugs(groups, operations, options.reservedSlugs);
+    const labels = operationLabels(operations, groups);
+    const pages = [];
+    const summaries = new Map();
+    const groupOf = new Map();
+    for (const g of groups)
+        for (const op of g.ops)
+            groupOf.set(op, g);
+    for (const op of operations) {
+        const { method, path, operation, props } = op;
+        const group = groupOf.get(op);
+        const opSlug = slugs.operations.get(op);
+        const slug = group ? `${slugs.groups.get(group)}/${opSlug}` : opSlug;
+        const { title, navLabel, summary } = labels.get(op);
+        pages.push({
+            slug,
+            title,
+            tree: [{ type: "endpoint", props: structuredClone(props) }],
+            headings: [{ depth: 1, slug: opSlug, text: title }],
+        });
+        summaries.set(op, { slug, title, navLabel, summary, method, path, deprecated: operation.deprecated === true });
+    }
+    // A page per group (a tag, or one resource of a very large tag).
+    for (const g of groups) {
+        pages.push(buildTagPage(g.label, slugs.groups.get(g), g.description, g.ops.map((op) => summaries.get(op))));
+    }
+    // Root info page.
+    const info = spec.info || {};
+    pages.push(buildInfoPage(txt(info.title) || "API Reference", txt(info.description) ?? "", txt(info.version) ?? (typeof info.version === "number" ? String(info.version) : "")));
+    // Nav: the groups in order, each with its operations; ungrouped
+    // operations under a synthetic "Other" group.
+    const nav = [{ label: txt(info.title) || "API Reference", href: hrefHref(hrefPrefix, "index") }];
+    const entries = (ops) => ops
+        .map((op) => summaries.get(op))
+        .sort(byPathThenMethod)
+        .map((op) => ({ label: op.navLabel, href: hrefHref(hrefPrefix, op.slug) }));
+    for (const g of groups) {
+        nav.push({ label: g.label, href: hrefHref(hrefPrefix, slugs.groups.get(g)), children: entries(g.ops) });
+    }
+    if (ungrouped.length > 0)
+        nav.push({ label: "Other", children: entries(ungrouped) });
+    return { pages, nav };
+}
+/**
+ * Operations per group, in nav order: one group per tag (the spec's declared
+ * order, then first use), holding the operations whose FIRST tag it is.
+ *
+ * A tag holding more than LARGE_TAG operations across several resources is
+ * split into a group per resource instead. Generated specs often put
+ * everything under one tag (drf-yasg: all 610 operations of the AAP
+ * controller API under `api`), and a flat list of 610 is unusable; Swagger UI
+ * and Redoc readers navigate by resource. The resource is the first path
+ * segment after the tag's common prefix that is not a version or a parameter:
+ * `/api/v2/projects/{id}/` → `projects`, groups in alphabetical order.
+ * Operations with no resource (`/api/`) go in a "Root" group.
+ */
+const LARGE_TAG = 50;
+function groupOperations(spec, operations) {
+    const descriptions = new Map();
+    const order = [];
+    for (const t of spec.tags || []) {
+        const name = txt(t?.name);
+        if (!name || descriptions.has(name))
+            continue;
+        descriptions.set(name, txt(t.description) ?? "");
+        order.push(name);
+    }
+    const byTag = new Map();
+    const ungrouped = [];
+    for (const op of operations) {
+        const tag = op.props.tags?.[0];
+        if (!tag) {
+            ungrouped.push(op);
+            continue;
+        }
+        if (!byTag.has(tag))
+            byTag.set(tag, []);
+        byTag.get(tag).push(op);
+        if (!order.includes(tag))
+            order.push(tag);
+    }
+    const groups = [];
+    const splits = new Map();
+    for (const tag of order) {
+        const ops = byTag.get(tag);
+        const split = ops && ops.length > LARGE_TAG ? byResource(ops) : undefined;
+        if (split)
+            splits.set(tag, split);
+    }
+    for (const tag of order) {
+        const ops = byTag.get(tag);
+        if (!ops)
+            continue;
+        const split = splits.get(tag);
+        if (!split) {
+            groups.push({ label: tag, slugBase: slugifyTag(tag) || "tag", description: descriptions.get(tag) ?? "", ops, kind: "tag" });
+            continue;
+        }
+        // Operations of the tag with no resource (`GET /api/`, `/api/v2/`) are
+        // the API's root paths: "Root", or "api: Root" when several tags split.
+        // The tag's own name read as one more resource ("api" beside the spec's
+        // title page).
+        if (split.none.length) {
+            // A hand-written `Root` tag or a `root` resource would read the same.
+            const clash = [...byTag.keys()].some((t) => t !== tag && t.toLowerCase() === "root") || split.groups.has("root");
+            const label = splits.size > 1 || clash ? `${tag}: Root` : "Root";
+            groups.push({ label, slugBase: "root", description: descriptions.get(tag) ?? "", ops: split.none, kind: "tag", pathLabels: true });
+        }
+        // Alphabetical: a resource list is looked up by name, and spec order put
+        // `/api/debug/` before every `/api/v2/` resource. Code-unit order, not
+        // the build machine's locale.
+        const resources = [...split.groups].sort(([a], [b]) => {
+            const x = humanize(a).toLowerCase();
+            const y = humanize(b).toLowerCase();
+            return x < y ? -1 : x > y ? 1 : 0;
+        });
+        for (const [resource, members] of resources) {
+            // Say which tag a resource belongs to when its name alone is
+            // ambiguous: two split tags may both have `projects`, and a
+            // hand-written `users` tag may sit beside a `users` resource.
+            const plain = humanize(resource);
+            const clash = [...byTag.keys()].some((t) => t !== tag && t.toLowerCase() === plain.toLowerCase());
+            const label = splits.size > 1 || clash ? `${tag}: ${plain}` : plain;
+            groups.push({ label, slugBase: slugifyTag(resource) || "resource", description: "", ops: members, shortPaths: split.shortPaths, kind: "resource" });
+        }
+    }
+    // Ungrouped operations in spec order.
+    const index = new Map(operations.map((op, i) => [op, i]));
+    ungrouped.sort((a, b) => index.get(a) - index.get(b));
+    return { groups, ungrouped };
+}
+const isParam = (seg) => seg.startsWith("{");
+const isVersion = (seg) => /^v\d+(?:[._-]\d+)*$/i.test(seg);
+/** Share of a large tag's operations that must have a resource for the tag to split. */
+const SPLIT_COVERAGE = 0.9;
+/**
+ * A large tag's operations by resource, or undefined when it does not
+ * divide that way: fewer than two resources, or fewer than 90% of the
+ * operations with one (tenant-style `/{tenant}/…` paths, or one resource's
+ * sub-actions under `/projects/{id}/…`, keep the tag whole).
+ *
+ * The prefix is the run of literal segments that 90% of the paths share, so
+ * one stray `/healthz` does not empty it; versions after it are skipped.
+ */
+function byResource(ops) {
+    const segs = ops.map((op) => op.path.split("/").filter(Boolean));
+    const need = Math.ceil(ops.length * SPLIT_COVERAGE);
+    const prefix = [];
+    const under = (s) => prefix.every((p, i) => s[i] === p);
+    for (;;) {
+        const d = prefix.length;
+        const counts = new Map();
+        for (const s of segs)
+            if (s.length > d + 1 && under(s))
+                counts.set(s[d], (counts.get(s[d]) ?? 0) + 1);
+        const top = [...counts].sort((a, b) => b[1] - a[1])[0];
+        // Extend while one literal segment is shared by nearly all the paths
+        // that go deeper than it.
+        if (!top || top[1] < need || isParam(top[0]))
+            break;
+        prefix.push(top[0]);
+    }
+    const groups = new Map();
+    const none = [];
+    const shortPaths = new Map();
+    const versions = new Map();
+    ops.forEach((op, k) => {
+        const s = segs[k];
+        let i = prefix.length;
+        while (i < s.length && isVersion(s[i]))
+            i++;
+        const resource = under(s) && i < s.length && !isParam(s[i]) ? s[i] : undefined;
+        if (!resource)
+            return void none.push(op);
+        if (!groups.has(resource))
+            groups.set(resource, []);
+        groups.get(resource).push(op);
+        versions.set(op, s.slice(prefix.length, i).join("/"));
+        shortPaths.set(op, "/" + s.slice(i).join("/") + (op.path.endsWith("/") ? "/" : ""));
+    });
+    if (groups.size < 2 || ops.length - none.length < need)
+        return undefined;
+    // A group spanning versions (`/api/v1/users/`, `/api/v2/users/`) keeps
+    // them in its nav labels, or both read `GET /users/`.
+    for (const members of groups.values()) {
+        if (new Set(members.map((op) => versions.get(op))).size < 2)
+            continue;
+        for (const op of members) {
+            const s = op.path.split("/").filter(Boolean);
+            shortPaths.set(op, "/" + s.slice(prefix.length).join("/") + (op.path.endsWith("/") ? "/" : ""));
+        }
+    }
+    return { groups, none, shortPaths };
+}
+/** A path segment as a label: `job_templates` → "Job Templates". */
+function humanize(segment) {
+    return segment
+        .split(/[_-]+/)
+        .filter(Boolean)
+        .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(" ") || segment;
+}
+/**
+ * Each operation's page title and nav label: its summary when no other
+ * operation has the same one, otherwise its method and path. Generated specs
+ * copy one summary to every method of a path (drf-yasg: 151 summaries for 610
+ * operations, so DELETE read "Make GET request to this resource…"), and a nav
+ * of identical labels cannot be read. In a resource group every nav label is
+ * the method and the path after the prefix the group already says
+ * (`PATCH /projects/{id}/`).
+ */
+function operationLabels(operations, groups) {
+    // A generator's placeholder is no summary: "No Description for get on /api/v2/…" (drf-yasg's exact form).
+    // The spec's own summary decides. One joined to the rest of its sentence
+    // (summaryAndDescription) is a docstring sentence, not a title: the shared
+    // "…retrieve the list of" becomes unique once joined, and would title every
+    // drf-yasg list page with a whole sentence.
+    const summaryOf = (op) => {
+        const s = txt(op.operation.summary)?.trim();
+        return s && !/^no description for \w+ on \//i.test(s) ? s : undefined;
+    };
+    // Counted over every operation, joined or not: two operations sharing
+    // "Retrieve the list of" share it whichever of them was joined.
+    const count = new Map();
+    for (const op of operations) {
+        const s = summaryOf(op);
+        if (s)
+            count.set(s, (count.get(s) ?? 0) + 1);
+    }
+    const joined = (op) => op.props.summary?.trim() !== summaryOf(op);
+    const shortPath = new Map();
+    for (const g of groups)
+        for (const op of g.ops) {
+            if (g.shortPaths?.has(op))
+                shortPath.set(op, g.shortPaths.get(op));
+            // The Root group sits among resource groups: the same `METHOD path` form (#104)
+            else if (g.pathLabels)
+                shortPath.set(op, op.path);
+        }
+    const out = new Map();
+    for (const op of operations) {
+        const s = summaryOf(op);
+        const method = op.method.toUpperCase();
+        const unique = s && count.get(s) === 1 && !joined(op) ? s : undefined;
+        // A resource group (a split, generated tag) lists method and path for
+        // every entry, as Swagger UI does: mixing in the few unique summaries
+        // made a column of near-identical prose ("Make GET request to this…").
+        const short = shortPath.get(op);
+        out.set(op, {
+            summary: unique,
+            title: unique ?? `${method} ${op.path}`,
+            navLabel: short !== undefined ? `${method} ${short}` : unique ?? `${method} ${op.path}`,
+        });
+    }
+    return out;
+}
+/**
+ * Every page's URL, distinct. The root page is `index`, a group's overview is
+ * `<group>`, a grouped operation `<group>/<operation>` and an ungrouped one
+ * `<operation>`, where `<operation>` comes from the operationId, or else the
+ * method and path. Slugs that would land on a URL already taken (`getPet` and
+ * `get_pet`; an operationId `index`; an ungrouped operation named like a
+ * group; two groups that slugify alike) are made distinct: an operation falls
+ * back to its method and path, then a numeric suffix, in spec order, so the
+ * first claimant keeps the plain slug. Before, the later page silently
+ * replaced the earlier one.
+ */
+function pageSlugs(groups, operations, reserved = []) {
+    const rootTaken = new Set(["index", ...reserved.map((r) => r.toLowerCase())]);
+    const groupSlugs = new Map();
+    const folderOf = new Map();
+    // Tags before resources: a resource of a large tag must not take the URL
+    // a hand-written tag has (`users` stays at /users when the large `api`
+    // tag also has a users resource, which becomes /users-2).
+    for (const kind of ["tag", "resource"]) {
+        for (const g of groups)
+            if (g.kind === kind)
+                groupSlugs.set(g, claim(g.slugBase, rootTaken));
+    }
+    for (const g of groups) {
+        const folder = new Set(["index"]);
+        for (const op of g.ops)
+            folderOf.set(op, folder);
+    }
+    const taken = (op) => folderOf.get(op) ?? rootTaken;
+    // Two passes: every operation's own slug first, so a fallback never takes
+    // the slug a LATER operation would have had (moving a URL that had no
+    // collision); then the operations that lost theirs.
+    const out = new Map();
+    for (const op of operations) {
+        const preferred = operationToSlug(op.method, op.path, txt(op.operation.operationId));
+        const set = taken(op);
+        if (preferred && !set.has(preferred)) {
+            set.add(preferred);
+            out.set(op, preferred);
+        }
+    }
+    for (const op of operations) {
+        if (out.has(op))
+            continue;
+        // Letters, digits and dashes only: a path's `:`, `?` or `%2F` must not
+        // reach a URL this function invents.
+        const fallback = operationToSlug(op.method, op.path).replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || op.method;
+        out.set(op, claim(fallback, taken(op)));
+    }
+    return { groups: groupSlugs, operations: out };
+}
+/** `base`, or `base-2`, `base-3`… : the first not in `used`, which it joins. */
+function claim(base, used) {
+    let slug = base;
+    for (let n = 2; used.has(slug); n++)
+        slug = `${base}-${n}`;
+    used.add(slug);
+    return slug;
+}
+/**
+ * Spec text → object. JSON is read natively; YAML needs a parser passed in
+ * (`yaml`'s `parse`, js-yaml's `load`), so a host that has one does not
+ * bundle a second.
+ */
+export function parseSpecText(text, parseYaml) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (err) {
+        if (!parseYaml)
+            throw new Error(`not JSON, and no YAML parser was given (${err.message})`);
+        return parseYaml(text);
+    }
+}
+/**
+ * A parsed spec → the dereferenced OpenAPI 3 document every function here
+ * reads. Swagger 2.0 is upgraded to OpenAPI 3 first: everything below reads
+ * the 3.x shape (`requestBody`, response `content`, `servers`), so a 2.0
+ * spec parsed without the upgrade lost every body parameter and response
+ * schema while still producing plausible-looking pages. Canonical's Anbox
+ * Cloud API specs are 2.0.
+ */
+export async function prepareSpec(parsed, label = "the spec") {
+    if (!parsed || typeof parsed !== "object")
+        throw new Error(`${label} is not an OpenAPI document`);
+    let doc = acyclic(parsed, label);
+    if (typeof doc.swagger === "string" && doc.swagger.startsWith("2")) {
+        // The upgrade moves a 2.0 parameter's type into `schema` but drops its
+        // `default` (`page: 1` vanished); carry it across. `doc` is acyclic's
+        // copy, so marking it does not touch the caller's object.
+        inlineSharedParams(doc);
+        swagger2Params(doc, (p) => {
+            if (p.in !== "body" && p.default !== undefined)
+                p[KEPT_DEFAULT] = p.default;
+        });
+        doc = upgrade(doc).specification;
+        swagger2ResponseExamples(doc);
+        swagger2Params(doc, (p) => {
+            if (!(KEPT_DEFAULT in p))
+                return;
+            if (p.schema && typeof p.schema === "object" && p.schema.default === undefined)
+                p.schema.default = p[KEPT_DEFAULT];
+            else if (!p.schema && p.default === undefined)
+                p.default = p[KEPT_DEFAULT];
+            delete p[KEPT_DEFAULT];
+        });
+    }
+    const { schema: spec } = await dereference(doc);
+    if (!spec)
+        throw new Error(`Failed to dereference OpenAPI spec at ${label}`);
+    return spec;
+}
+const KEPT_DEFAULT = "x-dogsbay-default";
+/**
+ * A 2.0 document's `{ $ref: "#/parameters/X" }` entries replaced by copies of
+ * the shared parameter. The upgrade writes an empty `schema: {}` beside such a
+ * reference and leaves `#/parameters` where it was, so every shared
+ * parameter came out with type "any" (and no default).
+ */
+function inlineSharedParams(doc) {
+    const shared = doc.parameters && typeof doc.parameters === "object" ? doc.parameters : undefined;
+    if (!shared)
+        return;
+    const resolve = (list) => Array.isArray(list)
+        ? list.map((p) => {
+            const m = typeof p?.$ref === "string" ? /^#\/parameters\/(.+)$/.exec(p.$ref) : null;
+            let name;
+            try {
+                name = m ? decodeURIComponent(m[1]).replace(/~1/g, "/").replace(/~0/g, "~") : undefined;
+            }
+            catch {
+                name = undefined; // a malformed `%`: leave the ref for the dereferencer to report
+            }
+            return name !== undefined && Object.hasOwn(shared, name) && shared[name] && typeof shared[name] === "object" ? { ...shared[name] } : p;
+        })
+        : list;
+    for (const item of Object.values(doc.paths ?? {})) {
+        if (!item || typeof item !== "object")
+            continue;
+        if (item.parameters)
+            item.parameters = resolve(item.parameters);
+        for (const m of HTTP_METHODS)
+            if (item[m]?.parameters)
+                item[m].parameters = resolve(item[m].parameters);
+    }
+}
+/**
+ * A 2.0 response's `examples` (media type → value) onto the upgraded
+ * response's `content[type].example`. The upgrade leaves them on the
+ * response, where 3.x has no such field, so the drf-yasg spec's 176 response
+ * examples were replaced by generated ones.
+ */
+function swagger2ResponseExamples(doc) {
+    const fix = (r) => {
+        if (!r || typeof r !== "object" || !r.examples || typeof r.examples !== "object" || Array.isArray(r.examples))
+            return;
+        const content = r.content && typeof r.content === "object" ? r.content : undefined;
+        for (const [type, value] of Object.entries(r.examples)) {
+            let media = content?.[type] ?? (/json/i.test(type) ? content?.["application/json"] : undefined);
+            // No schema, so the upgrade wrote no content: the example is all there is.
+            if (!media && !content)
+                media = (r.content ??= {})[type] = {};
+            if (media && typeof media === "object" && media.example === undefined)
+                media.example = value;
+        }
+        delete r.examples;
+    };
+    const responses = (map) => {
+        if (map && typeof map === "object")
+            for (const r of Object.values(map))
+                fix(r);
+    };
+    responses(doc.responses);
+    responses(doc.components?.responses);
+    for (const item of Object.values(doc.paths ?? {})) {
+        if (!item || typeof item !== "object")
+            continue;
+        for (const m of HTTP_METHODS)
+            responses(item[m]?.responses);
+    }
+}
+/** Every parameter object of a 2.0 document, before or after its upgrade (shared ones too). */
+function swagger2Params(doc, f) {
+    const each = (list) => {
+        if (Array.isArray(list))
+            for (const p of list)
+                if (p && typeof p === "object")
+                    f(p);
+    };
+    for (const shared of [doc.parameters, doc.components?.parameters]) {
+        if (shared && typeof shared === "object")
+            each(Object.values(shared));
+    }
+    for (const item of Object.values(doc.paths ?? {})) {
+        if (!item || typeof item !== "object")
+            continue;
+        each(item.parameters);
+        for (const m of HTTP_METHODS)
+            each(item[m]?.parameters);
+    }
+}
+/** The most a parsed document may expand to, in characters, counting every alias at each place it is used. */
+const SPEC_MAX_EXPANDED_CHARS = 64_000_000;
+/**
+ * A parsed document with no cycles, and no larger than SPEC_MAX_EXPANDED_CHARS
+ * once its aliases are expanded.
+ *
+ * YAML aliases make the parsed value a graph. `&a {self: *a}` is an object
+ * that contains itself, which sent the dereferencer into unbounded
+ * recursion (a stack overflow, not an error). A value reached again while
+ * it is still being copied (a cycle) becomes "(circular)"; one reached
+ * again after (an alias used twice) is shared, as the parser shared it, so
+ * the copy is linear.
+ *
+ * Sharing is not enough: the dereferencer and every renderer walk each path
+ * through the graph, so `l2: {l: *l1, r: *l1}` doubles per level (a 724-byte
+ * spec took 6.8 s to dereference at depth 22, and a `summary` aliased the
+ * same way made a 147 MB page). So the copy also counts the expanded size
+ * (memoized per node, so counting is linear too) and refuses a document past
+ * the bound, as the `yaml` parser does with its alias limit. js-yaml, which
+ * dogsbay-ssg parses with, has no such limit. JSON never has either problem.
+ */
+function acyclic(root, label) {
+    const done = new Map();
+    const open = new Set();
+    const add = (a, b) => Math.min(SPEC_MAX_EXPANDED_CHARS + 1, a + b);
+    const copy = (v, depth) => {
+        if (typeof v === "string")
+            return { out: v, size: v.length + 2 };
+        if (!v || typeof v !== "object" || v instanceof Date)
+            return { out: v, size: 8 };
+        const finished = done.get(v);
+        if (finished)
+            return finished;
+        if (open.has(v))
+            return { out: "(circular)", size: 12 };
+        if (depth > 1_000)
+            throw new Error(`${label} is nested more than 1,000 levels deep`);
+        open.add(v);
+        let size = 2;
+        let out;
+        if (Array.isArray(v)) {
+            out = v.map((e) => {
+                const c = copy(e, depth + 1);
+                size = add(size, c.size + 1);
+                return c.out;
+            });
+        }
+        else {
+            out = {};
+            for (const [k, e] of Object.entries(v)) {
+                const c = copy(e, depth + 1);
+                size = add(size, c.size + k.length + 4);
+                out[k] = c.out;
+            }
+        }
+        open.delete(v);
+        const r = { out, size };
+        done.set(v, r);
+        return r;
+    };
+    const r = copy(root, 0);
+    if (r.size > SPEC_MAX_EXPANDED_CHARS) {
+        throw new Error(`${label} expands to more than ${SPEC_MAX_EXPANDED_CHARS.toLocaleString("en")} characters through repeated YAML aliases`);
+    }
+    return r.out;
+}
+/**
+ * Prepared specs by path, each parsed and dereferenced once however many
+ * pages embed it. `read` returns the file's text; failures are cached too,
+ * so a broken spec is reported per page without being parsed again.
+ */
+export function createSpecCache(read, parseYaml) {
+    const specs = new Map();
+    return {
+        get(path) {
+            let p = specs.get(path);
+            if (!p) {
+                p = Promise.resolve()
+                    .then(() => read(path))
+                    .then((text) => prepareSpec(parseSpecText(text, parseYaml), path));
+                specs.set(path, p);
+            }
+            return p;
+        },
+        get size() {
+            return specs.size;
+        },
+    };
+}
+/** A spec field read as text: a YAML alias can put any value where a string belongs. */
+const txt = (v) => (typeof v === "string" ? v : undefined);
+// ─── Values copied from the spec ─────────────────────────────────────
+/**
+ * Bounds on the spec values an operation's props carry verbatim: examples,
+ * defaults and enums. A YAML anchor repeated through aliases is ONE object
+ * in the parsed spec and a full copy in every place a renderer serializes
+ * it: a 300-byte spec grew to a 33 MB page and 720 MB of memory in
+ * dogsbay-ssg, and an example that refers to itself crashed the build
+ * (JSON.stringify on a cycle). Values are copied here, so props are plain,
+ * acyclic and bounded, and every renderer is protected.
+ */
+const VALUE_MAX_CHARS = 4_000; // one default, enum entry or property example
+const EXAMPLE_MAX_CHARS = 50_000; // a request or response example
+const ENUM_MAX_VALUES = 200;
+const OPERATION_MAX_CHARS = 500_000; // everything copied for one operation
+const VALUE_MAX_DEPTH = 32;
+/** What a value over its bound is shown as. */
+export const VALUE_TOO_LARGE = "(not shown: too large)";
+/** The budget of the operation being collected (collectOperations is synchronous). */
+let operationBudget = OPERATION_MAX_CHARS;
+class TooLarge extends Error {
+}
+/**
+ * A plain JSON copy of a spec value within `max` serialized characters (and
+ * the operation's remaining budget), or VALUE_TOO_LARGE. A reference back
+ * to an enclosing value becomes "(circular)". Counting stops at the bound,
+ * so an exponentially aliased value costs no more than the bound to refuse.
+ */
+function copyValue(v, max = VALUE_MAX_CHARS) {
+    if (v === undefined)
+        return undefined;
+    const limit = Math.min(max, operationBudget);
+    let left = limit;
+    const ancestors = new Set();
+    const spend = (n) => {
+        if ((left -= n) < 0)
+            throw new TooLarge();
+    };
+    const copy = (x, depth) => {
+        if (x === null || x === undefined)
+            return spend(4), null;
+        if (typeof x === "string")
+            return spend(x.length + 2), x;
+        if (typeof x === "number" || typeof x === "boolean")
+            return spend(String(x).length), x;
+        if (x instanceof Date)
+            return spend(26), Number.isNaN(x.getTime()) ? String(x) : x.toISOString();
+        if (typeof x !== "object")
+            return spend(String(x).length + 2), String(x);
+        if (ancestors.has(x))
+            return spend(10), "(circular)";
+        if (depth >= VALUE_MAX_DEPTH)
+            throw new TooLarge();
+        ancestors.add(x);
+        try {
+            if (Array.isArray(x))
+                return spend(2), x.map((e) => (spend(1), copy(e, depth + 1)));
+            const out = {};
+            spend(2);
+            for (const [k, e] of Object.entries(x)) {
+                spend(k.length + 4);
+                out[k] = copy(e, depth + 1);
+            }
+            return out;
+        }
+        finally {
+            ancestors.delete(x);
+        }
+    };
+    try {
+        const out = copy(v, 0);
+        operationBudget -= limit - left;
+        return out;
+    }
+    catch (err) {
+        if (!(err instanceof TooLarge))
+            throw err;
+        operationBudget -= Math.min(operationBudget, VALUE_TOO_LARGE.length);
+        return VALUE_TOO_LARGE;
+    }
+}
+/** An enum's values, each copied with copyValue, at most ENUM_MAX_VALUES; a cut list ends in "…". */
+function copyEnum(list) {
+    if (!Array.isArray(list))
+        return undefined;
+    const out = [];
+    for (const v of list) {
+        if (out.length >= ENUM_MAX_VALUES || operationBudget <= 0)
+            return [...out, "…"];
+        out.push(copyValue(v));
+    }
+    return out;
+}
+/**
+ * The first server's URL, without a trailing slash: operation paths start
+ * with one. A Swagger 2.0 `basePath: /` upgrades to a server `/`, and joining
+ * it gave `//api/v2/…` in the URL bar and every code sample.
+ */
+function serverUrl(spec) {
+    return (txt(spec.servers?.[0]?.url) ?? "").replace(/\/+$/, "");
+}
+/** Every operation in the spec, in document order, as `endpoint` props. */
+function collectOperations(spec) {
+    const out = [];
+    const baseUrl = serverUrl(spec);
+    for (const [path, pathItem] of Object.entries(spec.paths || {})) {
+        if (!pathItem)
+            continue;
+        for (const method of HTTP_METHODS) {
+            const op = buildOperation(path, pathItem, method, baseUrl);
+            if (op)
+                out.push(op);
+        }
+    }
+    return out;
+}
+/** One operation as `endpoint` props, or undefined when the path item has none for `method`. */
+function buildOperation(path, pathItem, method, baseUrl) {
+    const operation = pathItem?.[method];
+    if (!operation)
+        return undefined;
+    operationBudget = OPERATION_MAX_CHARS;
+    const opTags = Array.isArray(operation.tags) ? operation.tags.filter((t) => typeof t === "string") : [];
+    const { summary, description } = summaryAndDescription(txt(operation.summary), txt(operation.description));
+    const props = {
+        method,
+        path,
+        baseUrl,
+        summary,
+        description,
+        operationId: txt(operation.operationId) || undefined,
+        tags: opTags.length > 0 ? opTags : undefined,
+        deprecated: operation.deprecated === true ? true : undefined,
+        parameters: extractParameters(operation, pathItem),
+        ...extractRequestBody(operation),
+        responses: extractResponses(operation),
+        codeSamples: resolveCodeSamples(operation, method, path, baseUrl),
+    };
+    return { method, path, operation, props };
+}
+/** Shortest summary read as a wrapped first line (drf-yasg's in AAP: 57-84 characters). */
+const SUMMARY_WRAP_MIN = 40;
+/**
+ * The summary and description, with a sentence the generator broke in two
+ * put back together. drf-yasg makes the summary from a docstring's first
+ * LINE and the description from the rest, so a sentence that wraps reads
+ * "…retrieve the list of" + a paragraph "activity streams.". A summary with
+ * no closing punctuation, followed by a description that starts in lower
+ * case, takes the description's first paragraph when that ends the
+ * sentence and the summary is long enough to be a wrapped line. Only plain text is moved:
+ * the summary is shown as text, so Markdown in the continuation would show
+ * its syntax.
+ */
+export function summaryAndDescription(summary, description) {
+    const s = summary?.trim();
+    // Blank lines only: an indented first line is a code block, not prose.
+    const d = description?.replace(/^(?:[ \t]*\r?\n)+/, "");
+    // A wrapped docstring line is long; a hand-written "Get user" is not, and
+    // "returns the user." after it is a description, not its continuation.
+    if (s && d && s.length >= SUMMARY_WRAP_MIN && !/[.!?:;)\]"'`]$/.test(s) && /^\p{Ll}/u.test(d)) {
+        const end = d.search(/\n\s*\n/);
+        const first = (end < 0 ? d : d.slice(0, end)).replace(/\s+/g, " ").trim();
+        // The continuation must finish the sentence. An underscore inside a word
+        // (`job_template`) is not emphasis.
+        if (/[.!?:]$/.test(first) && !/[`*[\]<>\\#|~]|(?<!\w)_|_(?!\w)/.test(first)) {
+            const rest = end < 0 ? "" : d.slice(end).trim();
+            return { summary: `${s} ${first}`, description: rest || undefined };
+        }
+    }
+    return { summary: summary || undefined, description: description || undefined };
+}
+/**
+ * The operation a `:::openapi` directive selects from its props, or why it
+ * cannot: `path` and `method` come together or not at all.
+ */
+export function directiveOperation(props) {
+    const path = typeof props?.path === "string" ? props.path.trim() : "";
+    const method = typeof props?.method === "string" ? props.method.trim().toLowerCase() : "";
+    if (!path && !method)
+        return {};
+    if (!path || !method)
+        return { error: "`path` and `method` select an operation together; give both or neither" };
+    if (!HTTP_METHODS.includes(method))
+        return { error: `not an HTTP method: ${method}` };
+    return { operation: { path, method } };
+}
+/**
+ * A whole spec as the BODY of one page: what Swagger UI or Redoc show when a
+ * page embeds them. The info version and description, then a section per tag
+ * (declared order, then first use; untagged operations last, under "Other"),
+ * each holding its operations as `endpoint` nodes in document order.
+ *
+ * `spec` is a dereferenced spec (`prepareSpec`), and is not modified: the
+ * nodes are copies, so one parsed spec serves every page that embeds it.
+ *
+ * `specToPages` is the other shape — a page per operation — for a spec
+ * that IS the source. This one is for a spec a prose page points at.
+ */
+export function embedSpec(spec, options = {}) {
+    if (options.operation) {
+        const { path, method } = options.operation;
+        // Only this operation is built: building them all to keep one made a page per operation
+        // quadratic in the spec (400 pages over a 400-operation spec: 4 s, in dogsbay-ssg).
+        const m = method.toLowerCase();
+        const paths = spec.paths && typeof spec.paths === "object" ? spec.paths : {};
+        const op = HTTP_METHODS.includes(m) && Object.hasOwn(paths, path) ? buildOperation(path, paths[path], m, serverUrl(spec)) : undefined;
+        if (!op)
+            throw new Error(`the spec has no operation ${method.toUpperCase()} ${path}`);
+        return { tree: [{ type: "endpoint", props: structuredClone(op.props) }], headings: [], operations: 1 };
+    }
+    const level = Math.min(6, Math.max(2, options.level ?? 2));
+    const tree = [];
+    const headings = [];
+    const used = new Set(options.usedIds ?? []);
+    // A description's own headings go under the section that holds it, with
+    // ids, and into the outline (a `# Title` was a second H1).
+    const describe = (text, minLevel) => {
+        const d = descriptionHtml(text, minLevel, used);
+        headings.push(...d.headings);
+        tree.push({ type: "prose", html: d.html });
+    };
+    const info = spec.info || {};
+    if (txt(info.version) || typeof info.version === "number") {
+        tree.push(versionLine(String(info.version)));
+    }
+    if (typeof info.description === "string" && info.description.trim()) {
+        describe(info.description, level);
+    }
+    // The same groups as a page per operation (specToPages): tags, very large
+    // ones split by resource, ungrouped operations last under "Other".
+    const operations = collectOperations(spec);
+    const { groups, ungrouped } = groupOperations(spec, operations);
+    const sections = [...groups, ...(ungrouped.length ? [{ label: "Other", description: "", ops: ungrouped }] : [])];
+    for (const { label, description, ops } of sections) {
+        const id = uniqueId(slugifyTag(label) || "section", used);
+        tree.push({
+            type: "heading",
+            props: { level, id },
+            inline: [{ type: "text", text: label }],
+        });
+        headings.push({ depth: level, slug: id, text: label });
+        if (description)
+            describe(description, level + 1);
+        // A copy: enum, default and example values are the spec's own objects, and the spec is shared.
+        for (const op of ops)
+            tree.push({ type: "endpoint", props: structuredClone(op.props) });
+    }
+    return { tree, headings, operations: operations.length };
+}
+function uniqueId(base, used) {
+    let id = base;
+    for (let n = 2; used.has(id); n++)
+        id = `${base}-${n}`;
+    used.add(id);
+    return id;
+}
+/**
+ * A description (CommonMark) → HTML with its headings shifted so the
+ * highest is `minLevel`, each given a unique id, and listed for the TOC.
+ * Raw HTML stays off (see `md`).
+ */
+function descriptionHtml(text, minLevel, used) {
+    const tokens = md.parse(text, {});
+    const levels = tokens.filter((t) => t.type === "heading_open").map((t) => Number(t.tag.slice(1)));
+    const headings = [];
+    if (levels.length) {
+        const shift = Math.max(0, minLevel - Math.min(...levels));
+        for (let i = 0; i < tokens.length; i++) {
+            const t = tokens[i];
+            if (t.type !== "heading_open")
+                continue;
+            const depth = Math.min(6, Number(t.tag.slice(1)) + shift);
+            const inline = tokens[i + 1];
+            const label = (inline?.children ?? [])
+                .filter((c) => c.type === "text" || c.type === "code_inline")
+                .map((c) => c.content)
+                .join("")
+                .trim();
+            const id = uniqueId(slugifyTag(label) || "section", used);
+            t.tag = `h${depth}`;
+            t.attrSet("id", id);
+            if (tokens[i + 2]?.type === "heading_close")
+                tokens[i + 2].tag = `h${depth}`;
+            headings.push({ depth, slug: id, text: label });
+        }
+    }
+    return { html: md.renderer.render(tokens, md.options, {}).trim(), headings };
+}
+function normalisePrefix(p) {
+    if (!p)
+        return "";
+    return p.replace(/\/+$/, "");
+}
+/** The one non-null type of a schema: OpenAPI 3.1 (and an upgraded 2.0
+ *  spec) writes a nullable object as `type: [object, "null"]`. */
+function primaryType(schema) {
+    if (!schema)
+        return undefined;
+    if (!Array.isArray(schema.type))
+        return schema.type;
+    const types = schema.type.filter((t) => t !== "null");
+    return types.length === 1 ? types[0] : undefined;
+}
+function schemaToType(schema, depth = 0) {
+    if (!schema)
+        return "any";
+    // An array of itself (a cycle once dereferenced) has no finite name.
+    if (depth > SCHEMA_MAX_DEPTH)
+        return "any";
+    // OpenAPI 3.1 (and a Swagger 2.0 spec upgraded to it) writes nullable as
+    // a type list: `type: [string, "null"]`.
+    if (Array.isArray(schema.type)) {
+        const types = schema.type.filter((t) => t !== "null");
+        if (types.length === 1)
+            return schemaToType({ ...schema, type: types[0] }, depth + 1);
+        return types.length ? types.join(" | ") : "null";
+    }
+    if (schema.type === "array") {
+        const itemType = schema.items ? schemaToType(schema.items, depth + 1) : "any";
+        return `${itemType}[]`;
+    }
+    return schema.type || "any";
+}
+/**
+ * Bounds on walking one schema. A dereferenced spec is a GRAPH: a
+ * self-referencing schema is a cycle (the walk overflowed the stack), and
+ * eight properties that each reference the level below grow 8× per level
+ * (a 2.2 KB spec made 18 MB of tree at depth 6). Past a bound the walk stops
+ * and the property shows without children.
+ */
+const SCHEMA_MAX_DEPTH = 10;
+const SCHEMA_MAX_NODES = 2000;
+const newWalk = () => ({ nodes: SCHEMA_MAX_NODES, depth: 0, ancestors: new Set() });
+/** Run `f` one level into `schema`, or return `empty` past a bound. */
+function descend(walk, schema, empty, f) {
+    if (!schema || typeof schema !== "object")
+        return f();
+    if (walk.depth >= SCHEMA_MAX_DEPTH || walk.nodes <= 0 || walk.ancestors.has(schema))
+        return empty;
+    walk.depth++;
+    walk.ancestors.add(schema);
+    try {
+        return f();
+    }
+    finally {
+        walk.depth--;
+        walk.ancestors.delete(schema);
+    }
+}
+function extractSchemaProperties(schema, requiredFields, walk = newWalk()) {
+    if (!schema?.properties)
+        return [];
+    return descend(walk, schema, [], () => propertiesOf(schema, requiredFields, walk));
+}
+function propertiesOf(schema, requiredFields, walk) {
+    const required = requiredFields || schema.required || [];
+    const out = [];
+    for (const [name, prop] of Object.entries(schema.properties)) {
+        if (walk.nodes-- <= 0)
+            break;
+        out.push(propertyOf(name, prop ?? {}, required, walk));
+    }
+    return out;
+}
+function propertyOf(name, prop, required, walk) {
+    const result = {
+        name,
+        type: schemaToType(prop),
+        required: required.includes(name),
+    };
+    if (txt(prop.description))
+        result.description = prop.description;
+    if (prop.nullable)
+        result.nullable = true;
+    if (txt(prop.format))
+        result.format = prop.format;
+    if (prop.enum)
+        result.enum = copyEnum(prop.enum);
+    if (prop.default !== undefined)
+        result.default = copyValue(prop.default);
+    const example = schemaExample(prop);
+    if (example !== undefined)
+        result.example = copyValue(example);
+    if (primaryType(prop) === "object" && prop.properties) {
+        result.properties = extractSchemaProperties(prop, undefined, walk);
+    }
+    if (primaryType(prop) === "array" && prop.items) {
+        if (primaryType(prop.items) === "object" && prop.items.properties) {
+            result.items = extractSchemaProperties(prop.items, undefined, walk);
+        }
+    }
+    return result;
+}
+function extractParameters(operation, pathItem) {
+    const params = [];
+    const allParams = [
+        ...(pathItem.parameters || []),
+        ...(operation.parameters || []),
+    ];
+    // Operation-level wins over path-level on (name, in) collision.
+    const seen = new Map();
+    for (const p of allParams) {
+        if (!txt(p?.name) || !txt(p?.in))
+            continue;
+        seen.set(`${p.name}:${p.in}`, p);
+    }
+    for (const p of seen.values()) {
+        // A Swagger 2.0 parameter keeps its type on itself, not in `schema`; the
+        // upgrade to 3.1 leaves PATH-ITEM-level parameters that way (drf-yasg's
+        // `{version}`/`{id}` showed type "any" where Swagger UI says "string").
+        const schema = p.schema ?? (txt(p.type) ? { type: p.type, format: p.format, enum: p.enum, default: p.default, items: p.items } : undefined);
+        const param = {
+            name: p.name,
+            in: p.in,
+            type: schemaToType(schema),
+            required: p.required || false,
+        };
+        if (txt(p.description))
+            param.description = p.description;
+        if (schema?.default !== undefined) {
+            const d = copyValue(schema.default);
+            param.default = typeof d === "string" ? d : JSON.stringify(d);
+        }
+        if (schema?.enum)
+            param.enum = copyEnum(schema.enum);
+        if (p.deprecated)
+            param.deprecated = true;
+        params.push(param);
+    }
+    return params;
+}
+function extractRequestBody(operation) {
+    const body = operation.requestBody;
+    if (!body?.content)
+        return {};
+    const contentType = body.content["application/json"] ? "application/json" : Object.keys(body.content)[0];
+    const mediaType = body.content[contentType];
+    if (!mediaType?.schema)
+        return {};
+    return {
+        requestBody: extractSchemaProperties(mediaType.schema),
+        requestBodyExample: copyValue(mediaExample(mediaType, contentType) ?? generateExampleFromSchema(mediaType.schema), EXAMPLE_MAX_CHARS),
+    };
+}
+function extractResponses(operation) {
+    if (!operation.responses)
+        return [];
+    return Object.entries(operation.responses)
+        .filter(([status]) => status !== "default")
+        .map(([status, resp]) => {
+        const result = {
+            status,
+            description: txt(resp.description),
+        };
+        if (resp.content) {
+            const contentTypeKey = resp.content["application/json"]
+                ? "application/json"
+                : Object.keys(resp.content)[0];
+            const mediaType = resp.content[contentTypeKey];
+            if (contentTypeKey)
+                result.contentType = contentTypeKey;
+            if (mediaType?.schema) {
+                const rawSchema = mediaType.schema;
+                const schema = primaryType(rawSchema) === "array" && rawSchema.items
+                    ? rawSchema.items
+                    : rawSchema;
+                result.schema = extractSchemaProperties(schema);
+                result.example = copyValue(mediaExample(mediaType, contentTypeKey) ?? generateExampleFromSchema(rawSchema), EXAMPLE_MAX_CHARS);
+            }
+            else {
+                // An example with no schema (drf-yasg's `GET /api/v2/` lists its resources this way).
+                const own = mediaExample(mediaType, contentTypeKey);
+                if (own !== undefined)
+                    result.example = copyValue(own, EXAMPLE_MAX_CHARS);
+            }
+        }
+        return result;
+    })
+        .sort((a, b) => a.status.localeCompare(b.status));
+}
+function generateExampleFromSchema(schema, walk = newWalk()) {
+    if (!schema)
+        return undefined;
+    if (walk.nodes-- <= 0)
+        return null;
+    return descend(walk, schema, null, () => exampleOf(schema, walk));
+}
+/**
+ * A schema's own example. OpenAPI 3.0 writes `example: x`; 3.1 (JSON Schema)
+ * writes `examples: [x]`, and prepareSpec upgrades every spec to 3.1, so a
+ * Swagger 2.0 or 3.0 example arrives in the second form. Reading only the
+ * first put `null` where drf-yasg's request body examples were.
+ */
+function schemaExample(schema) {
+    if (schema?.example !== undefined)
+        return schema.example;
+    return Array.isArray(schema?.examples) && schema.examples.length > 0 ? schema.examples[0] : undefined;
+}
+/**
+ * A media type's own example: `example`, or the first of `examples` (a map
+ * of `{ value }`). JSON media types only: the example panel is JSON, and an
+ * XML or text example would print as a quoted string.
+ */
+function mediaExample(mediaType, contentType) {
+    if (!contentType || !/(^application\/json|\+json)(;|$)/i.test(contentType))
+        return undefined;
+    if (mediaType?.example !== undefined)
+        return mediaType.example;
+    const first = mediaType?.examples && typeof mediaType.examples === "object" ? Object.values(mediaType.examples)[0] : undefined;
+    return first && typeof first === "object" && "value" in first ? first.value : undefined;
+}
+function exampleOf(schema, walk) {
+    const own = schemaExample(schema);
+    if (own !== undefined)
+        return own;
+    switch (primaryType(schema)) {
+        case "object": {
+            if (!schema.properties)
+                return {};
+            const obj = {};
+            for (const [name, prop] of Object.entries(schema.properties)) {
+                obj[name] = generateExampleFromSchema(prop, walk);
+            }
+            return obj;
+        }
+        case "array":
+            return schema.items ? [generateExampleFromSchema(schema.items, walk)] : [];
+        case "string": {
+            if (schema.enum)
+                return schema.enum[0];
+            if (schema.format === "date-time")
+                return "2024-01-01T00:00:00Z";
+            if (schema.format === "email")
+                return "user@example.com";
+            if (schema.format === "uri" || schema.format === "url") {
+                return "https://example.com";
+            }
+            if (schema.format === "uuid") {
+                return "550e8400-e29b-41d4-a716-446655440000";
+            }
+            if (schema.default !== undefined)
+                return schema.default;
+            return "string";
+        }
+        case "integer":
+            return schema.default ?? 0;
+        case "number":
+            return schema.default ?? 0.0;
+        case "boolean":
+            return schema.default ?? true;
+        default:
+            return null;
+    }
+}
+function buildTagPage(tagName, tagSlug, description, ops) {
+    const tree = [
+        {
+            type: "heading",
+            props: { level: 1, id: tagSlug },
+            inline: [{ type: "text", text: tagName }],
+        },
+    ];
+    const used = new Set([tagSlug]);
+    const described = description ? descriptionHtml(description, 2, used) : null;
+    if (described)
+        tree.push({ type: "prose", html: described.html });
+    // One line per operation, as Swagger UI lists a tag: the method as a
+    // coloured badge, the path linking to its page, and the summary when the
+    // spec gives it one of its own. Built from badge, link and code nodes, so
+    // every exporter has a case for it (Obsidian, MkDocs: a plain label).
+    //
+    // Site-root hrefs, as an importer writes them, so the build adds the base
+    // path and the source's /<name>/ prefix like any other link. These were
+    // relative `<a href="pets/list-pets">` in raw HTML: on the tag page,
+    // served at /pets/, the browser read them as /pets/pets/list-pets.
+    const items = [...ops].sort(byPathThenMethod).map((op) => ({
+        type: "list-item",
+        inline: [
+            { type: "badge", text: op.method.toUpperCase(), variant: METHOD_BADGE[op.method] ?? "secondary" },
+            { type: "text", text: " " },
+            { type: "link", href: `/${op.slug}`, children: [{ type: "code", text: op.path }] },
+            ...(op.summary ? [{ type: "text", text: ` — ${op.summary}` }] : []),
+            ...(op.deprecated ? [{ type: "text", text: " (deprecated)" }] : []),
+        ],
+    }));
+    tree.push({ type: "unordered-list", children: items });
+    return {
+        slug: tagSlug,
+        title: tagName,
+        tree,
+        headings: [{ depth: 1, slug: tagSlug, text: tagName }, ...(described?.headings ?? [])],
+    };
+}
+function buildInfoPage(title, description, version) {
+    const tree = [
+        {
+            type: "heading",
+            props: { level: 1, id: "api-reference" },
+            inline: [{ type: "text", text: title }],
+        },
+    ];
+    if (version) {
+        tree.push(versionLine(version));
+    }
+    const described = description ? descriptionHtml(description, 2, new Set(["api-reference"])) : null;
+    if (described)
+        tree.push({ type: "prose", html: described.html });
+    return {
+        slug: "index",
+        title,
+        tree,
+        headings: [{ depth: 1, slug: "api-reference", text: title }, ...(described?.headings ?? [])],
+    };
+}
+const METHOD_ORDER = ["get", "post", "put", "patch", "delete", "head", "options"];
+/** A method's badge variant on a group page: the Badge status colour nearest the URL bar's (--api-get green, --api-post blue), contrast-tested. */
+const METHOD_BADGE = { get: "success", post: "info", put: "warning", patch: "warning", delete: "danger" };
+/** By path, then GET, POST, PUT, PATCH, DELETE: a resource's operations together. */
+function byPathThenMethod(a, b) {
+    if (a.path !== b.path)
+        return a.path < b.path ? -1 : 1;
+    return METHOD_ORDER.indexOf(a.method) - METHOD_ORDER.indexOf(b.method);
+}
+function hrefHref(prefix, slug) {
+    const p = prefix ? `${prefix}/` : "/";
+    return slug === "index" ? p : `${p}${slug}`;
+}
+/**
+ * A spec description (CommonMark, per OpenAPI) → HTML, raw HTML off: a `<`
+ * in the spec is escaped, and markdown-it refuses `javascript:` links.
+ * Plain-text paragraphs showed a spec's `## Authentication` literally.
+ */
+const md = new MarkdownIt({ html: false, linkify: false });
+/**
+ * The spec's version as a badge, not raw HTML: a sanitizing renderer drops a
+ * raw `<p class>`'s class, so every spec warned `removed p[class]` and lost
+ * the styling (#103). A badge renders the same in every target.
+ */
+function versionLine(version) {
+    return { type: "paragraph", inline: [{ type: "badge", text: `Version ${version}`, variant: "outline" }] };
+}