@fern-api/fdr-sdk 1.2.39-dc3805e7f9 → 1.2.39-ef1dbb46ea

package/dist/navigation/ledger-root-builder.js

@@ -1,1904 +0,0 @@
-import * as FernNavigation from "./index.js";
-/** @internal Exported for testing only. */
-export function createBuildContext(basePath) {
-    // Tracks how many times each id key has been handed out, so collisions get
-    // a deterministic `-N` suffix. NodeIds only need to be unique within a
-    // single tree; keying them off content (slug/scope) instead of a running
-    // counter makes them stable across builds — so client state keyed by
-    // node.id (e.g. playground form state in localStorage) survives republish
-    // as long as the node's slug/position is unchanged.
-    const seen = new Map();
-    // Nav `fullPath`s are stored relative to the docs root (no basepath);
-    // FernNavigation slugs include the basepath prefix, so content node slugs
-    // are joined onto this prefix.
-    const basePrefix = basePath.replace(/^\/+|\/+$/g, "");
-    return {
-        nodeId: (key) => {
-            const count = seen.get(key) ?? 0;
-            seen.set(key, count + 1);
-            return FernNavigation.NodeId(count === 0 ? key : `${key}-${count}`);
-        },
-        contentSlug: (relativePath) => {
-            const clean = relativePath.replace(/^\/+|\/+$/g, "");
-            return basePrefix === "" ? FernNavigation.Slug(clean) : FernNavigation.slugjoin(basePrefix, clean);
-        }
-    };
-}
-function asSlug(path) {
-    return FernNavigation.Slug(path.replace(/^\/+|\/+$/g, ""));
-}
-/**
- * Resolve a product/version/tab `metadata.pointsTo` value to a node slug.
- *
- * `pointsTo` is written basepath-ABSOLUTE: it is a V1 accumulated slug, rooted
- * at the deployment basepath (`root.slug`), exactly like the `routes` dict
- * keys, the `routing` table, and `versionFirstRoute`. Only sidebar `fullPath`s
- * are stored basepath-RELATIVE and re-prefixed via {@link BuildContext.contentSlug}.
- *
- * Passing `pointsTo` through `contentSlug` would prepend the basepath a SECOND
- * time (`docs/runtime/overview` → `docs/docs/runtime/overview`), so the bare
- * product/version landing redirect targets a non-existent route and 404s on any
- * non-root (`/docs`) site. Treat it as already-absolute — only normalise slashes.
- */
-function pointsToSlug(metaPointsTo) {
-    return asSlug(metaPointsTo);
-}
-/** Read a string field off an unknown metadata blob. */
-function metaStr(metadata, key) {
-    if (metadata != null && typeof metadata === "object" && key in metadata) {
-        const v = metadata[key];
-        return typeof v === "string" ? v : undefined;
-    }
-    return undefined;
-}
-function metaBool(metadata, key) {
-    if (metadata != null && typeof metadata === "object" && key in metadata) {
-        const v = metadata[key];
-        return typeof v === "boolean" ? v : undefined;
-    }
-    return undefined;
-}
-function metaNum(metadata, key) {
-    if (metadata != null && typeof metadata === "object" && key in metadata) {
-        const v = metadata[key];
-        return typeof v === "number" ? v : undefined;
-    }
-    return undefined;
-}
-/** Read the `collapsed` field which can be boolean or "open-by-default". */
-function metaCollapsed(metadata) {
-    if (metadata != null && typeof metadata === "object" && "collapsed" in metadata) {
-        const v = metadata.collapsed;
-        if (typeof v === "boolean") {
-            return v;
-        }
-        if (v === "open-by-default") {
-            return "open-by-default";
-        }
-    }
-    return undefined;
-}
-/** Extract a string array from a metadata blob (e.g. page-level `viewers`). */
-function metaStrArr(metadata, key) {
-    if (metadata != null && typeof metadata === "object" && key in metadata) {
-        const v = metadata[key];
-        if (Array.isArray(v)) {
-            return v.filter((x) => typeof x === "string");
-        }
-    }
-    return undefined;
-}
-function metaFeatureFlags(metadata) {
-    if (metadata != null && typeof metadata === "object" && "featureFlags" in metadata) {
-        const v = metadata.featureFlags;
-        return Array.isArray(v) && v.length > 0 ? v : undefined;
-    }
-    return undefined;
-}
-/** Map raw viewer role strings to branded RoleIds, or undefined when empty. */
-function toViewers(viewers) {
-    if (viewers == null || viewers.length === 0) {
-        return undefined;
-    }
-    return viewers.map((v) => FernNavigation.RoleId(v));
-}
-/**
- * Merge segment-level viewers with the owning variant's viewers so that
- * variant-level RBAC restrictions propagate into section/apiReference/changelog
- * nodes. Without this, removing the variant filter from `inScope` would allow
- * cross-variant prev/next links to disclose restricted content.
- */
-function mergeVariantViewers(seg) {
-    const segViewers = seg.metadata.type === "section" ||
-        seg.metadata.type === "apiReference" ||
-        seg.metadata.type === "apiPackage" ||
-        seg.metadata.type === "changelog"
-        ? seg.metadata.viewers
-        : undefined;
-    const variantViewers = seg.variant?.viewers;
-    if ((segViewers == null || segViewers.length === 0) && (variantViewers == null || variantViewers.length === 0)) {
-        return undefined;
-    }
-    const merged = new Set();
-    if (segViewers != null) {
-        for (const v of segViewers) {
-            merged.add(v);
-        }
-    }
-    if (variantViewers != null) {
-        for (const v of variantViewers) {
-            merged.add(v);
-        }
-    }
-    return merged.size > 0 ? [...merged].map((v) => FernNavigation.RoleId(v)) : undefined;
-}
-function detailSlug(detail) {
-    return detail.metadata?.slug ?? "";
-}
-function detailIsDefault(detail) {
-    return detail.metadata?.default ?? false;
-}
-// ── scope grouping ───────────────────────────────────────────────────────
-/** Stable identity for a (product, version, variant, tab) scope. */
-function scopeKey(seg) {
-    return [seg.product?.id ?? "", seg.version?.id ?? "", seg.variant?.id ?? "", seg.tab?.id ?? ""].join("|");
-}
-// ── artifact → node conversion ─────────────────────────────────────────────
-function withMetadataDefaults(base) {
-    const { viewers, featureFlags, ...rest } = base;
-    return {
-        ...rest,
-        canonicalSlug: undefined,
-        authed: base.authed === true ? true : undefined,
-        collapsed: undefined,
-        // Normalise empty arrays to undefined so unrestricted nodes don't add
-        // filter-level noise; a non-empty array engages the RBAC view gate.
-        viewers: viewers != null && viewers.length > 0 ? viewers : undefined,
-        orphaned: base.orphaned === true ? true : undefined,
-        featureFlags: featureFlags != null && featureFlags.length > 0 ? featureFlags : undefined
-    };
-}
-/**
- * Convert one sidebar nav artifact into a leaf navigation node. Returns
- * undefined for artifacts that don't become standalone sidebar nodes here
- * (endpoints live under paginated apiReferences; overview pages are folded
- * into their owning section).
- */
-function artifactToNode(ctx, route) {
-    const md = route.metadata;
-    const title = metaStr(md, "title") ?? "";
-    const icon = metaStr(md, "icon");
-    const viewers = toViewers(metaStrArr(md, "viewers"));
-    const slug = ctx.contentSlug(route.fullPath ?? "");
-    switch (route.type) {
-        case "markdown": {
-            // Overview pages are represented on their section, not as a sibling.
-            if (metaBool(md, "isOverview")) {
-                return undefined;
-            }
-            const pageId = metaStr(md, "pageId") ?? "";
-            const node = {
-                type: "page",
-                ...withMetadataDefaults({
-                    id: ctx.nodeId(`page:${slug}`),
-                    title,
-                    slug,
-                    icon,
-                    hidden: route.hidden,
-                    authed: metaBool(md, "authed"),
-                    viewers,
-                    orphaned: metaBool(md, "orphaned"),
-                    featureFlags: metaFeatureFlags(md)
-                }),
-                pageId: FernNavigation.PageId(pageId),
-                noindex: metaBool(md, "noindex"),
-                availability: undefined
-            };
-            return node;
-        }
-        case "link": {
-            const node = {
-                type: "link",
-                id: ctx.nodeId(`link:${metaStr(md, "url") ?? route.fullPath ?? ""}`),
-                collapsed: undefined,
-                title,
-                icon,
-                url: FernNavigation.Url(metaStr(md, "url") ?? ""),
-                target: metaStr(md, "target")
-            };
-            return node;
-        }
-        // API leaf types are handled by apiReferenceNode (which calls
-        // apiLeafNodeFromNavRouteInternal), not by section-level artifact
-        // conversion. Returning undefined here prevents them from appearing
-        // as duplicate siblings alongside the apiReference node.
-        case "rest":
-        case "asyncapi":
-        case "webhook":
-        case "grpc":
-        case "graphql":
-            return undefined;
-        default:
-            return undefined;
-    }
-}
-/**
- * Convert one API-leaf nav route into its navigation node, or undefined when
- * the route is not an API leaf carrying the required identifiers.
- *
- * @internal Exported for the ledger loader's scoped explorer methods.
- */
-export function apiLeafNodeFromNavRoute(route, basePath, segmentApiDefinitionId) {
-    const ctx = createBuildContext(basePath);
-    return apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId);
-}
-function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId) {
-    const md = route.metadata;
-    const apiDefinitionId = FernNavigation.ApiDefinitionId(metaStr(md, "apiDefinitionId") ?? segmentApiDefinitionId);
-    const slug = ctx.contentSlug(route.fullPath ?? "");
-    const title = metaStr(md, "title") ?? "";
-    const icon = metaStr(md, "icon");
-    const viewers = toViewers(metaStrArr(md, "viewers"));
-    const meta = withMetadataDefaults({
-        id: ctx.nodeId(`api-leaf:${slug}`),
-        title,
-        slug,
-        icon,
-        hidden: route.hidden,
-        authed: metaBool(md, "authed"),
-        viewers,
-        orphaned: metaBool(md, "orphaned"),
-        featureFlags: metaFeatureFlags(md)
-    });
-    if (route.type === "rest") {
-        const endpointId = metaStr(md, "endpointId");
-        const method = metaStr(md, "method");
-        if (endpointId == null || method == null) {
-            return undefined;
-        }
-        return {
-            type: "endpoint",
-            ...meta,
-            method: method,
-            endpointId: FernNavigation.EndpointId(endpointId),
-            apiDefinitionId,
-            isResponseStream: metaBool(md, "isResponseStream"),
-            availability: metaStr(md, "availability"),
-            playground: undefined
-        };
-    }
-    if (route.type === "webhook") {
-        const webhookId = metaStr(md, "webhookId");
-        const method = metaStr(md, "method");
-        if (webhookId == null || method == null) {
-            return undefined;
-        }
-        return {
-            type: "webhook",
-            ...meta,
-            method: method,
-            webhookId: FernNavigation.WebhookId(webhookId),
-            apiDefinitionId,
-            availability: metaStr(md, "availability")
-        };
-    }
-    if (route.type === "asyncapi") {
-        const webSocketId = metaStr(md, "webSocketId");
-        if (webSocketId == null) {
-            return undefined;
-        }
-        return {
-            type: "webSocket",
-            ...meta,
-            webSocketId: FernNavigation.WebSocketId(webSocketId),
-            apiDefinitionId,
-            availability: metaStr(md, "availability"),
-            playground: undefined
-        };
-    }
-    if (route.type === "grpc") {
-        const grpcId = metaStr(md, "grpcId");
-        const method = metaStr(md, "method");
-        if (grpcId == null || method == null) {
-            return undefined;
-        }
-        return {
-            type: "grpc",
-            ...meta,
-            method: method,
-            grpcId: FernNavigation.GrpcId(grpcId),
-            apiDefinitionId,
-            availability: metaStr(md, "availability")
-        };
-    }
-    if (route.type === "graphql") {
-        const graphqlOperationId = metaStr(md, "graphqlOperationId");
-        const operationType = metaStr(md, "operationType");
-        if (graphqlOperationId == null || operationType == null) {
-            return undefined;
-        }
-        return {
-            type: "graphql",
-            ...meta,
-            operationType: operationType,
-            graphqlOperationId: FernNavigation.GraphQlOperationId(graphqlOperationId),
-            graphqlOperationIds: undefined,
-            apiDefinitionId,
-            availability: metaStr(md, "availability"),
-            playground: undefined
-        };
-    }
-    return undefined;
-}
-function apiLeafPositionKey(node) {
-    switch (node.type) {
-        case "endpoint":
-            return `endpoint:${node.endpointId}`;
-        case "webhook":
-            return `webhook:${node.webhookId}`;
-        case "webSocket":
-            return `webSocket:${node.webSocketId}`;
-        case "grpc":
-            return `grpc:${node.grpcId}`;
-        case "graphql":
-            return `graphql:${node.graphqlOperationId}`;
-    }
-}
-function apiChildPositionKey(node) {
-    switch (node.type) {
-        case "endpoint":
-        case "webhook":
-        case "webSocket":
-        case "grpc":
-        case "graphql":
-            return apiLeafPositionKey(node);
-        default:
-            return undefined;
-    }
-}
-function positionedApiLeafChildren(ctx, nav, apiDefinitionId) {
-    const rawLeafNodes = [];
-    const leafPositions = new Map();
-    const nonApiLeafNodes = [];
-    for (let i = 0; i < nav.length; i++) {
-        const route = nav[i];
-        const pos = route.displaySortOrder ?? i;
-        const apiLeaf = apiLeafNodeFromNavRouteInternal(ctx, route, apiDefinitionId);
-        if (apiLeaf != null) {
-            rawLeafNodes.push(apiLeaf);
-            const key = apiLeafPositionKey(apiLeaf);
-            leafPositions.set(key, Math.min(leafPositions.get(key) ?? pos, pos));
-            continue;
-        }
-        const node = artifactToNode(ctx, route);
-        if (node?.type === "page" || node?.type === "link") {
-            nonApiLeafNodes.push({ node, pos });
-        }
-    }
-    const apiLeafNodes = mergeEndpointPairs(ctx, rawLeafNodes, nav);
-    const positionedApiLeafNodes = apiLeafNodes.map((node, index) => {
-        if (node.type === "endpointPair") {
-            const streamPos = leafPositions.get(apiLeafPositionKey(node.stream)) ?? index;
-            const nonStreamPos = leafPositions.get(apiLeafPositionKey(node.nonStream)) ?? index;
-            return { node, pos: Math.min(streamPos, nonStreamPos) };
-        }
-        const key = apiChildPositionKey(node);
-        return { node, pos: key != null ? (leafPositions.get(key) ?? index) : index };
-    });
-    return [...positionedApiLeafNodes, ...nonApiLeafNodes];
-}
-/**
- * Collect every endpoint/webhook navigation node from a single API segment's
- * nav routes. The root builder now populates apiReference children directly,
- * but this helper is still used by the ledger loader's per-apiDefinitionId
- * explorer methods (getApiLeafNodes) which scope to a single API definition.
- *
- * @internal Exported for the ledger loader's scoped explorer methods.
- */
-export function collectApiLeafNodesFromNav(routes, basePath, segmentApiDefinitionId) {
-    const ctx = createBuildContext(basePath);
-    return routes
-        .map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId))
-        .filter((node) => node != null);
-}
-/** Read the apiDefinitionId off a segment's metadata, or undefined. */
-export function segmentApiDefinitionId(metadata) {
-    switch (metadata.type) {
-        case "apiReference":
-        case "apiPackage":
-        case "changelog":
-            return metadata.apiDefinitionId;
-        default:
-            return undefined;
-    }
-}
-/** Find the overview artifact (isOverview) within a segment's nav, if any. */
-function overviewRoute(nav) {
-    return nav.find((r) => r.type === "markdown" && metaBool(r.metadata, "isOverview"));
-}
-/**
- * Find the overview page for a section using the segment's own
- * `metadata.overviewPageId` when `overviewRoute` (isOverview flag on nav
- * routes) fails. This handles sections where the CLI stored the overview
- * reference on the segment metadata but didn't set `isOverview` on the page.
- *
- * Legacy compat: older CLI versions wrote `overviewPageId` on the segment
- * metadata but omitted the `isOverview` flag on the nav route itself. This
- * fallback keeps those segments working. Once all published sites have been
- * re-published with a CLI that sets `isOverview`, this path can be removed.
- */
-function overviewRouteFromSegmentMeta(seg, nav) {
-    const overviewPageId = metaStr(seg.metadata, "overviewPageId");
-    if (overviewPageId == null) {
-        return undefined;
-    }
-    return nav.find((r) => metaStr(r.metadata, "pageId") === overviewPageId);
-}
-/**
- * Infer the section slug for a root section (`seg.section === ""`) from its
- * child pages' fullPaths. When the section path is empty and there is no
- * overview page, we look at the first routable page whose content slug
- * extends beyond the scope prefix. The first path segment past the scope
- * prefix is the section's implicit slug segment (e.g. `overview` in
- * `{scope}/overview/introduction`).
- *
- * Limitations:
- * - Assumes the first routable child's path structure matches the section
- *   slug. Heterogeneous child path prefixes (rare) would infer incorrectly.
- * - Sections with only single-segment children (path = `{scope}/pagename`)
- *   cannot be distinguished from bare pages, so inference falls through to
- *   the bare scope prefix. This is acceptable — the section effectively
- *   has no URL-visible slug of its own.
- */
-function inferSectionSlugFromNav(ctx, nav, scopePrefix) {
-    const scopeStr = String(scopePrefix);
-    const prefix = scopeStr !== "" ? scopeStr + "/" : "";
-    for (const r of nav) {
-        if (r.fullPath == null) {
-            continue;
-        }
-        if (r.type !== "markdown" && r.type !== "page") {
-            continue;
-        }
-        const contentSlug = String(ctx.contentSlug(r.fullPath));
-        const rel = prefix !== "" ? (contentSlug.startsWith(prefix) ? contentSlug.slice(prefix.length) : null) : contentSlug;
-        if (rel == null) {
-            continue;
-        }
-        const parts = rel.split("/");
-        // Need at least 2 parts (section-slug / page-name) to distinguish
-        // a section slug from a bare page slug.
-        if (parts.length >= 2 && parts[0] !== "") {
-            return FernNavigation.slugjoin(scopePrefix, parts[0]);
-        }
-    }
-    // No child had a multi-segment path past the scope prefix — fall back
-    // to the caller's default (bare scope prefix).
-    return undefined;
-}
-/**
- * Derive the slug for a structural section / apiReference node.
- *
- * When the section has its own routable overview page, that page's `fullPath`
- * (basepath-relative) is the canonical slug — re-prefix the basepath via
- * {@link BuildContext.contentSlug}. When it does NOT (a pure sidebar grouping
- * with no own route), the node still needs a slug for the tree, but
- * `seg.section` is only a structural path string (`release-information`,
- * `develop-with-the-cli/run-airflow-locally`) that does NOT carry the scope
- * prefix.
- *
- * The fallback MUST be rooted at the enclosing scope (`{basepath}/{product}/
- * {version}/…`) rather than just `{basepath}/{section}`. `NodeCollector`'s
- * default-version pruning (`pruneVersionNode` → `toDefaultSlug`) walks the
- * default version subtree and SKIPS a node — and all its descendants — whose
- * slug does not start with the version slug (it assumes such a node was already
- * pruned). A structural section slugged `{basepath}/{section}` does not start
- * with the version slug, so its child pages (e.g. `…/v-1-42/release-notes`)
- * would never be pruned into their clean default-version alias, and the clean
- * URL 404s with `page-not-in-nav` on basepath sites. Rooting the structural
- * slug at the scope prefix keeps the subtree inside the prune window.
- * (ADR-0014 #6.)
- */
-function structuralNodeSlug(ctx, overviewFullPath, section, scopePrefix) {
-    if (overviewFullPath != null) {
-        return ctx.contentSlug(overviewFullPath);
-    }
-    // No own route: derive a structural slug rooted at the enclosing scope so it
-    // stays within the default-version prune window. `scopePrefix` is already
-    // basepath-absolute (it is the version/product/tab node's slug), so join it
-    // directly rather than going through `contentSlug` (which would re-prefix
-    // the basepath).
-    return section !== "" ? FernNavigation.slugjoin(scopePrefix, section) : scopePrefix;
-}
-function stripLeadingScopePrefix(section, scopePrefix) {
-    const prefix = scopePrefix;
-    if (prefix === "") {
-        return section;
-    }
-    if (section === prefix) {
-        return "";
-    }
-    if (section.startsWith(prefix + "/")) {
-        return section.slice(prefix.length + 1);
-    }
-    return section;
-}
-/**
- * Merge leaf children and section children by their original V1 tree position.
- * Leaves carry position via `displaySortOrder` (stored in nav routes), sections
- * carry position via `childIndex` in segment metadata. When both have positions,
- * we interleave them in ascending order. When positions are absent (old
- * deployments without childIndex), falls back to `[...leaves, ...sections]`.
- */
-function mergeChildrenByPosition(ctx, nav, sectionChildren) {
-    const leafNodes = [];
-    for (let i = 0; i < nav.length; i++) {
-        const route = nav[i];
-        const node = artifactToNode(ctx, route);
-        if (node != null) {
-            leafNodes.push({ node, pos: route.displaySortOrder ?? i });
-        }
-    }
-    const hasChildIndex = sectionChildren.some((s) => s.childIndex != null);
-    if (!hasChildIndex) {
-        return [...leafNodes.map((l) => l.node), ...sectionChildren.map((s) => s.node)];
-    }
-    const positioned = [...leafNodes];
-    for (const s of sectionChildren) {
-        positioned.push({ node: s.node, pos: s.childIndex ?? Number.MAX_SAFE_INTEGER });
-    }
-    positioned.sort((a, b) => a.pos - b.pos);
-    return positioned.map((p) => p.node);
-}
-function sectionNode(ctx, scoped, sectionChildren, scopePrefix) {
-    const { seg, nav } = scoped;
-    const overview = overviewRoute(nav) ?? overviewRouteFromSegmentMeta(seg, nav);
-    const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : undefined;
-    // Strip the leading scope prefix to prevent double-prefixing when the
-    // section path already includes the scope (e.g. section="2026-02-09"
-    // with scopePrefix="2026-02-09" would produce "2026-02-09/2026-02-09").
-    const relSection = stripLeadingScopePrefix(seg.section, scopePrefix);
-    let slug = structuralNodeSlug(ctx, overview?.fullPath, relSection, scopePrefix);
-    // When the section path is empty and there is no overview page, the
-    // structural slug collapses to the bare scope prefix (the tab slug),
-    // losing the section segment that v2 derives from the overview page or
-    // the config's urlSlug. Infer it from child page fullPaths instead.
-    if (relSection === "" && overview?.fullPath == null) {
-        slug = inferSectionSlugFromNav(ctx, nav, scopePrefix) ?? slug;
-    }
-    const metaPointsTo = metaStr(seg.metadata, "pointsTo");
-    const defaults = withMetadataDefaults({
-        id: ctx.nodeId(`section:${slug}`),
-        title: metaStr(seg.metadata, "title") ?? "",
-        slug,
-        icon: metaStr(seg.metadata, "icon"),
-        hidden: seg.hidden,
-        authed: metaBool(seg.metadata, "authed"),
-        viewers: mergeVariantViewers(seg),
-        orphaned: metaBool(seg.metadata, "orphaned"),
-        featureFlags: metaFeatureFlags(seg.metadata)
-    });
-    return {
-        type: "section",
-        ...defaults,
-        collapsed: metaCollapsed(seg.metadata) ?? defaults.collapsed,
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: metaBool(overview?.metadata, "noindex") ?? metaBool(seg.metadata, "noindex"),
-        collapsible: metaBool(seg.metadata, "collapsible") ?? (metaCollapsed(seg.metadata) === true ? true : undefined),
-        collapsedByDefault: metaBool(seg.metadata, "collapsedByDefault") ?? (metaCollapsed(seg.metadata) === true ? true : undefined),
-        availability: metaStr(seg.metadata, "availability"),
-        pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : undefined,
-        children: mergeChildrenByPosition(ctx, nav, sectionChildren)
-    };
-}
-/**
- * Find direct child apiPackage segments of `parentSection`. A direct child has
- * `parentSectionPath(seg.section) === parentSection`, or is an orphaned segment
- * whose nearest existing ancestor is `parentSection`.
- */
-function directChildApiPackages(parentSection, scopeSegs) {
-    const sectionPaths = new Set(scopeSegs.map((s) => s.seg.section));
-    return scopeSegs
-        .filter((s) => {
-        if (metaStr(s.seg.metadata, "type") !== "apiPackage") {
-            return false;
-        }
-        const parent = parentSectionPath(s.seg.section);
-        if (parent === parentSection) {
-            return true;
-        }
-        // Orphaned: parent doesn't exist, adopt if nearest ancestor is parentSection.
-        if (!sectionPaths.has(parent)) {
-            return nearestExistingAncestor(s.seg.section, sectionPaths) === parentSection;
-        }
-        return false;
-    })
-        .sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
-}
-/**
- * Build the children of an API section (apiReference or apiPackage) by combining
- * the segment's own leaf nodes with nested apiPackage children.
- */
-function buildApiChildren(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix) {
-    const { seg, nav } = scoped;
-    // Build leaf nodes from this segment's own nav routes (not descendants).
-    // API references can contain normal docs pages and links in addition to
-    // endpoint leaves, so include markdown/link artifacts here instead of only
-    // API leaf types.
-    const leafNodes = positionedApiLeafChildren(ctx, nav, apiDefinitionId);
-    // Build nested ApiPackageNodes from direct child apiPackage segments.
-    const childPackages = directChildApiPackages(seg.section, scopeSegs);
-    const packageNodes = childPackages.map((child) => ({
-        node: apiPackageChildNode(ctx, child, scopeSegs, apiDefinitionId, scopePrefix),
-        childIndex: metaNum(child.seg.metadata, "childIndex")
-    }));
-    // Interleave by position when childIndex metadata is available
-    const hasChildIndex = packageNodes.some((p) => p.childIndex != null);
-    if (!hasChildIndex) {
-        return [...leafNodes, ...packageNodes.map((p) => ({ node: p.node, pos: Number.MAX_SAFE_INTEGER }))]
-            .sort((a, b) => a.pos - b.pos)
-            .map((p) => p.node);
-    }
-    const positioned = [];
-    positioned.push(...leafNodes);
-    for (const p of packageNodes) {
-        positioned.push({ node: p.node, pos: p.childIndex ?? Number.MAX_SAFE_INTEGER });
-    }
-    positioned.sort((a, b) => a.pos - b.pos);
-    return positioned.map((p) => p.node);
-}
-/**
- * Build an ApiPackageNode from an apiPackage segment, recursively nesting any
- * deeper sub-packages.
- */
-function apiPackageChildNode(ctx, scoped, scopeSegs, parentApiDefinitionId, scopePrefix) {
-    const { seg, nav } = scoped;
-    const overview = overviewRoute(nav);
-    const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : undefined;
-    const apiDefinitionId = metaStr(seg.metadata, "apiDefinitionId") ?? parentApiDefinitionId;
-    // Use structuralNodeSlug so the package gets its own slug (matching V2)
-    // rather than inheriting the first endpoint's path.
-    const slug = structuralNodeSlug(ctx, overview?.fullPath, stripLeadingScopePrefix(seg.section, scopePrefix), scopePrefix);
-    const metaPointsTo = metaStr(seg.metadata, "pointsTo");
-    const children = buildApiChildren(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix);
-    return {
-        type: "apiPackage",
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`api-pkg:${slug}`),
-            title: metaStr(seg.metadata, "title") ?? "",
-            slug,
-            icon: metaStr(seg.metadata, "icon"),
-            hidden: seg.hidden,
-            authed: metaBool(seg.metadata, "authed"),
-            viewers: toViewers(metaStrArr(seg.metadata, "viewers")),
-            orphaned: metaBool(seg.metadata, "orphaned"),
-            featureFlags: metaFeatureFlags(seg.metadata)
-        }),
-        apiDefinitionId: FernNavigation.ApiDefinitionId(apiDefinitionId),
-        availability: metaStr(seg.metadata, "availability"),
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: metaBool(overview?.metadata, "noindex") ?? metaBool(seg.metadata, "noindex"),
-        pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : undefined,
-        children,
-        playground: undefined
-    };
-}
-/**
- * Merge endpoint nodes that were originally part of an `endpointPair` in the V1
- * tree. The publish transform stamps both artifacts with a shared
- * `endpointPairKey` in their route metadata; this function groups endpoints by
- * that key and reconstructs `EndpointPairNode`s — matching the v2 nav tree
- * structure where stream/non-stream variants share a single page with a toggle.
- */
-/** @internal Exported for testing only. */
-export function mergeEndpointPairs(ctx, leafNodes, allNav) {
-    // Build a lookup from endpointId → endpointPairKey using route metadata.
-    // Only REST routes carry `endpointPairKey`.
-    const endpointIdToPairKey = new Map();
-    for (const route of allNav) {
-        if (route.type !== "rest") {
-            continue;
-        }
-        const pairKey = metaStr(route.metadata, "endpointPairKey");
-        const endpointId = metaStr(route.metadata, "endpointId");
-        if (pairKey != null && endpointId != null) {
-            endpointIdToPairKey.set(endpointId, pairKey);
-        }
-    }
-    // If no pair keys exist (pre-existing data without the key), return as-is.
-    if (endpointIdToPairKey.size === 0) {
-        return leafNodes;
-    }
-    const result = [];
-    // Track which pair keys we've already merged so we only emit the pair once.
-    const mergedPairKeys = new Map();
-    for (const node of leafNodes) {
-        if (node.type !== "endpoint") {
-            result.push(node);
-            continue;
-        }
-        const pairKey = endpointIdToPairKey.get(String(node.endpointId));
-        if (pairKey == null) {
-            result.push(node);
-            continue;
-        }
-        const existingIdx = mergedPairKeys.get(pairKey);
-        if (existingIdx == null) {
-            // First endpoint of the pair — push it and record its position.
-            mergedPairKeys.set(pairKey, result.length);
-            result.push(node);
-        }
-        else {
-            // Second endpoint — merge with the first into an EndpointPairNode.
-            const first = result[existingIdx];
-            if (first == null || first.type !== "endpoint") {
-                result.push(node);
-                continue;
-            }
-            // Determine which is stream and which is non-stream.
-            const stream = node.isResponseStream ? node : first;
-            const nonStream = node.isResponseStream ? first : node;
-            // Point the stream endpoint's canonicalSlug to the non-stream slug
-            // so the sitemap deduplicates them (matching v2 behavior where the
-            // v1→latest migrator's title-disambiguation cache achieves the same).
-            stream.canonicalSlug = nonStream.slug;
-            const pairNode = {
-                id: ctx.nodeId(`endpoint-pair:${pairKey}`),
-                type: "endpointPair",
-                collapsed: undefined,
-                stream,
-                nonStream
-            };
-            result[existingIdx] = pairNode;
-        }
-    }
-    return result;
-}
-function apiReferenceNode(ctx, scoped, scopeSegs, scopePrefix) {
-    const { seg, nav } = scoped;
-    const overview = overviewRoute(nav);
-    const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : undefined;
-    const apiDefinitionId = metaStr(seg.metadata, "apiDefinitionId") ?? "";
-    // Slug: prefer the overview route, else a structural slug rooted at the
-    // enclosing scope (so the subtree stays inside the default-version prune
-    // window — see {@link structuralNodeSlug}).
-    // NOTE: do NOT fall back to nav[0]?.fullPath here. When the apiReference
-    // has direct endpoint children (no sub-packages), that would set the
-    // apiReference's slug to the first endpoint's slug. Then
-    // mutableUpdatePointsTo clears pointsTo (slug === redirect target),
-    // breaking the breadcrumb link.
-    const slug = structuralNodeSlug(ctx, overview?.fullPath, stripLeadingScopePrefix(seg.section, scopePrefix), scopePrefix);
-    const metaPointsTo = metaStr(seg.metadata, "pointsTo");
-    const children = buildApiChildren(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix);
-    const changelog = attachedApiChangelogNode(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix);
-    return {
-        type: "apiReference",
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`api:${slug}`),
-            title: metaStr(seg.metadata, "title") ?? "",
-            slug,
-            icon: metaStr(seg.metadata, "icon"),
-            hidden: seg.hidden,
-            authed: metaBool(seg.metadata, "authed"),
-            viewers: mergeVariantViewers(seg),
-            orphaned: metaBool(seg.metadata, "orphaned"),
-            featureFlags: metaFeatureFlags(seg.metadata)
-        }),
-        apiDefinitionId: FernNavigation.ApiDefinitionId(apiDefinitionId),
-        availability: metaStr(seg.metadata, "availability"),
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: metaBool(overview?.metadata, "noindex") ?? metaBool(seg.metadata, "noindex"),
-        paginated: true,
-        showErrors: metaBool(seg.metadata, "showErrors"),
-        hideTitle: metaBool(seg.metadata, "hideTitle"),
-        pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : undefined,
-        children,
-        changelog,
-        playground: undefined,
-        postmanCollectionUrl: undefined
-    };
-}
-function attachedApiChangelogNode(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix) {
-    const { seg } = scoped;
-    const candidates = scopeSegs.filter((candidate) => {
-        if (metaStr(candidate.seg.metadata, "type") !== "changelog") {
-            return false;
-        }
-        return metaStr(candidate.seg.metadata, "apiDefinitionId") === apiDefinitionId;
-    });
-    const changelogSeg = candidates.find((candidate) => parentSectionPath(candidate.seg.section) === seg.section) ?? candidates[0];
-    return changelogSeg != null ? changelogNode(ctx, changelogSeg, scopePrefix) : undefined;
-}
-function hasOwningApiReference(scoped, scopeSegs) {
-    const apiDefinitionId = metaStr(scoped.seg.metadata, "apiDefinitionId");
-    if (apiDefinitionId == null || metaStr(scoped.seg.metadata, "type") !== "changelog") {
-        return false;
-    }
-    return scopeSegs.some((candidate) => {
-        if (metaStr(candidate.seg.metadata, "type") !== "apiReference") {
-            return false;
-        }
-        return metaStr(candidate.seg.metadata, "apiDefinitionId") === apiDefinitionId;
-    });
-}
-function changelogNode(ctx, scoped, scopePrefix) {
-    const { seg, nav } = scoped;
-    const overview = overviewRoute(nav);
-    const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : undefined;
-    // Group changelog entries by year → month. Entry dates are ISO strings.
-    const entries = nav.filter((r) => r.type === "changelog");
-    const byYear = new Map();
-    for (const r of entries) {
-        const dateStr = metaStr(r.metadata, "date");
-        const date = dateStr != null ? new Date(dateStr) : new Date(0);
-        const year = date.getUTCFullYear();
-        const month = date.getUTCMonth() + 1;
-        const entry = {
-            type: "changelogEntry",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`cl-entry:${r.fullPath ?? metaStr(r.metadata, "pageId") ?? ""}`),
-                title: metaStr(r.metadata, "title") ?? "",
-                slug: ctx.contentSlug(r.fullPath ?? ""),
-                icon: metaStr(r.metadata, "icon"),
-                hidden: r.hidden,
-                authed: metaBool(r.metadata, "authed"),
-                viewers: toViewers(metaStrArr(r.metadata, "viewers")),
-                orphaned: metaBool(r.metadata, "orphaned"),
-                featureFlags: metaFeatureFlags(r.metadata)
-            }),
-            pageId: FernNavigation.PageId(metaStr(r.metadata, "pageId") ?? ""),
-            noindex: metaBool(r.metadata, "noindex"),
-            date: dateStr ?? "",
-            tags: metaStrArr(r.metadata, "tags")
-        };
-        let months = byYear.get(year);
-        if (months == null) {
-            months = new Map();
-            byYear.set(year, months);
-        }
-        const arr = months.get(month) ?? [];
-        arr.push(entry);
-        months.set(month, arr);
-    }
-    // The publish transform stores changelog section paths in two shapes:
-    //  • Changelog TABs:           "home/changelog" (scope prefix baked in)
-    //  • Changelog sidebar children: "changelog"      (relative to the tab)
-    // `structuralNodeSlug` unconditionally joins `scopePrefix + section`, so
-    // an already-scoped section gets double-prefixed ("home/home/changelog").
-    // Strip the leading scope prefix when present so the join is idempotent.
-    const relativeSection = stripLeadingScopePrefix(seg.section, scopePrefix);
-    const baseSlug = structuralNodeSlug(ctx, overview?.fullPath, relativeSection, scopePrefix);
-    const years = [...byYear.entries()]
-        .sort((a, b) => b[0] - a[0])
-        .map(([year, months]) => ({
-        type: "changelogYear",
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`cl-year:${baseSlug}/${year}`),
-            title: String(year),
-            slug: asSlug(`${baseSlug}/${year}`),
-            icon: undefined,
-            hidden: undefined
-        }),
-        year,
-        children: [...months.entries()]
-            .sort((a, b) => b[0] - a[0])
-            .map(([month, children]) => ({
-            type: "changelogMonth",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`cl-month:${baseSlug}/${year}/${month}`),
-                title: String(month),
-                slug: asSlug(`${baseSlug}/${year}/${month}`),
-                icon: undefined,
-                hidden: undefined
-            }),
-            month,
-            children
-        }))
-    }));
-    return {
-        type: "changelog",
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`changelog:${baseSlug}`),
-            title: metaStr(seg.metadata, "title") ?? "",
-            slug: baseSlug,
-            icon: metaStr(seg.metadata, "icon"),
-            hidden: seg.hidden,
-            authed: metaBool(seg.metadata, "authed"),
-            viewers: mergeVariantViewers(seg),
-            orphaned: metaBool(seg.metadata, "orphaned"),
-            featureFlags: metaFeatureFlags(seg.metadata)
-        }),
-        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
-        noindex: metaBool(overview?.metadata, "noindex") ?? metaBool(seg.metadata, "noindex"),
-        children: years
-    };
-}
-/** The immediate parent section path of a section path ("a/b/c" → "a/b", "a" → ""). */
-function parentSectionPath(sectionPath) {
-    const idx = sectionPath.lastIndexOf("/");
-    return idx === -1 ? "" : sectionPath.slice(0, idx);
-}
-/** Walk up the section path hierarchy to find the nearest ancestor that exists in the set. */
-function nearestExistingAncestor(sectionPath, existing) {
-    let current = parentSectionPath(sectionPath);
-    while (current !== "") {
-        if (existing.has(current)) {
-            return current;
-        }
-        current = parentSectionPath(current);
-    }
-    return "";
-}
-/**
- * Build the section/api/changelog nodes whose immediate parent is `parentPath`,
- * recursing into nested sections. Also picks up orphaned segments whose parent
- * section doesn't exist but whose nearest existing ancestor is `parentPath`.
- */
-function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScopePrefix) {
-    const sectionPaths = new Set(scopeSegs.map((s) => s.seg.section));
-    const direct = scopeSegs
-        .filter((s) => {
-        const sec = s.seg.section;
-        const type = metaStr(s.seg.metadata, "type");
-        if (sec === "" || type === "tabRoot") {
-            return false;
-        }
-        if (hasOwningApiReference(s, scopeSegs)) {
-            return false;
-        }
-        const parent = parentSectionPath(sec);
-        if (parent === parentPath) {
-            return true;
-        }
-        // Orphaned segment: parent doesn't exist, walk up to find nearest
-        // existing ancestor. If it's parentPath, adopt this segment.
-        if (!sectionPaths.has(parent)) {
-            return nearestExistingAncestor(sec, sectionPaths) === parentPath;
-        }
-        return false;
-    })
-        .sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
-    return direct.map((s) => {
-        const type = metaStr(s.seg.metadata, "type");
-        const childIndex = metaNum(s.seg.metadata, "childIndex");
-        let node;
-        if (type === "apiReference" || type === "apiPackage") {
-            node = apiReferenceNode(ctx, s, scopeSegs, scopePrefix);
-        }
-        else if (type === "changelog") {
-            node = changelogNode(ctx, s, changelogScopePrefix ?? scopePrefix);
-        }
-        else {
-            // section (or unrecognised) → recurse for nested sections.
-            node = sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, s.seg.section, scopePrefix, changelogScopePrefix), scopePrefix);
-        }
-        return { node, childIndex };
-    });
-}
-// ── build a sidebarRoot for a single scope ─────────────────────────────────
-/**
- * When multiple root-level sections share the same section path (common for
- * versioned docs where all tab-level sections receive the version slug as
- * their path), we need to scope buildSectionTree so each section only adopts
- * the child segments that physically belong to it.
- *
- * Ownership is determined by sortOrder ranges: a section owns segments whose
- * sortOrder falls between its own and the next sibling section's sortOrder.
- * Returns a map only for sections that have duplicates; unique sections won't
- * appear (and should pass unfiltered scopeSegs to buildSectionTree).
- */
-function computeSiblingSortBoundaries(ordered) {
-    const result = new Map();
-    // Collect root-level sections grouped by their section path.
-    const sectionPaths = new Set(ordered.map((s) => s.seg.section));
-    const rootSections = [];
-    for (const s of ordered) {
-        const type = metaStr(s.seg.metadata, "type");
-        const sec = s.seg.section;
-        if (type !== "section" || sec === "") {
-            continue;
-        }
-        const parent = parentSectionPath(sec);
-        const isRootLevel = parent === "" || (!sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === "");
-        if (isRootLevel) {
-            rootSections.push(s);
-        }
-    }
-    // Group by section path — only paths with >1 section need boundaries.
-    const byPath = new Map();
-    for (const s of rootSections) {
-        const group = byPath.get(s.seg.section) ?? [];
-        group.push(s);
-        byPath.set(s.seg.section, group);
-    }
-    for (const [, siblings] of byPath) {
-        if (siblings.length <= 1) {
-            continue;
-        }
-        // Siblings are already in sortOrder (from `ordered`).
-        for (let i = 0; i < siblings.length; i++) {
-            const lo = siblings[i].seg.sortOrder;
-            const hi = i + 1 < siblings.length ? siblings[i + 1].seg.sortOrder : Number.MAX_SAFE_INTEGER;
-            result.set(siblings[i], { lo, hi });
-        }
-    }
-    return result;
-}
-/**
- * Assemble the children of a scope's sidebar root in cross-segment order.
- * `tabRoot` segments contribute their page/link artifacts inline at their
- * sort position; depth-0 `section`/`apiReference`/`changelog` segments become
- * their own nodes (with nested sections attached recursively).
- *
- * Segments whose parent section path doesn't correspond to any existing
- * segment are "orphaned" and emitted at the top level. This happens when
- * the publish transform skips segment creation for an apiReference with no
- * direct artifacts (e.g. no overview page), leaving only apiPackage children
- * like `rest-api/store` with no `rest-api` parent segment.
- */
-function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePrefix) {
-    const ordered = [...scopeSegs].sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
-    const sectionPaths = new Set(ordered.map((s) => s.seg.section));
-    // `pos` is the original V1 child position when known — `displaySortOrder`
-    // for root-level loose artifacts, `metadata.childIndex` for depth-0
-    // segments. Both index into the SAME child list at write time, so they
-    // interleave directly (e.g. [page 0, page 1, section 2…15, page 16, 17]).
-    const annotated = [];
-    // ── Root-section adoption flow ──────────────────────────────────────
-    //
-    // A scope may contain a "root section" — a segment with type "section"
-    // and section path "". When present, it acts as a structural wrapper:
-    //
-    //   hasRootSection = true
-    //   │
-    //   ├─ (A) tabRoot / loose artifacts (sec=="", type!="section")
-    //   │      → emit pages/links inline at their displaySortOrder
-    //   │
-    //   ├─ (B) the root section itself (sec=="", type=="section")
-    //   │      → buildSectionTree adopts ALL depth-0 children as its own
-    //   │      → emit one sectionNode wrapping the whole subtree
-    //   │
-    //   └─ (C) depth-0 sections (parentSectionPath=="")
-    //          → SKIP — already adopted by (B) via buildSectionTree
-    //
-    // Without a root section, depth-0 sections are emitted directly.
-    const hasRootSection = ordered.some((s) => metaStr(s.seg.metadata, "type") === "section" && s.seg.section === "");
-    // ── Sibling section ownership ────────────────────────────────────────
-    //
-    // Multiple root-level sections can share the same section path (e.g.
-    // three sections all with path equal to the version slug). When this
-    // happens, buildSectionTree would incorrectly give ALL child subsections
-    // to each sibling. We resolve ownership via sortOrder: a section owns
-    // segments whose sortOrder falls between its own and the next sibling's.
-    const siblingBoundaries = computeSiblingSortBoundaries(ordered);
-    for (const s of ordered) {
-        const type = metaStr(s.seg.metadata, "type");
-        const sec = s.seg.section;
-        if (hasOwningApiReference(s, scopeSegs)) {
-            continue;
-        }
-        if (type === "tabRoot" && metaBool(s.seg.metadata, "landingPage") === true) {
-            continue;
-        }
-        // (A) Loose artifacts: tabRoot or non-section segments at section path "".
-        if (type === "tabRoot" || (sec === "" && type !== "section")) {
-            for (const r of s.nav) {
-                const node = artifactToNode(ctx, r);
-                if (node != null) {
-                    annotated.push({ node, pos: r.displaySortOrder ?? undefined, isLeaf: true });
-                }
-            }
-            continue;
-        }
-        // (B) Root section wrapper — adopts depth-0 children via buildSectionTree.
-        if (type === "section" && sec === "") {
-            const sectionChildren = buildSectionTree(ctx, scopeSegs, "", scopePrefix);
-            const node = sectionNode(ctx, s, sectionChildren, scopePrefix);
-            annotated.push({ node, pos: metaNum(s.seg.metadata, "childIndex"), isLeaf: false });
-            continue;
-        }
-        // (C) Depth-0 or orphaned sections — emit at root unless already
-        // adopted by a root section (B).
-        const parent = parentSectionPath(sec);
-        const isRootLevel = parent === "" || (!sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === "");
-        if (isRootLevel && hasRootSection) {
-            continue;
-        }
-        if (isRootLevel) {
-            let node;
-            if (type === "apiReference" || type === "apiPackage") {
-                node = apiReferenceNode(ctx, s, scopeSegs, scopePrefix);
-            }
-            else if (type === "changelog") {
-                node = changelogNode(ctx, s, changelogScopePrefix ?? scopePrefix);
-            }
-            else {
-                // Scope child segments to this section's sortOrder range when
-                // sibling sections share the same path.
-                const bounds = siblingBoundaries.get(s);
-                const ownedSegs = bounds != null
-                    ? scopeSegs.filter((seg) => seg.seg.sortOrder >= bounds.lo && seg.seg.sortOrder < bounds.hi)
-                    : scopeSegs;
-                node = sectionNode(ctx, s, buildSectionTree(ctx, ownedSegs, sec, scopePrefix, changelogScopePrefix), scopePrefix);
-            }
-            // Shared/merged sections (paths not rooted in scopePrefix) must not
-            // carry childIndex — their source-version positions would sort them
-            // ahead of native sections. Only applies when sibling sections exist
-            // (multiple sections sharing same path), indicating a versioned site
-            // where shared sections were merged from a sibling version.
-            const isSharedSection = siblingBoundaries.size > 0 && scopePrefix !== "" && sec !== "" && !sec.startsWith(scopePrefix);
-            annotated.push({
-                node,
-                pos: isSharedSection ? undefined : metaNum(s.seg.metadata, "childIndex"),
-                isLeaf: false
-            });
-        }
-    }
-    // Interleave by V1 position only when BOTH leaves and segments carry one.
-    // Manifests written before displaySortOrder was carried through have
-    // position-less leaves; reordering on childIndex alone would move every
-    // loose page behind its sibling sections, so those keep the legacy
-    // (segment-sortOrder) order. The seq tiebreak preserves legacy order for
-    // equal or missing positions.
-    const hasLeafPos = annotated.some((a) => a.isLeaf && a.pos != null);
-    const hasSegmentPos = annotated.some((a) => !a.isLeaf && a.pos != null);
-    const flat = hasLeafPos && hasSegmentPos
-        ? annotated
-            .map((a, seq) => ({ ...a, seq }))
-            .sort((x, y) => (x.pos ?? Number.MAX_SAFE_INTEGER) - (y.pos ?? Number.MAX_SAFE_INTEGER) || x.seq - y.seq)
-            .map((a) => a.node)
-        : annotated.map((a) => a.node);
-    return groupSidebarRootChildren(ctx, flat);
-}
-/**
- * `SidebarRootChild` only permits SidebarGroupNode / ApiReferenceNode /
- * SectionNode / VariantedNode.  Sections, apiReferences, and varianted nodes
- * pass through as direct root children (rendered as static headings via
- * SidebarRootSectionNode / SidebarRootApiPackageNode — always expanded, no
- * toggle).  Pages, links, and changelogs are wrapped into a SidebarGroupNode
- * so they render via SidebarNavigationChild (mirroring the V1 tree structure
- * where sections are always direct SidebarRootChildren).
- */
-function groupSidebarRootChildren(ctx, children) {
-    const out = [];
-    let run = [];
-    const flushRun = () => {
-        if (run.length > 0) {
-            // Key off the first child's (already-stable) id so the group id is
-            // stable across builds and unique per run.
-            out.push({
-                type: "sidebarGroup",
-                id: ctx.nodeId(`sidebar-group:${run[0]?.id ?? ""}`),
-                collapsed: undefined,
-                children: run
-            });
-            run = [];
-        }
-    };
-    for (const child of children) {
-        if (child.type === "apiReference" || child.type === "varianted") {
-            flushRun();
-            out.push(child);
-        }
-        else if (child.type === "section" && !child.collapsible) {
-            // Match V2 NavigationConfigConverter.groupSidebarRootChildren:
-            // all non-collapsible sections become direct SidebarRootChildren
-            // (rendered via SidebarRootSectionNode — always-expanded heading).
-            // Only sections with explicit `collapsible: true` stay in a
-            // sidebarGroup.
-            flushRun();
-            out.push(child);
-        }
-        else if (child.type === "changelog") {
-            flushRun();
-            run.push(child);
-            flushRun();
-        }
-        else {
-            run.push(child);
-        }
-    }
-    flushRun();
-    return out;
-}
-function buildSidebarRoot(ctx, scopeSegs, scopePrefix, changelogScopePrefix) {
-    const first = scopeSegs[0];
-    return {
-        type: "sidebarRoot",
-        id: ctx.nodeId(`sidebar:${first != null ? scopeKey(first.seg) : "root"}`),
-        collapsed: undefined,
-        children: buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePrefix)
-    };
-}
-// ── public entrypoint ───────────────────────────────────────────────────────
-/**
- * Build a full (un-pruned) `RootNode` from the decomposed ledger model.
- */
-export function buildFullRootFromSegments(options) {
-    const { basePath, rootSlug: sourceRootSlug, title, segments, navBySegment, skipSharedSectionMerge } = options;
-    // Per-call state — never shared across concurrent builds.
-    const ctx = createBuildContext(basePath);
-    const scoped = segments
-        // Infrastructure segments (files/redirects) are filtered server-side,
-        // but guard here too.
-        .filter((seg) => {
-        const t = metaStr(seg.metadata, "type");
-        return t !== "files" && t !== "redirects";
-    })
-        .map((seg) => ({ seg, nav: navBySegment.get(seg.segmentHash) ?? [] }));
-    const rootSlug = asSlug(sourceRootSlug ?? basePath);
-    // Group by scope identity.
-    const scopesByKey = new Map();
-    for (const s of scoped) {
-        const key = scopeKey(s.seg);
-        const arr = scopesByKey.get(key) ?? [];
-        arr.push(s);
-        scopesByKey.set(key, arr);
-    }
-    const products = uniqueDetails(scoped, "product");
-    const versions = uniqueDetails(scoped, "version");
-    const tabs = uniqueDetails(scoped, "tab");
-    let child;
-    if (products.length > 0) {
-        child = buildProductGroup(ctx, products, scoped, rootSlug, skipSharedSectionMerge);
-    }
-    else if (versions.length > 0) {
-        child = buildVersioned(ctx, versions, scoped, rootSlug, undefined, skipSharedSectionMerge);
-    }
-    else {
-        child = buildUnversioned(ctx, scoped, rootSlug, tabs.length > 0);
-    }
-    // Derive root.pointsTo from the default child's metadata so root-slug
-    // visits redirect correctly even when mutableUpdatePointsTo is skipped
-    // (structure-only roots).  On the full root mutableUpdatePointsTo
-    // recomputes this via tree traversal; this seed value is only visible
-    // on structure-only roots where the traversal is intentionally skipped.
-    let rootPointsTo;
-    if (child.type === "productgroup") {
-        const defaultProduct = child.children.find((p) => p.default) ?? child.children[0];
-        rootPointsTo = defaultProduct?.type === "product" ? defaultProduct.pointsTo : undefined;
-    }
-    else if (child.type === "versioned") {
-        const defaultVersion = child.children.find((v) => v.default) ?? child.children[0];
-        rootPointsTo = defaultVersion?.pointsTo;
-    }
-    else if (child.type === "unversioned") {
-        // Unversioned sites have no product/version metadata to seed pointsTo.
-        // Derive from the first tab's or first section segment's metadata.
-        if (tabs.length > 0) {
-            const firstTab = tabs[0];
-            const pt = firstTab != null ? metaStr(firstTab.metadata, "pointsTo") : undefined;
-            rootPointsTo = pt != null ? pointsToSlug(pt) : undefined;
-        }
-        else {
-            const sorted = [...scoped].sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
-            for (const s of sorted) {
-                if (s.seg.hidden) {
-                    continue;
-                }
-                const pt = metaStr(s.seg.metadata, "pointsTo");
-                if (pt != null) {
-                    rootPointsTo = pointsToSlug(pt);
-                    break;
-                }
-            }
-        }
-    }
-    const root = {
-        type: "root",
-        version: "v2",
-        ...withMetadataDefaults({ id: ctx.nodeId("root"), title, slug: rootSlug, icon: undefined, hidden: undefined }),
-        roles: undefined,
-        pointsTo: rootPointsTo,
-        child
-    };
-    return root;
-}
-// ── scaffolding builders ────────────────────────────────────────────────────
-/**
- * Collapse segment details by identity.
- *
- * Primary key is the detail's slug when non-empty — this deduplicates
- * stale rows from old publishes that share the same slug but have
- * different DB ids. When the slug is empty (skip-slug items) we fall
- * back to `detail.id` so that distinct skip-slug tabs/products aren't
- * collapsed into a single entry.
- *
- * Tabs always key by `d.id` because skip-slug tabs inherit their
- * parent's slug (e.g. the version slug "v-2"), so multiple distinct
- * tabs share the same slug — keying by slug would collapse them.
- *
- * Among duplicates at the same key we prefer the one whose metadata
- * carries a `pointsTo` value (richer / more recent publish).
- */
-function uniqueDetails(scoped, dim) {
-    const byKey = new Map();
-    for (const s of scoped) {
-        const d = s.seg[dim];
-        if (d == null) {
-            continue;
-        }
-        const slug = detailSlug(d);
-        // Tabs always key by id: skip-slug tabs share the parent slug
-        // (e.g. "v-2") and would otherwise collapse into one entry.
-        const key = dim === "tab" ? d.id : slug !== "" ? slug : d.id;
-        const existing = byKey.get(key);
-        if (existing == null) {
-            byKey.set(key, d);
-        }
-        else if (metaStr(d.metadata, "pointsTo") != null && metaStr(existing.metadata, "pointsTo") == null) {
-            byKey.set(key, d);
-        }
-    }
-    return [...byKey.values()].sort((a, b) => a.sortOrder - b.sortOrder);
-}
-function scopeSlugPrefix(rootSlug, ...details) {
-    const parts = [rootSlug];
-    for (const d of details) {
-        if (d != null && !detailIsDefault(d)) {
-            const s = detailSlug(d);
-            if (s !== "") {
-                parts.push(s);
-            }
-        }
-    }
-    return FernNavigation.slugjoin(...parts);
-}
-/**
- * Build a VariantedNode from variant details, grouping segments by variant
- * so each variant gets its own scoped sidebar children.
- */
-function buildVariantedNode(ctx, variants, scopeSegs, scopePrefix) {
-    const variantChildren = variants.map((variant) => {
-        const variantSegs = scopeSegs.filter((s) => s.seg.variant?.id === variant.id);
-        // V2 never elides variant slugs — they always appear in the URL
-        // (unlike product/version defaults which ARE elided). Use the
-        // variant's individual slug directly instead of scopeSlugPrefix
-        // which skips default details.
-        const variantIndividualSlug = detailSlug(variant);
-        const variantSlug = variantIndividualSlug !== ""
-            ? asSlug(FernNavigation.slugjoin(scopePrefix, variantIndividualSlug))
-            : scopePrefix;
-        const metaPointsTo = metaStr(variant.metadata, "pointsTo");
-        const children = buildSidebarRootChildren(ctx, variantSegs, scopePrefix);
-        return {
-            type: "variant",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`variant:${variantSlug}`),
-                title: variant.displayName,
-                slug: variantSlug,
-                icon: variant.icon ?? undefined,
-                hidden: variant.hidden,
-                viewers: toViewers(variant.viewers)
-            }),
-            default: detailIsDefault(variant),
-            variantId: FernNavigation.VariantId(String(variant.id)),
-            subtitle: metaStr(variant.metadata, "subtitle") ?? undefined,
-            image: metaStr(variant.metadata, "image") != null
-                ? FernNavigation.FileId(metaStr(variant.metadata, "image"))
-                : undefined,
-            pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : undefined,
-            children: children
-        };
-    });
-    return {
-        type: "varianted",
-        id: ctx.nodeId(`varianted:${scopeSegs[0] != null ? scopeKey(scopeSegs[0].seg) : "root"}`),
-        collapsed: undefined,
-        children: variantChildren
-    };
-}
-/**
- * Build a sidebar root, wrapping content in a VariantedNode when variants exist.
- * Without this, all variant segments merge into one flat sidebar — causing the
- * "double sidebar" where both variants' nav entries render simultaneously.
- */
-function buildSidebarRootWithVariants(ctx, scopeSegs, scopePrefix, changelogScopePrefix) {
-    const variants = uniqueDetails(scopeSegs, "variant");
-    if (variants.length <= 1) {
-        return buildSidebarRoot(ctx, scopeSegs, scopePrefix, changelogScopePrefix);
-    }
-    const sharedSegs = scopeSegs.filter((s) => s.seg.variant == null);
-    const variantedNode = buildVariantedNode(ctx, variants, scopeSegs, scopePrefix);
-    const sharedChildren = sharedSegs.length > 0 ? buildSidebarRootChildren(ctx, sharedSegs, scopePrefix, changelogScopePrefix) : [];
-    const first = scopeSegs[0];
-    return {
-        type: "sidebarRoot",
-        id: ctx.nodeId(`sidebar:${first != null ? scopeKey(first.seg) : "root"}`),
-        collapsed: undefined,
-        children: [...sharedChildren, variantedNode]
-    };
-}
-function buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent, scopePrefix) {
-    if (!tabsPresent) {
-        // When no tabs exist but variants do, wrap variant-scoped segments
-        // in a VariantedNode and include non-variant segments alongside it.
-        const variants = uniqueDetails(scopeSegs, "variant");
-        if (variants.length > 1) {
-            const sharedSegs = scopeSegs.filter((s) => s.seg.variant == null);
-            const variantedNode = buildVariantedNode(ctx, variants, scopeSegs, scopePrefix);
-            if (sharedSegs.length > 0) {
-                const sharedChildren = buildSidebarRootChildren(ctx, sharedSegs, scopePrefix);
-                const first = scopeSegs[0];
-                return {
-                    type: "sidebarRoot",
-                    id: ctx.nodeId(`sidebar:${first != null ? scopeKey(first.seg) : "root"}`),
-                    collapsed: undefined,
-                    children: [...sharedChildren, variantedNode]
-                };
-            }
-            return variantedNode;
-        }
-        return buildSidebarRoot(ctx, scopeSegs, scopePrefix);
-    }
-    // Group this scope's segments by tab.
-    const tabDetails = uniqueDetails(scopeSegs, "tab");
-    const children = tabDetails.map((tab) => {
-        const tabType = metaStr(tab.metadata, "tab_type");
-        // The tab slug ACCUMULATES the enclosing scope prefix (basepath/product/
-        // version) and appends the tab segment, mirroring the canonical V1->V2
-        // converter (`SlugGenerator.apply`, which appends the tab onto the
-        // version/product slug). Rooting at the empty slug instead would drop
-        // the product/version prefix, breaking parity with v2's tab/breadcrumb
-        // slugs AND breaking default-version elision: the tab node's slug would
-        // not start with the version slug, so `toDefaultSlug` (the prune window)
-        // would skip it. Because `scopePrefix` already carries the FULL version
-        // segment, `{...}/{version}/{tab}` still starts with the version slug and
-        // stays inside the prune window (see {@link structuralNodeSlug}).
-        // V2's SlugGenerator.set() treats a tab slug that starts with the
-        // version slug as a fullSlug (absolute path) and uses it as-is.
-        // Without this check, scopeSlugPrefix joins version + tab producing
-        // a doubled prefix (e.g. "2026-02-09/2026-02-09").
-        const rawTabSlug = detailSlug(tab);
-        const versionDetail = scopeSegs[0]?.seg.version;
-        const versionSlugStr = versionDetail != null ? detailSlug(versionDetail) : undefined;
-        const tabSlug = versionSlugStr != null &&
-            rawTabSlug !== "" &&
-            (rawTabSlug === versionSlugStr || rawTabSlug.startsWith(versionSlugStr + "/"))
-            ? asSlug(rawTabSlug)
-            : asSlug(scopeSlugPrefix(scopePrefix, tab));
-        if (tabType === "link") {
-            return {
-                type: "link",
-                id: ctx.nodeId(`link:${metaStr(tab.metadata, "url") ?? tabSlug}`),
-                collapsed: undefined,
-                title: tab.displayName,
-                icon: tab.icon ?? undefined,
-                url: FernNavigation.Url(metaStr(tab.metadata, "url") ?? ""),
-                target: metaStr(tab.metadata, "target")
-            };
-        }
-        if (tabType === "changelog") {
-            const tabSegs = scopeSegs.filter((s) => s.seg.tab?.id === tab.id);
-            const changelogSeg = tabSegs.find((s) => metaStr(s.seg.metadata, "type") === "changelog");
-            if (changelogSeg != null) {
-                // Root the changelog content at the SCOPE prefix (not `tabSlug`).
-                // For a changelog tab the tab's own segment IS the changelog
-                // section, and `changelogNode` -> `structuralNodeSlug` already
-                // appends that section onto the prefix. So passing `scopePrefix`
-                // yields `{...}/{changelog}` — the same accumulated slug as
-                // `tabSlug` (and as v2). Passing `tabSlug` here would append the
-                // changelog segment twice (`{...}/changelog/changelog`).
-                return changelogNode(ctx, changelogSeg, scopePrefix);
-            }
-            // Fallback: empty changelog node for the tab
-            return {
-                type: "changelog",
-                ...withMetadataDefaults({
-                    id: ctx.nodeId(`changelog:${tabSlug}`),
-                    title: tab.displayName,
-                    slug: tabSlug,
-                    icon: tab.icon ?? undefined,
-                    hidden: tab.hidden,
-                    viewers: toViewers(tab.viewers)
-                }),
-                overviewPageId: undefined,
-                noindex: undefined,
-                children: []
-            };
-        }
-        // Default: regular tab
-        const tabSegs = scopeSegs.filter((s) => s.seg.tab?.id === tab.id);
-        const metaPointsTo = metaStr(tab.metadata, "pointsTo");
-        return {
-            type: "tab",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`tab:${tabSlug}`),
-                title: tab.displayName,
-                slug: tabSlug,
-                icon: tab.icon ?? undefined,
-                hidden: tab.hidden,
-                viewers: toViewers(tab.viewers)
-            }),
-            pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : undefined,
-            // Structural sections under this tab are rooted at the TAB slug
-            // (`{...}/{version}/{tab}`) so their slugs nest under the tab
-            // (matching v2) while still starting with the version slug, keeping
-            // the subtree inside the default-version prune window (see
-            // {@link structuralNodeSlug}).
-            // Changelog sidebar children use the product/version prefix — v2
-            // roots changelogs at the scope level, not under the tab.
-            child: buildSidebarRootWithVariants(ctx, tabSegs, tabSlug, scopePrefix)
-        };
-    });
-    const first = scopeSegs[0];
-    return {
-        type: "tabbed",
-        id: ctx.nodeId(`tabbed:${first != null ? scopeKey(first.seg) : "root"}`),
-        collapsed: undefined,
-        children
-    };
-}
-function buildUnversioned(ctx, scopeSegs, scopePrefix, tabsPresent) {
-    const first = scopeSegs[0];
-    return {
-        type: "unversioned",
-        id: ctx.nodeId(`unversioned:${first?.seg.product?.id ?? "root"}`),
-        collapsed: undefined,
-        landingPage: buildLandingPage(ctx, scopeSegs),
-        // The enclosing scope prefix (product slug, or rootSlug at the top
-        // level) roots structural sections so they share the scope's slug
-        // namespace.
-        child: buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent, scopePrefix)
-    };
-}
-/**
- * Merge shared (tab-level) sections from sibling versions into the default
- * version's segment list. A section is considered "shared" when its section
- * path does NOT start with any version slug — indicating it was authored at
- * the tab level and the publish transform assigned it to only one version.
- */
-function mergeSharedSections(defaultSegs, allScoped, defaultVersion, versionSlugs) {
-    // Build a map of the default version's tabs by displayName for
-    // cross-version matching. Tab slugs can't be used because the "default"
-    // tab's slug equals the version slug (e.g. "2026-02-09" vs "2025-04-21"
-    // for the same logical "Documentation" tab across versions).
-    const defaultTabsByName = new Map();
-    for (const s of defaultSegs) {
-        if (s.seg.tab != null) {
-            const tabName = s.seg.tab.displayName;
-            if (!defaultTabsByName.has(tabName)) {
-                defaultTabsByName.set(tabName, s.seg.tab);
-            }
-        }
-    }
-    // Collect section paths already present in the default version.
-    const existingSections = new Set(defaultSegs.filter((s) => metaStr(s.seg.metadata, "type") === "section").map((s) => s.seg.section));
-    // Merged sections must sort AFTER all native default segments so they
-    // appear in a trailing sidebarGroup (after non-collapsible sections like
-    // "Getting Started", "Dev Tools", "Capabilities") matching v2 ordering.
-    const maxSortOrder = defaultSegs.reduce((max, s) => Math.max(max, s.seg.sortOrder), 0);
-    let nextSortOrder = maxSortOrder + 1;
-    const merged = [...defaultSegs];
-    for (const s of allScoped) {
-        if (s.seg.version?.id === defaultVersion.id) {
-            continue;
-        }
-        const type = metaStr(s.seg.metadata, "type");
-        if (type !== "section") {
-            continue;
-        }
-        const sectionPath = s.seg.section;
-        // Skip version-specific sections (path starts with a version slug).
-        if (versionSlugs.some((vs) => sectionPath === vs || sectionPath.startsWith(vs + "/"))) {
-            continue;
-        }
-        // Skip if the default version already has this section.
-        if (existingSections.has(sectionPath)) {
-            continue;
-        }
-        // Match the source tab to the default version's corresponding tab
-        // by displayName (tab slugs differ across versions for the default tab).
-        const sourceTabName = s.seg.tab?.displayName ?? "";
-        const targetTab = defaultTabsByName.get(sourceTabName);
-        if (targetTab == null) {
-            continue;
-        }
-        // Re-map the segment's tab and version to the default version's.
-        // Strip childIndex from metadata so merged sections don't sort before
-        // native sections in the annotated interleave step, and assign a
-        // sortOrder after all native segments to place them in the trailing
-        // sidebarGroup.
-        const metadata = s.seg.metadata != null ? { ...s.seg.metadata, childIndex: undefined } : s.seg.metadata;
-        merged.push({
-            seg: {
-                ...s.seg,
-                tab: targetTab,
-                version: defaultVersion,
-                sortOrder: nextSortOrder++,
-                metadata
-            },
-            nav: s.nav
-        });
-        existingSections.add(sectionPath);
-    }
-    return merged;
-}
-function buildVersioned(ctx, versions, scoped, rootSlug, productPrefix, skipSharedSectionMerge) {
-    // Collect version slugs for detecting version-prefixed section paths.
-    const versionSlugs = versions.map((v) => detailSlug(v)).filter((s) => s !== "");
-    const children = versions.map((version) => {
-        let versionSegs = scoped.filter((s) => s.seg.version?.id === version.id);
-        // Merge shared tab-level sections from sibling versions into the
-        // default version. The publish transform may assign tab-level content
-        // (sections without a version-prefixed path) to a single version;
-        // v2's monolith root includes them in every version's sidebar.
-        // Skipped for scoped roots: the scoped root only loads nav for a
-        // single route's scope, so merged sections carry the source version's
-        // fullPaths into the default tree, creating duplicate slugs that
-        // orphan the real version's pages in NodeCollector.
-        if (detailIsDefault(version) && !skipSharedSectionMerge) {
-            versionSegs = mergeSharedSections(versionSegs, scoped, version, versionSlugs);
-        }
-        const tabsPresent = uniqueDetails(versionSegs, "tab").length > 0;
-        const prefix = productPrefix != null ? productPrefix : rootSlug;
-        // The version node always carries its FULL versioned slug
-        // (`{basepath}/{product}/{version}`), even when it is the default
-        // version. This matches the canonical V1→V2 converter
-        // (`SlugGenerator.setVersionSlug`, which never elides the version
-        // segment) and is REQUIRED for default-version elision: `NodeCollector`
-        // prunes the default version by passing `node.slug` to
-        // `toDefaultSlug(pageSlug, productSlug, versionSlug)`, which strips the
-        // version segment from each page slug to produce the clean alias
-        // (`docs/astro/cli/v-1-42/overview` → `docs/astro/cli/overview`). If the
-        // default version's slug were collapsed to the product prefix
-        // (`versionSlug === productSlug`), `toDefaultSlug` would be a no-op and
-        // the elided slug would never enter the slugMap — so the clean URL 404s
-        // with `page-not-in-nav` on basepath (`/docs`) sites. (ADR-0014 #6.)
-        //
-        // `scopeSlugPrefix(rootSlug, version)` is NOT used here because it joins
-        // only the rootSlug + version segment (dropping the product prefix);
-        // joining the resolved `prefix` (product prefix, or rootSlug when
-        // version-less) with the version's own slug segment yields the correct
-        // fully-qualified slug.
-        const versionSegment = detailSlug(version);
-        const slug = versionSegment !== "" ? FernNavigation.slugjoin(asSlug(prefix), versionSegment) : asSlug(prefix);
-        const node = {
-            type: "version",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`version:${slug}`),
-                title: version.displayName,
-                slug: asSlug(slug),
-                icon: version.icon ?? undefined,
-                hidden: version.hidden,
-                viewers: toViewers(version.viewers)
-            }),
-            default: detailIsDefault(version),
-            versionId: FernNavigation.VersionId(version.id),
-            availability: undefined,
-            landingPage: buildLandingPage(ctx, versionSegs),
-            announcement: undefined,
-            pointsTo: metaStr(version.metadata, "pointsTo") != null
-                ? pointsToSlug(metaStr(version.metadata, "pointsTo"))
-                : undefined,
-            // The version's full slug roots structural sections so the whole
-            // version subtree stays inside the default-version prune window.
-            child: buildTabbedOrSidebar(ctx, versionSegs, tabsPresent, asSlug(slug))
-        };
-        if (node.default) {
-            markDefaultVersionCanonicalSlugs(node, productPrefix != null ? asSlug(productPrefix) : rootSlug, node.slug);
-        }
-        return node;
-    });
-    // Cross-version canonical slug deduplication (V2 parity).
-    // V2's migrator deduplicates pages across versions using a title-based
-    // disambiguation key. Without this, non-default version pages that have
-    // a title-equivalent in the default version appear as separate sitemap
-    // entries (e.g. `/2024-12-23/evaluation/overview` alongside the default
-    // `/evaluation/overview`).
-    markCrossVersionCanonicalSlugs(children);
-    return {
-        type: "versioned",
-        id: ctx.nodeId(`versioned:${productPrefix ?? "root"}`),
-        collapsed: undefined,
-        children
-    };
-}
-function markDefaultVersionCanonicalSlugs(node, pruneSlug, versionSlug) {
-    FernNavigation.traverseDF(node, (child) => {
-        if (FernNavigation.hasMetadata(child)) {
-            const canonicalSlug = FernNavigation.toDefaultSlug(child.canonicalSlug ?? child.slug, pruneSlug, versionSlug);
-            if (canonicalSlug !== child.slug) {
-                child.canonicalSlug = canonicalSlug;
-            }
-        }
-        if (FernNavigation.hasRedirect(child)) {
-            child.pointsTo = FernNavigation.toDefaultSlug(child.pointsTo, pruneSlug, versionSlug);
-        }
-        return;
-    });
-}
-/**
- * Find parents after the innermost version node (unversioned ancestors).
- */
-function unversionedParents(parents) {
-    let versionIdx = -1;
-    for (let i = parents.length - 1; i >= 0; i--) {
-        if (parents[i].type === "version") {
-            versionIdx = i;
-            break;
-        }
-    }
-    return versionIdx >= 0 ? parents.slice(versionIdx + 1) : parents;
-}
-/**
- * Build dedup keys for a page node, mirroring V2's `#getAndSetCanonicalSlug`.
- * V2 uses multiple keys per node so ANY match deduplicates:
- *   - `pageId` / `overviewPageId` — content-addressable, same across versions
- *   - API-specific key (`api:endpoint:METHOD:ID`) — for API leaf nodes
- *   - title disambiguation key — structural fallback using parent titles
- */
-function crossVersionDedupKeys(node, parents) {
-    const keys = [];
-    const uParents = unversionedParents(parents);
-    // 1. Content-ID key (pageId or overviewPageId)
-    const pid = FernNavigation.getPageId(node);
-    if (pid != null) {
-        keys.push(`pid:${pid}`);
-    }
-    // 2. API-specific key for endpoints/websockets/webhooks/grpc/graphql
-    if (node.type === "endpoint" ||
-        node.type === "webSocket" ||
-        node.type === "webhook" ||
-        node.type === "grpc" ||
-        node.type === "graphql") {
-        const apiParentTitles = uParents
-            .filter((p) => p.type === "apiReference")
-            .map((p) => p.title.replaceAll(" ", ""));
-        const apiPrefix = apiParentTitles.join(":");
-        if (node.type === "endpoint") {
-            keys.push(`${apiPrefix}:api:endpoint:${node.method}:${node.endpointId}`);
-        }
-        else if (node.type === "webSocket") {
-            keys.push(`${apiPrefix}:api:websocket:${node.webSocketId}`);
-        }
-        else if (node.type === "webhook") {
-            keys.push(`${apiPrefix}:api:webhook:${node.method}:${node.webhookId}`);
-        }
-        else if (node.type === "grpc") {
-            keys.push(`${apiPrefix}:api:grpc:${node.method}:${node.grpcId}`);
-        }
-        else if (node.type === "graphql") {
-            keys.push(`${apiPrefix}:api:graphql:${node.id}`);
-        }
-    }
-    // 3. Title disambiguation key (structural fallback)
-    const parentTitles = [];
-    for (const p of uParents) {
-        if (FernNavigation.hasMetadata(p)) {
-            parentTitles.push(p.title);
-        }
-    }
-    keys.push([...parentTitles, node.title].join("###"));
-    return keys;
-}
-function routeToLandingPage(ctx, route) {
-    if (route == null || route.type !== "markdown" || route.fullPath == null) {
-        return undefined;
-    }
-    const md = route.metadata;
-    const pageId = metaStr(md, "pageId");
-    if (pageId == null) {
-        return undefined;
-    }
-    const slug = ctx.contentSlug(route.fullPath);
-    return {
-        type: "landingPage",
-        ...withMetadataDefaults({
-            id: ctx.nodeId(`landing:${slug}`),
-            title: metaStr(md, "title") ?? "",
-            slug,
-            icon: metaStr(md, "icon"),
-            hidden: route.hidden,
-            authed: metaBool(md, "authed"),
-            viewers: toViewers(metaStrArr(md, "viewers")),
-            orphaned: metaBool(md, "orphaned"),
-            featureFlags: metaFeatureFlags(md)
-        }),
-        pageId: FernNavigation.PageId(pageId),
-        noindex: metaBool(md, "noindex")
-    };
-}
-/**
- * Build a LandingPageNode from the explicit landing-page segment emitted by
- * the publish transform. This avoids confusing ordinary loose tabRoot pages
- * with root/product/version landing pages.
- */
-function buildLandingPage(ctx, scopeSegs) {
-    const landingSegment = scopeSegs.find((s) => metaStr(s.seg.metadata, "type") === "tabRoot" && metaBool(s.seg.metadata, "landingPage") === true);
-    return routeToLandingPage(ctx, landingSegment?.nav.find((route) => route.type === "markdown"));
-}
-/**
- * After default-version canonical slugs are marked, propagate them across
- * ALL versions using a global first-come-first-served approach (matching V2).
- * V2's migrator uses a single `#canonicalSlugs` map across the entire tree,
- * so the first version to register a key wins. This deduplicates pages both
- * default→non-default AND across non-default versions (e.g. v2025-04-21
- * and v2024-12-23 sharing the same pageId).
- */
-function markCrossVersionCanonicalSlugs(versionNodes) {
-    const keyToCanonical = new Map();
-    // Process versions in order (default first, then non-default in tree order).
-    // The first version to register a key wins — matching V2's DFS traversal
-    // which processes the default version before others.
-    const sorted = [...versionNodes].sort((a, b) => {
-        if (a.default !== b.default) {
-            return a.default ? -1 : 1;
-        }
-        return 0;
-    });
-    for (const version of sorted) {
-        FernNavigation.traverseDF(version, (child, parents) => {
-            if (FernNavigation.hasMetadata(child) && FernNavigation.isPage(child)) {
-                const keys = crossVersionDedupKeys(child, parents);
-                let matched = false;
-                for (const key of keys) {
-                    const canonical = keyToCanonical.get(key);
-                    if (canonical != null && !version.default) {
-                        child.canonicalSlug = canonical;
-                        matched = true;
-                        break;
-                    }
-                }
-                if (!matched) {
-                    const canonical = child.canonicalSlug ?? child.slug;
-                    for (const key of keys) {
-                        if (!keyToCanonical.has(key)) {
-                            keyToCanonical.set(key, canonical);
-                        }
-                    }
-                }
-            }
-        });
-    }
-}
-function buildProductGroup(ctx, products, scoped, rootSlug, skipSharedSectionMerge) {
-    const children = products.map((product) => {
-        const productSegs = scoped.filter((s) => s.seg.product?.id === product.id);
-        const versions = uniqueDetails(productSegs, "version");
-        const tabsPresent = uniqueDetails(productSegs, "tab").length > 0;
-        const productPrefix = scopeSlugPrefix(rootSlug, product);
-        // ProductChild is VersionedNode | UnversionedNode — a version-less
-        // product wraps its sidebar/tabs in an UnversionedNode.
-        const productChild = versions.length > 0
-            ? buildVersioned(ctx, versions, productSegs, rootSlug, productPrefix, skipSharedSectionMerge)
-            : buildUnversioned(ctx, productSegs, asSlug(productPrefix), tabsPresent);
-        const node = {
-            type: "product",
-            ...withMetadataDefaults({
-                id: ctx.nodeId(`product:${productPrefix}`),
-                title: product.displayName,
-                slug: asSlug(detailIsDefault(product) ? rootSlug : productPrefix),
-                icon: product.icon ?? undefined,
-                hidden: product.hidden,
-                viewers: toViewers(product.viewers)
-            }),
-            default: detailIsDefault(product),
-            // `product.id` is the content-addressed STORAGE hash (the segment
-            // key). `productId` is the SEMANTIC identifier search/UI key off
-            // (the product-scoped search filter does `product.title:${productId}`,
-            // so it must equal the product title). v2 carries the display name
-            // here; sourcing it from the hash makes that filter match nothing.
-            productId: FernNavigation.ProductId(product.displayName),
-            subtitle: metaStr(product.metadata, "subtitle") ?? "",
-            image: metaStr(product.metadata, "image") != null
-                ? FernNavigation.FileId(metaStr(product.metadata, "image"))
-                : undefined,
-            announcement: undefined,
-            pointsTo: metaStr(product.metadata, "pointsTo") != null
-                ? pointsToSlug(metaStr(product.metadata, "pointsTo"))
-                : undefined,
-            child: productChild
-        };
-        return node;
-    });
-    return {
-        type: "productgroup",
-        id: ctx.nodeId("productgroup"),
-        collapsed: undefined,
-        landingPage: buildLandingPage(ctx, scoped.filter((s) => s.seg.product == null)),
-        children
-    };
-}
-// (root keeps the bare "root" id; it is the single tree root.)
-//# sourceMappingURL=ledger-root-builder.js.map