@fern-api/fdr-sdk 1.2.20-5945c5cfaa → 1.2.20-5f94cb7f17

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

@@ -0,0 +1,846 @@
+import * as FernNavigation from "./index.js";
+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, ""));
+}
+/** 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;
+}
+/** 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;
+}
+/** 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));
+}
+function detailSlug(detail) {
+    return metaStr(detail.metadata, "slug") ?? "";
+}
+function detailIsDefault(detail) {
+    return metaBool(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, ...rest } = base;
+    return {
+        ...rest,
+        canonicalSlug: undefined,
+        authed: 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: undefined,
+        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,
+                    viewers
+                }),
+                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: undefined
+            };
+            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,
+        viewers
+    });
+    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: undefined,
+            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: undefined
+        };
+    }
+    if (route.type === "asyncapi") {
+        const webSocketId = metaStr(md, "webSocketId");
+        if (webSocketId == null) {
+            return undefined;
+        }
+        return {
+            type: "webSocket",
+            ...meta,
+            webSocketId: FernNavigation.WebSocketId(webSocketId),
+            apiDefinitionId,
+            availability: undefined,
+            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: undefined
+        };
+    }
+    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),
+            apiDefinitionId,
+            availability: undefined,
+            playground: undefined
+        };
+    }
+    return undefined;
+}
+/**
+ * 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) {
+    return metaStr(metadata, "apiDefinitionId");
+}
+/** 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"));
+}
+function sectionNode(ctx, scoped, sectionChildren) {
+    const { seg, nav } = scoped;
+    const overview = overviewRoute(nav);
+    const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : undefined;
+    const slug = ctx.contentSlug(overview?.fullPath ?? seg.section);
+    const leafChildren = nav
+        .map((r) => artifactToNode(ctx, r))
+        .filter((n) => n != null);
+    return {
+        type: "section",
+        ...withMetadataDefaults({
+            id: ctx.nodeId(`section:${slug}`),
+            title: metaStr(seg.metadata, "title") ?? "",
+            slug,
+            icon: metaStr(seg.metadata, "icon"),
+            hidden: seg.hidden,
+            viewers: toViewers(metaStrArr(seg.metadata, "viewers"))
+        }),
+        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
+        noindex: undefined,
+        collapsible: metaBool(seg.metadata, "collapsible"),
+        collapsedByDefault: metaBool(seg.metadata, "collapsedByDefault"),
+        availability: undefined,
+        pointsTo: undefined,
+        children: [...leafChildren, ...sectionChildren]
+    };
+}
+/**
+ * Collect nav routes from the apiReference segment itself plus all descendant
+ * apiPackage segments. The publish transform creates a separate segment for
+ * each apiPackage (e.g. section "rest-api/store"), so the apiReference segment
+ * (section "rest-api") only contains its overview page. This gathers routes
+ * from the full subtree.
+ */
+function collectDescendantApiNav(root, scopeSegs) {
+    const rootSection = root.seg.section;
+    const prefix = rootSection === "" ? "" : `${rootSection}/`;
+    const routes = [...root.nav];
+    for (const s of scopeSegs) {
+        if (s === root) {
+            continue;
+        }
+        const type = metaStr(s.seg.metadata, "type");
+        if (type !== "apiPackage") {
+            continue;
+        }
+        if (s.seg.section === rootSection || s.seg.section.startsWith(prefix)) {
+            routes.push(...s.nav);
+        }
+    }
+    return routes;
+}
+function apiReferenceNode(ctx, scoped, scopeSegs) {
+    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 the first child's parent path.
+    const slug = ctx.contentSlug(overview?.fullPath ?? nav[0]?.fullPath ?? seg.section);
+    // Collect endpoint/webhook nav routes from this segment AND all descendant
+    // apiPackage segments. The publish transform creates separate segments for
+    // each apiPackage (e.g. "rest-api/store", "rest-api/plant"), so the
+    // apiReference segment itself only has its overview page. We gather routes
+    // from the full subtree so findNode and the slug map can locate all API
+    // leaf pages.
+    const allNav = collectDescendantApiNav(scoped, scopeSegs);
+    const children = allNav
+        .map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, apiDefinitionId))
+        .filter((node) => node != null);
+    return {
+        type: "apiReference",
+        ...withMetadataDefaults({
+            id: ctx.nodeId(`api:${slug}`),
+            title: metaStr(seg.metadata, "title") ?? "",
+            slug,
+            icon: metaStr(seg.metadata, "icon"),
+            hidden: seg.hidden,
+            viewers: toViewers(metaStrArr(seg.metadata, "viewers"))
+        }),
+        apiDefinitionId: FernNavigation.ApiDefinitionId(apiDefinitionId),
+        availability: undefined,
+        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
+        noindex: undefined,
+        paginated: true,
+        showErrors: metaBool(seg.metadata, "showErrors"),
+        hideTitle: metaBool(seg.metadata, "hideTitle"),
+        pointsTo: undefined,
+        children,
+        changelog: undefined,
+        playground: undefined,
+        postmanCollectionUrl: undefined
+    };
+}
+function changelogNode(ctx, scoped) {
+    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,
+                viewers: toViewers(metaStrArr(r.metadata, "viewers"))
+            }),
+            pageId: FernNavigation.PageId(metaStr(r.metadata, "pageId") ?? ""),
+            noindex: undefined,
+            date: dateStr ?? "",
+            tags: undefined
+        };
+        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);
+    }
+    const baseSlug = ctx.contentSlug(overview?.fullPath ?? seg.section);
+    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,
+            viewers: toViewers(metaStrArr(seg.metadata, "viewers"))
+        }),
+        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
+        noindex: undefined,
+        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) {
+    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;
+        }
+        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");
+        if (type === "apiReference" || type === "apiPackage") {
+            return apiReferenceNode(ctx, s, scopeSegs);
+        }
+        if (type === "changelog") {
+            return changelogNode(ctx, s);
+        }
+        // section (or unrecognised) → recurse for nested sections.
+        return sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, s.seg.section));
+    });
+}
+// ── build a sidebarRoot for a single scope ─────────────────────────────────
+/**
+ * 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) {
+    const ordered = [...scopeSegs].sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
+    const sectionPaths = new Set(ordered.map((s) => s.seg.section));
+    const flat = [];
+    for (const s of ordered) {
+        const type = metaStr(s.seg.metadata, "type");
+        const sec = s.seg.section;
+        if (type === "tabRoot" || sec === "") {
+            // Top-level pages/links of this sidebar root, in nav order.
+            for (const r of s.nav) {
+                const node = artifactToNode(ctx, r);
+                if (node != null) {
+                    flat.push(node);
+                }
+            }
+            continue;
+        }
+        // Emit segments at root level if they are depth-0 OR orphaned (nearest
+        // existing ancestor is root ""). Deeper segments with existing parents
+        // are attached via buildSectionTree recursion.
+        const parent = parentSectionPath(sec);
+        const isRootLevel = parent === "" || (!sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === "");
+        if (isRootLevel) {
+            if (type === "apiReference" || type === "apiPackage") {
+                flat.push(apiReferenceNode(ctx, s, scopeSegs));
+            }
+            else if (type === "changelog") {
+                flat.push(changelogNode(ctx, s));
+            }
+            else {
+                flat.push(sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, sec)));
+            }
+        }
+    }
+    return groupSidebarRootChildren(ctx, flat);
+}
+/**
+ * `SidebarRootChild` only permits SidebarGroupNode / ApiReferenceNode /
+ * SectionNode / VariantedNode. Sections and apiReferences pass through; any
+ * contiguous run of pages / links / changelogs is wrapped into a
+ * SidebarGroupNode (mirroring the V1→latest migration).
+ */
+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 === "section" || child.type === "apiReference" || child.type === "varianted") {
+            flushRun();
+            out.push(child);
+        }
+        else {
+            run.push(child);
+        }
+    }
+    flushRun();
+    return out;
+}
+function buildSidebarRoot(ctx, scopeSegs) {
+    const first = scopeSegs[0];
+    return {
+        type: "sidebarRoot",
+        id: ctx.nodeId(`sidebar:${first != null ? scopeKey(first.seg) : "root"}`),
+        collapsed: undefined,
+        children: buildSidebarRootChildren(ctx, scopeSegs)
+    };
+}
+// ── public entrypoint ───────────────────────────────────────────────────────
+/**
+ * Build a full (un-pruned) `RootNode` from the decomposed ledger model.
+ */
+export function buildFullRootFromSegments(options) {
+    const { basePath, title, segments, navBySegment } = 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(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);
+    }
+    else if (versions.length > 0) {
+        child = buildVersioned(ctx, versions, scoped, rootSlug, undefined);
+    }
+    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;
+    }
+    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 logical slug identity (not DB id).
+ * Old publishes can leave stale detail rows that share the same slug
+ * but lack metadata fields (e.g. `pointsTo`). When duplicates exist
+ * we prefer the detail with the most complete metadata.
+ */
+function uniqueDetails(scoped, dim) {
+    const bySlug = new Map();
+    for (const s of scoped) {
+        const d = s.seg[dim];
+        if (d == null) {
+            continue;
+        }
+        const slug = detailSlug(d);
+        const existing = bySlug.get(slug);
+        if (existing == null) {
+            bySlug.set(slug, d);
+        }
+        else if (metaStr(d.metadata, "pointsTo") != null && metaStr(existing.metadata, "pointsTo") == null) {
+            bySlug.set(slug, d);
+        }
+    }
+    return [...bySlug.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);
+}
+function buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent) {
+    if (!tabsPresent) {
+        return buildSidebarRoot(ctx, scopeSegs);
+    }
+    // Group this scope's segments by tab.
+    const tabDetails = uniqueDetails(scopeSegs, "tab");
+    const children = tabDetails.map((tab) => {
+        const tabType = metaStr(tab.metadata, "tab_type");
+        const tabSlug = asSlug(scopeSlugPrefix(FernNavigation.Slug(""), 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: undefined
+            };
+        }
+        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) {
+                return changelogNode(ctx, changelogSeg);
+            }
+            // 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 ? ctx.contentSlug(metaPointsTo) : undefined,
+            child: buildSidebarRoot(ctx, tabSegs)
+        };
+    });
+    const first = scopeSegs[0];
+    return {
+        type: "tabbed",
+        id: ctx.nodeId(`tabbed:${first != null ? scopeKey(first.seg) : "root"}`),
+        collapsed: undefined,
+        children
+    };
+}
+function buildUnversioned(ctx, scopeSegs, rootSlug, tabsPresent) {
+    void rootSlug;
+    const first = scopeSegs[0];
+    return {
+        type: "unversioned",
+        id: ctx.nodeId(`unversioned:${first?.seg.product?.id ?? "root"}`),
+        collapsed: undefined,
+        landingPage: undefined,
+        child: buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent)
+    };
+}
+function buildVersioned(ctx, versions, scoped, rootSlug, productPrefix) {
+    const children = versions.map((version) => {
+        const versionSegs = scoped.filter((s) => s.seg.version?.id === version.id);
+        const tabsPresent = uniqueDetails(versionSegs, "tab").length > 0;
+        const prefix = productPrefix != null ? productPrefix : rootSlug;
+        const slug = version.metadata != null && detailIsDefault(version) ? prefix : scopeSlugPrefix(rootSlug, version);
+        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: undefined,
+            announcement: undefined,
+            pointsTo: metaStr(version.metadata, "pointsTo") != null
+                ? ctx.contentSlug(metaStr(version.metadata, "pointsTo"))
+                : undefined,
+            child: buildTabbedOrSidebar(ctx, versionSegs, tabsPresent)
+        };
+        return node;
+    });
+    return {
+        type: "versioned",
+        id: ctx.nodeId(`versioned:${productPrefix ?? "root"}`),
+        collapsed: undefined,
+        children
+    };
+}
+function buildProductGroup(ctx, products, scoped, rootSlug) {
+    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)
+            : buildUnversioned(ctx, productSegs, rootSlug, 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),
+            productId: FernNavigation.ProductId(product.id),
+            subtitle: metaStr(product.metadata, "subtitle") ?? "",
+            image: undefined,
+            announcement: undefined,
+            pointsTo: metaStr(product.metadata, "pointsTo") != null
+                ? ctx.contentSlug(metaStr(product.metadata, "pointsTo"))
+                : undefined,
+            child: productChild
+        };
+        return node;
+    });
+    return {
+        type: "productgroup",
+        id: ctx.nodeId("productgroup"),
+        collapsed: undefined,
+        landingPage: undefined,
+        children
+    };
+}
+// (root keeps the bare "root" id; it is the single tree root.)
+//# sourceMappingURL=ledger-root-builder.js.map