@fern-api/fdr-sdk 1.2.35-07f6dfd14f → 1.2.35-09eb5b04f6

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

@@ -0,0 +1,906 @@
+import * as FernNavigation from "./index.js";
+/** Zero-cost cast: trusts the transform pipeline wrote well-typed metadata. */
+const segMeta = (seg) => (seg.metadata ?? {});
+const routeMeta = (route) => (route.metadata ?? {});
+const detailMeta = (detail) => (detail.metadata ?? {});
+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, ""));
+}
+/** 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 all = [...(segMeta(seg).viewers ?? []), ...(seg.variant?.viewers ?? [])];
+    return all.length > 0 ? [...new Set(all)].map((v) => FernNavigation.RoleId(v)) : undefined;
+}
+function detailSlug(detail) {
+    return detailMeta(detail).slug ?? "";
+}
+function detailIsDefault(detail) {
+    return detailMeta(detail).default ?? false;
+}
+/** Resolve a detail's `pointsTo` into a basepath-prefixed slug, or undefined. */
+function pointsToSlug(ctx, meta) {
+    return meta.pointsTo != null ? ctx.contentSlug(meta.pointsTo) : undefined;
+}
+// ── 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 = routeMeta(route);
+    const slug = ctx.contentSlug(route.fullPath ?? "");
+    switch (route.type) {
+        case "markdown": {
+            if (md.isOverview) {
+                return undefined;
+            }
+            return {
+                type: "page",
+                ...withMetadataDefaults({
+                    id: ctx.nodeId(`page:${slug}`),
+                    title: md.title ?? "",
+                    slug,
+                    icon: md.icon,
+                    hidden: route.hidden,
+                    viewers: toViewers(md.viewers)
+                }),
+                pageId: FernNavigation.PageId(md.pageId ?? ""),
+                noindex: md.noindex,
+                availability: undefined
+            };
+        }
+        case "link": {
+            return {
+                type: "link",
+                id: ctx.nodeId(`link:${md.url ?? route.fullPath ?? ""}`),
+                collapsed: undefined,
+                title: md.title ?? "",
+                icon: md.icon,
+                url: FernNavigation.Url(md.url ?? ""),
+                target: undefined
+            };
+        }
+        // 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.
+        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, segmentApiDefId) {
+    const ctx = createBuildContext(basePath);
+    return apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefId);
+}
+function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefId) {
+    const md = routeMeta(route);
+    const slug = ctx.contentSlug(route.fullPath ?? "");
+    const base = {
+        ...withMetadataDefaults({
+            id: ctx.nodeId(`api-leaf:${slug}`),
+            title: md.title ?? "",
+            slug,
+            icon: md.icon,
+            hidden: route.hidden,
+            viewers: toViewers(md.viewers)
+        }),
+        apiDefinitionId: FernNavigation.ApiDefinitionId(md.apiDefinitionId ?? segmentApiDefId),
+        availability: undefined
+    };
+    switch (route.type) {
+        case "rest":
+            if (md.endpointId == null || md.method == null) {
+                return undefined;
+            }
+            return {
+                type: "endpoint",
+                ...base,
+                method: md.method,
+                endpointId: FernNavigation.EndpointId(md.endpointId),
+                isResponseStream: md.isResponseStream,
+                playground: undefined
+            };
+        case "webhook":
+            if (md.webhookId == null || md.method == null) {
+                return undefined;
+            }
+            return {
+                type: "webhook",
+                ...base,
+                method: md.method,
+                webhookId: FernNavigation.WebhookId(md.webhookId)
+            };
+        case "asyncapi":
+            if (md.webSocketId == null) {
+                return undefined;
+            }
+            return {
+                type: "webSocket",
+                ...base,
+                webSocketId: FernNavigation.WebSocketId(md.webSocketId),
+                playground: undefined
+            };
+        case "grpc":
+            if (md.grpcId == null || md.method == null) {
+                return undefined;
+            }
+            return {
+                type: "grpc",
+                ...base,
+                method: md.method,
+                grpcId: FernNavigation.GrpcId(md.grpcId)
+            };
+        case "graphql":
+            if (md.graphqlOperationId == null || md.operationType == null) {
+                return undefined;
+            }
+            return {
+                type: "graphql",
+                ...base,
+                operationType: md.operationType,
+                graphqlOperationId: FernNavigation.GraphQlOperationId(md.graphqlOperationId),
+                graphqlOperationIds: undefined,
+                playground: undefined
+            };
+        default:
+            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, segmentApiDefId) {
+    const ctx = createBuildContext(basePath);
+    return routes
+        .map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefId))
+        .filter((node) => node != null);
+}
+/** Read the apiDefinitionId off a segment's metadata, or undefined. */
+export function segmentApiDefinitionId(metadata) {
+    return metadata?.apiDefinitionId;
+}
+/** Find the overview artifact (isOverview) within a segment's nav, if any. */
+function overviewRoute(nav) {
+    for (const r of nav) {
+        if (r.type === "markdown") {
+            const meta = routeMeta(r);
+            if (meta.isOverview) {
+                return { route: r, meta };
+            }
+        }
+    }
+    return undefined;
+}
+function sectionNode(ctx, scoped, sectionChildren) {
+    const { seg, meta: sm, nav } = scoped;
+    const overview = overviewRoute(nav);
+    const overviewPageId = overview?.meta.pageId;
+    const slug = ctx.contentSlug(overview?.route.fullPath ?? seg.section);
+    const leafChildren = nav
+        .map((r) => artifactToNode(ctx, r))
+        .filter((n) => n != null);
+    const defaults = withMetadataDefaults({
+        id: ctx.nodeId(`section:${slug}`),
+        title: sm.title ?? "",
+        slug,
+        icon: sm.icon,
+        hidden: seg.hidden,
+        viewers: mergeVariantViewers(seg)
+    });
+    return {
+        type: "section",
+        ...defaults,
+        collapsed: sm.collapsed ?? defaults.collapsed,
+        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
+        noindex: undefined,
+        collapsible: sm.collapsible,
+        collapsedByDefault: sm.collapsedByDefault,
+        availability: undefined,
+        pointsTo: undefined,
+        children: [...leafChildren, ...sectionChildren]
+    };
+}
+/** 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 "";
+}
+/**
+ * Determine whether `sec` is a direct child of `parentPath`, accounting for
+ * orphaned segments whose parent section doesn't exist but whose nearest
+ * existing ancestor is `parentPath`.
+ */
+function isDirectChildOf(sec, parentPath, sectionPaths) {
+    const parent = parentSectionPath(sec);
+    if (parent === parentPath) {
+        return true;
+    }
+    // Orphaned: parent doesn't exist, adopt if nearest ancestor is parentPath.
+    return !sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === parentPath;
+}
+/**
+ * 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, sectionPaths) {
+    return scopeSegs
+        .filter((s) => s.meta.type === "apiPackage" && isDirectChildOf(s.seg.section, parentSection, sectionPaths))
+        .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, apiDefId, sectionPaths) {
+    const { nav } = scoped;
+    // Build leaf nodes from this segment's own nav routes (not descendants).
+    const rawLeafNodes = nav
+        .map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, apiDefId))
+        .filter((node) => node != null);
+    // Merge stream/non-stream endpoint pairs into EndpointPairNodes.
+    const leafNodes = mergeEndpointPairs(ctx, rawLeafNodes, nav);
+    // Build nested ApiPackageNodes from direct child apiPackage segments.
+    const childPackages = directChildApiPackages(scoped.seg.section, scopeSegs, sectionPaths);
+    const packageNodes = childPackages.map((child) => apiPackageChildNode(ctx, child, scopeSegs, apiDefId, sectionPaths));
+    // Interleave: leaf nodes first (in their nav sort order), then package nodes
+    // (in their segment sort order). This matches v2's structure where direct
+    // artifacts precede sub-packages.
+    return [...leafNodes, ...packageNodes];
+}
+/**
+ * Build an ApiPackageNode from an apiPackage segment, recursively nesting any
+ * deeper sub-packages.
+ */
+function apiPackageChildNode(ctx, scoped, scopeSegs, parentApiDefId, sectionPaths) {
+    const { seg, meta: sm, nav } = scoped;
+    const overview = overviewRoute(nav);
+    const overviewPageId = overview?.meta.pageId;
+    const apiDefId = sm.apiDefinitionId ?? parentApiDefId;
+    const slug = ctx.contentSlug(overview?.route.fullPath ?? nav[0]?.fullPath ?? seg.section);
+    const children = buildApiChildren(ctx, scoped, scopeSegs, apiDefId, sectionPaths);
+    return {
+        type: "apiPackage",
+        ...withMetadataDefaults({
+            id: ctx.nodeId(`api-pkg:${slug}`),
+            title: sm.title ?? "",
+            slug,
+            icon: sm.icon,
+            hidden: seg.hidden,
+            viewers: toViewers(sm.viewers)
+        }),
+        apiDefinitionId: FernNavigation.ApiDefinitionId(apiDefId),
+        availability: sm.availability,
+        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
+        noindex: undefined,
+        pointsTo: 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.
+ */
+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 md = routeMeta(route);
+        if (md.endpointPairKey != null && md.endpointId != null) {
+            endpointIdToPairKey.set(md.endpointId, md.endpointPairKey);
+        }
+    }
+    // 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;
+            const pairNode = {
+                id: ctx.nodeId(`endpoint-pair:${pairKey}`),
+                type: "endpointPair",
+                collapsed: undefined,
+                stream,
+                nonStream
+            };
+            result[existingIdx] = pairNode;
+        }
+    }
+    return result;
+}
+function apiReferenceNode(ctx, scoped, scopeSegs, sectionPaths) {
+    const { seg, meta: sm, nav } = scoped;
+    const overview = overviewRoute(nav);
+    const overviewPageId = overview?.meta.pageId;
+    const apiDefId = sm.apiDefinitionId ?? "";
+    const slug = ctx.contentSlug(overview?.route.fullPath ?? nav[0]?.fullPath ?? seg.section);
+    const children = buildApiChildren(ctx, scoped, scopeSegs, apiDefId, sectionPaths);
+    return {
+        type: "apiReference",
+        ...withMetadataDefaults({
+            id: ctx.nodeId(`api:${slug}`),
+            title: sm.title ?? "",
+            slug,
+            icon: sm.icon,
+            hidden: seg.hidden,
+            viewers: mergeVariantViewers(seg)
+        }),
+        apiDefinitionId: FernNavigation.ApiDefinitionId(apiDefId),
+        availability: undefined,
+        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
+        noindex: undefined,
+        paginated: true,
+        showErrors: sm.showErrors,
+        hideTitle: sm.hideTitle,
+        pointsTo: undefined,
+        children,
+        changelog: undefined,
+        playground: undefined,
+        postmanCollectionUrl: undefined
+    };
+}
+function changelogNode(ctx, scoped) {
+    const { seg, meta: sm, nav } = scoped;
+    const overview = overviewRoute(nav);
+    const overviewPageId = overview?.meta.pageId;
+    // 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 md = routeMeta(r);
+        const date = md.date != null ? new Date(md.date) : new Date(0);
+        const year = date.getUTCFullYear();
+        const month = date.getUTCMonth() + 1;
+        const entry = {
+            type: "changelogEntry",
+            ...withMetadataDefaults({
+                id: ctx.nodeId(`cl-entry:${r.fullPath ?? md.pageId ?? ""}`),
+                title: md.title ?? "",
+                slug: ctx.contentSlug(r.fullPath ?? ""),
+                icon: md.icon,
+                hidden: r.hidden,
+                viewers: toViewers(md.viewers)
+            }),
+            pageId: FernNavigation.PageId(md.pageId ?? ""),
+            noindex: undefined,
+            date: md.date ?? "",
+            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?.route.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: sm.title ?? "",
+            slug: baseSlug,
+            icon: sm.icon,
+            hidden: seg.hidden,
+            viewers: mergeVariantViewers(seg)
+        }),
+        overviewPageId: overviewPageId != null ? FernNavigation.PageId(overviewPageId) : undefined,
+        noindex: undefined,
+        children: years
+    };
+}
+/**
+ * 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, sectionPaths) {
+    const direct = scopeSegs
+        .filter((s) => {
+        const sec = s.seg.section;
+        return sec !== "" && s.meta.type !== "tabRoot" && isDirectChildOf(sec, parentPath, sectionPaths);
+    })
+        .sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
+    return direct.map((s) => {
+        const { type } = s.meta;
+        if (type === "apiReference" || type === "apiPackage") {
+            return apiReferenceNode(ctx, s, scopeSegs, sectionPaths);
+        }
+        if (type === "changelog") {
+            return changelogNode(ctx, s);
+        }
+        // section (or unrecognised) → recurse for nested sections.
+        return sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, s.seg.section, sectionPaths));
+    });
+}
+// ── 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 } = s.meta;
+        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.
+        if (isDirectChildOf(sec, "", sectionPaths)) {
+            if (type === "apiReference" || type === "apiPackage") {
+                flat.push(apiReferenceNode(ctx, s, scopeSegs, sectionPaths));
+            }
+            else if (type === "changelog") {
+                flat.push(changelogNode(ctx, s));
+            }
+            else {
+                flat.push(sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, sec, sectionPaths)));
+            }
+        }
+    }
+    return groupSidebarRootChildren(ctx, flat);
+}
+/**
+ * `SidebarRootChild` only permits SidebarGroupNode / ApiReferenceNode /
+ * SectionNode / VariantedNode.  Non-collapsible sections and apiReferences
+ * pass through as direct root children (rendered as static headings);
+ * collapsible sections, pages, links, and changelogs are wrapped into a
+ * SidebarGroupNode so they render via SidebarNavigationChild → collapsible
+ * (mirroring the V1→latest migration in NavigationConfigConverter).
+ */
+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 === false || (child.collapsible == null && child.collapsed === false))) {
+            // Match SidebarVariantedNode's isStaticHeader logic: a section
+            // is a static root heading only when explicitly non-collapsible
+            // or when collapsible is unset and collapsed is explicitly false.
+            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
+        .map((seg) => ({ seg, meta: segMeta(seg), nav: navBySegment.get(seg.segmentHash) ?? [] }))
+        // Infrastructure segments (files/redirects) are filtered server-side, but guard here too.
+        .filter((s) => s.meta.type !== "files" && s.meta.type !== "redirects");
+    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, 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;
+    }
+    return {
+        type: "root",
+        version: "v2",
+        ...withMetadataDefaults({
+            id: ctx.nodeId("root"),
+            title,
+            slug: rootSlug,
+            icon: undefined,
+            hidden: undefined
+        }),
+        roles: undefined,
+        pointsTo: rootPointsTo,
+        child
+    };
+}
+// ── 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 dm = detailMeta(d);
+        const slug = dm.slug ?? "";
+        const existing = bySlug.get(slug);
+        if (existing == null || (dm.pointsTo != null && existing.meta.pointsTo == null)) {
+            bySlug.set(slug, { detail: d, meta: dm });
+        }
+    }
+    return [...bySlug.values()].map((e) => e.detail).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 tm = detailMeta(tab);
+        const tabSlug = asSlug(scopeSlugPrefix(FernNavigation.Slug(""), tab));
+        if (tm.tab_type === "link") {
+            return {
+                type: "link",
+                id: ctx.nodeId(`link:${tm.url ?? tabSlug}`),
+                collapsed: undefined,
+                title: tab.displayName,
+                icon: tab.icon ?? undefined,
+                url: FernNavigation.Url(tm.url ?? ""),
+                target: undefined
+            };
+        }
+        if (tm.tab_type === "changelog") {
+            const tabSegs = scopeSegs.filter((s) => s.seg.tab?.id === tab.id);
+            const changelogSeg = tabSegs.find((s) => s.meta.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);
+        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: pointsToSlug(ctx, tm),
+            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, tabsPresent) {
+    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 vm = detailMeta(version);
+        const versionSegs = scoped.filter((s) => s.seg.version?.id === version.id);
+        const tabsPresent = uniqueDetails(versionSegs, "tab").length > 0;
+        const prefix = productPrefix ?? rootSlug;
+        const slug = vm.default ? prefix : scopeSlugPrefix(rootSlug, version);
+        return {
+            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: vm.default ?? false,
+            versionId: FernNavigation.VersionId(version.id),
+            availability: undefined,
+            landingPage: undefined,
+            announcement: undefined,
+            pointsTo: pointsToSlug(ctx, vm),
+            child: buildTabbedOrSidebar(ctx, versionSegs, tabsPresent)
+        };
+    });
+    return {
+        type: "versioned",
+        id: ctx.nodeId(`versioned:${productPrefix ?? "root"}`),
+        collapsed: undefined,
+        children
+    };
+}
+function buildProductGroup(ctx, products, scoped, rootSlug) {
+    const children = products.map((product) => {
+        const pm = detailMeta(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, tabsPresent);
+        return {
+            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: pm.subtitle ?? "",
+            image: undefined,
+            announcement: undefined,
+            pointsTo: pointsToSlug(ctx, pm),
+            child: productChild
+        };
+    });
+    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