sourcey 3.4.10 → 3.5.0

package/dist/core/markdown-loader.js

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { basename, extname, relative } from "node:path";
 import { load as parseYaml } from "js-yaml";
+import { normalizeChangelog } from "./changelog-normalizer.js";
 import { htmlId } from "../utils/html-id.js";
 import { renderIcon } from "../utils/icons.js";
 import { renderCodeBlock, renderMarkdown, renderMarkdownInline, extractHeadings, } from "../utils/markdown.js";
@@ -215,31 +216,6 @@ function buildDirectiveAttrList(entries) {
         .map(([key, value]) => `${key}="${escapeDirectiveAttr(value)}"`);
     return attrs.length > 0 ? `{${attrs.join(" ")}}` : "";
 }
-function indentBlock(text, prefix) {
-    const lines = text.split("\n");
-    const result = [];
-    let fence = null;
-    for (const line of lines) {
-        if (fence) {
-            // Inside a fenced code block — don't indent
-            result.push(line);
-            if (closesFence(line, fence))
-                fence = null;
-        }
-        else {
-            const nextFence = isFenceStart(line);
-            if (nextFence) {
-                // Fence opener — don't indent so markdown recognises it
-                fence = nextFence;
-                result.push(line);
-            }
-            else {
-                result.push(`${prefix}${line}`);
-            }
-        }
-    }
-    return result.join("\n");
-}
 function isWhitespaceOnlyText(node) {
     return node.kind === "text" && node.value.trim() === "";
 }
@@ -406,10 +382,17 @@ function collectChildComponents(children, expected) {
  * indented JSX content (e.g. code fences inside <Step>) is handled correctly.
  */
 function renderComponentChildrenToHtml(children) {
+    // Save outer protection maps — renderDirectiveMarkdown → preprocessComponents will overwrite them
+    const savedFenceBlocks = activeFenceBlocks;
+    const savedInlineSpans = activeInlineSpans;
     let raw = renderParsedComponentNodes(children);
-    raw = restoreFencedCodeBlocks(raw, activeFenceBlocks);
-    raw = restoreInlineCodeSpans(raw, activeInlineSpans);
-    return renderDirectiveMarkdown(dedent(raw));
+    raw = restoreFencedCodeBlocks(raw, savedFenceBlocks);
+    raw = restoreInlineCodeSpans(raw, savedInlineSpans);
+    const result = renderDirectiveMarkdown(dedent(raw));
+    // Restore outer maps for sibling components
+    activeFenceBlocks = savedFenceBlocks;
+    activeInlineSpans = savedInlineSpans;
+    return result;
 }
 /**
  * Strip common leading whitespace from a block of text.
@@ -946,6 +929,47 @@ function preprocessDirectives(body) {
 export async function loadMarkdownPage(filePath, slug) {
     const raw = await readFile(filePath, "utf-8");
     const { meta, body } = parseFrontmatter(raw);
+    return loadMarkdownPageFromBody(filePath, slug, body, meta);
+}
+export async function loadDocsPage(filePath, slug, options = {}) {
+    const raw = await readFile(filePath, "utf-8");
+    const { meta, body } = parseFrontmatter(raw);
+    if (shouldTreatAsChangelog(filePath, meta, options)) {
+        const sourcePath = relative(process.cwd(), filePath);
+        const changelog = normalizeChangelog(body, {
+            title: typeof meta.title === "string" ? meta.title : undefined,
+            description: typeof meta.description === "string" ? meta.description : undefined,
+            repoUrl: options.repoUrl,
+        });
+        const description = typeof meta.description === "string"
+            ? meta.description
+            : changelog.description ?? "";
+        return {
+            kind: "changelog",
+            title: changelog.title,
+            description,
+            slug,
+            headings: changelog.versions.map((version) => ({
+                level: 2,
+                text: version.version ?? "Unreleased",
+                id: version.id,
+            })),
+            sourcePath,
+            editPath: sourcePath,
+            changelog,
+            rawBody: body,
+        };
+    }
+    return loadMarkdownPageFromBody(filePath, slug, body, meta);
+}
+function shouldTreatAsChangelog(filePath, meta, options) {
+    if (options.changelog === false)
+        return false;
+    if (typeof meta.layout === "string" && meta.layout.toLowerCase() === "changelog")
+        return true;
+    return basename(filePath).toLowerCase() === "changelog.md";
+}
+function loadMarkdownPageFromBody(filePath, slug, body, meta) {
     resetDirectiveCounter();
     const componentPreprocessed = preprocessComponents(body);
     const preprocessed = preprocessDirectives(componentPreprocessed);
@@ -957,6 +981,7 @@ export async function loadMarkdownPage(filePath, slug) {
     const cleanHtml = html.replace(/^\s*<h1[^>]*>(.*?)<\/h1>\s*/i, (_m, inner) => inner.replace(/<[^>]+>/g, "").trim() === title ? "" : _m);
     const sourcePath = relative(process.cwd(), filePath);
     return {
+        kind: "markdown",
         title,
         description,
         slug,

package/dist/core/mcp-normalizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-normalizer.d.ts","sourceRoot":"","sources":["../../src/core/mcp-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAoE,MAAM,YAAY,CAAC;AAC5G,OAAO,KAAK,EACV,cAAc,EAUf,MAAM,YAAY,CAAC;AAKpB,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CA+C9D"}
+{"version":3,"file":"mcp-normalizer.d.ts","sourceRoot":"","sources":["../../src/core/mcp-normalizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAoE,MAAM,YAAY,CAAC;AAC5G,OAAO,KAAK,EACV,cAAc,EASf,MAAM,YAAY,CAAC;AAKpB,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,cAAc,CA+C9D"}

package/dist/core/navigation.d.ts

@@ -1,6 +1,6 @@
 import type { NormalizedSpec } from "./types.js";
 import type { ResolvedTab } from "../config.js";
-import type { MarkdownPage } from "./markdown-loader.js";
+import type { DocsPage } from "./markdown-loader.js";
 export interface SiteNavigation {
     tabs: SiteTab[];
     activeTabSlug: string;
@@ -38,7 +38,7 @@ export declare function buildNavFromSpec(spec: NormalizedSpec, tabSlug: string):
  * Build a navigation tab from markdown pages.
  * Groups come from the config; items come from loaded page data.
  */
-export declare function buildNavFromPages(tab: ResolvedTab, pagesByPath: Map<string, MarkdownPage>): SiteTab;
+export declare function buildNavFromPages(tab: ResolvedTab, pagesByPath: Map<string, DocsPage>): SiteTab;
 /**
  * Assemble a SiteNavigation from a list of tabs.
  * Defaults to the first tab and first page as active.

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

@@ -1 +1 @@
-{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/core/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAOzD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,GACd,OAAO,CA+CT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,GACrC,OAAO,CA6BT;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CASnE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,cAAc,CAEhB"}
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../src/core/navigation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAOrD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,EAAE,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,WAAW,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,GACd,OAAO,CAiDT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,WAAW,EAChB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,GACjC,OAAO,CA6BT;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CASnE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,cAAc,EACnB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,cAAc,CAEhB"}

package/dist/core/navigation.js

@@ -1,3 +1,4 @@
+import { tagNavigationLabel } from "./tag-utils.js";
 import { tabPath } from "../config.js";
 import { htmlId } from "../utils/html-id.js";
 // ---------------------------------------------------------------------------
@@ -25,6 +26,7 @@ export function buildNavFromSpec(spec, tabSlug) {
     }
     groups.push({ label: "", items: introItems });
     // Tag groups with operations
+    const tagsByName = new Map(spec.tags.map((tag) => [tag.name, tag]));
     for (const tag of spec.tags) {
         if (tag.hidden)
             continue;
@@ -34,7 +36,9 @@ export function buildNavFromSpec(spec, tabSlug) {
             id: `operation-${htmlId(op.path)}-${htmlId(op.method)}`,
             method: op.method,
         }));
-        groups.push({ label: tag.name, items });
+        if (!items.length)
+            continue;
+        groups.push({ label: tagNavigationLabel(tag, tagsByName), items });
     }
     // Models group
     const schemaNames = Object.keys(spec.schemas);

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

@@ -1 +1 @@
-{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../src/core/normalizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,UAAU,EACV,cAAc,EAqBf,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAoBhE"}
+{"version":3,"file":"normalizer.d.ts","sourceRoot":"","sources":["../../src/core/normalizer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,UAAU,EACV,cAAc,EAsBf,MAAM,YAAY,CAAC;AAMpB;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAoBhE"}

package/dist/core/normalizer.js

@@ -1,5 +1,5 @@
 const HTTP_METHODS = [
-    "get", "post", "put", "delete", "patch", "options", "head", "trace",
+    "get", "post", "put", "delete", "patch", "options", "head", "trace", "query",
 ];
 /**
  * Transform a fully dereferenced OpenAPI 3.x document into a NormalizedSpec.
@@ -29,6 +29,7 @@ function normalizeInfo(doc) {
     const info = doc.info ?? {};
     return {
         title: str(info.title, "Untitled API"),
+        summary: optStr(info.summary),
         version: str(info.version, "0.0.0"),
         description: optStr(info.description),
         termsOfService: optStr(info.termsOfService),
@@ -82,7 +83,10 @@ function normalizeTags(rawTags, operations) {
             if (name) {
                 tagMap.set(name, {
                     name,
+                    summary: optStr(t.summary),
                     description: optStr(t.description),
+                    parent: optStr(t.parent),
+                    kind: optStr(t.kind),
                     externalDocs: normalizeExternalDocs(t.externalDocs),
                     operations: [],
                     hidden: t["x-sourcey-hide"] === true,
@@ -106,10 +110,49 @@ function normalizeTags(rawTags, operations) {
             tagMap.get(tagName).operations.push(op);
         }
     }
-    // Filter out tags with no operations (unless they have a description)
-    return Array.from(tagMap.values()).filter((t) => t.operations.length > 0 || t.description);
+    const referencedAsParent = new Set();
+    for (const tag of tagMap.values()) {
+        if (tag.parent && tagMap.has(tag.parent)) {
+            referencedAsParent.add(tag.parent);
+        }
+    }
+    // Keep tags that contribute visible metadata or structure, even without operations.
+    return sortTagsByHierarchy(Array.from(tagMap.values()).filter((t) => t.operations.length > 0
+        || !!t.summary
+        || !!t.description
+        || !!t.kind
+        || referencedAsParent.has(t.name)));
+}
+function sortTagsByHierarchy(tags) {
+    const tagsByName = new Map(tags.map((tag) => [tag.name, tag]));
+    const childrenByParent = new Map();
+    const roots = [];
+    for (const tag of tags) {
+        if (tag.parent && tag.parent !== tag.name && tagsByName.has(tag.parent)) {
+            const siblings = childrenByParent.get(tag.parent) ?? [];
+            siblings.push(tag);
+            childrenByParent.set(tag.parent, siblings);
+            continue;
+        }
+        roots.push(tag);
+    }
+    const sorted = [];
+    const visited = new Set();
+    const visit = (tag) => {
+        if (visited.has(tag.name))
+            return;
+        visited.add(tag.name);
+        sorted.push(tag);
+        for (const child of childrenByParent.get(tag.name) ?? []) {
+            visit(child);
+        }
+    };
+    for (const tag of roots)
+        visit(tag);
+    for (const tag of tags)
+        visit(tag);
+    return sorted;
 }
-// ── Operations ─────────────────────────────────────────────────────
 function normalizeOperations(paths, globalSecurity) {
     if (!paths)
         return [];
@@ -173,6 +216,9 @@ function normalizeParameters(params) {
         schema: p.schema
             ? normalizeSchema(p.schema)
             : undefined,
+        content: p.content
+            ? normalizeContent(p.content)
+            : undefined,
         example: p.example,
         examples: p.examples
             ? normalizeExamples(p.examples)
@@ -201,15 +247,57 @@ function normalizeContent(content) {
             examples: value.examples
                 ? normalizeExamples(value.examples)
                 : undefined,
+            encoding: isRecord(value.encoding)
+                ? normalizeEncodingMap(value.encoding)
+                : undefined,
+            prefixEncoding: Array.isArray(value.prefixEncoding)
+                ? value.prefixEncoding
+                    .filter(isRecord)
+                    .map((entry) => normalizeEncodingObject(entry))
+                : undefined,
+            itemEncoding: isRecord(value.itemEncoding)
+                ? normalizeEncodingObject(value.itemEncoding)
+                : undefined,
         };
     }
     return result;
 }
+function normalizeEncodingMap(encodings) {
+    const result = {};
+    for (const [name, encoding] of Object.entries(encodings)) {
+        if (!isRecord(encoding))
+            continue;
+        result[name] = normalizeEncodingObject(encoding);
+    }
+    return result;
+}
+function normalizeEncodingObject(encoding) {
+    return {
+        contentType: optStr(encoding.contentType),
+        headers: isRecord(encoding.headers)
+            ? normalizeResponseHeaders(encoding.headers)
+            : undefined,
+        style: optStr(encoding.style),
+        explode: typeof encoding.explode === "boolean" ? encoding.explode : undefined,
+        allowReserved: typeof encoding.allowReserved === "boolean"
+            ? encoding.allowReserved
+            : undefined,
+        prefixEncoding: Array.isArray(encoding.prefixEncoding)
+            ? encoding.prefixEncoding
+                .filter(isRecord)
+                .map((entry) => normalizeEncodingObject(entry))
+            : undefined,
+        itemEncoding: isRecord(encoding.itemEncoding)
+            ? normalizeEncodingObject(encoding.itemEncoding)
+            : undefined,
+    };
+}
 function normalizeResponses(responses) {
     if (!responses)
         return [];
     return Object.entries(responses).map(([statusCode, r]) => ({
         statusCode,
+        summary: optStr(r.summary),
         description: str(r.description, ""),
         content: r.content
             ? normalizeContent(r.content)
@@ -234,6 +322,9 @@ function normalizeResponseHeaders(headers) {
             schema: h.schema
                 ? normalizeSchema(h.schema)
                 : undefined,
+            content: h.content
+                ? normalizeContent(h.content)
+                : undefined,
         };
     }
     return result;
@@ -409,6 +500,8 @@ function normalizeSecuritySchemes(schemes) {
                 ? normalizeOAuthFlows(raw.flows)
                 : undefined,
             openIdConnectUrl: optStr(raw.openIdConnectUrl),
+            oauth2MetadataUrl: optStr(raw.oauth2MetadataUrl),
+            deprecated: raw.deprecated === true,
         };
     }
     return result;
@@ -420,6 +513,7 @@ function normalizeOAuthFlows(flows) {
         "password",
         "clientCredentials",
         "authorizationCode",
+        "deviceAuthorization",
     ]) {
         if (flows[flowType]) {
             result[flowType] = normalizeOAuthFlow(flows[flowType]);
@@ -430,6 +524,7 @@ function normalizeOAuthFlows(flows) {
 function normalizeOAuthFlow(flow) {
     return {
         authorizationUrl: optStr(flow.authorizationUrl),
+        deviceAuthorizationUrl: optStr(flow.deviceAuthorizationUrl),
         tokenUrl: optStr(flow.tokenUrl),
         refreshUrl: optStr(flow.refreshUrl),
         scopes: (flow.scopes ?? {}),
@@ -469,3 +564,6 @@ function str(value, fallback) {
 function optStr(value) {
     return typeof value === "string" ? value : undefined;
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/core/parser.d.ts

@@ -3,8 +3,8 @@ import type { LoadedSpec, ParsedSpec } from "./types.js";
  * Dereference a loaded spec document.
  * All $ref pointers are resolved (local, remote, circular).
  *
- * For local files, dereferences from the file path directly so
- * relative $refs resolve correctly against the file's directory.
+ * Uses the document source as the base URI, but honors OpenAPI 3.2's
+ * `$self` field when present so relative references resolve canonically.
  */
 export declare function parseSpec(loaded: LoadedSpec): Promise<ParsedSpec>;
 //# sourceMappingURL=parser.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/core/parser.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAyBvE"}
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../../src/core/parser.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAmB,UAAU,EAAE,MAAM,YAAY,CAAC;AAE1E;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAiBvE"}

package/dist/core/parser.js

@@ -1,26 +1,16 @@
-import { dereference } from "@readme/openapi-parser";
+import { $RefParser } from "@apidevtools/json-schema-ref-parser";
+import { fileURLToPath, pathToFileURL } from "node:url";
 /**
  * Dereference a loaded spec document.
  * All $ref pointers are resolved (local, remote, circular).
  *
- * For local files, dereferences from the file path directly so
- * relative $refs resolve correctly against the file's directory.
+ * Uses the document source as the base URI, but honors OpenAPI 3.2's
+ * `$self` field when present so relative references resolve canonically.
  */
 export async function parseSpec(loaded) {
     try {
-        const isLocalFile = !loaded.source.startsWith("http://") && !loaded.source.startsWith("https://");
-        let dereferenced;
-        if (isLocalFile) {
-            // Dereference from file path so relative $refs resolve correctly
-            dereferenced = await dereference(loaded.source, {
-                dereference: { circular: "ignore" },
-            });
-        }
-        else {
-            dereferenced = await dereference(structuredClone(loaded.raw), {
-                dereference: { circular: "ignore" },
-            });
-        }
+        const parser = new $RefParser();
+        const dereferenced = await parser.dereference(resolveDocumentUri(loaded), structuredClone(loaded.raw), { dereference: { circular: "ignore" } });
         return {
             document: dereferenced,
             source: loaded.source,
@@ -31,3 +21,20 @@ export async function parseSpec(loaded) {
         throw new Error(`Failed to parse OpenAPI spec: ${message}`);
     }
 }
+function resolveDocumentUri(loaded) {
+    const self = typeof loaded.raw["$self"] === "string" ? loaded.raw["$self"] : undefined;
+    if (!self)
+        return loaded.source;
+    try {
+        if (loaded.source.startsWith("http://") || loaded.source.startsWith("https://")) {
+            return new URL(self, loaded.source).toString();
+        }
+        const resolved = new URL(self, pathToFileURL(loaded.source));
+        return resolved.protocol === "file:"
+            ? fileURLToPath(resolved)
+            : resolved.toString();
+    }
+    catch {
+        return loaded.source;
+    }
+}

package/dist/core/search-indexer.d.ts

@@ -1,6 +1,7 @@
 import type { NormalizedSpec } from "./types.js";
-import type { MarkdownPage } from "./markdown-loader.js";
+import type { DocsPage } from "./markdown-loader.js";
 import type { SiteNavigation } from "./navigation.js";
+import type { PrettyUrls } from "../site-url.js";
 export interface SearchEntry {
     /** Display title */
     title: string;
@@ -23,5 +24,5 @@ export interface SearchEntry {
  * Build a search index from specs and markdown pages.
  * Returns a JSON string ready to write to disk.
  */
-export declare function buildSearchIndex(specs: Map<string, NormalizedSpec>, pages: Map<string, MarkdownPage[]>, navigation: SiteNavigation, assetBase?: string, featuredSlugs?: string[]): string;
+export declare function buildSearchIndex(specs: Map<string, NormalizedSpec>, pages: Map<string, DocsPage[]>, navigation: SiteNavigation, assetBase?: string, featuredSlugs?: string[], prettyUrls?: PrettyUrls): string;
 //# sourceMappingURL=search-indexer.d.ts.map

package/dist/core/search-indexer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"search-indexer.d.ts","sourceRoot":"","sources":["../../src/core/search-indexer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAOtD,MAAM,WAAW,WAAW;IAC1B,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,CAAC,EAClC,UAAU,EAAE,cAAc,EAC1B,SAAS,SAAM,EACf,aAAa,GAAE,MAAM,EAAO,GAC3B,MAAM,CAoER"}
+{"version":3,"file":"search-indexer.d.ts","sourceRoot":"","sources":["../../src/core/search-indexer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAOjD,MAAM,WAAW,WAAW;IAC1B,oBAAoB;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAMD;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC,EAClC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,EAC9B,UAAU,EAAE,cAAc,EAC1B,SAAS,SAAM,EACf,aAAa,GAAE,MAAM,EAAO,EAC5B,UAAU,GAAE,UAAkB,GAC7B,MAAM,CAuFR"}

package/dist/core/search-indexer.js

@@ -6,21 +6,29 @@ import { htmlId } from "../utils/html-id.js";
  * Build a search index from specs and markdown pages.
  * Returns a JSON string ready to write to disk.
  */
-export function buildSearchIndex(specs, pages, navigation, assetBase = "/", featuredSlugs = []) {
+export function buildSearchIndex(specs, pages, navigation, assetBase = "/", featuredSlugs = [], prettyUrls = false) {
     const base = assetBase.endsWith("/") ? assetBase : assetBase + "/";
     const featuredSet = new Set(featuredSlugs);
     const entries = [];
+    const pageUrl = (tabSlug, slug) => {
+        const tabPrefix = tabSlug ? `${base}${tabSlug}/` : base;
+        if (prettyUrls === "strip")
+            return `${tabPrefix}${slug}`;
+        if (prettyUrls === "slash")
+            return `${tabPrefix}${slug}/`;
+        return `${tabPrefix}${slug}.html`;
+    };
     // Index OpenAPI specs
     for (const [tabSlug, spec] of specs) {
         const tab = navigation.tabs.find((t) => t.slug === tabSlug);
         const tabLabel = tab?.label ?? tabSlug;
-        const basePath = `${tabSlug}/index.html`;
+        const tabBase = tabSlug ? `${base}${tabSlug}/` : base;
         // Operations
         for (const op of spec.operations) {
             entries.push({
                 title: op.summary ?? `${op.method.toUpperCase()} ${op.path}`,
                 content: op.description?.slice(0, 200) ?? "",
-                url: `${base}${basePath}#operation-${htmlId(op.path)}-${htmlId(op.method)}`,
+                url: `${tabBase}#operation-${htmlId(op.path)}-${htmlId(op.method)}`,
                 method: op.method,
                 path: op.path,
                 tab: tabLabel,
@@ -32,7 +40,7 @@ export function buildSearchIndex(specs, pages, navigation, assetBase = "/", feat
             entries.push({
                 title: name,
                 content: spec.schemas[name].description?.slice(0, 200) ?? "",
-                url: `${base}${basePath}#definition-${htmlId(name)}`,
+                url: `${tabBase}#definition-${htmlId(name)}`,
                 tab: tabLabel,
                 category: "Models",
             });
@@ -43,26 +51,39 @@ export function buildSearchIndex(specs, pages, navigation, assetBase = "/", feat
         const tab = navigation.tabs.find((t) => t.slug === tabSlug);
         const tabLabel = tab?.label ?? tabSlug;
         for (const page of tabPages) {
-            // Page itself
-            const pageBase = tabSlug ? `${base}${tabSlug}/` : base;
             const isFeatured = featuredSet.has(page.slug);
+            const href = pageUrl(tabSlug, page.slug);
             entries.push({
                 title: page.title,
-                content: page.description || stripHtml(page.html).slice(0, 200),
-                url: `${pageBase}${page.slug}.html`,
+                content: page.kind === "markdown"
+                    ? page.description || stripHtml(page.html).slice(0, 200)
+                    : page.description || summarizeChangelog(page).slice(0, 200),
+                url: href,
                 tab: tabLabel,
                 category: "Pages",
                 ...(isFeatured && { featured: true }),
             });
-            // Headings within page
-            for (const heading of page.headings) {
-                entries.push({
-                    title: heading.text,
-                    content: `${page.title} — ${heading.text}`,
-                    url: `${pageBase}${page.slug}.html#${heading.id}`,
-                    tab: tabLabel,
-                    category: "Sections",
-                });
+            if (page.kind === "markdown") {
+                for (const heading of page.headings) {
+                    entries.push({
+                        title: heading.text,
+                        content: `${page.title} — ${heading.text}`,
+                        url: `${href}#${heading.id}`,
+                        tab: tabLabel,
+                        category: "Sections",
+                    });
+                }
+            }
+            else {
+                for (const version of page.changelog.versions) {
+                    entries.push({
+                        title: version.version ?? "Unreleased",
+                        content: summarizeVersion(version).slice(0, 200),
+                        url: `${href}#${version.id}`,
+                        tab: tabLabel,
+                        category: "Releases",
+                    });
+                }
             }
         }
     }
@@ -74,3 +95,15 @@ export function buildSearchIndex(specs, pages, navigation, assetBase = "/", feat
 function stripHtml(html) {
     return html.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
 }
+function summarizeChangelog(page) {
+    return page.changelog.versions
+        .slice(0, 3)
+        .map(summarizeVersion)
+        .join(" ");
+}
+function summarizeVersion(version) {
+    if (version.summary)
+        return version.summary;
+    const entries = version.sections.flatMap((section) => section.entries.map((entry) => entry.text));
+    return entries.slice(0, 3).join(" ");
+}

package/dist/core/tag-utils.d.ts

@@ -0,0 +1,5 @@
+import type { NormalizedTag } from "./types.js";
+export declare function tagDisplayName(tag: Pick<NormalizedTag, "name" | "summary">): string;
+export declare function tagLineage(tag: Pick<NormalizedTag, "name" | "parent">, tagsByName: Map<string, NormalizedTag>): NormalizedTag[];
+export declare function tagNavigationLabel(tag: NormalizedTag, tagsByName: Map<string, NormalizedTag>): string;
+//# sourceMappingURL=tag-utils.d.ts.map

package/dist/core/tag-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-utils.d.ts","sourceRoot":"","sources":["../../src/core/tag-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,wBAAgB,cAAc,CAAC,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,CAEnF;AAED,wBAAgB,UAAU,CACxB,GAAG,EAAE,IAAI,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ,CAAC,EAC3C,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GACrC,aAAa,EAAE,CAcjB;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,aAAa,EAClB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GACrC,MAAM,CAIR"}

package/dist/core/tag-utils.js

@@ -0,0 +1,22 @@
+export function tagDisplayName(tag) {
+    return tag.summary ?? tag.name;
+}
+export function tagLineage(tag, tagsByName) {
+    const lineage = [];
+    const seen = new Set([tag.name]);
+    let parentName = tag.parent;
+    while (parentName && !seen.has(parentName)) {
+        const parent = tagsByName.get(parentName);
+        if (!parent)
+            break;
+        lineage.unshift(parent);
+        seen.add(parent.name);
+        parentName = parent.parent;
+    }
+    return lineage;
+}
+export function tagNavigationLabel(tag, tagsByName) {
+    return [...tagLineage(tag, tagsByName), tag]
+        .map(tagDisplayName)
+        .join(" / ");
+}