@fern-api/fdr-sdk 1.2.39-99e577b270 → 1.2.39-a23cd4c739

package/dist/navigation/__test__/ledger-root-builder.variantSharedSegments.test.js

@@ -0,0 +1,262 @@
+import { describe, expect, it } from "vitest";
+import { buildFullRootFromSegments } from "../ledger-root-builder.js";
+/**
+ * When a sidebar scope contains both variant-scoped segments (e.g., API
+ * references inside variants) and non-variant segments (e.g., guide sections
+ * at the product level), the non-variant segments must appear alongside the
+ * VariantedNode — not be silently dropped.
+ */
+function pageRoute(opts) {
+    return {
+        type: "markdown",
+        fullPath: opts.fullPath,
+        hidden: false,
+        metadata: { title: opts.title, pageId: `pg-${opts.title}` },
+        ...(opts.displaySortOrder != null ? { displaySortOrder: opts.displaySortOrder } : {})
+    };
+}
+function endpointRoute(opts) {
+    return {
+        type: "rest",
+        fullPath: opts.fullPath,
+        hidden: false,
+        metadata: {
+            title: opts.title,
+            slug: opts.title.toLowerCase().replace(/\s+/g, "-"),
+            apiDefinitionId: opts.apiDefinitionId,
+            endpointId: opts.title.toLowerCase().replace(/\s+/g, "-"),
+            method: "GET"
+        },
+        ...(opts.displaySortOrder != null ? { displaySortOrder: opts.displaySortOrder } : {})
+    };
+}
+const variantA = {
+    id: "variant-a-id",
+    displayName: "Accounting",
+    icon: undefined,
+    sortOrder: 0,
+    hidden: false,
+    viewers: [],
+    orphaned: false,
+    featureFlags: [],
+    metadata: { slug: "accounting", default: true, pointsTo: "prod/accounting/list-accounts" }
+};
+const variantB = {
+    id: "variant-b-id",
+    displayName: "HRIS",
+    icon: undefined,
+    sortOrder: 1,
+    hidden: false,
+    viewers: [],
+    orphaned: false,
+    featureFlags: [],
+    metadata: { slug: "hris", pointsTo: "prod/hris/list-employees" }
+};
+function segment(opts) {
+    return {
+        segmentId: opts.segmentHash,
+        segmentHash: opts.segmentHash,
+        section: opts.section,
+        locale: "en",
+        sortOrder: opts.sortOrder,
+        hidden: false,
+        metadata: opts.metadata,
+        product: opts.product ?? null,
+        version: null,
+        variant: opts.variant ?? null,
+        tab: null
+    };
+}
+/** Collect all page/endpoint slugs from the tree. */
+function collectSlugs(node) {
+    const slugs = [];
+    function walk(n) {
+        if (n == null || typeof n !== "object") {
+            return;
+        }
+        const obj = n;
+        const type = obj.type;
+        if (type === "page" || type === "endpoint") {
+            if (typeof obj.slug === "string") {
+                slugs.push(obj.slug);
+            }
+        }
+        if (Array.isArray(obj.children)) {
+            for (const c of obj.children) {
+                walk(c);
+            }
+        }
+        if (obj.child != null) {
+            walk(obj.child);
+        }
+    }
+    walk(node);
+    return slugs;
+}
+/** Find all top-level sidebar child types under unversioned. */
+function sidebarChildTypes(root) {
+    const unversioned = root.child;
+    // child might be sidebarRoot or varianted
+    const sidebar = unversioned.child;
+    if (sidebar.type === "sidebarRoot") {
+        return sidebar.children.map((c) => c.type);
+    }
+    return [sidebar.type];
+}
+describe("buildFullRootFromSegments — non-variant segments alongside variants", () => {
+    it("includes non-variant guide sections when variants are present (no tabs)", () => {
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                // Non-variant guide section
+                segment({
+                    segmentHash: "seg-guides",
+                    section: "guides",
+                    sortOrder: 0,
+                    metadata: { type: "section", title: "Guides" }
+                }),
+                // Variant A: API reference
+                segment({
+                    segmentHash: "seg-acct-api",
+                    section: "accounting",
+                    sortOrder: 1,
+                    metadata: { type: "apiReference", title: "Accounting API", apiDefinitionId: "api-acct" },
+                    variant: variantA
+                }),
+                // Variant B: API reference
+                segment({
+                    segmentHash: "seg-hris-api",
+                    section: "hris",
+                    sortOrder: 2,
+                    metadata: { type: "apiReference", title: "HRIS API", apiDefinitionId: "api-hris" },
+                    variant: variantB
+                })
+            ],
+            navBySegment: new Map([
+                [
+                    "seg-guides",
+                    [
+                        pageRoute({ fullPath: "guides/overview", title: "Overview", displaySortOrder: 0 }),
+                        pageRoute({ fullPath: "guides/quickstart", title: "Quickstart", displaySortOrder: 1 })
+                    ]
+                ],
+                [
+                    "seg-acct-api",
+                    [
+                        endpointRoute({
+                            fullPath: "accounting/list-accounts",
+                            title: "List Accounts",
+                            apiDefinitionId: "api-acct",
+                            displaySortOrder: 0
+                        })
+                    ]
+                ],
+                [
+                    "seg-hris-api",
+                    [
+                        endpointRoute({
+                            fullPath: "hris/list-employees",
+                            title: "List Employees",
+                            apiDefinitionId: "api-hris",
+                            displaySortOrder: 0
+                        })
+                    ]
+                ]
+            ])
+        });
+        const slugs = collectSlugs(root);
+        // Guide pages from non-variant segment must survive
+        expect(slugs).toContain("guides/overview");
+        expect(slugs).toContain("guides/quickstart");
+        // Variant-scoped endpoints must also survive
+        expect(slugs).toContain("accounting/list-accounts");
+        expect(slugs).toContain("hris/list-employees");
+        // The sidebar should contain both a section and a varianted node
+        const types = sidebarChildTypes(root);
+        expect(types).toContain("section");
+        expect(types).toContain("varianted");
+    });
+    it("includes non-variant sections when variants exist inside a tab", () => {
+        const tab = {
+            id: "tab-main",
+            displayName: "Main",
+            icon: undefined,
+            sortOrder: 0,
+            hidden: false,
+            viewers: [],
+            orphaned: false,
+            featureFlags: [],
+            metadata: { slug: "main" }
+        };
+        const root = buildFullRootFromSegments({
+            basePath: "",
+            title: "Test",
+            segments: [
+                // Non-variant guide section inside tab
+                segment({
+                    segmentHash: "seg-tab-guides",
+                    section: "guides",
+                    sortOrder: 0,
+                    metadata: { type: "section", title: "Guides" },
+                    variant: undefined
+                }),
+                // Variant A inside same tab
+                segment({
+                    segmentHash: "seg-tab-acct",
+                    section: "accounting",
+                    sortOrder: 1,
+                    metadata: { type: "apiReference", title: "Accounting API", apiDefinitionId: "api-acct" },
+                    variant: variantA
+                }),
+                // Variant B inside same tab
+                segment({
+                    segmentHash: "seg-tab-hris",
+                    section: "hris",
+                    sortOrder: 2,
+                    metadata: { type: "apiReference", title: "HRIS API", apiDefinitionId: "api-hris" },
+                    variant: variantB
+                })
+            ].map((s) => ({ ...s, tab })),
+            navBySegment: new Map([
+                [
+                    "seg-tab-guides",
+                    [
+                        pageRoute({ fullPath: "main/guides/overview", title: "Overview", displaySortOrder: 0 }),
+                        pageRoute({ fullPath: "main/guides/quickstart", title: "Quickstart", displaySortOrder: 1 })
+                    ]
+                ],
+                [
+                    "seg-tab-acct",
+                    [
+                        endpointRoute({
+                            fullPath: "main/accounting/list-accounts",
+                            title: "List Accounts",
+                            apiDefinitionId: "api-acct",
+                            displaySortOrder: 0
+                        })
+                    ]
+                ],
+                [
+                    "seg-tab-hris",
+                    [
+                        endpointRoute({
+                            fullPath: "main/hris/list-employees",
+                            title: "List Employees",
+                            apiDefinitionId: "api-hris",
+                            displaySortOrder: 0
+                        })
+                    ]
+                ]
+            ])
+        });
+        const slugs = collectSlugs(root);
+        // Non-variant guide pages must survive inside tab
+        expect(slugs).toContain("main/guides/overview");
+        expect(slugs).toContain("main/guides/quickstart");
+        // Variant-scoped endpoints must also survive
+        expect(slugs).toContain("main/accounting/list-accounts");
+        expect(slugs).toContain("main/hris/list-employees");
+    });
+});
+//# sourceMappingURL=ledger-root-builder.variantSharedSegments.test.js.map

package/dist/navigation/__test__/ledger-root-builder.variantSharedSegments.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-root-builder.variantSharedSegments.test.js","sourceRoot":"","sources":["../../../src/navigation/__test__/ledger-root-builder.variantSharedSegments.test.ts"],"names":[],"mappings":"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"}

package/dist/navigation/ledger-root-builder.d.ts

@@ -101,7 +101,11 @@ export declare function apiLeafNodeFromNavRoute(route: NavRoute, basePath: strin
  * @internal Exported for the ledger loader's scoped explorer methods.
  */
 export declare function collectApiLeafNodesFromNav(routes: NavRoute[], basePath: string, segmentApiDefinitionId: string): ApiLeafNode[];
-/** 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 declare function segmentApiDefinitionId(metadata: Segment["metadata"]): string | undefined;
 /**
  * Merge endpoint nodes that were originally part of an `endpointPair` in the V1

package/dist/navigation/ledger-root-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ledger-root-builder.d.ts","sourceRoot":"","sources":["../../src/navigation/ledger-root-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,KAAK,cAAc,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,KAAK,OAAO,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC7B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,6DAA6D;IAC7D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IACtC;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACpC;AAID;;;;;;GAMG;AACH,UAAU,YAAY;IAClB,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,cAAc,CAAC,MAAM,CAAC;IAC/C,kFAAkF;IAClF,WAAW,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,cAAc,CAAC,IAAI,CAAC;CAC9D;AAED,2CAA2C;AAC3C,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAuBjE;AAmPD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACjB,cAAc,CAAC,YAAY,GAC3B,cAAc,CAAC,WAAW,GAC1B,cAAc,CAAC,aAAa,GAC5B,cAAc,CAAC,QAAQ,GACvB,cAAc,CAAC,WAAW,CAAC;AAOjC;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACnC,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,MAAM,EAChB,sBAAsB,EAAE,MAAM,GAC/B,WAAW,GAAG,SAAS,CAGzB;AA+KD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACtC,MAAM,EAAE,QAAQ,EAAE,EAClB,QAAQ,EAAE,MAAM,EAChB,sBAAsB,EAAE,MAAM,GAC/B,WAAW,EAAE,CAKf;AAED,uEAAuE;AACvE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,SAAS,CASxF;AAgWD;;;;;;GAMG;AACH,2CAA2C;AAC3C,wBAAgB,kBAAkB,CAC9B,GAAG,EAAE,YAAY,EACjB,SAAS,EAAE,WAAW,EAAE,EACxB,MAAM,EAAE,QAAQ,EAAE,GACnB,cAAc,CAAC,eAAe,EAAE,CAsElC;AAgiBD;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CAAC,QAAQ,CAmF5F"}
+{"version":3,"file":"ledger-root-builder.d.ts","sourceRoot":"","sources":["../../src/navigation/ledger-root-builder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,KAAK,cAAc,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,KAAK,OAAO,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,KAAK,QAAQ,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC;AA6B9C,MAAM,WAAW,gBAAgB;IAC7B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,6DAA6D;IAC7D,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC;IACtC;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CACpC;AAID;;;;;;GAMG;AACH,UAAU,YAAY;IAClB,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,cAAc,CAAC,MAAM,CAAC;IAC/C,kFAAkF;IAClF,WAAW,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,cAAc,CAAC,IAAI,CAAC;CAC9D;AAED,2CAA2C;AAC3C,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAuBjE;AA+OD;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GACjB,cAAc,CAAC,YAAY,GAC3B,cAAc,CAAC,WAAW,GAC1B,cAAc,CAAC,aAAa,GAC5B,cAAc,CAAC,QAAQ,GACvB,cAAc,CAAC,WAAW,CAAC;AAOjC;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACnC,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,MAAM,EAChB,sBAAsB,EAAE,MAAM,GAC/B,WAAW,GAAG,SAAS,CAGzB;AA+KD;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACtC,MAAM,EAAE,QAAQ,EAAE,EAClB,QAAQ,EAAE,MAAM,EAChB,sBAAsB,EAAE,MAAM,GAC/B,WAAW,EAAE,CAKf;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,SAAS,CASxF;AAgWD;;;;;;GAMG;AACH,2CAA2C;AAC3C,wBAAgB,kBAAkB,CAC9B,GAAG,EAAE,YAAY,EACjB,SAAS,EAAE,WAAW,EAAE,EACxB,MAAM,EAAE,QAAQ,EAAE,GACnB,cAAc,CAAC,eAAe,EAAE,CAsElC;AAsiBD;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CAAC,QAAQ,CAmF5F"}

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;
@@ -401,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":
@@ -962,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") {
@@ -1051,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")
@@ -1080,8 +1089,10 @@ function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePre
         if (type === "tabRoot" && metaBool(s.seg.metadata, "landingPage") === true) {
             continue;
         }
-        // (A) Loose artifacts: tabRoot or non-section segments at section path "".
-        if (type === "tabRoot" || (sec === "" && type !== "section")) {
+        // (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) {
@@ -1101,12 +1112,16 @@ 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") {
@@ -1223,7 +1238,7 @@ 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(sourceRootSlug ?? basePath);
@@ -1398,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);
     }