@fern-api/fdr-sdk 1.2.40-bcfd2ff480 → 1.2.41-02971594aa

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

@@ -0,0 +1,1923 @@
+import * as FernNavigation from "./index.js";
+const STRUCTURAL_SEGMENT_TYPES = new Set([
+    "section",
+    "apiReference",
+    "apiPackage",
+    "changelog"
+]);
+const API_NODE_SEGMENT_TYPES = new Set(["apiReference", "apiPackage"]);
+const INFRA_SEGMENT_TYPES = new Set(["files", "redirects"]);
+/** @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 = STRUCTURAL_SEGMENT_TYPES.has(seg.metadata.type)
+        ? 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.
+ * The matched types (apiReference, apiPackage, changelog) are the
+ * subset of {@link StructuralSegmentType} that carry an apiDefinitionId.
+ */
+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 (API_NODE_SEGMENT_TYPES.has(type ?? "")) {
+            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=="", !STRUCTURAL_SEGMENT_TYPES)
+    //   │      → 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-structural segments at section path "".
+        // Structural types need their own node builders in (B)/(C) even when
+        // their section path is "" (which happens with skip-slug: true).
+        if (type === "tabRoot" || (sec === "" && !STRUCTURAL_SEGMENT_TYPES.has(type ?? ""))) {
+            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) === "");
+        // Skip depth-0 sections already adopted by the root section wrapper (B),
+        // but NOT structural types with sec="" (skip-slug). buildSectionTree
+        // filters out sec="" segments (line 1249), so they wouldn't be adopted
+        // and must be emitted here directly.
+        if (isRootLevel && hasRootSection && sec !== "") {
+            continue;
+        }
+        if (isRootLevel) {
+            let node;
+            if (API_NODE_SEGMENT_TYPES.has(type ?? "")) {
+                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 !INFRA_SEGMENT_TYPES.has(t ?? "");
+    })
+        .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 at the TAB slug (`tabSlug`), not the bare
+                // scope prefix. Tab-level changelogs have an empty section path
+                // (the publish transform strips the tab segment because
+                // `extractSlugSegment(tabSlug, tabSlug) === ""`), so
+                // `structuralNodeSlug(ctx, null, "", scopePrefix)` collapses to
+                // just the scope prefix — which is the product/version slug.
+                // That slug collision causes the changelog node to replace the
+                // product node in NodeCollector's slug map, breaking structural
+                // redirects (the product slug renders changelog content instead
+                // of redirecting to the first docs page). Passing `tabSlug`
+                // yields the correct `{...}/{changelog}` structural slug.
+                return changelogNode(ctx, changelogSeg, tabSlug);
+            }
+            // 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