@takazudo/zudo-doc 5.28.2 → 6.0.1

package/eject/image-enlarge/index.tsx

@@ -1,21 +1,18 @@
 "use client";
 
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-
 // Image-enlarge island — relocated from src/components/image-enlarge.tsx
 // (host showcase) into the package as part of Package-First Wave 3 (S3,
-// epic #2344). Uses shared hook + constants from S1a foundation:
-//   - useModalDialog  from @takazudo/zudo-doc/use-modal-dialog
-//   - IMAGE_ENLARGE_DIALOG_CLASS / ENLARGE_DIALOG_STYLE from @takazudo/zudo-doc/island-types
+// epic #2344). The browser-only observers and delegated listeners are owned
+// by this island's activation scope.
 //
 // The `/api/ai-chat` endpoint stays host-side (showcase-only).
 // CSS blocks (.zd-enlargeable, .zd-enlarge-btn, .zd-enlarge-dialog*) are
 // shipped in @takazudo/zudo-doc/features.css (moved from src/styles/global.css).
 
-import { useState, useEffect } from "preact/compat";
+import { computed, getScope, Show, signal } from "@takazudo/zfb/zudo-react";
 import { AFTER_NAVIGATE_EVENT } from "../transitions/index.js";
-import { useModalDialog } from "../use-modal-dialog/index.js";
+import { modalDialog } from "../use-modal-dialog/index.js";
 import {
   IMAGE_ENLARGE_DIALOG_CLASS,
   ENLARGE_DIALOG_STYLE,
@@ -32,12 +29,24 @@ interface ImageData {
 }
 
 export function ImageEnlarge() {
-  const [imgData, setImgData] = useState<ImageData | null>(null);
-
-  // Eligibility detection: toggle .zd-enlarge-btn[hidden] per image
-  useEffect(() => {
+  const scope = getScope();
+  const imgData = signal<ImageData | null>(null);
+  const isOpen = computed(() => imgData.value !== null);
+  const imageSrc = computed(() => {
+    const current = imgData.value;
+    return current ? current.currentSrc || current.src : "";
+  });
+  const imageSrcset = computed(() => imgData.value?.srcset ?? "");
+  const imageHasSrcset = computed(() => Boolean(imgData.value?.srcset));
+  const imageAlt = computed(() => imgData.value?.alt ?? "");
+
+  // Eligibility detection and route-aware image scanning. All browser access
+  // starts at activation so SSR and hydration begin from the same closed shell.
+  scope.onActivate(() => {
+    let active = true;
     const observedImages = new Set<HTMLImageElement>();
     const sharedResizeObserver = new ResizeObserver((entries) => {
+      if (!active) return;
       for (const entry of entries) {
         evaluateEligibility(entry.target as HTMLImageElement);
       }
@@ -49,7 +58,7 @@ export function ImageEnlarge() {
     function evaluateEligibility(img: HTMLImageElement) {
       const container = img.closest(".zd-enlargeable");
       if (!container) return;
-      const btn = container.querySelector(".zd-enlarge-btn") as HTMLElement | null;
+      const btn = container.querySelector<HTMLElement>(".zd-enlarge-btn");
       if (!btn) return;
       const eligible = img.naturalWidth > img.clientWidth * window.devicePixelRatio;
       if (eligible) {
@@ -75,26 +84,30 @@ export function ImageEnlarge() {
     }
 
     function scanContent() {
-      const scope = document.querySelector("main .zd-content");
-      if (!scope) return;
-      scope.querySelectorAll<HTMLImageElement>(".zd-enlargeable img").forEach(observeImage);
+      const content = document.querySelector("main .zd-content");
+      if (!content) return;
+      content.querySelectorAll<HTMLImageElement>(".zd-enlargeable img").forEach(observeImage);
     }
 
     function startObserving() {
-      const scope = document.querySelector("main .zd-content");
-      if (scope) {
+      const content = document.querySelector("main .zd-content");
+      if (content) {
         mutationObserver = new MutationObserver((mutations) => {
+          if (!active) return;
           for (const mutation of mutations) {
             for (const node of mutation.addedNodes) {
               if (!(node instanceof Element)) continue;
               if (node.matches(".zd-enlargeable")) {
                 node.querySelectorAll<HTMLImageElement>("img").forEach(observeImage);
               }
+              if (node instanceof HTMLImageElement && node.closest(".zd-enlargeable")) {
+                observeImage(node);
+              }
               node.querySelectorAll<HTMLImageElement>(".zd-enlargeable img").forEach(observeImage);
             }
           }
         });
-        mutationObserver.observe(scope, { childList: true, subtree: true });
+        mutationObserver.observe(content, { childList: true, subtree: true });
       }
       scanContent();
     }
@@ -102,11 +115,13 @@ export function ImageEnlarge() {
     function handleWindowResize() {
       clearTimeout(resizeTimer);
       resizeTimer = window.setTimeout(() => {
+        if (!active) return;
         observedImages.forEach((img) => evaluateEligibility(img));
       }, 150);
     }
 
-    function handleAfterSwap() {
+    function handleAfterNavigate() {
+      if (!active) return;
       sharedResizeObserver.disconnect();
       observedImages.clear();
       mutationObserver?.disconnect();
@@ -118,32 +133,36 @@ export function ImageEnlarge() {
 
     startObserving();
     window.addEventListener("resize", handleWindowResize);
-    document.addEventListener(AFTER_NAVIGATE_EVENT, handleAfterSwap);
+    document.addEventListener(AFTER_NAVIGATE_EVENT, handleAfterNavigate);
 
     return () => {
+      active = false;
       sharedResizeObserver.disconnect();
       observedImages.clear();
       mutationObserver?.disconnect();
       loadAbortController.abort();
       window.removeEventListener("resize", handleWindowResize);
-      document.removeEventListener(AFTER_NAVIGATE_EVENT, handleAfterSwap);
+      document.removeEventListener(AFTER_NAVIGATE_EVENT, handleAfterNavigate);
       clearTimeout(resizeTimer);
     };
-  }, []);
+  });
 
-  useEffect(() => {
-    function handleDocumentClick(e: MouseEvent) {
-      const sel = window.getSelection();
-      if (sel && !sel.isCollapsed) return;
-      const target = e.target as Element;
+  // Click detection is delegated because the images live in authored MDX.
+  scope.onActivate(() => {
+    let active = true;
+    function handleDocumentClick(event: Event) {
+      if (!active || !(event.target instanceof Element)) return;
+      const target = event.target;
+      const selection = window.getSelection();
+      if (selection && !selection.isCollapsed) return;
       const container = target.closest(".zd-enlargeable");
       if (!container) return;
       if (!target.closest(".zd-enlarge-btn") && !target.closest("img")) return;
-      const btn = container.querySelector(".zd-enlarge-btn") as HTMLElement | null;
+      const btn = container.querySelector<HTMLElement>(".zd-enlarge-btn");
       if (!btn || btn.hasAttribute("hidden")) return;
-      const img = container.querySelector("img") as HTMLImageElement | null;
+      const img = container.querySelector<HTMLImageElement>("img");
       if (!img) return;
-      setImgData({
+      imgData.value = {
         src: img.src,
         currentSrc: img.currentSrc,
         srcset: img.srcset || undefined,
@@ -151,16 +170,20 @@ export function ImageEnlarge() {
         alt: img.alt,
         naturalWidth: img.naturalWidth,
         naturalHeight: img.naturalHeight,
-      });
+      };
     }
     document.addEventListener("click", handleDocumentClick);
-    return () => document.removeEventListener("click", handleDocumentClick);
-  }, []);
-
-  const handleClose = () => setImgData(null);
+    return () => {
+      active = false;
+      document.removeEventListener("click", handleDocumentClick);
+    };
+  });
 
-  const { dialogRef, handleBackdropClick } = useModalDialog({
-    isOpen: imgData !== null,
+  const handleClose = () => {
+    imgData.value = null;
+  };
+  const { dialogRef, handleBackdropClick } = modalDialog(scope, {
+    isOpen,
     onClose: handleClose,
     navigateEvent: AFTER_NAVIGATE_EVENT,
     backdropClickClose: true,
@@ -169,51 +192,43 @@ export function ImageEnlarge() {
   return (
     <dialog
       ref={dialogRef}
-      onClick={handleBackdropClick}
-      className={IMAGE_ENLARGE_DIALOG_CLASS}
+      on:click={handleBackdropClick}
+      class={IMAGE_ENLARGE_DIALOG_CLASS}
       style={ENLARGE_DIALOG_STYLE}
     >
-      {imgData && (
+      <Show when={isOpen}>{() => (
         <>
-          <div className="relative">
-            <img
-              src={imgData.currentSrc || imgData.src}
-              srcSet={imgData.srcset}
-              sizes={imgData.srcset ? "85vw" : undefined}
-              alt={imgData.alt}
-              className="block max-h-[85vh] max-w-[85vw] object-contain"
-            />
+          <div class="relative">
+            <Show when={imageHasSrcset}>{() => (
+              <img
+                src={imageSrc}
+                srcset={imageSrcset}
+                sizes="85vw"
+                alt={imageAlt}
+                class="block max-h-[85vh] max-w-[85vw] object-contain"
+              />
+            )}</Show>
+            <Show when={computed(() => !imageHasSrcset.value)}>{() => (
+              <img
+                src={imageSrc}
+                alt={imageAlt}
+                class="block max-h-[85vh] max-w-[85vw] object-contain"
+              />
+            )}</Show>
           </div>
           <button
             type="button"
-            onClick={() => dialogRef.current?.close()}
-            className="zd-enlarge-dialog-close"
+            on:click={() => dialogRef.current?.close()}
+            class="zd-enlarge-dialog-close"
             aria-label="Close enlarged image"
           >
-            <svg viewBox="0 0 161.03 161.03" fill="currentColor" aria-hidden="true" focusable="false">
+            <svg viewBox="0 0 161.03 161.03" fill="currentColor" aria-hidden="true">
               <polygon points="161.03 10.27 150.76 0 80.51 70.24 10.27 0 0 10.27 70.24 80.51 0 150.76 10.27 161.03 80.51 90.78 150.76 161.03 161.03 150.76 90.78 80.51 161.03 10.27" />
             </svg>
           </button>
         </>
-      )}
+      )}</Show>
     </dialog>
   );
 }
 ImageEnlarge.displayName = "ImageEnlarge";
-
-/**
- * Static SSR fallback for the {@link ImageEnlarge} island.
- *
- * Renders an empty, closed `<dialog class="zd-enlarge-dialog ...">` so the
- * dist HTML carries the dialog shell even before hydration. Sources its
- * class and inline style from the shared constants in island-types so the
- * SSR fallback cannot drift from the hydrated dialog above.
- */
-export function ImageEnlargeSsrFallback() {
-  return (
-    <dialog
-      className={IMAGE_ENLARGE_DIALOG_CLASS}
-      style={ENLARGE_DIALOG_STYLE}
-    />
-  );
-}

package/eject/image-enlarge/public.ts

@@ -0,0 +1,2 @@
+export { ImageEnlarge } from "./index.js";
+export { ImageEnlargeSsrFallback } from "./ssr-fallback.js";

package/eject/image-enlarge/ssr-fallback.tsx

@@ -0,0 +1,7 @@
+/** @jsxRuntime automatic */
+import { IMAGE_ENLARGE_DIALOG_CLASS, ENLARGE_DIALOG_STYLE } from "../island-types/index.js";
+
+/** Closed dialog shell rendered before island activation. */
+export function ImageEnlargeSsrFallback() {
+  return <dialog class={IMAGE_ENLARGE_DIALOG_CLASS} style={ENLARGE_DIALOG_STYLE} />;
+}

package/eject/page-loading/page-loading-overlay.tsx

@@ -1,18 +1,12 @@
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-
 // Server-rendered, zero-hydration full-page loading overlay.
 //
-// Renders three things into the document:
+// Renders the overlay and its bootstrap into the document:
 //
 //   1. A fixed-position overlay `<div>` with a centered spinner. Hidden
 //      by default (`opacity: 0; pointer-events: none;`) and made
 //      visible by adding `data-visible` to it.
-//   2. A `<style>` block that owns the overlay + spinner CSS plus the
-//      `prefers-reduced-motion` fallback. Inlined via
-//      `dangerouslySetInnerHTML` (matching the ColorSchemeProvider
-//      pattern) so no separate stylesheet has to be wired up.
-//   3. A small `<script>` that toggles the `data-visible` attribute on
+//   2. A small `<script>` that toggles the `data-visible` attribute on
 //      navigation lifecycle events. The event names come from the
 //      `@takazudo/zudo-doc/transitions` module — this component does
 //      not reach for the underlying browser event names directly. Under
@@ -21,9 +15,8 @@
 //      `zfb:after-swap` (AFTER_NAVIGATE_EVENT); see
 //      `transitions/page-events.ts` for rationale.
 //
-// The component is intentionally not hydrated. Hydrating Preact just to
-// attach two listeners would be wasteful given the original Astro file
-// shipped a tiny imperative script — this port keeps that profile.
+// Its CSS stays in the host's global stylesheet, and the component is not
+// hydrated: the static script owns its navigation listeners.
 
 import {
   AFTER_NAVIGATE_EVENT,
@@ -52,7 +45,9 @@ export function buildPageLoadingOverlayBootstrap(overlayId: string): string {
   // (see ColorSchemeProvider). Event names come from the transitions
   // module's exported constants — no raw `astro:*` strings live in
   // this file.
-  const id = JSON.stringify(overlayId);
+  // JSON quoting protects JavaScript syntax, and escaping `<` additionally
+  // prevents a caller-controlled id from terminating the HTML script element.
+  const id = JSON.stringify(overlayId).replaceAll("<", "\\u003c");
   const before = JSON.stringify(BEFORE_NAVIGATE_EVENT);
   const after = JSON.stringify(AFTER_NAVIGATE_EVENT);
   return `(function(){
@@ -94,9 +89,7 @@ export default function PageLoadingOverlay({
         <span class="page-loading-spinner" />
       </div>
       <script
-        dangerouslySetInnerHTML={{
-          __html: buildPageLoadingOverlayBootstrap(id),
-        }}
+        rawHtml={buildPageLoadingOverlayBootstrap(id)}
       />
     </>
   );

package/eject/sidebar/client-data.ts

@@ -0,0 +1,68 @@
+import { normalizeIslandData } from "../chrome/island-data.js";
+import type { SidebarNavNode, SidebarNavigationContext } from "./types.js";
+
+/** Navigation data needed by the native sidebar islands, without server prose. */
+export type SidebarClientNode = Omit<SidebarNavNode, "description" | "children"> & {
+  children: SidebarClientNode[];
+};
+
+export type SidebarClientNavigation = Omit<SidebarNavigationContext, "roots"> & {
+  roots: SidebarClientNode[];
+};
+
+// Exhaustive policy: new server fields require an explicit transport decision.
+const nodeFields = {
+  occurrenceId: true,
+  slug: true,
+  label: true,
+  description: false,
+  position: true,
+  href: true,
+  hasPage: true,
+  children: true,
+  sortOrder: true,
+  collapsed: true,
+  shape: true,
+  noteTrayDated: true,
+  noteTraySidebar: true,
+  date: true,
+  updated: true,
+  rank: true,
+} as const satisfies Record<keyof SidebarNavNode, boolean>;
+
+/**
+ * Copy navigation for SSR and hydration at an island boundary. Server builders
+ * retain descriptions; custom island hosts can opt into this same projection.
+ * Validate before selecting fields so discarded data cannot conceal invalid
+ * transport values. Preserve the opaque scope ID and editorial topology.
+ */
+export function toSidebarClientData(
+  nodes: SidebarNavNode[],
+  navigation?: SidebarNavigationContext,
+): { nodes: SidebarClientNode[]; navigation?: SidebarClientNavigation } {
+  const source = normalizeIslandData({ nodes, navigation });
+  function project(node: SidebarNavNode): SidebarClientNode {
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(nodeFields) as Array<keyof SidebarNavNode>) {
+      if (nodeFields[key] && key !== "children" && node[key] !== undefined) {
+        result[key] = node[key];
+      }
+    }
+    result.children = node.children.map(project);
+    return result as SidebarClientNode;
+  }
+  return {
+    nodes: source.nodes.map(project),
+    ...(source.navigation ? {
+      navigation: {
+        id: source.navigation.id,
+        roots: source.navigation.roots.map(project),
+        parents: source.navigation.parents,
+        ...(source.navigation.initialExpansion !== undefined
+          ? { initialExpansion: source.navigation.initialExpansion } : {}),
+        ...(source.navigation.localParentId !== undefined
+          ? { localParentId: source.navigation.localParentId } : {}),
+      },
+    } : {}),
+  };
+}

package/eject/sidebar/index.ts

@@ -18,10 +18,13 @@
  */
 
 export { Sidebar } from "./sidebar.js";
+export { toSidebarClientData } from "./client-data.js";
+export type { SidebarClientNode, SidebarClientNavigation } from "./client-data.js";
 export type { SidebarProps } from "./sidebar.js";
 export type {
   SidebarLocaleLink,
   SidebarNavNode,
+  SidebarNavigationContext,
   SidebarRootMenuItem,
   SidebarTreeIslandProps,
 } from "./types.js";

package/eject/sidebar/sidebar.tsx

@@ -1,108 +1,30 @@
-"use client";
-
 /** @jsxRuntime automatic */
-/** @jsxImportSource preact */
-
-// JSX port of src/components/sidebar.
-//
-// The original Astro template was almost entirely data assembly —
-// build root-menu items from `settings.headerNav`, load the locale's
-// docs collection, build the nav tree for the active section, optionally
-// remap hrefs for versioned routes, and finally render the project's
-// `<SidebarTree client:load .../>` Preact island.
-//
-// All of that data-prep depends on host-only helpers (`@/config/i18n`,
-// `@/utils/sidebar`, `@/utils/locale-docs`, `@/utils/base`,
-// `@/config/settings`) that v2 must not import. This shell therefore
-// keeps the data-prep on the host side and only provides:
-//
-//   - typed props that match the SidebarTree island's prop shape, so
-//     the host's prep code can be typed against v2's interface;
-//   - a `treeComponent` prop the host supplies (their existing Preact
-//     island) — the shell instantiates it with the typed props and
-//     forwards everything;
-//   - a `children` fallback for callers that want to render the tree
-//     themselves (useful for tests, fixtures, and downstream projects
-//     that swap the tree out wholesale).
-//
-// Wave 13 ("smoke-toc duplicate-nav regression follow-on", zudolab/zudo-doc#1355):
-// before this refactor, this module exported a `Sidebar` wrapper that
-// itself called `Island({when:"load", children:<SidebarInner/>})` and
-// returned the wrapped div. The zfb island scanner picked the exported
-// `Sidebar` (the wrapper) as the bundle's hydration target, so on the
-// client `mountIslands` ran `hydrate(<Sidebar/>, dataIslandDiv)` where
-// the rendered vnode itself emitted *another* `<div data-zfb-island=
-// "Sidebar"><SidebarInner/></div>` inside the existing one. Unlike the
-// `Toc` / `MobileToc` case (where the inner re-rendered identical
-// content alongside the SSR'd content, producing a visible duplicate),
-// the duplicate here was silent: the host passes `treeComponent` (a
-// Preact component function) as a prop, and `island.ts`'s
-// `captureSerializableProps` does `JSON.stringify` on the props bag,
-// which silently drops function values. At hydrate time the
-// deserialized props had no `treeComponent`, `SidebarInner` returned
-// `null`, and the appended wrapper-div was empty. Net result: an extra
-// dead-mount data-zfb-island Sidebar div alongside the SSR'd tree, with
-// no observable content — but a wasted hydration slot, and the actual
-// user-facing event-handler / state work was being done entirely by
-// the host's `SidebarTree` island registration.
-//
-// Fix: same shape as Toc / MobileToc — drop the `Island`-wrapping
-// outer, export the bare component (was `SidebarInner`) as `Sidebar`,
-// pin `displayName` explicitly. The `<Island when="load">` wrapper is
-// applied at the call site (`<DocLayoutWithDefaults>`).
 
-import type { ComponentChildren, FunctionComponent, VNode } from "preact";
+import type { Child, Component } from "@takazudo/zfb/zudo-react";
 
 import type { SidebarTreeIslandProps } from "./types.js";
 
+/**
+ * Props for the server-rendered Sidebar shell. Data preparation stays with the
+ * caller, which may supply a tree component or already-rendered children.
+ */
 export interface SidebarProps extends SidebarTreeIslandProps {
-  /**
-   * The host's SidebarTree component. When present, the shell renders
-   * `<TreeComponent {...islandProps} />` with the typed props below.
-   * Mutually exclusive with `children`: prefer this form so v2 owns the
-   * prop forwarding contract.
-   */
-  treeComponent?: FunctionComponent<SidebarTreeIslandProps>;
-  /**
-   * Pre-rendered tree content — falls back to this when
-   * `treeComponent` is omitted. Useful for tests and for layouts that
-   * compose the tree separately (e.g. inside a host wrapper
-   * that needs `client:load` on the actual island element).
-   */
-  children?: ComponentChildren;
+  /** Component used to render the prepared tree. */
+  treeComponent?: Component<SidebarTreeIslandProps>;
+  /** Pre-rendered tree content for callers that compose the tree separately. */
+  children?: Child;
 }
 
 /**
- * Sidebar shell — typed wrapper around the SidebarTree island.
- *
- * Two usage shapes (matching the breadcrumb shell's pattern):
- *
- *   1. Pass `treeComponent` plus the data props (`nodes`,
- *      `rootMenuItems`, `localeLinks`, …). The shell forwards them all
- *      to the supplied component.
- *
- *   2. Pass `children` (e.g. a pre-instantiated `<SidebarTree
- *      client:load … />` from an Astro wrapper). The shell renders
- *      them as-is — the typed island props are then unused but kept on
- *      the type signature so call-sites stay self-documenting.
- *
- * **The caller is responsible for wrapping this in `<Island when="load">`**
- * so the SSG output emits the `data-zfb-island="Sidebar"` hydration
- * marker around the rendered tree. `<DocLayoutWithDefaults>` does this
- * for you; consumers who render `<Sidebar>` outside the default layout
- * (e.g. via the `sidebarOverride` prop or in a custom layout) must
- * apply the wrapper themselves — otherwise no hydration marker is
- * emitted, and the runtime walks past the SSR'd tree without claiming
- * it as an island. Either way the actual user-facing interactivity
- * comes from the `treeComponent`'s own island registration; the
- * `<Island>` wrapper here exists so the shell can host data-only
- * variants in the future without losing the marker contract.
+ * Server-rendered shell around prepared navigation content. An empty node list
+ * has no sidebar output and returns null without creating an island boundary.
  */
-export function Sidebar(props: SidebarProps): VNode | null {
+export function Sidebar(props: SidebarProps): Child {
   const {
     treeComponent: TreeComponent,
     children,
     nodes,
+    navigation,
     currentSlug,
     rootMenuItems,
     backToMenuLabel,
@@ -110,10 +32,13 @@ export function Sidebar(props: SidebarProps): VNode | null {
     themeDefaultMode,
   } = props;
 
+  if (nodes.length === 0) return null;
+
   if (TreeComponent) {
     return (
       <TreeComponent
         nodes={nodes}
+        navigation={navigation}
         currentSlug={currentSlug}
         rootMenuItems={rootMenuItems}
         backToMenuLabel={backToMenuLabel}
@@ -129,9 +54,3 @@ export function Sidebar(props: SidebarProps): VNode | null {
 
   return null;
 }
-// Pin the marker name to "Sidebar" regardless of how Preact's compat
-// layer or esbuild minification renames the function. Island's SSR
-// pass reads `displayName ?? name` to derive the marker string;
-// pinning both means the SSG marker stays `data-zfb-island="Sidebar"`
-// independent of the bundle's symbol-renaming.
-Sidebar.displayName = "Sidebar";

package/eject/sidebar/types.ts

@@ -26,6 +26,8 @@
  * Matches `NavNode` in the host project's `src/utils/docs.ts`.
  */
 export interface SidebarNavNode {
+  /** Stable identity of this editorial occurrence, independent of the page slug. */
+  occurrenceId?: string;
   slug: string;
   label: string;
   description?: string;
@@ -71,9 +73,22 @@ export interface SidebarLocaleLink {
  */
 export interface SidebarTreeIslandProps {
   nodes: SidebarNavNode[];
+  navigation?: SidebarNavigationContext;
   currentSlug?: string;
   rootMenuItems?: SidebarRootMenuItem[];
   backToMenuLabel?: string;
   localeLinks?: SidebarLocaleLink[];
   themeDefaultMode?: "light" | "dark";
 }
+
+/** Complete editorial topology, captured before local scoping or filtering. */
+export interface SidebarNavigationContext {
+  /** Locale/version/document-context identity including the topology revision. */
+  id: string;
+  roots: SidebarNavNode[];
+  /** Explicit page/index author defaults; resolved against the current destination. */
+  initialExpansion?: Record<string, "collapsed" | "expanded">;
+  parents: Record<string, string | null>;
+  /** Explicit enclosing occurrence for a local forest spanning emitted children. */
+  localParentId?: string;
+}