@fern-api/fdr-sdk 1.2.39-4ae10c3282 → 1.2.39-4e8e68c5b4

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

@@ -1,4 +1,12 @@
 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
@@ -109,10 +117,7 @@ function toViewers(viewers) {
  * cross-variant prev/next links to disclose restricted content.
  */
 function mergeVariantViewers(seg) {
-    const segViewers = seg.metadata.type === "section" ||
-        seg.metadata.type === "apiReference" ||
-        seg.metadata.type === "apiPackage" ||
-        seg.metadata.type === "changelog"
+    const segViewers = STRUCTURAL_SEGMENT_TYPES.has(seg.metadata.type)
         ? seg.metadata.viewers
         : undefined;
     const variantViewers = seg.variant?.viewers;
@@ -330,6 +335,63 @@ function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId) {
     }
     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,
@@ -344,7 +406,11 @@ export function collectApiLeafNodesFromNav(routes, basePath, segmentApiDefinitio
         .map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId))
         .filter((node) => node != null);
 }
-/** Read the apiDefinitionId off a segment's metadata, or undefined. */
+/**
+ * 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":
@@ -524,14 +590,10 @@ function sectionNode(ctx, scoped, sectionChildren, scopePrefix) {
     return {
         type: "section",
         ...defaults,
-        // V2 convention: collapsed:false in docs.yml maps to "open-by-default"
-        // so getInitiallyOpenByDefaultNodes picks it up and the UI starts open.
-        collapsed: metaCollapsed(seg.metadata) === false
-            ? "open-by-default"
-            : (metaCollapsed(seg.metadata) ?? defaults.collapsed),
+        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) != null ? true : undefined),
+        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,
@@ -569,11 +631,10 @@ function directChildApiPackages(parentSection, scopeSegs) {
 function buildApiChildren(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix) {
     const { seg, nav } = scoped;
     // Build leaf nodes from this segment's own nav routes (not descendants).
-    const rawLeafNodes = nav
-        .map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, apiDefinitionId))
-        .filter((node) => node != null);
-    // Merge stream/non-stream endpoint pairs into EndpointPairNodes.
-    const leafNodes = mergeEndpointPairs(ctx, rawLeafNodes, nav);
+    // 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) => ({
@@ -583,18 +644,12 @@ function buildApiChildren(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix)
     // Interleave by position when childIndex metadata is available
     const hasChildIndex = packageNodes.some((p) => p.childIndex != null);
     if (!hasChildIndex) {
-        return [...leafNodes, ...packageNodes.map((p) => p.node)];
-    }
-    const leafPositions = [];
-    for (const route of nav) {
-        if (route.displaySortOrder != null) {
-            leafPositions.push(route.displaySortOrder);
-        }
+        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 = [];
-    for (let i = 0; i < leafNodes.length; i++) {
-        positioned.push({ node: leafNodes[i], pos: leafPositions[i] ?? i });
-    }
+    positioned.push(...leafNodes);
     for (const p of packageNodes) {
         positioned.push({ node: p.node, pos: p.childIndex ?? Number.MAX_SAFE_INTEGER });
     }
@@ -803,7 +858,7 @@ function changelogNode(ctx, scoped, scopePrefix) {
             pageId: FernNavigation.PageId(metaStr(r.metadata, "pageId") ?? ""),
             noindex: metaBool(r.metadata, "noindex"),
             date: dateStr ?? "",
-            tags: undefined
+            tags: metaStrArr(r.metadata, "tags")
         };
         let months = byYear.get(year);
         if (months == null) {
@@ -916,7 +971,7 @@ function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScop
         const type = metaStr(s.seg.metadata, "type");
         const childIndex = metaNum(s.seg.metadata, "childIndex");
         let node;
-        if (type === "apiReference" || type === "apiPackage") {
+        if (API_NODE_SEGMENT_TYPES.has(type ?? "")) {
             node = apiReferenceNode(ctx, s, scopeSegs, scopePrefix);
         }
         else if (type === "changelog") {
@@ -930,6 +985,54 @@ function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScop
     });
 }
 // ── 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
@@ -957,7 +1060,7 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
     //
     //   hasRootSection = true
     //   │
-    //   ├─ (A) tabRoot / loose artifacts (sec=="", type!="section")
+    //   ├─ (A) tabRoot / loose artifacts (sec=="", !STRUCTURAL_SEGMENT_TYPES)
     //   │      → emit pages/links inline at their displaySortOrder
     //   │
     //   ├─ (B) the root section itself (sec=="", type=="section")
@@ -969,14 +1072,27 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
     //
     // 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;
         }
-        // (A) Loose artifacts: tabRoot or non-section segments at section path "".
-        if (type === "tabRoot" || (sec === "" && type !== "section")) {
+        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) {
@@ -996,21 +1112,41 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
         // adopted by a root section (B).
         const parent = parentSectionPath(sec);
         const isRootLevel = parent === "" || (!sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === "");
-        if (isRootLevel && hasRootSection) {
+        // 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 (type === "apiReference" || type === "apiPackage") {
+            if (API_NODE_SEGMENT_TYPES.has(type ?? "")) {
                 node = apiReferenceNode(ctx, s, scopeSegs, scopePrefix);
             }
             else if (type === "changelog") {
                 node = changelogNode(ctx, s, changelogScopePrefix ?? scopePrefix);
             }
             else {
-                node = sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, sec, scopePrefix, changelogScopePrefix), scopePrefix);
+                // 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);
             }
-            annotated.push({ node, pos: metaNum(s.seg.metadata, "childIndex"), isLeaf: false });
+            // 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.
@@ -1094,7 +1230,7 @@ function buildSidebarRoot(ctx, scopeSegs, scopePrefix, changelogScopePrefix) {
  * Build a full (un-pruned) `RootNode` from the decomposed ledger model.
  */
 export function buildFullRootFromSegments(options) {
-    const { basePath, title, segments, navBySegment } = 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
@@ -1102,10 +1238,10 @@ export function buildFullRootFromSegments(options) {
         // but guard here too.
         .filter((seg) => {
         const t = metaStr(seg.metadata, "type");
-        return t !== "files" && t !== "redirects";
+        return !INFRA_SEGMENT_TYPES.has(t ?? "");
     })
         .map((seg) => ({ seg, nav: navBySegment.get(seg.segmentHash) ?? [] }));
-    const rootSlug = asSlug(basePath);
+    const rootSlug = asSlug(sourceRootSlug ?? basePath);
     // Group by scope identity.
     const scopesByKey = new Map();
     for (const s of scoped) {
@@ -1119,10 +1255,10 @@ export function buildFullRootFromSegments(options) {
     const tabs = uniqueDetails(scoped, "tab");
     let child;
     if (products.length > 0) {
-        child = buildProductGroup(ctx, products, scoped, rootSlug);
+        child = buildProductGroup(ctx, products, scoped, rootSlug, skipSharedSectionMerge);
     }
     else if (versions.length > 0) {
-        child = buildVersioned(ctx, versions, scoped, rootSlug, undefined);
+        child = buildVersioned(ctx, versions, scoped, rootSlug, undefined, skipSharedSectionMerge);
     }
     else {
         child = buildUnversioned(ctx, scoped, rootSlug, tabs.length > 0);
@@ -1277,22 +1413,36 @@ function buildSidebarRootWithVariants(ctx, scopeSegs, scopePrefix, changelogScop
     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: [variantedNode]
+        children: [...sharedChildren, variantedNode]
     };
 }
 function buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent, scopePrefix) {
     if (!tabsPresent) {
-        // When no tabs exist but variants do, emit a VariantedNode directly
-        // so each variant gets its own sidebar scope.
+        // 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) {
-            return buildVariantedNode(ctx, variants, scopeSegs, scopePrefix);
+            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);
     }
@@ -1400,16 +1550,101 @@ function buildUnversioned(ctx, scopeSegs, scopePrefix, tabsPresent) {
         type: "unversioned",
         id: ctx.nodeId(`unversioned:${first?.seg.product?.id ?? "root"}`),
         collapsed: undefined,
-        landingPage: 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)
     };
 }
-function buildVersioned(ctx, versions, scoped, rootSlug, productPrefix) {
+/**
+ * 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) => {
-        const versionSegs = scoped.filter((s) => s.seg.version?.id === version.id);
+        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
@@ -1446,7 +1681,7 @@ function buildVersioned(ctx, versions, scoped, rootSlug, productPrefix) {
             default: detailIsDefault(version),
             versionId: FernNavigation.VersionId(version.id),
             availability: undefined,
-            landingPage: buildVersionLandingPage(ctx, versionSegs, asSlug(slug)),
+            landingPage: buildLandingPage(ctx, versionSegs),
             announcement: undefined,
             pointsTo: metaStr(version.metadata, "pointsTo") != null
                 ? pointsToSlug(metaStr(version.metadata, "pointsTo"))
@@ -1552,38 +1787,41 @@ function crossVersionDedupKeys(node, parents) {
     keys.push([...parentTitles, node.title].join("###"));
     return keys;
 }
-/**
- * Build a LandingPageNode from tab-less segments (segments with no tab_id).
- * In V1, these are version-level landing pages that sit outside any tab.
- */
-function buildVersionLandingPage(ctx, versionSegs, versionSlug) {
-    const tablessSegs = versionSegs.filter((s) => s.seg.tab == null);
-    if (tablessSegs.length === 0) {
+function routeToLandingPage(ctx, route) {
+    if (route == null || route.type !== "markdown" || route.fullPath == null) {
         return undefined;
     }
-    for (const s of tablessSegs) {
-        for (const r of s.nav) {
-            if (r.type === "markdown" && r.fullPath != null) {
-                const md = r.metadata;
-                const pageId = metaStr(md, "pageId") ?? "";
-                const slug = ctx.contentSlug(r.fullPath);
-                return {
-                    type: "landingPage",
-                    ...withMetadataDefaults({
-                        id: ctx.nodeId(`landing:${slug}`),
-                        title: metaStr(md, "title") ?? "",
-                        slug,
-                        icon: metaStr(md, "icon"),
-                        hidden: r.hidden,
-                        viewers: toViewers(metaStrArr(md, "viewers"))
-                    }),
-                    pageId: FernNavigation.PageId(pageId),
-                    noindex: metaBool(md, "noindex")
-                };
-            }
-        }
+    const md = route.metadata;
+    const pageId = metaStr(md, "pageId");
+    if (pageId == null) {
+        return undefined;
     }
-    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
@@ -1629,7 +1867,7 @@ function markCrossVersionCanonicalSlugs(versionNodes) {
         });
     }
 }
-function buildProductGroup(ctx, products, scoped, rootSlug) {
+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");
@@ -1638,7 +1876,7 @@ function buildProductGroup(ctx, products, scoped, rootSlug) {
         // 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)
+            ? buildVersioned(ctx, versions, productSegs, rootSlug, productPrefix, skipSharedSectionMerge)
             : buildUnversioned(ctx, productSegs, asSlug(productPrefix), tabsPresent);
         const node = {
             type: "product",
@@ -1673,7 +1911,7 @@ function buildProductGroup(ctx, products, scoped, rootSlug) {
         type: "productgroup",
         id: ctx.nodeId("productgroup"),
         collapsed: undefined,
-        landingPage: undefined,
+        landingPage: buildLandingPage(ctx, scoped.filter((s) => s.seg.product == null)),
         children
     };
 }