@takazudo/zudo-doc 5.5.2 → 5.6.0

package/dist/sidebar-tree-island/index.js

@@ -9,6 +9,7 @@ import { smartBreakToHtml } from "../smart-break/index.js";
 import { AFTER_NAVIGATE_EVENT, BEFORE_NAVIGATE_EVENT } from "../transitions/index.js";
 import { filterTree } from "../sidebar-filter/index.js";
 import { findActiveSlug, normalizePath } from "../sidebar-active-slug/index.js";
+import { CURRENT_PATH_DATASET_KEY, readCurrentPath } from "../current-path/index.js";
 import { ensureSidebarScrollPreserve } from "./sidebar-scroll-preserve.js";
 ensureSidebarScrollPreserve();
 function ToggleChevron({ isExpanded, className }) {
@@ -40,24 +41,25 @@ function saveOpenSet(set) {
   } catch {
   }
 }
-function deriveActiveSlugFromUrl(nodes) {
-  if (typeof window === "undefined") return void 0;
-  const pathname = normalizePath(window.location.pathname);
-  return findActiveSlug(nodes, pathname);
+function deriveActiveSlug(nodes, pathname) {
+  const resolved = readCurrentPath(CURRENT_PATH_DATASET_KEY, pathname);
+  if (!resolved) return void 0;
+  return findActiveSlug(nodes, normalizePath(resolved));
 }
-function useActiveSlug(nodes, initial) {
+function useActiveSlug(nodes, initial, currentPath) {
   const [slug, setSlug] = useState(
-    () => initial !== void 0 ? initial : deriveActiveSlugFromUrl(nodes)
+    () => initial !== void 0 ? initial : deriveActiveSlug(nodes, currentPath)
   );
   useEffect(() => {
-    const update = () => {
-      const found = deriveActiveSlugFromUrl(nodes);
+    const update = (pathname) => {
+      const found = deriveActiveSlug(nodes, pathname);
       if (found !== void 0) setSlug(found);
     };
-    update();
-    document.addEventListener(AFTER_NAVIGATE_EVENT, update);
-    return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, update);
-  }, [nodes]);
+    const onNavigate = () => update();
+    update(currentPath);
+    document.addEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
+    return () => document.removeEventListener(AFTER_NAVIGATE_EVENT, onNavigate);
+  }, [nodes, currentPath]);
   return slug;
 }
 function RootMenuItemEntry({ item }) {
@@ -112,8 +114,8 @@ function SidebarFooter({ links, themeDefaultMode }) {
     ] })
   );
 }
-function SidebarTree({ nodes, currentSlug, rootMenuItems, backToMenuLabel, localeLinks, themeDefaultMode }) {
-  const activeSlug = useActiveSlug(nodes, currentSlug);
+function SidebarTree({ nodes, currentSlug, currentPath, rootMenuItems, backToMenuLabel, localeLinks, themeDefaultMode }) {
+  const activeSlug = useActiveSlug(nodes, currentSlug, currentPath);
   const [query, setQuery] = useState("");
   const [showingRootMenu, setShowingRootMenu] = useState(false);
   const filterRef = useRef(null);

package/dist/site-schema/doc-route-entries.d.ts

@@ -0,0 +1,89 @@
+import type { AutoIndexNode, CategoryMeta, DocEntryLike, DocNavNode, DocPageBaseProps, HeadingItem, NavSourceDocs } from "./types.js";
+/** One enumerated doc route: a content entry or an auto-generated category
+ *  index, with all per-page derived data pre-computed. */
+export interface DocRouteEntry<E extends DocEntryLike = DocEntryLike> {
+    /** Canonical route slug ("" for the docs root index — #1891). */
+    slug: string;
+    /** Optional-catchall params array — `toSlugParams(slug)` ([] for the root). */
+    slugParams: string[];
+    /**
+     * True when the entry came from the base collection rather than the locale
+     * collection (`!localeSlugSet.has(slug)`). Only meaningful on routes whose
+     * nav source performs a locale merge — routes without one (default-locale /
+     * versioned-EN, where `localeSlugSet` is empty) must ignore this field.
+     * Always false for autoIndex items.
+     */
+    isFallback: boolean;
+    /** Shared page props (kind/entry/autoIndex/breadcrumbs/prev/next/headings). */
+    props: DocPageBaseProps<E>;
+}
+export interface BuildDocRouteEntriesArgs<E extends DocEntryLike = DocEntryLike> {
+    /** Identity-stable nav source for this route's (locale, version) context. */
+    source: NavSourceDocs<E>;
+    /** Active locale for nav-tree labels and breadcrumbs. */
+    locale: string;
+    /**
+     * Unique memo signature for this route context. Each route file passes its
+     * own prefix plus the loop variables (version slug / locale), e.g.
+     * "docs;en", "locale-docs;ja", "v-docs;1.0", "v-locale-docs;1.0;ja" —
+     * call sites that share a docs array identity must never collide on a key.
+     */
+    routeSig: string;
+    /** Versioned URL closure bound to the route's version (+ locale). Presence
+     *  switches the versioned behaviors (breadcrumbs, prev/next, child hrefs). */
+    urlFor?: (slug: string) => string;
+}
+/**
+ * Context slice `createDocRouteEntries` derives its bag from (epic Collapse
+ * Wiring Shells #2420, FACTORIES #2424 — breaking signature). STRUCTURAL SUBSET
+ * of the unified `RouteContext`/`ChromeContext` — the nav-tree builder is
+ * reconstructed by binding the context's 4-arg `buildNavTree` to `docsUrl`, and
+ * the breadcrumb trail by binding the package `buildBreadcrumbs` to the
+ * locale-prefixed `withBase` base, exactly as the pre-collapse wiring did.
+ */
+export interface DocRouteEntriesContext<E extends DocEntryLike = DocEntryLike> {
+    /** Default locale code (drives the breadcrumb base-prefix selection). */
+    defaultLocale: string;
+    /** Build the nav tree for a locale (4-arg form with an explicit href builder). */
+    buildNavTree: (docs: E[], locale: string, categoryMeta: Map<string, CategoryMeta> | undefined, buildHref: (slug: string, locale: string) => string) => DocNavNode[];
+    /** Build a docs URL for the given slug and locale. */
+    docsUrl: (slug: string, locale?: string) => string;
+    /** Prefix a path with the configured base directory. */
+    withBase: (path: string) => string;
+    /** Collect all auto-generated index nodes (categories without index.mdx). */
+    collectAutoIndexNodes: (tree: DocNavNode[]) => AutoIndexNode[];
+    /** Determine the nav section (categoryMatch) for a slug. */
+    getNavSectionForSlug: (slug: string) => string | undefined;
+    /** Filter top-level nav nodes by a categoryMatch value. */
+    getNavSubtree: (tree: DocNavNode[], categoryMatch?: string) => DocNavNode[];
+    /** Convert a content entry slug to a canonical route slug. */
+    toRouteSlug: (entrySlug: string) => string;
+    /** Convert a canonical route slug to an optional-catchall params array. */
+    toSlugParams: (slug: string) => string[];
+    /** Extract headings from a raw MDX body (bound to settings depth/strategy). */
+    extractHeadings: (body: string) => HeadingItem[];
+}
+/**
+ * Result of `createDocRouteEntries`. Contains the `buildDocRouteEntries`
+ * function bound to the injected context.
+ */
+export interface DocRouteEntriesAPI<E extends DocEntryLike = DocEntryLike> {
+    /**
+     * Enumerate all doc routes for one (locale, version) context, with per-entry
+     * derived data pre-computed. Memoized per build on the identity-stable
+     * `source.docs` array.
+     */
+    buildDocRouteEntries: (args: BuildDocRouteEntriesArgs<E>) => DocRouteEntry<E>[];
+}
+/**
+ * Create the `buildDocRouteEntries` function bound to the host's injected
+ * context.
+ *
+ * @example
+ * ```ts
+ * import { createDocRouteEntries } from "@takazudo/zudo-doc/site-schema";
+ *
+ * export const { buildDocRouteEntries } = createDocRouteEntries(routeContext);
+ * ```
+ */
+export declare function createDocRouteEntries<E extends DocEntryLike = DocEntryLike>(ctx: DocRouteEntriesContext<E>): DocRouteEntriesAPI<E>;

package/dist/site-schema/doc-route-entries.js

@@ -0,0 +1,83 @@
+import { memoizeDerived } from "../nav-source-cache/index.js";
+import {
+  resolveDocPrevNext,
+  flattenSubtree,
+  rewriteNavHref,
+  remapNavChildHrefs
+} from "../doc-route-paths/index.js";
+import { buildBreadcrumbs as buildBreadcrumbsImpl } from "./nav-tree.js";
+let nextFactoryId = 1;
+function createDocRouteEntries(ctx) {
+  const factoryId = nextFactoryId++;
+  const defaultLocale = ctx.defaultLocale;
+  const buildNavTree = (docs, locale, categoryMeta) => ctx.buildNavTree(docs, locale, categoryMeta, (slug, loc) => ctx.docsUrl(slug, loc));
+  const buildBreadcrumbs = (tree, slug, locale, urlFor) => buildBreadcrumbsImpl(
+    tree,
+    slug,
+    locale === defaultLocale ? ctx.withBase("/") : ctx.withBase(`/${locale}/`),
+    urlFor
+  );
+  const collectAutoIndexNodes = ctx.collectAutoIndexNodes;
+  const getNavSectionForSlug = ctx.getNavSectionForSlug;
+  const getNavSubtree = ctx.getNavSubtree;
+  const toRouteSlug = ctx.toRouteSlug;
+  const toSlugParams = ctx.toSlugParams;
+  const extractHeadings = ctx.extractHeadings;
+  function buildDocRouteEntries(args) {
+    const { source, locale, routeSig, urlFor } = args;
+    return memoizeDerived([source.docs], `docRouteEntries;${factoryId};${routeSig}`, () => {
+      const { docs, navDocs, categoryMeta, localeSlugSet } = source;
+      const tree = buildNavTree(navDocs, locale, categoryMeta);
+      const breadcrumbTree = urlFor ? tree : buildNavTree(docs, locale, categoryMeta);
+      const result = [];
+      for (const entry of docs) {
+        if (entry.data.category_no_page === true) continue;
+        const slug = entry.data.slug ?? toRouteSlug(entry.slug);
+        const navSection = getNavSectionForSlug(slug);
+        const subtree = getNavSubtree(tree, navSection);
+        const { prev: prevNode, next: nextNode } = resolveDocPrevNext(
+          tree,
+          flattenSubtree(subtree),
+          slug,
+          entry.data
+        );
+        result.push({
+          slug,
+          slugParams: toSlugParams(slug),
+          isFallback: !localeSlugSet.has(slug),
+          props: {
+            kind: "entry",
+            entry,
+            breadcrumbs: buildBreadcrumbs(breadcrumbTree, slug, locale, urlFor),
+            prev: rewriteNavHref(prevNode, urlFor),
+            next: rewriteNavHref(nextNode, urlFor),
+            headings: extractHeadings(entry.body ?? "")
+          }
+        });
+      }
+      for (const node of collectAutoIndexNodes(tree)) {
+        result.push({
+          slug: node.slug,
+          slugParams: toSlugParams(node.slug),
+          isFallback: false,
+          props: {
+            kind: "autoIndex",
+            autoIndex: urlFor ? {
+              ...node,
+              children: remapNavChildHrefs(node.children, urlFor)
+            } : node,
+            breadcrumbs: buildBreadcrumbs(breadcrumbTree, node.slug, locale, urlFor),
+            prev: null,
+            next: null,
+            headings: []
+          }
+        });
+      }
+      return result;
+    });
+  }
+  return { buildDocRouteEntries };
+}
+export {
+  createDocRouteEntries
+};

package/dist/site-schema/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Contract version of this module's shape. Bump on any breaking change to the
+ * exported types or functions so a consumer can fail closed rather than
+ * silently mis-read a newer schema (`@takazudo/zudo-doc/catalog` precedent).
+ */
+export declare const schemaVersion = 1;
+export type { AutoIndexNode, BreadcrumbItem, CategoryMeta, CollectionEntryLike, DocEntryLike, DocNavNode, DocPageAutoIndexProps, DocPageBaseProps, DocPageEntryProps, DocPageFrontmatter, HeadingItem, NavSourceDocs, SidebarFrontmatter, SidebarNode, } from "./types.js";
+export type { BuildDocRouteEntriesArgs, DocRouteEntriesAPI, DocRouteEntriesContext, DocRouteEntry, } from "./doc-route-entries.js";
+export type { BuildHref } from "./nav-tree.js";
+export type { PaginationOverrides } from "../doc-route-paths/index.js";
+export { buildBreadcrumbs, buildNavTree, collectAutoIndexNodes, findNode, firstRoutedHref, groupSatelliteNodes, isNavVisible, } from "./nav-tree.js";
+export { flattenSubtree, flattenTree, remapNavChildHrefs, resolveDocPrevNext, rewriteNavHref, } from "../doc-route-paths/index.js";
+export { getCategoryOrder, getNavSectionForSlug, getNavSubtree, } from "../nav-scope/index.js";
+export type { NavScopeHeaderNavItem, NavScopeNode } from "../nav-scope/index.js";
+export { buildSidebarTree } from "../sidebar-tree/build-tree.js";
+export { extractHeadings } from "../extract-headings/index.js";
+export { createDocRouteEntries } from "./doc-route-entries.js";

package/dist/site-schema/index.js

@@ -0,0 +1,46 @@
+const schemaVersion = 1;
+import {
+  buildBreadcrumbs,
+  buildNavTree,
+  collectAutoIndexNodes,
+  findNode,
+  firstRoutedHref,
+  groupSatelliteNodes,
+  isNavVisible
+} from "./nav-tree.js";
+import {
+  flattenSubtree,
+  flattenTree,
+  remapNavChildHrefs,
+  resolveDocPrevNext,
+  rewriteNavHref
+} from "../doc-route-paths/index.js";
+import {
+  getCategoryOrder,
+  getNavSectionForSlug,
+  getNavSubtree
+} from "../nav-scope/index.js";
+import { buildSidebarTree } from "../sidebar-tree/build-tree.js";
+import { extractHeadings } from "../extract-headings/index.js";
+import { createDocRouteEntries } from "./doc-route-entries.js";
+export {
+  buildBreadcrumbs,
+  buildNavTree,
+  buildSidebarTree,
+  collectAutoIndexNodes,
+  createDocRouteEntries,
+  extractHeadings,
+  findNode,
+  firstRoutedHref,
+  flattenSubtree,
+  flattenTree,
+  getCategoryOrder,
+  getNavSectionForSlug,
+  getNavSubtree,
+  groupSatelliteNodes,
+  isNavVisible,
+  remapNavChildHrefs,
+  resolveDocPrevNext,
+  rewriteNavHref,
+  schemaVersion
+};

package/dist/site-schema/nav-tree.d.ts

@@ -0,0 +1,28 @@
+import type { CategoryMeta } from "../sidebar-tree/types.js";
+import type { BreadcrumbItem, DocEntryLike, DocNavNode } from "./types.js";
+/** Filter predicate: true when a doc should appear in navigation. */
+export declare function isNavVisible(doc: DocEntryLike): boolean;
+/** A docs-href builder: `(slug, locale) => url`. */
+export type BuildHref = (slug: string, locale: string) => string;
+/**
+ * Build a recursive navigation tree from a flat doc collection. Delegates tree
+ * construction to the shared `buildSidebarTree`; keeps the host-side concerns
+ * (DocNavNode shape, root-index node synthesis). `buildHref` parameterizes the
+ * href space (default: the injected `docsUrl`). Unlike the host copy this drops
+ * the LRU / identity caches — the snapshot-anchored `stableDocs` already makes
+ * the input arrays identity-stable so the factory-level `memoizeDerived` short-
+ * circuits per build.
+ */
+export declare function buildNavTree(docs: DocEntryLike[], locale: string, categoryMeta: Map<string, CategoryMeta> | undefined, buildHref: BuildHref): DocNavNode[];
+/** Group "satellite" nodes (slug-prefix siblings) under their primary node. */
+export declare function groupSatelliteNodes(tree: DocNavNode[], prefixes: string[]): DocNavNode[];
+/** Find a node by slug anywhere in the tree. */
+export declare function findNode(nodes: DocNavNode[], slug: string): DocNavNode | undefined;
+/** Href of the first routed descendant, walking children depth-first. */
+export declare function firstRoutedHref(node: DocNavNode): string | undefined;
+/** Collect all category nodes that have children but no page (no index.mdx). */
+export declare function collectAutoIndexNodes(nodes: DocNavNode[]): DocNavNode[];
+/** Build breadcrumb trail by walking the nav tree. `homeHref` is the locale
+ *  docs root (injected). `hrefFor` optionally remaps intermediate crumbs into
+ *  a versioned URL space. */
+export declare function buildBreadcrumbs(tree: DocNavNode[], slug: string, homeHref: string, hrefFor?: (slug: string) => string): BreadcrumbItem[];

package/dist/site-schema/nav-tree.js

@@ -0,0 +1,138 @@
+import { buildSidebarTree } from "../sidebar-tree/build-tree.js";
+import { toRouteSlug } from "../slug/index.js";
+function isNavVisible(doc) {
+  return !doc.data.unlisted && !doc.data.standalone;
+}
+function toNavNode(node) {
+  return {
+    slug: node.id,
+    label: node.label,
+    description: node.description,
+    position: node.sidebar_position ?? 999,
+    href: node.href,
+    hasPage: node.hasPage,
+    children: node.children.map(toNavNode),
+    sortOrder: node.sortOrder ?? "asc"
+  };
+}
+function findRootIndexDoc(docs) {
+  let found;
+  for (const d of docs) {
+    const slug = d.data.slug ?? toRouteSlug(d.slug);
+    if (slug === "") found = d;
+  }
+  return found;
+}
+function toRootNavNode(doc, locale, buildHref, categoryMeta) {
+  const meta = categoryMeta?.get("");
+  const noPage = doc.data.category_no_page ?? meta?.noPage;
+  const sortOrder = doc.data.category_sort_order ?? meta?.sortOrder ?? "asc";
+  return {
+    slug: "",
+    label: doc.data.sidebar_label ?? doc.data.title ?? meta?.label ?? "",
+    description: doc.data.description ?? meta?.description,
+    position: doc.data.sidebar_position ?? meta?.position ?? 999,
+    href: noPage ? void 0 : buildHref("", locale),
+    hasPage: noPage !== true,
+    children: [],
+    sortOrder
+  };
+}
+function buildNavTree(docs, locale, categoryMeta, buildHref) {
+  const href = buildHref;
+  const sidebarTree = buildSidebarTree(
+    docs,
+    locale,
+    {
+      categoryMeta,
+      buildHref: (slug, loc) => href(slug, loc),
+      // Host call sites own visibility; disable the builder's default filter so
+      // breadcrumb (unfiltered) and nav (pre-filtered) paths are unchanged.
+      isNavVisible: () => true
+    }
+  );
+  const result = sidebarTree.map(toNavNode);
+  const rootDoc = findRootIndexDoc(docs);
+  if (rootDoc) {
+    result.push(toRootNavNode(rootDoc, locale, href, categoryMeta));
+    result.sort((a, b) => {
+      const posCompare = a.position - b.position;
+      if (posCompare !== 0) return posCompare;
+      return a.slug.localeCompare(b.slug);
+    });
+  }
+  return result;
+}
+function groupSatelliteNodes(tree, prefixes) {
+  const result = [...tree];
+  for (const prefix of prefixes) {
+    const primaryIdx = result.findIndex((n) => n.slug === prefix);
+    if (primaryIdx < 0) continue;
+    const primary = result[primaryIdx];
+    if (!primary) continue;
+    const satelliteIdxs = [];
+    for (let i = 0; i < result.length; i++) {
+      const node = result[i];
+      if (node && i !== primaryIdx && node.slug.startsWith(`${prefix}-`)) {
+        satelliteIdxs.push(i);
+      }
+    }
+    if (satelliteIdxs.length === 0) continue;
+    const extraChildren = [];
+    for (const idx of satelliteIdxs) {
+      const node = result[idx];
+      if (node) extraChildren.push(node);
+    }
+    result[primaryIdx] = { ...primary, children: [...primary.children, ...extraChildren] };
+    for (const idx of satelliteIdxs.reverse()) result.splice(idx, 1);
+  }
+  return result;
+}
+function findNode(nodes, slug) {
+  for (const node of nodes) {
+    if (node.slug === slug) return node;
+    const found = findNode(node.children, slug);
+    if (found) return found;
+  }
+  return void 0;
+}
+function firstRoutedHref(node) {
+  for (const child of node.children) {
+    if (child.hasPage && child.href) return child.href;
+    const nested = firstRoutedHref(child);
+    if (nested) return nested;
+  }
+  return void 0;
+}
+function collectAutoIndexNodes(nodes) {
+  const result = [];
+  for (const node of nodes) {
+    if (!node.hasPage && node.children.length > 0 && node.href) result.push(node);
+    result.push(...collectAutoIndexNodes(node.children));
+  }
+  return result;
+}
+function buildBreadcrumbs(tree, slug, homeHref, hrefFor) {
+  const parts = slug.split("/");
+  const crumbs = [{ label: "", href: homeHref }];
+  let nodes = tree;
+  for (let i = 0; i < parts.length; i++) {
+    const partialSlug = parts.slice(0, i + 1).join("/");
+    const node = nodes.find((n) => n.slug === partialSlug);
+    if (!node) break;
+    const isLast = i === parts.length - 1;
+    const href = isLast ? void 0 : hrefFor && node.href !== void 0 ? hrefFor(node.slug) : node.href;
+    crumbs.push({ label: node.label, href });
+    nodes = node.children;
+  }
+  return crumbs;
+}
+export {
+  buildBreadcrumbs,
+  buildNavTree,
+  collectAutoIndexNodes,
+  findNode,
+  firstRoutedHref,
+  groupSatelliteNodes,
+  isNavVisible
+};

package/dist/site-schema/types.d.ts

@@ -0,0 +1,97 @@
+import type { CategoryMeta, CollectionEntryLike, SidebarFrontmatter, SidebarNode } from "../sidebar-tree/types.js";
+import type { BreadcrumbItem } from "../breadcrumb/types.js";
+import type { HeadingItem } from "../extract-headings/index.js";
+export type { BreadcrumbItem, CategoryMeta, CollectionEntryLike, HeadingItem, SidebarFrontmatter, SidebarNode, };
+/**
+ * Nav tree node shape as consumed by doc-route pages.
+ *
+ * Structurally identical to a host project's `NavNode`. Defined here so the
+ * package types depend on no host alias and no engine package; a host `NavNode`
+ * is a structural subtype and assignable wherever `DocNavNode` is expected.
+ */
+export interface DocNavNode {
+    slug: string;
+    label: string;
+    description?: string;
+    position: number;
+    href?: string;
+    hasPage: boolean;
+    children: DocNavNode[];
+    sortOrder?: "asc" | "desc";
+    collapsed?: boolean;
+}
+/** A category node with children but no page of its own — an auto-index. */
+export interface AutoIndexNode extends DocNavNode {
+    children: DocNavNode[];
+}
+/**
+ * Minimal docs frontmatter shape consumed by the doc-page types.
+ *
+ * A structural subset of a project's full docs schema — only the fields the
+ * nav/route domain actually reads. A richer `DocsData` is a structural
+ * supertype and is assignable here.
+ */
+export interface DocPageFrontmatter {
+    title: string;
+    description?: string;
+    slug?: string;
+    draft?: boolean;
+    unlisted?: boolean;
+    standalone?: boolean;
+    sidebar_position?: number;
+    sidebar_label?: string;
+    category_no_page?: boolean;
+    category_sort_order?: "asc" | "desc";
+    pagination_prev?: string | null;
+    pagination_next?: string | null;
+    tags?: string[];
+    [key: string]: unknown;
+}
+/**
+ * The structural doc-collection entry this domain reads: a slug, docs
+ * frontmatter, and an optional raw body. zfb's `CollectionEntry<DocPageFrontmatter>`
+ * (exported as `DocPageEntry` from `@takazudo/zudo-doc/doc-page-props`) is
+ * assignable to it, as is any plain fixture object of the same shape.
+ */
+export type DocEntryLike = CollectionEntryLike<DocPageFrontmatter>;
+/** Shared fields present in every doc-page route. */
+interface DocPagePropsBase {
+    breadcrumbs: BreadcrumbItem[];
+    prev: DocNavNode | null;
+    next: DocNavNode | null;
+    /** Depth-2/3/4 headings extracted from the MDX body, for SSG TOC links. */
+    headings: HeadingItem[];
+}
+/** Branch: a real content entry. `autoIndex` is absent. */
+export interface DocPageEntryProps<E extends DocEntryLike = DocEntryLike> extends DocPagePropsBase {
+    kind: "entry";
+    entry: E;
+    autoIndex?: undefined;
+}
+/** Branch: an auto-generated category index. `entry` is absent. */
+export interface DocPageAutoIndexProps extends DocPagePropsBase {
+    kind: "autoIndex";
+    autoIndex: AutoIndexNode;
+    entry?: undefined;
+}
+/** Discriminated union for the `kind` prop. Narrow via `props.kind === "entry"`. */
+export type DocPageBaseProps<E extends DocEntryLike = DocEntryLike> = DocPageEntryProps<E> | DocPageAutoIndexProps;
+/**
+ * The resolved, identity-stable doc set for one (locale, version) context —
+ * the input every route-entry enumeration starts from.
+ *
+ * The concrete resolver that PRODUCES one (`createNavSourceDocs`) reads
+ * `_category_.json` sidecars off disk and therefore stays in
+ * `@takazudo/zudo-doc/nav-source-docs`; only the shape is browser-safe.
+ */
+export interface NavSourceDocs<E extends DocEntryLike = DocEntryLike> {
+    /** Full doc list (merged + draft-filtered; unlisted retained per options). */
+    docs: E[];
+    /** `docs.filter(isNavVisible)` — stable instance for buildNavTree. */
+    navDocs: E[];
+    /** Stable category-meta Map for the active (locale, version). */
+    categoryMeta: Map<string, CategoryMeta>;
+    /** Slugs that came from the locale collection (for isFallback). Empty for
+     *  default-locale / single-collection cases. */
+    localeSlugSet: ReadonlySet<string>;
+}

package/dist/theme/theme-pack-provider.d.ts

@@ -1,5 +1,34 @@
 import type { JSX } from "preact";
 import type { ThemePackRegistry } from "../theme-packs-registry/index.js";
+/**
+ * Transient `<html>` attribute the bootstrap sets while the pack stylesheet
+ * request is in flight, but ONLY while `document.readyState === "loading"`
+ * (#3407/#3413) — a post-paint re-evaluation (SPA embedding, #3399) inserts a
+ * corrective link without ever arming the latch, since the body it would hide
+ * is already painted. Paired with {@link THEME_PACK_LATCH_CSS}; cleared on
+ * the link's load/error or by the watchdog. Deliberately NOT part of
+ * `preserveHtmlAttrs` — it must never survive a soft navigation.
+ *
+ * Not to be confused with `THEME_PACK_LINK_LOADING_ATTR`
+ * (`data-zd-theme-pack-css-loading`), which marks the in-flight `<link>`
+ * during a RUNTIME `applyThemePack` swap. Different element, different
+ * mechanism — a runtime swap awaits the sheet off-screen and never hides
+ * the body.
+ */
+export declare const THEME_PACK_LOADING_ATTR = "data-zd-theme-pack-loading";
+/**
+ * Upper bound (ms) on how long the latch may hide the body. Past this the
+ * attribute is cleared regardless of the stylesheet's state: blank-screen
+ * avoidance wins over strict no-FOUC (see the latch contract in the file
+ * header).
+ */
+export declare const THEME_PACK_LOAD_WATCHDOG_MS = 2000;
+/**
+ * The latch rule, emitted as a build-static `<style>` BEFORE the bootstrap
+ * script so it is live by the time the body parses. Inert until the script
+ * sets {@link THEME_PACK_LOADING_ATTR}.
+ */
+export declare const THEME_PACK_LATCH_CSS = "html[data-zd-theme-pack-loading] body{visibility:hidden}";
 export interface ThemePackProviderProps {
     /** The build-configured pack slug (`settings.themePack`, default `"default"`). */
     configuredSlug: string;
@@ -35,8 +64,10 @@ export declare function resolveThemePackSsrSlug(registry: ThemePackRegistry | nu
  */
 export declare function buildThemePackBootstrap(configuredSlug: string, enabled: Record<string, string>, base: string): string;
 /**
- * Server-rendered head fragment: the pre-paint bootstrap `<script>` plus the
- * `<noscript>` configured-pack fallback. No hydration — like
- * `ColorSchemeProvider` it just emits markup the engine streams into `<head>`.
+ * Server-rendered head fragment: the anti-FOUC latch `<style>`, the pre-paint
+ * bootstrap `<script>`, and the `<noscript>` configured-pack fallback. No
+ * hydration — like `ColorSchemeProvider` it just emits markup the engine
+ * streams into `<head>`. The latch style MUST stay first (see the contract in
+ * the file header).
  */
 export default function ThemePackProvider({ configuredSlug, enabled, base, }: ThemePackProviderProps): JSX.Element;