@fern-api/fdr-sdk 1.2.36-eaea1f74f7 → 1.2.37-94cc3f83f5

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

@@ -596,6 +596,82 @@ function NodeId(value) {
 function ProductId(value) {
   return value;
 }
+function VariantId(value) {
+  return value;
+}
+
+// src/navigation/versions/latest/getChildren.ts
+import { UnreachableCaseError } from "ts-essentials";
+
+// src/navigation/versions/latest/NavigationNodeApiLeaf.ts
+function isApiLeaf(node) {
+  return node.type === "endpoint" || node.type === "webSocket" || node.type === "webhook" || node.type === "grpc" || node.type === "graphql" || node.type === "graphqlType";
+}
+
+// src/navigation/versions/latest/NavigationNodePageLeaf.ts
+function isMarkdownLeaf(node) {
+  return node.type === "page" || node.type === "landingPage" || node.type === "changelogEntry";
+}
+
+// src/navigation/versions/latest/NavigationNodeLeaf.ts
+function isLeaf(node) {
+  return isApiLeaf(node) || isMarkdownLeaf(node) || node.type === "link";
+}
+
+// src/navigation/versions/latest/getChildren.ts
+function getChildren(node) {
+  if (isLeaf(node)) {
+    return [];
+  }
+  switch (node.type) {
+    case "apiPackage":
+    case "changelog":
+    case "changelogMonth":
+    case "changelogYear":
+    case "section":
+    case "sidebarGroup":
+    case "sidebarRoot":
+    case "tabbed":
+    case "versioned":
+    case "varianted":
+      return node.children;
+    case "product":
+    case "root":
+    case "tab":
+      return [node.child];
+    case "productLink":
+      return [];
+    case "variant":
+      return node.children;
+    case "apiReference":
+      return [...node.children, ...node.changelog ? [node.changelog] : []];
+    case "endpointPair":
+      return [node.nonStream, node.stream];
+    case "productgroup":
+      return [...node.landingPage ? [node.landingPage] : [], ...node.children];
+    case "unversioned":
+    case "version":
+      return [...node.landingPage ? [node.landingPage] : [], node.child];
+    default:
+      throw new UnreachableCaseError(node);
+  }
+}
+
+// src/navigation/versions/latest/NavigationNodeWithMetadata.ts
+function hasMetadata(node) {
+  return typeof node.title === "string" && typeof node.slug === "string";
+}
+
+// src/navigation/versions/latest/NavigationNodeWithRedirect.ts
+function hasPointsTo(node) {
+  return node.type === "root" || node.type === "product" || node.type === "version" || node.type === "tab" || node.type === "section" || node.type === "apiReference" || node.type === "apiPackage";
+}
+function hasRedirect(node) {
+  if (!hasPointsTo(node)) {
+    return false;
+  }
+  return node.pointsTo != null;
+}
 
 // ../commons/core-utils/dist/isNonNullish.js
 function isNonNullish(x) {
@@ -611,10 +687,50 @@ function slugjoin(...parts) {
   return Slug(normalized);
 }
 
+// src/navigation/versions/latest/toDefaultSlug.ts
+import { escapeRegExp } from "es-toolkit/string";
+function toDefaultSlug(slug, rootSlug, versionSlug) {
+  if (slug == null) {
+    return void 0;
+  }
+  if (slug.startsWith(versionSlug)) {
+    return Slug(slug.replace(new RegExp(`^${escapeRegExp(versionSlug)}`), rootSlug).replace(/^\//, ""));
+  }
+  return slug;
+}
+
+// src/utils/traversers/types.ts
+var SKIP = "skip";
+var STOP = false;
+
+// src/utils/traversers/dfs.ts
+function dfs(root, visit, getChildren2, isParent = (node) => true) {
+  const stack = [[root, []]];
+  while (stack.length > 0) {
+    const [node, parents] = stack.pop() ?? [];
+    if (!node) {
+      continue;
+    }
+    const next = visit(node, parents ?? []);
+    if (next === SKIP) {
+      continue;
+    } else if (next === STOP) {
+      return;
+    }
+    if (isParent(node)) {
+      for (const child of [...getChildren2(node)].reverse()) {
+        stack.push([child, [...parents ?? [], node]]);
+      }
+    }
+  }
+}
+
+// src/navigation/versions/latest/traverseDF.ts
+function traverseDF(node, visit) {
+  return dfs(node, visit, getChildren);
+}
+
 // src/navigation/ledger-root-builder.ts
-var segMeta = (seg) => seg.metadata ?? {};
-var routeMeta = (route) => route.metadata ?? {};
-var detailMeta = (detail) => detail.metadata ?? {};
 function createBuildContext(basePath) {
   const seen = /* @__PURE__ */ new Map();
   const basePrefix = basePath.replace(/^\/+|\/+$/g, "");
@@ -633,6 +749,51 @@ function createBuildContext(basePath) {
 function asSlug(path) {
   return Slug(path.replace(/^\/+|\/+$/g, ""));
 }
+function pointsToSlug(metaPointsTo) {
+  return asSlug(metaPointsTo);
+}
+function metaStr(metadata, key) {
+  if (metadata != null && typeof metadata === "object" && key in metadata) {
+    const v = metadata[key];
+    return typeof v === "string" ? v : void 0;
+  }
+  return void 0;
+}
+function metaBool(metadata, key) {
+  if (metadata != null && typeof metadata === "object" && key in metadata) {
+    const v = metadata[key];
+    return typeof v === "boolean" ? v : void 0;
+  }
+  return void 0;
+}
+function metaNum(metadata, key) {
+  if (metadata != null && typeof metadata === "object" && key in metadata) {
+    const v = metadata[key];
+    return typeof v === "number" ? v : void 0;
+  }
+  return void 0;
+}
+function metaCollapsed(metadata) {
+  if (metadata != null && typeof metadata === "object" && "collapsed" in metadata) {
+    const v = metadata.collapsed;
+    if (typeof v === "boolean") {
+      return v;
+    }
+    if (v === "open-by-default") {
+      return "open-by-default";
+    }
+  }
+  return void 0;
+}
+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 void 0;
+}
 function toViewers(viewers) {
   if (viewers == null || viewers.length === 0) {
     return void 0;
@@ -640,17 +801,29 @@ function toViewers(viewers) {
   return viewers.map((v) => RoleId(v));
 }
 function mergeVariantViewers(seg) {
-  const all = [...segMeta(seg).viewers ?? [], ...seg.variant?.viewers ?? []];
-  return all.length > 0 ? [...new Set(all)].map((v) => RoleId(v)) : void 0;
+  const segViewers = seg.metadata.type === "section" || seg.metadata.type === "apiReference" || seg.metadata.type === "apiPackage" || seg.metadata.type === "changelog" ? seg.metadata.viewers : void 0;
+  const variantViewers = seg.variant?.viewers;
+  if ((segViewers == null || segViewers.length === 0) && (variantViewers == null || variantViewers.length === 0)) {
+    return void 0;
+  }
+  const merged = /* @__PURE__ */ new Set();
+  if (segViewers != null) {
+    for (const v of segViewers) {
+      merged.add(v);
+    }
+  }
+  if (variantViewers != null) {
+    for (const v of variantViewers) {
+      merged.add(v);
+    }
+  }
+  return merged.size > 0 ? [...merged].map((v) => RoleId(v)) : void 0;
 }
 function detailSlug(detail) {
-  return detailMeta(detail).slug ?? "";
+  return detail.metadata?.slug ?? "";
 }
 function detailIsDefault(detail) {
-  return detailMeta(detail).default ?? false;
-}
-function pointsToSlug(ctx, meta) {
-  return meta.pointsTo != null ? ctx.contentSlug(meta.pointsTo) : void 0;
+  return detail.metadata?.default ?? false;
 }
 function scopeKey(seg) {
   return [seg.product?.id ?? "", seg.version?.id ?? "", seg.variant?.id ?? "", seg.tab?.id ?? ""].join("|");
@@ -670,226 +843,347 @@ function withMetadataDefaults(base) {
   };
 }
 function artifactToNode(ctx, route) {
-  const md = routeMeta(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": {
-      if (md.isOverview) {
+      if (metaBool(md, "isOverview")) {
         return void 0;
       }
-      return {
+      const pageId = metaStr(md, "pageId") ?? "";
+      const node = {
         type: "page",
         ...withMetadataDefaults({
           id: ctx.nodeId(`page:${slug}`),
-          title: md.title ?? "",
+          title,
           slug,
-          icon: md.icon,
+          icon,
           hidden: route.hidden,
-          viewers: toViewers(md.viewers)
+          viewers
         }),
-        pageId: PageId(md.pageId ?? ""),
-        noindex: md.noindex,
+        pageId: PageId(pageId),
+        noindex: metaBool(md, "noindex"),
         availability: void 0
       };
+      return node;
     }
     case "link": {
-      return {
+      const node = {
         type: "link",
-        id: ctx.nodeId(`link:${md.url ?? route.fullPath ?? ""}`),
+        id: ctx.nodeId(`link:${metaStr(md, "url") ?? route.fullPath ?? ""}`),
         collapsed: void 0,
-        title: md.title ?? "",
-        icon: md.icon,
-        url: Url(md.url ?? ""),
+        title,
+        icon,
+        url: Url(metaStr(md, "url") ?? ""),
         target: void 0
       };
+      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 void 0;
     default:
       return void 0;
   }
 }
-function apiLeafNodeFromNavRoute(route, basePath, segmentApiDefId) {
+function apiLeafNodeFromNavRoute(route, basePath, segmentApiDefinitionId2) {
   const ctx = createBuildContext(basePath);
-  return apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefId);
+  return apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId2);
 }
-function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefId) {
-  const md = routeMeta(route);
+function apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId2) {
+  const md = route.metadata;
+  const apiDefinitionId = ApiDefinitionId(metaStr(md, "apiDefinitionId") ?? segmentApiDefinitionId2);
   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: ApiDefinitionId(md.apiDefinitionId ?? segmentApiDefId),
-    availability: void 0
-  };
-  switch (route.type) {
-    case "rest":
-      if (md.endpointId == null || md.method == null) {
-        return void 0;
-      }
-      return {
-        type: "endpoint",
-        ...base,
-        method: md.method,
-        endpointId: EndpointId(md.endpointId),
-        isResponseStream: md.isResponseStream,
-        playground: void 0
-      };
-    case "webhook":
-      if (md.webhookId == null || md.method == null) {
-        return void 0;
-      }
-      return {
-        type: "webhook",
-        ...base,
-        method: md.method,
-        webhookId: WebhookId(md.webhookId)
-      };
-    case "asyncapi":
-      if (md.webSocketId == null) {
-        return void 0;
-      }
-      return {
-        type: "webSocket",
-        ...base,
-        webSocketId: WebSocketId(md.webSocketId),
-        playground: void 0
-      };
-    case "grpc":
-      if (md.grpcId == null || md.method == null) {
-        return void 0;
-      }
-      return {
-        type: "grpc",
-        ...base,
-        method: md.method,
-        grpcId: GrpcId(md.grpcId)
-      };
-    case "graphql":
-      if (md.graphqlOperationId == null || md.operationType == null) {
-        return void 0;
-      }
-      return {
-        type: "graphql",
-        ...base,
-        operationType: md.operationType,
-        graphqlOperationId: GraphQlOperationId(md.graphqlOperationId),
-        graphqlOperationIds: void 0,
-        playground: void 0
-      };
-    default:
+  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 void 0;
+    }
+    return {
+      type: "endpoint",
+      ...meta,
+      method,
+      endpointId: EndpointId(endpointId),
+      apiDefinitionId,
+      isResponseStream: metaBool(md, "isResponseStream"),
+      availability: void 0,
+      playground: void 0
+    };
+  }
+  if (route.type === "webhook") {
+    const webhookId = metaStr(md, "webhookId");
+    const method = metaStr(md, "method");
+    if (webhookId == null || method == null) {
+      return void 0;
+    }
+    return {
+      type: "webhook",
+      ...meta,
+      method,
+      webhookId: WebhookId(webhookId),
+      apiDefinitionId,
+      availability: void 0
+    };
+  }
+  if (route.type === "asyncapi") {
+    const webSocketId = metaStr(md, "webSocketId");
+    if (webSocketId == null) {
+      return void 0;
+    }
+    return {
+      type: "webSocket",
+      ...meta,
+      webSocketId: WebSocketId(webSocketId),
+      apiDefinitionId,
+      availability: void 0,
+      playground: void 0
+    };
+  }
+  if (route.type === "grpc") {
+    const grpcId = metaStr(md, "grpcId");
+    const method = metaStr(md, "method");
+    if (grpcId == null || method == null) {
+      return void 0;
+    }
+    return {
+      type: "grpc",
+      ...meta,
+      method,
+      grpcId: GrpcId(grpcId),
+      apiDefinitionId,
+      availability: void 0
+    };
+  }
+  if (route.type === "graphql") {
+    const graphqlOperationId = metaStr(md, "graphqlOperationId");
+    const operationType = metaStr(md, "operationType");
+    if (graphqlOperationId == null || operationType == null) {
       return void 0;
+    }
+    return {
+      type: "graphql",
+      ...meta,
+      operationType,
+      graphqlOperationId: GraphQlOperationId(graphqlOperationId),
+      graphqlOperationIds: void 0,
+      apiDefinitionId,
+      availability: void 0,
+      playground: void 0
+    };
   }
+  return void 0;
 }
-function collectApiLeafNodesFromNav(routes, basePath, segmentApiDefId) {
+function collectApiLeafNodesFromNav(routes, basePath, segmentApiDefinitionId2) {
   const ctx = createBuildContext(basePath);
-  return routes.map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefId)).filter((node) => node != null);
+  return routes.map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, segmentApiDefinitionId2)).filter((node) => node != null);
 }
 function segmentApiDefinitionId(metadata) {
-  return metadata?.apiDefinitionId;
+  switch (metadata.type) {
+    case "apiReference":
+    case "apiPackage":
+    case "changelog":
+      return metadata.apiDefinitionId;
+    default:
+      return void 0;
+  }
 }
 function overviewRoute(nav) {
+  return nav.find((r) => r.type === "markdown" && metaBool(r.metadata, "isOverview"));
+}
+function overviewRouteFromSegmentMeta(seg, nav) {
+  const overviewPageId = metaStr(seg.metadata, "overviewPageId");
+  if (overviewPageId == null) {
+    return void 0;
+  }
+  return nav.find((r) => metaStr(r.metadata, "pageId") === overviewPageId);
+}
+function inferSectionSlugFromNav(ctx, nav, scopePrefix) {
+  const scopeStr = String(scopePrefix);
+  const prefix = scopeStr !== "" ? scopeStr + "/" : "";
   for (const r of nav) {
-    if (r.type === "markdown") {
-      const meta = routeMeta(r);
-      if (meta.isOverview) {
-        return { route: r, meta };
-      }
+    if (r.fullPath == null) {
+      continue;
+    }
+    if (r.type !== "markdown" && r.type !== "page") {
+      continue;
+    }
+    const contentSlug = String(ctx.contentSlug(r.fullPath));
+    const rel = prefix !== "" ? contentSlug.startsWith(prefix) ? contentSlug.slice(prefix.length) : null : contentSlug;
+    if (rel == null) {
+      continue;
+    }
+    const parts = rel.split("/");
+    if (parts.length >= 2 && parts[0] !== "") {
+      return slugjoin(scopePrefix, parts[0]);
     }
   }
   return void 0;
 }
-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);
+function structuralNodeSlug(ctx, overviewFullPath, section, scopePrefix) {
+  if (overviewFullPath != null) {
+    return ctx.contentSlug(overviewFullPath);
+  }
+  return section !== "" ? slugjoin(scopePrefix, section) : scopePrefix;
+}
+function stripLeadingScopePrefix(section, scopePrefix) {
+  const prefix = scopePrefix;
+  if (prefix === "") {
+    return section;
+  }
+  if (section === prefix) {
+    return "";
+  }
+  if (section.startsWith(prefix + "/")) {
+    return section.slice(prefix.length + 1);
+  }
+  return section;
+}
+function mergeChildrenByPosition(ctx, nav, sectionChildren) {
+  const leafNodes = [];
+  for (let i = 0; i < nav.length; i++) {
+    const route = nav[i];
+    const node = artifactToNode(ctx, route);
+    if (node != null) {
+      leafNodes.push({ node, pos: route.displaySortOrder ?? i });
+    }
+  }
+  const hasChildIndex = sectionChildren.some((s) => s.childIndex != null);
+  if (!hasChildIndex) {
+    return [...leafNodes.map((l) => l.node), ...sectionChildren.map((s) => s.node)];
+  }
+  const positioned = [...leafNodes];
+  for (const s of sectionChildren) {
+    positioned.push({ node: s.node, pos: s.childIndex ?? Number.MAX_SAFE_INTEGER });
+  }
+  positioned.sort((a, b) => a.pos - b.pos);
+  return positioned.map((p) => p.node);
+}
+function sectionNode(ctx, scoped, sectionChildren, scopePrefix) {
+  const { seg, nav } = scoped;
+  const overview = overviewRoute(nav) ?? overviewRouteFromSegmentMeta(seg, nav);
+  const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : void 0;
+  let slug = structuralNodeSlug(ctx, overview?.fullPath, seg.section, scopePrefix);
+  if (seg.section === "" && overview?.fullPath == null) {
+    slug = inferSectionSlugFromNav(ctx, nav, scopePrefix) ?? slug;
+  }
+  const metaPointsTo = metaStr(seg.metadata, "pointsTo");
   const defaults = withMetadataDefaults({
     id: ctx.nodeId(`section:${slug}`),
-    title: sm.title ?? "",
+    title: metaStr(seg.metadata, "title") ?? "",
     slug,
-    icon: sm.icon,
+    icon: metaStr(seg.metadata, "icon"),
     hidden: seg.hidden,
     viewers: mergeVariantViewers(seg)
   });
   return {
     type: "section",
     ...defaults,
-    collapsed: sm.collapsed ?? defaults.collapsed,
+    collapsed: metaCollapsed(seg.metadata) ?? defaults.collapsed,
     overviewPageId: overviewPageId != null ? PageId(overviewPageId) : void 0,
     noindex: void 0,
-    collapsible: sm.collapsible,
-    collapsedByDefault: sm.collapsedByDefault,
+    collapsible: metaBool(seg.metadata, "collapsible") ?? (metaCollapsed(seg.metadata) != null ? true : void 0),
+    collapsedByDefault: metaBool(seg.metadata, "collapsedByDefault") ?? (metaCollapsed(seg.metadata) === true ? true : void 0),
     availability: void 0,
-    pointsTo: void 0,
-    children: [...leafChildren, ...sectionChildren]
+    pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : void 0,
+    children: mergeChildrenByPosition(ctx, nav, sectionChildren)
   };
 }
-function parentSectionPath(sectionPath) {
-  const idx = sectionPath.lastIndexOf("/");
-  return idx === -1 ? "" : sectionPath.slice(0, idx);
+function directChildApiPackages(parentSection, scopeSegs) {
+  const sectionPaths = new Set(scopeSegs.map((s) => s.seg.section));
+  return scopeSegs.filter((s) => {
+    if (metaStr(s.seg.metadata, "type") !== "apiPackage") {
+      return false;
+    }
+    const parent = parentSectionPath(s.seg.section);
+    if (parent === parentSection) {
+      return true;
+    }
+    if (!sectionPaths.has(parent)) {
+      return nearestExistingAncestor(s.seg.section, sectionPaths) === parentSection;
+    }
+    return false;
+  }).sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
 }
-function nearestExistingAncestor(sectionPath, existing) {
-  let current = parentSectionPath(sectionPath);
-  while (current !== "") {
-    if (existing.has(current)) {
-      return current;
+function buildApiChildren(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix) {
+  const { seg, nav } = scoped;
+  const rawLeafNodes = nav.map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, apiDefinitionId)).filter((node) => node != null);
+  const leafNodes = mergeEndpointPairs(ctx, rawLeafNodes, nav);
+  const childPackages = directChildApiPackages(seg.section, scopeSegs);
+  const packageNodes = childPackages.map((child) => ({
+    node: apiPackageChildNode(
+      ctx,
+      child,
+      scopeSegs,
+      apiDefinitionId,
+      scopePrefix
+    ),
+    childIndex: metaNum(child.seg.metadata, "childIndex")
+  }));
+  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);
     }
-    current = parentSectionPath(current);
   }
-  return "";
-}
-function isDirectChildOf(sec, parentPath, sectionPaths) {
-  const parent = parentSectionPath(sec);
-  if (parent === parentPath) {
-    return true;
+  const positioned = [];
+  for (let i = 0; i < leafNodes.length; i++) {
+    positioned.push({ node: leafNodes[i], pos: leafPositions[i] ?? i });
   }
-  return !sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === parentPath;
-}
-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);
+  for (const p of packageNodes) {
+    positioned.push({ node: p.node, pos: p.childIndex ?? Number.MAX_SAFE_INTEGER });
+  }
+  positioned.sort((a, b) => a.pos - b.pos);
+  return positioned.map((p) => p.node);
 }
-function buildApiChildren(ctx, scoped, scopeSegs, apiDefId, sectionPaths) {
-  const { nav } = scoped;
-  const rawLeafNodes = nav.map((route) => apiLeafNodeFromNavRouteInternal(ctx, route, apiDefId)).filter((node) => node != null);
-  const leafNodes = mergeEndpointPairs(ctx, rawLeafNodes, nav);
-  const childPackages = directChildApiPackages(scoped.seg.section, scopeSegs, sectionPaths);
-  const packageNodes = childPackages.map(
-    (child) => apiPackageChildNode(ctx, child, scopeSegs, apiDefId, sectionPaths)
-  );
-  return [...leafNodes, ...packageNodes];
-}
-function apiPackageChildNode(ctx, scoped, scopeSegs, parentApiDefId, sectionPaths) {
-  const { seg, meta: sm, nav } = scoped;
+function apiPackageChildNode(ctx, scoped, scopeSegs, parentApiDefinitionId, scopePrefix) {
+  const { seg, 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);
+  const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : void 0;
+  const apiDefinitionId = metaStr(seg.metadata, "apiDefinitionId") ?? parentApiDefinitionId;
+  const slug = structuralNodeSlug(ctx, overview?.fullPath, seg.section, scopePrefix);
+  const metaPointsTo = metaStr(seg.metadata, "pointsTo");
+  const children = buildApiChildren(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix);
   return {
     type: "apiPackage",
     ...withMetadataDefaults({
       id: ctx.nodeId(`api-pkg:${slug}`),
-      title: sm.title ?? "",
+      title: metaStr(seg.metadata, "title") ?? "",
       slug,
-      icon: sm.icon,
+      icon: metaStr(seg.metadata, "icon"),
       hidden: seg.hidden,
-      viewers: toViewers(sm.viewers)
+      viewers: toViewers(metaStrArr(seg.metadata, "viewers"))
     }),
-    apiDefinitionId: ApiDefinitionId(apiDefId),
-    availability: sm.availability,
+    apiDefinitionId: ApiDefinitionId(apiDefinitionId),
+    availability: metaStr(seg.metadata, "availability"),
     overviewPageId: overviewPageId != null ? PageId(overviewPageId) : void 0,
     noindex: void 0,
-    pointsTo: void 0,
+    pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : void 0,
     children,
     playground: void 0
   };
@@ -900,9 +1194,10 @@ function mergeEndpointPairs(ctx, leafNodes, allNav) {
     if (route.type !== "rest") {
       continue;
     }
-    const md = routeMeta(route);
-    if (md.endpointPairKey != null && md.endpointId != null) {
-      endpointIdToPairKey.set(md.endpointId, md.endpointPairKey);
+    const pairKey = metaStr(route.metadata, "endpointPairKey");
+    const endpointId = metaStr(route.metadata, "endpointId");
+    if (pairKey != null && endpointId != null) {
+      endpointIdToPairKey.set(endpointId, pairKey);
     }
   }
   if (endpointIdToPairKey.size === 0) {
@@ -932,6 +1227,7 @@ function mergeEndpointPairs(ctx, leafNodes, allNav) {
       }
       const stream = node.isResponseStream ? node : first;
       const nonStream = node.isResponseStream ? first : node;
+      stream.canonicalSlug = nonStream.slug;
       const pairNode = {
         id: ctx.nodeId(`endpoint-pair:${pairKey}`),
         type: "endpointPair",
@@ -944,61 +1240,86 @@ function mergeEndpointPairs(ctx, leafNodes, allNav) {
   }
   return result;
 }
-function apiReferenceNode(ctx, scoped, scopeSegs, sectionPaths) {
-  const { seg, meta: sm, nav } = scoped;
+function apiReferenceNode(ctx, scoped, scopeSegs, scopePrefix) {
+  const { seg, 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);
+  const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : void 0;
+  const apiDefinitionId = metaStr(seg.metadata, "apiDefinitionId") ?? "";
+  const slug = structuralNodeSlug(ctx, overview?.fullPath, seg.section, scopePrefix);
+  const metaPointsTo = metaStr(seg.metadata, "pointsTo");
+  const children = buildApiChildren(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix);
+  const changelog = attachedApiChangelogNode(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix);
   return {
     type: "apiReference",
     ...withMetadataDefaults({
       id: ctx.nodeId(`api:${slug}`),
-      title: sm.title ?? "",
+      title: metaStr(seg.metadata, "title") ?? "",
       slug,
-      icon: sm.icon,
+      icon: metaStr(seg.metadata, "icon"),
       hidden: seg.hidden,
       viewers: mergeVariantViewers(seg)
     }),
-    apiDefinitionId: ApiDefinitionId(apiDefId),
+    apiDefinitionId: ApiDefinitionId(apiDefinitionId),
     availability: void 0,
     overviewPageId: overviewPageId != null ? PageId(overviewPageId) : void 0,
     noindex: void 0,
     paginated: true,
-    showErrors: sm.showErrors,
-    hideTitle: sm.hideTitle,
-    pointsTo: void 0,
+    showErrors: metaBool(seg.metadata, "showErrors"),
+    hideTitle: metaBool(seg.metadata, "hideTitle"),
+    pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : void 0,
     children,
-    changelog: void 0,
+    changelog,
     playground: void 0,
     postmanCollectionUrl: void 0
   };
 }
-function changelogNode(ctx, scoped) {
-  const { seg, meta: sm, nav } = scoped;
+function attachedApiChangelogNode(ctx, scoped, scopeSegs, apiDefinitionId, scopePrefix) {
+  const { seg } = scoped;
+  const candidates = scopeSegs.filter((candidate) => {
+    if (metaStr(candidate.seg.metadata, "type") !== "changelog") {
+      return false;
+    }
+    return metaStr(candidate.seg.metadata, "apiDefinitionId") === apiDefinitionId;
+  });
+  const changelogSeg = candidates.find((candidate) => parentSectionPath(candidate.seg.section) === seg.section) ?? candidates[0];
+  return changelogSeg != null ? changelogNode(ctx, changelogSeg, scopePrefix) : void 0;
+}
+function hasOwningApiReference(scoped, scopeSegs) {
+  const apiDefinitionId = metaStr(scoped.seg.metadata, "apiDefinitionId");
+  if (apiDefinitionId == null || metaStr(scoped.seg.metadata, "type") !== "changelog") {
+    return false;
+  }
+  return scopeSegs.some((candidate) => {
+    if (metaStr(candidate.seg.metadata, "type") !== "apiReference") {
+      return false;
+    }
+    return metaStr(candidate.seg.metadata, "apiDefinitionId") === apiDefinitionId;
+  });
+}
+function changelogNode(ctx, scoped, scopePrefix) {
+  const { seg, nav } = scoped;
   const overview = overviewRoute(nav);
-  const overviewPageId = overview?.meta.pageId;
+  const overviewPageId = overview != null ? metaStr(overview.metadata, "pageId") : void 0;
   const entries = nav.filter((r) => r.type === "changelog");
   const byYear = /* @__PURE__ */ new Map();
   for (const r of entries) {
-    const md = routeMeta(r);
-    const date = md.date != null ? new Date(md.date) : /* @__PURE__ */ new Date(0);
+    const dateStr = metaStr(r.metadata, "date");
+    const date = dateStr != null ? new Date(dateStr) : /* @__PURE__ */ 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 ?? "",
+        id: ctx.nodeId(`cl-entry:${r.fullPath ?? metaStr(r.metadata, "pageId") ?? ""}`),
+        title: metaStr(r.metadata, "title") ?? "",
         slug: ctx.contentSlug(r.fullPath ?? ""),
-        icon: md.icon,
+        icon: metaStr(r.metadata, "icon"),
         hidden: r.hidden,
-        viewers: toViewers(md.viewers)
+        viewers: toViewers(metaStrArr(r.metadata, "viewers"))
       }),
-      pageId: PageId(md.pageId ?? ""),
+      pageId: PageId(metaStr(r.metadata, "pageId") ?? ""),
       noindex: void 0,
-      date: md.date ?? "",
+      date: dateStr ?? "",
       tags: void 0
     };
     let months = byYear.get(year);
@@ -1010,7 +1331,8 @@ function changelogNode(ctx, scoped) {
     arr.push(entry);
     months.set(month, arr);
   }
-  const baseSlug = ctx.contentSlug(overview?.route.fullPath ?? seg.section);
+  const relativeSection = stripLeadingScopePrefix(seg.section, scopePrefix);
+  const baseSlug = structuralNodeSlug(ctx, overview?.fullPath, relativeSection, scopePrefix);
   const years = [...byYear.entries()].sort((a, b) => b[0] - a[0]).map(([year, months]) => ({
     type: "changelogYear",
     ...withMetadataDefaults({
@@ -1038,9 +1360,9 @@ function changelogNode(ctx, scoped) {
     type: "changelog",
     ...withMetadataDefaults({
       id: ctx.nodeId(`changelog:${baseSlug}`),
-      title: sm.title ?? "",
+      title: metaStr(seg.metadata, "title") ?? "",
       slug: baseSlug,
-      icon: sm.icon,
+      icon: metaStr(seg.metadata, "icon"),
       hidden: seg.hidden,
       viewers: mergeVariantViewers(seg)
     }),
@@ -1049,48 +1371,112 @@ function changelogNode(ctx, scoped) {
     children: years
   };
 }
-function buildSectionTree(ctx, scopeSegs, parentPath, sectionPaths) {
+function parentSectionPath(sectionPath) {
+  const idx = sectionPath.lastIndexOf("/");
+  return idx === -1 ? "" : sectionPath.slice(0, idx);
+}
+function nearestExistingAncestor(sectionPath, existing) {
+  let current = parentSectionPath(sectionPath);
+  while (current !== "") {
+    if (existing.has(current)) {
+      return current;
+    }
+    current = parentSectionPath(current);
+  }
+  return "";
+}
+function buildSectionTree(ctx, scopeSegs, parentPath, scopePrefix, changelogScopePrefix) {
+  const sectionPaths = new Set(scopeSegs.map((s) => s.seg.section));
   const direct = scopeSegs.filter((s) => {
     const sec = s.seg.section;
-    return sec !== "" && s.meta.type !== "tabRoot" && isDirectChildOf(sec, parentPath, sectionPaths);
+    const type = metaStr(s.seg.metadata, "type");
+    if (sec === "" || type === "tabRoot") {
+      return false;
+    }
+    if (hasOwningApiReference(s, scopeSegs)) {
+      return false;
+    }
+    const parent = parentSectionPath(sec);
+    if (parent === parentPath) {
+      return true;
+    }
+    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 } = s.meta;
+    const type = metaStr(s.seg.metadata, "type");
+    const childIndex = metaNum(s.seg.metadata, "childIndex");
+    let node;
     if (type === "apiReference" || type === "apiPackage") {
-      return apiReferenceNode(ctx, s, scopeSegs, sectionPaths);
-    }
-    if (type === "changelog") {
-      return changelogNode(ctx, s);
+      node = apiReferenceNode(ctx, s, scopeSegs, scopePrefix);
+    } else if (type === "changelog") {
+      node = changelogNode(ctx, s, changelogScopePrefix ?? scopePrefix);
+    } else {
+      node = sectionNode(
+        ctx,
+        s,
+        buildSectionTree(ctx, scopeSegs, s.seg.section, scopePrefix, changelogScopePrefix),
+        scopePrefix
+      );
     }
-    return sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, s.seg.section, sectionPaths));
+    return { node, childIndex };
   });
 }
-function buildSidebarRootChildren(ctx, scopeSegs) {
+function buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePrefix) {
   const ordered = [...scopeSegs].sort((a, b) => a.seg.sortOrder - b.seg.sortOrder);
   const sectionPaths = new Set(ordered.map((s) => s.seg.section));
-  const flat = [];
+  const annotated = [];
+  const hasRootSection = ordered.some((s) => metaStr(s.seg.metadata, "type") === "section" && s.seg.section === "");
   for (const s of ordered) {
-    const { type } = s.meta;
+    const type = metaStr(s.seg.metadata, "type");
     const sec = s.seg.section;
-    if (type === "tabRoot" || sec === "") {
+    if (hasOwningApiReference(s, scopeSegs)) {
+      continue;
+    }
+    if (type === "tabRoot" || sec === "" && type !== "section") {
       for (const r of s.nav) {
         const node = artifactToNode(ctx, r);
         if (node != null) {
-          flat.push(node);
+          annotated.push({ node, pos: r.displaySortOrder ?? void 0, isLeaf: true });
         }
       }
       continue;
     }
-    if (isDirectChildOf(sec, "", sectionPaths)) {
+    if (type === "section" && sec === "") {
+      const sectionChildren = buildSectionTree(ctx, scopeSegs, "", scopePrefix);
+      const node = sectionNode(ctx, s, sectionChildren, scopePrefix);
+      annotated.push({ node, pos: metaNum(s.seg.metadata, "childIndex"), isLeaf: false });
+      continue;
+    }
+    const parent = parentSectionPath(sec);
+    const isRootLevel = parent === "" || !sectionPaths.has(parent) && nearestExistingAncestor(sec, sectionPaths) === "";
+    if (isRootLevel && hasRootSection) {
+      continue;
+    }
+    if (isRootLevel) {
+      let node;
       if (type === "apiReference" || type === "apiPackage") {
-        flat.push(apiReferenceNode(ctx, s, scopeSegs, sectionPaths));
+        node = apiReferenceNode(ctx, s, scopeSegs, scopePrefix);
       } else if (type === "changelog") {
-        flat.push(changelogNode(ctx, s));
+        node = changelogNode(ctx, s, changelogScopePrefix ?? scopePrefix);
       } else {
-        flat.push(sectionNode(ctx, s, buildSectionTree(ctx, scopeSegs, sec, sectionPaths)));
+        node = sectionNode(
+          ctx,
+          s,
+          buildSectionTree(ctx, scopeSegs, sec, scopePrefix, changelogScopePrefix),
+          scopePrefix
+        );
       }
+      annotated.push({ node, pos: metaNum(s.seg.metadata, "childIndex"), isLeaf: false });
     }
   }
+  const hasLeafPos = annotated.some((a) => a.isLeaf && a.pos != null);
+  const hasSegmentPos = annotated.some((a) => !a.isLeaf && a.pos != null);
+  const flat = hasLeafPos && hasSegmentPos ? annotated.map((a, seq) => ({ ...a, seq })).sort(
+    (x, y) => (x.pos ?? Number.MAX_SAFE_INTEGER) - (y.pos ?? Number.MAX_SAFE_INTEGER) || x.seq - y.seq
+  ).map((a) => a.node) : annotated.map((a) => a.node);
   return groupSidebarRootChildren(ctx, flat);
 }
 function groupSidebarRootChildren(ctx, children) {
@@ -1111,9 +1497,13 @@ function groupSidebarRootChildren(ctx, 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)) {
+    } else if (child.type === "section" && !child.collapsible) {
       flushRun();
       out.push(child);
+    } else if (child.type === "changelog") {
+      flushRun();
+      run.push(child);
+      flushRun();
     } else {
       run.push(child);
     }
@@ -1121,19 +1511,22 @@ function groupSidebarRootChildren(ctx, children) {
   flushRun();
   return out;
 }
-function buildSidebarRoot(ctx, scopeSegs) {
+function buildSidebarRoot(ctx, scopeSegs, scopePrefix, changelogScopePrefix) {
   const first = scopeSegs[0];
   return {
     type: "sidebarRoot",
     id: ctx.nodeId(`sidebar:${first != null ? scopeKey(first.seg) : "root"}`),
     collapsed: void 0,
-    children: buildSidebarRootChildren(ctx, scopeSegs)
+    children: buildSidebarRootChildren(ctx, scopeSegs, scopePrefix, changelogScopePrefix)
   };
 }
 function buildFullRootFromSegments(options) {
   const { basePath, title, segments, navBySegment } = options;
   const ctx = createBuildContext(basePath);
-  const scoped = segments.map((seg) => ({ seg, meta: segMeta(seg), nav: navBySegment.get(seg.segmentHash) ?? [] })).filter((s) => s.meta.type !== "files" && s.meta.type !== "redirects");
+  const scoped = segments.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);
   const scopesByKey = /* @__PURE__ */ new Map();
   for (const s of scoped) {
@@ -1151,7 +1544,7 @@ function buildFullRootFromSegments(options) {
   } else if (versions.length > 0) {
     child = buildVersioned(ctx, versions, scoped, rootSlug, void 0);
   } else {
-    child = buildUnversioned(ctx, scoped, tabs.length > 0);
+    child = buildUnversioned(ctx, scoped, rootSlug, tabs.length > 0);
   }
   let rootPointsTo;
   if (child.type === "productgroup") {
@@ -1161,20 +1554,15 @@ function buildFullRootFromSegments(options) {
     const defaultVersion = child.children.find((v) => v.default) ?? child.children[0];
     rootPointsTo = defaultVersion?.pointsTo;
   }
-  return {
+  const root = {
     type: "root",
     version: "v2",
-    ...withMetadataDefaults({
-      id: ctx.nodeId("root"),
-      title,
-      slug: rootSlug,
-      icon: void 0,
-      hidden: void 0
-    }),
+    ...withMetadataDefaults({ id: ctx.nodeId("root"), title, slug: rootSlug, icon: void 0, hidden: void 0 }),
     roles: void 0,
     pointsTo: rootPointsTo,
     child
   };
+  return root;
 }
 function uniqueDetails(scoped, dim) {
   const bySlug = /* @__PURE__ */ new Map();
@@ -1183,14 +1571,15 @@ function uniqueDetails(scoped, dim) {
     if (d == null) {
       continue;
     }
-    const dm = detailMeta(d);
-    const slug = dm.slug ?? "";
+    const slug = detailSlug(d);
     const existing = bySlug.get(slug);
-    if (existing == null || dm.pointsTo != null && existing.meta.pointsTo == null) {
-      bySlug.set(slug, { detail: d, meta: dm });
+    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()].map((e) => e.detail).sort((a, b) => a.sortOrder - b.sortOrder);
+  return [...bySlug.values()].sort((a, b) => a.sortOrder - b.sortOrder);
 }
 function scopeSlugPrefix(rootSlug, ...details) {
   const parts = [rootSlug];
@@ -1204,30 +1593,80 @@ function scopeSlugPrefix(rootSlug, ...details) {
   }
   return slugjoin(...parts);
 }
-function buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent) {
+function buildVariantedNode(ctx, variants, scopeSegs, scopePrefix) {
+  const variantChildren = variants.map((variant) => {
+    const variantSegs = scopeSegs.filter((s) => s.seg.variant?.id === variant.id);
+    const variantIndividualSlug = detailSlug(variant);
+    const variantSlug = variantIndividualSlug !== "" ? asSlug(slugjoin(scopePrefix, variantIndividualSlug)) : scopePrefix;
+    const metaPointsTo = metaStr(variant.metadata, "pointsTo");
+    const children = buildSidebarRootChildren(ctx, variantSegs, scopePrefix);
+    return {
+      type: "variant",
+      ...withMetadataDefaults({
+        id: ctx.nodeId(`variant:${variantSlug}`),
+        title: variant.displayName,
+        slug: variantSlug,
+        icon: variant.icon ?? void 0,
+        hidden: variant.hidden,
+        viewers: toViewers(variant.viewers)
+      }),
+      default: detailIsDefault(variant),
+      variantId: VariantId(String(variant.id)),
+      subtitle: metaStr(variant.metadata, "subtitle") ?? void 0,
+      image: void 0,
+      pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : void 0,
+      children
+    };
+  });
+  return {
+    type: "varianted",
+    id: ctx.nodeId(`varianted:${scopeSegs[0] != null ? scopeKey(scopeSegs[0].seg) : "root"}`),
+    collapsed: void 0,
+    children: variantChildren
+  };
+}
+function buildSidebarRootWithVariants(ctx, scopeSegs, scopePrefix, changelogScopePrefix) {
+  const variants = uniqueDetails(scopeSegs, "variant");
+  if (variants.length <= 1) {
+    return buildSidebarRoot(ctx, scopeSegs, scopePrefix, changelogScopePrefix);
+  }
+  const variantedNode = buildVariantedNode(ctx, variants, scopeSegs, scopePrefix);
+  const first = scopeSegs[0];
+  return {
+    type: "sidebarRoot",
+    id: ctx.nodeId(`sidebar:${first != null ? scopeKey(first.seg) : "root"}`),
+    collapsed: void 0,
+    children: [variantedNode]
+  };
+}
+function buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent, scopePrefix) {
   if (!tabsPresent) {
-    return buildSidebarRoot(ctx, scopeSegs);
+    const variants = uniqueDetails(scopeSegs, "variant");
+    if (variants.length > 1) {
+      return buildVariantedNode(ctx, variants, scopeSegs, scopePrefix);
+    }
+    return buildSidebarRoot(ctx, scopeSegs, scopePrefix);
   }
   const tabDetails = uniqueDetails(scopeSegs, "tab");
   const children = tabDetails.map((tab) => {
-    const tm = detailMeta(tab);
-    const tabSlug = asSlug(scopeSlugPrefix(Slug(""), tab));
-    if (tm.tab_type === "link") {
+    const tabType = metaStr(tab.metadata, "tab_type");
+    const tabSlug = asSlug(scopeSlugPrefix(scopePrefix, tab));
+    if (tabType === "link") {
       return {
         type: "link",
-        id: ctx.nodeId(`link:${tm.url ?? tabSlug}`),
+        id: ctx.nodeId(`link:${metaStr(tab.metadata, "url") ?? tabSlug}`),
         collapsed: void 0,
         title: tab.displayName,
         icon: tab.icon ?? void 0,
-        url: Url(tm.url ?? ""),
+        url: Url(metaStr(tab.metadata, "url") ?? ""),
         target: void 0
       };
     }
-    if (tm.tab_type === "changelog") {
+    if (tabType === "changelog") {
       const tabSegs2 = scopeSegs.filter((s) => s.seg.tab?.id === tab.id);
-      const changelogSeg = tabSegs2.find((s) => s.meta.type === "changelog");
+      const changelogSeg = tabSegs2.find((s) => metaStr(s.seg.metadata, "type") === "changelog");
       if (changelogSeg != null) {
-        return changelogNode(ctx, changelogSeg);
+        return changelogNode(ctx, changelogSeg, scopePrefix);
       }
       return {
         type: "changelog",
@@ -1245,6 +1684,7 @@ function buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent) {
       };
     }
     const tabSegs = scopeSegs.filter((s) => s.seg.tab?.id === tab.id);
+    const metaPointsTo = metaStr(tab.metadata, "pointsTo");
     return {
       type: "tab",
       ...withMetadataDefaults({
@@ -1255,8 +1695,15 @@ function buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent) {
         hidden: tab.hidden,
         viewers: toViewers(tab.viewers)
       }),
-      pointsTo: pointsToSlug(ctx, tm),
-      child: buildSidebarRoot(ctx, tabSegs)
+      pointsTo: metaPointsTo != null ? pointsToSlug(metaPointsTo) : void 0,
+      // Structural sections under this tab are rooted at the TAB slug
+      // (`{...}/{version}/{tab}`) so their slugs nest under the tab
+      // (matching v2) while still starting with the version slug, keeping
+      // the subtree inside the default-version prune window (see
+      // {@link structuralNodeSlug}).
+      // Changelog sidebar children use the product/version prefix — v2
+      // roots changelogs at the scope level, not under the tab.
+      child: buildSidebarRootWithVariants(ctx, tabSegs, tabSlug, scopePrefix)
     };
   });
   const first = scopeSegs[0];
@@ -1267,24 +1714,27 @@ function buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent) {
     children
   };
 }
-function buildUnversioned(ctx, scopeSegs, tabsPresent) {
+function buildUnversioned(ctx, scopeSegs, scopePrefix, tabsPresent) {
   const first = scopeSegs[0];
   return {
     type: "unversioned",
     id: ctx.nodeId(`unversioned:${first?.seg.product?.id ?? "root"}`),
     collapsed: void 0,
     landingPage: void 0,
-    child: buildTabbedOrSidebar(ctx, scopeSegs, tabsPresent)
+    // 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) {
   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 {
+    const prefix = productPrefix != null ? productPrefix : rootSlug;
+    const versionSegment = detailSlug(version);
+    const slug = versionSegment !== "" ? slugjoin(asSlug(prefix), versionSegment) : asSlug(prefix);
+    const node = {
       type: "version",
       ...withMetadataDefaults({
         id: ctx.nodeId(`version:${slug}`),
@@ -1294,14 +1744,20 @@ function buildVersioned(ctx, versions, scoped, rootSlug, productPrefix) {
         hidden: version.hidden,
         viewers: toViewers(version.viewers)
       }),
-      default: vm.default ?? false,
+      default: detailIsDefault(version),
       versionId: VersionId(version.id),
       availability: void 0,
       landingPage: void 0,
       announcement: void 0,
-      pointsTo: pointsToSlug(ctx, vm),
-      child: buildTabbedOrSidebar(ctx, versionSegs, tabsPresent)
+      pointsTo: metaStr(version.metadata, "pointsTo") != null ? pointsToSlug(metaStr(version.metadata, "pointsTo")) : void 0,
+      // The version's full slug roots structural sections so the whole
+      // version subtree stays inside the default-version prune window.
+      child: buildTabbedOrSidebar(ctx, versionSegs, tabsPresent, asSlug(slug))
     };
+    if (node.default) {
+      markDefaultVersionCanonicalSlugs(node, productPrefix != null ? asSlug(productPrefix) : rootSlug, node.slug);
+    }
+    return node;
   });
   return {
     type: "versioned",
@@ -1310,15 +1766,32 @@ function buildVersioned(ctx, versions, scoped, rootSlug, productPrefix) {
     children
   };
 }
+function markDefaultVersionCanonicalSlugs(node, pruneSlug, versionSlug) {
+  traverseDF(node, (child) => {
+    if (hasMetadata(child)) {
+      const canonicalSlug = toDefaultSlug(
+        child.canonicalSlug ?? child.slug,
+        pruneSlug,
+        versionSlug
+      );
+      if (canonicalSlug !== child.slug) {
+        child.canonicalSlug = canonicalSlug;
+      }
+    }
+    if (hasRedirect(child)) {
+      child.pointsTo = toDefaultSlug(child.pointsTo, pruneSlug, versionSlug);
+    }
+    return;
+  });
+}
 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);
-    const productChild = versions.length > 0 ? buildVersioned(ctx, versions, productSegs, rootSlug, productPrefix) : buildUnversioned(ctx, productSegs, tabsPresent);
-    return {
+    const productChild = versions.length > 0 ? buildVersioned(ctx, versions, productSegs, rootSlug, productPrefix) : buildUnversioned(ctx, productSegs, asSlug(productPrefix), tabsPresent);
+    const node = {
       type: "product",
       ...withMetadataDefaults({
         id: ctx.nodeId(`product:${productPrefix}`),
@@ -1329,13 +1802,19 @@ function buildProductGroup(ctx, products, scoped, rootSlug) {
         viewers: toViewers(product.viewers)
       }),
       default: detailIsDefault(product),
-      productId: ProductId(product.id),
-      subtitle: pm.subtitle ?? "",
+      // `product.id` is the content-addressed STORAGE hash (the segment
+      // key). `productId` is the SEMANTIC identifier search/UI key off
+      // (the product-scoped search filter does `product.title:${productId}`,
+      // so it must equal the product title). v2 carries the display name
+      // here; sourcing it from the hash makes that filter match nothing.
+      productId: ProductId(product.displayName),
+      subtitle: metaStr(product.metadata, "subtitle") ?? "",
       image: void 0,
       announcement: void 0,
-      pointsTo: pointsToSlug(ctx, pm),
+      pointsTo: metaStr(product.metadata, "pointsTo") != null ? pointsToSlug(metaStr(product.metadata, "pointsTo")) : void 0,
       child: productChild
     };
+    return node;
   });
   return {
     type: "productgroup",
@@ -1349,6 +1828,8 @@ export {
   apiLeafNodeFromNavRoute,
   buildFullRootFromSegments,
   collectApiLeafNodesFromNav,
+  createBuildContext,
+  mergeEndpointPairs,
   segmentApiDefinitionId
 };
 //# sourceMappingURL=ledger-root-builder.mjs.map