@takazudo/zudo-doc 0.2.21 → 1.0.0

package/dist/nav-data-prep/index.js

@@ -0,0 +1,34 @@
+function remapVersionedHrefs(nodes, version, nodeLang, versionedDocsUrl) {
+  return nodes.map((node) => {
+    const children = node.children.length > 0 ? remapVersionedHrefs(node.children, version, nodeLang, versionedDocsUrl) : node.children;
+    if (!node.href || node.slug.startsWith("__link__")) {
+      return children !== node.children ? { ...node, children } : node;
+    }
+    const newHref = versionedDocsUrl(node.slug, version, nodeLang);
+    return { ...node, href: newHref, children };
+  });
+}
+function buildRootMenuItems(lang, currentVersion, headerNav, t, navHref) {
+  return headerNav.map((item) => ({
+    label: item.labelKey ? t(item.labelKey, lang) : item.label,
+    href: navHref(item.path, lang, currentVersion),
+    children: item.children?.map((child) => ({
+      label: child.labelKey ? t(child.labelKey, lang) : child.label,
+      href: navHref(child.path, lang, currentVersion)
+    }))
+  }));
+}
+function buildLocaleLinksForNav(currentPath, lang, localeCount, buildLocaleLinks) {
+  return localeCount > 1 ? buildLocaleLinks(currentPath, lang) : void 0;
+}
+function getThemeDefaultMode(colorMode) {
+  if (!colorMode) return void 0;
+  const mode = colorMode.defaultMode;
+  return mode === "light" || mode === "dark" ? mode : void 0;
+}
+export {
+  buildLocaleLinksForNav,
+  buildRootMenuItems,
+  getThemeDefaultMode,
+  remapVersionedHrefs
+};

package/dist/nav-indexing/category-nav.d.ts

@@ -1,10 +1,8 @@
-import { JSX } from 'preact';
-import { NavNode } from './types.js';
-
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-
-interface CategoryNavProps {
+import type { JSX } from "preact";
+import type { NavNode } from "./types.js";
+export interface CategoryNavProps {
     /**
      * Direct children of the target category node. The consumer pre-filters to
      * the desired category and passes the immediate children. Only nodes with
@@ -23,6 +21,4 @@ interface CategoryNavProps {
  *
  * Returns `null` when no `hasPage` children are found.
  */
-declare function CategoryNav(props: CategoryNavProps): JSX.Element | null;
-
-export { CategoryNav, type CategoryNavProps };
+export declare function CategoryNav(props: CategoryNavProps): JSX.Element | null;

package/dist/nav-indexing/category-tree-nav.d.ts

@@ -1,10 +1,8 @@
-import { JSX } from 'preact';
-import { NavNode } from './types.js';
-
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-
-interface CategoryTreeNavProps {
+import type { JSX } from "preact";
+import type { NavNode } from "./types.js";
+export interface CategoryTreeNavProps {
     /**
      * Direct children of the target category node. Nodes are filtered to
      * those with `hasPage` or with child nodes before rendering.
@@ -22,6 +20,4 @@ interface CategoryTreeNavProps {
  *
  * Returns `null` when no renderable children exist.
  */
-declare function CategoryTreeNav(props: CategoryTreeNavProps): JSX.Element | null;
-
-export { CategoryTreeNav, type CategoryTreeNavProps };
+export declare function CategoryTreeNav(props: CategoryTreeNavProps): JSX.Element | null;

package/dist/nav-indexing/doc-card-grid.d.ts

@@ -1,10 +1,8 @@
-import { JSX } from 'preact';
-
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-
+import type { JSX } from "preact";
 /** A single resolved doc card item. */
-interface DocCardItem {
+export interface DocCardItem {
     /** Pre-resolved href (base-prefixed, locale-aware). */
     href: string;
     /** Display title for the card. */
@@ -12,7 +10,7 @@ interface DocCardItem {
     /** Optional description shown below the title. */
     description?: string;
 }
-interface DocCardGridProps {
+export interface DocCardGridProps {
     /** Flat list of fully resolved card items. */
     items: DocCardItem[];
     /** Accessible label for the `<nav>` element. Defaults to "Child pages". */
@@ -33,6 +31,4 @@ interface DocCardGridProps {
  *
  * Returns `null` when `items` is empty.
  */
-declare function DocCardGrid(props: DocCardGridProps): JSX.Element | null;
-
-export { DocCardGrid, type DocCardGridProps, type DocCardItem };
+export declare function DocCardGrid(props: DocCardGridProps): JSX.Element | null;

package/dist/nav-indexing/docs-sitemap.d.ts

@@ -1,10 +1,8 @@
-import { JSX } from 'preact';
-import { NavNode } from './types.js';
-
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-
-interface DocsSitemapProps {
+import type { JSX } from "preact";
+import type { NavNode } from "./types.js";
+export interface DocsSitemapProps {
     /**
      * Pre-built navigation tree. Each top-level entry maps to one collapsible
      * section in the sitemap.
@@ -20,6 +18,4 @@ interface DocsSitemapProps {
  *
  * Returns `null` when `tree` is empty.
  */
-declare function DocsSitemap(props: DocsSitemapProps): JSX.Element | null;
-
-export { DocsSitemap, type DocsSitemapProps };
+export declare function DocsSitemap(props: DocsSitemapProps): JSX.Element | null;

package/dist/nav-indexing/index.d.ts

@@ -1,10 +1,37 @@
-export { CategoryNav, CategoryNavProps } from './category-nav.js';
-export { CategoryTreeNav, CategoryTreeNavProps } from './category-tree-nav.js';
-export { SiteTreeNavDemo, SiteTreeNavDemoProps } from './site-tree-nav-demo.js';
-export { TagNav, TagNavAllProps, TagNavPageProps, TagNavProps } from './tag-nav.js';
-export { DocsSitemap, DocsSitemapProps } from './docs-sitemap.js';
-export { NavCardGrid, NavCardGridProps } from './nav-card-grid.js';
-export { DocCardGrid, DocCardGridProps, DocCardItem } from './doc-card-grid.js';
-export { VersionsPageContent, VersionsPageContentProps } from './versions-page-content.js';
-export { NavNode, TagItem, TagLink, TagNavLabels, VersionPageEntry, VersionsPageLabels } from './types.js';
-import 'preact';
+/**
+ * Public entry for the nav-indexing v2 primitives.
+ *
+ * Consumers import from `@takazudo/zudo-doc/nav-indexing`:
+ *
+ *   import {
+ *     CategoryNav,
+ *     CategoryTreeNav,
+ *     SiteTreeNavDemo,
+ *     TagNav,
+ *     DocsSitemap,
+ *     NavCardGrid,
+ *     DocCardGrid,
+ *     VersionsPageContent,
+ *   } from "@takazudo/zudo-doc/nav-indexing";
+ *
+ * All components are purely presentational — the host project assembles the
+ * collection data (navtrees, tag lists, version entries) before rendering.
+ * No `getCollection()` calls, no `@/` host-project imports, no Astro APIs.
+ */
+export { CategoryNav } from "./category-nav.js";
+export type { CategoryNavProps } from "./category-nav.js";
+export { CategoryTreeNav } from "./category-tree-nav.js";
+export type { CategoryTreeNavProps } from "./category-tree-nav.js";
+export { SiteTreeNavDemo } from "./site-tree-nav-demo.js";
+export type { SiteTreeNavDemoProps } from "./site-tree-nav-demo.js";
+export { TagNav } from "./tag-nav.js";
+export type { TagNavProps, TagNavAllProps, TagNavPageProps, } from "./tag-nav.js";
+export { DocsSitemap } from "./docs-sitemap.js";
+export type { DocsSitemapProps } from "./docs-sitemap.js";
+export { NavCardGrid } from "./nav-card-grid.js";
+export type { NavCardGridProps } from "./nav-card-grid.js";
+export { DocCardGrid } from "./doc-card-grid.js";
+export type { DocCardGridProps, DocCardItem } from "./doc-card-grid.js";
+export { VersionsPageContent } from "./versions-page-content.js";
+export type { VersionsPageContentProps } from "./versions-page-content.js";
+export type { NavNode, TagItem, TagLink, TagNavLabels, VersionPageEntry, VersionsPageLabels, } from "./types.js";

package/dist/nav-indexing/nav-card-grid.d.ts

@@ -1,10 +1,8 @@
-import { JSX } from 'preact';
-import { NavNode } from './types.js';
-
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-
-interface NavCardGridProps {
+import type { JSX } from "preact";
+import type { NavNode } from "./types.js";
+export interface NavCardGridProps {
     /**
      * Direct children of the target category node. The consumer should
      * pre-resolve `href` for each node (e.g. via `docsUrl(slug, locale)`).
@@ -26,6 +24,4 @@ interface NavCardGridProps {
  *
  * Returns `null` when no renderable items remain.
  */
-declare function NavCardGrid(props: NavCardGridProps): JSX.Element | null;
-
-export { NavCardGrid, type NavCardGridProps };
+export declare function NavCardGrid(props: NavCardGridProps): JSX.Element | null;

package/dist/nav-indexing/site-tree-nav-demo.d.ts

@@ -1,10 +1,8 @@
-import { JSX } from 'preact';
-import { NavNode } from './types.js';
-
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-
-interface SiteTreeNavDemoProps {
+import type { JSX } from "preact";
+import type { NavNode } from "./types.js";
+export interface SiteTreeNavDemoProps {
     /**
      * Pre-built top-level tree nodes. The host calls buildNavTree (or
      * buildSidebarTree) + groupSatelliteNodes before rendering this component.
@@ -34,6 +32,4 @@ interface SiteTreeNavDemoProps {
  *
  * Returns `null` when the tree is empty after filtering.
  */
-declare function SiteTreeNavDemo(props: SiteTreeNavDemoProps): JSX.Element | null;
-
-export { SiteTreeNavDemo, type SiteTreeNavDemoProps };
+export declare function SiteTreeNavDemo(props: SiteTreeNavDemoProps): JSX.Element | null;

package/dist/nav-indexing/tag-nav.d.ts

@@ -1,24 +1,22 @@
-import { JSX } from 'preact';
-import { TagItem, TagNavLabels, TagLink } from './types.js';
-
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-
-interface TagNavAllProps {
+import type { JSX } from "preact";
+import type { TagItem, TagLink, TagNavLabels } from "./types.js";
+export interface TagNavAllProps {
     variant: "all";
     /** Pre-sorted tag list with counts and pre-resolved hrefs. */
     tags: TagItem[];
     /** i18n strings for aria-labels. */
     labels: TagNavLabels;
 }
-interface TagNavPageProps {
+export interface TagNavPageProps {
     variant: "page";
     /** Tags for the current page with pre-resolved hrefs. */
     tagLinks: TagLink[];
     /** i18n strings for aria-labels. */
     labels: TagNavLabels;
 }
-type TagNavProps = TagNavAllProps | TagNavPageProps;
+export type TagNavProps = TagNavAllProps | TagNavPageProps;
 /**
  * TagNav — JSX port of `src/components/tag-nav`.
  *
@@ -33,6 +31,4 @@ type TagNavProps = TagNavAllProps | TagNavPageProps;
  *
  * Returns `null` when the relevant data is empty.
  */
-declare function TagNav(props: TagNavProps): JSX.Element | null;
-
-export { TagNav, type TagNavAllProps, type TagNavPageProps, type TagNavProps };
+export declare function TagNav(props: TagNavProps): JSX.Element | null;

package/dist/nav-indexing/types.d.ts

@@ -12,7 +12,7 @@
  * `src/utils/docs.ts` and with `SidebarNode` from `sidebar-tree/`, so
  * callers can pass either through with minor adapter mapping if needed.
  */
-interface NavNode {
+export interface NavNode {
     label: string;
     description?: string;
     /** Pre-resolved href. Undefined for category-only nodes without an index page. */
@@ -24,7 +24,7 @@ interface NavNode {
 /**
  * A single tag entry with pre-resolved href — for `TagNav` "all" variant.
  */
-interface TagItem {
+export interface TagItem {
     tag: string;
     count: number;
     /** Pre-resolved href including locale prefix and base path. */
@@ -33,7 +33,7 @@ interface TagItem {
 /**
  * A tag with its pre-resolved href — for `TagNav` "page" variant.
  */
-interface TagLink {
+export interface TagLink {
     tag: string;
     /** Pre-resolved href. */
     href: string;
@@ -43,7 +43,7 @@ interface TagLink {
  * function — the consumer resolves strings for the active locale and passes
  * them in.
  */
-interface TagNavLabels {
+export interface TagNavLabels {
     /** e.g. "Tags" / "タグ" — prefix label shown before the chips. */
     tags: string;
     /** e.g. "Pages tagged with" — used for aria-label on each chip link. */
@@ -55,7 +55,7 @@ interface TagNavLabels {
  * Extends `VersionEntry` from `@takazudo/zudo-doc/i18n-version/types`
  * with the pre-resolved doc href and optional status banner.
  */
-interface VersionPageEntry {
+export interface VersionPageEntry {
     slug: string;
     label: string;
     /** Pre-resolved href to the version's default doc page. */
@@ -67,7 +67,7 @@ interface VersionPageEntry {
  * i18n label bag for `VersionsPageContent`. The consumer resolves all
  * strings for the active locale and passes them in.
  */
-interface VersionsPageLabels {
+export interface VersionsPageLabels {
     /** Page `<h1>` text, e.g. "Documentation Versions". */
     pageTitle: string;
     /** Latest version section heading, e.g. "Latest Version (Current)". */
@@ -91,5 +91,3 @@ interface VersionsPageLabels {
     /** Table column: docs link heading (also used as the link text). */
     docsCol: string;
 }
-
-export type { NavNode, TagItem, TagLink, TagNavLabels, VersionPageEntry, VersionsPageLabels };

package/dist/nav-indexing/versions-page-content.d.ts

@@ -1,10 +1,8 @@
-import { JSX } from 'preact';
-import { VersionPageEntry, VersionsPageLabels } from './types.js';
-
 /** @jsxRuntime automatic */
 /** @jsxImportSource preact */
-
-interface VersionsPageContentProps {
+import type { JSX } from "preact";
+import type { VersionPageEntry, VersionsPageLabels } from "./types.js";
+export interface VersionsPageContentProps {
     /** Pre-resolved href to the latest version's default docs page. */
     latestHref: string;
     /** Past version entries. Empty array hides the past-versions section. */
@@ -24,6 +22,4 @@ interface VersionsPageContentProps {
  * All strings and hrefs are pre-resolved by the consumer so this component
  * stays locale- and settings-agnostic.
  */
-declare function VersionsPageContent(props: VersionsPageContentProps): JSX.Element;
-
-export { VersionsPageContent, type VersionsPageContentProps };
+export declare function VersionsPageContent(props: VersionsPageContentProps): JSX.Element;

package/dist/nav-scope/index.d.ts

@@ -0,0 +1,41 @@
+/** Minimal nav node shape required by nav-scope functions. */
+export interface NavScopeNode {
+    slug: string;
+    children: NavScopeNode[];
+}
+/** Minimal shape of a headerNav item the nav-scope functions need. */
+export interface NavScopeHeaderNavItem {
+    categoryMatch?: string;
+    children?: Array<{
+        categoryMatch?: string;
+    }>;
+}
+/**
+ * Collect all categoryMatch strings from headerNav (including children), in order.
+ *
+ * Parameterized version of the host's `getCategoryOrder()` — receives the
+ * headerNav array instead of reading `settings.headerNav` directly.
+ */
+export declare function getCategoryOrder(headerNav: NavScopeHeaderNavItem[]): string[];
+/**
+ * Given a doc's slug (e.g. "getting-started/introduction" or "guides/overview"),
+ * return the categoryMatch value of the headerNav item it belongs to.
+ *
+ * Parameterized version of the host's `getNavSectionForSlug()` — receives the
+ * headerNav array instead of reading `settings.headerNav` directly.
+ */
+export declare function getNavSectionForSlug(slug: string, headerNav: NavScopeHeaderNavItem[]): string | undefined;
+/**
+ * Filter top-level NavNodes by a headerNav categoryMatch value.
+ * - `"!"` means everything NOT claimed by explicit matchers
+ * - `"claude"` means nodes whose slug starts with `"claude"`
+ * - `undefined` means all nodes
+ *
+ * Parameterized version of the host's `getNavSubtree()` — receives the
+ * headerNav array instead of reading `settings.headerNav` directly.
+ *
+ * Generic so callers can pass their concrete node type (e.g. the host's
+ * `NavNode` which extends this shape) and get back the same type without
+ * an unsafe cast.
+ */
+export declare function getNavSubtree<T extends NavScopeNode>(tree: T[], categoryMatch: string | undefined, headerNav: NavScopeHeaderNavItem[]): T[];

package/dist/nav-scope/index.js

@@ -0,0 +1,41 @@
+function getCategoryOrder(headerNav) {
+  return headerNav.flatMap((item) => {
+    const matches = [];
+    if (item.categoryMatch) matches.push(item.categoryMatch);
+    if (item.children) {
+      for (const child of item.children) {
+        if (child.categoryMatch) matches.push(child.categoryMatch);
+      }
+    }
+    return matches;
+  });
+}
+function getNavSectionForSlug(slug, headerNav) {
+  const topCategory = slug.split("/")[0] ?? "";
+  const all = getCategoryOrder(headerNav);
+  const explicitMatches = all.filter(
+    (cm) => cm !== "!" && topCategory.startsWith(cm)
+  );
+  if (explicitMatches.length > 0) {
+    return explicitMatches.sort((a, b) => b.length - a.length)[0];
+  }
+  const defaultItem = headerNav.find(
+    (item) => item.categoryMatch === "!"
+  );
+  return defaultItem?.categoryMatch;
+}
+function getNavSubtree(tree, categoryMatch, headerNav) {
+  if (!categoryMatch) return tree;
+  if (categoryMatch === "!") {
+    const explicitPrefixes = getCategoryOrder(headerNav).filter((cm) => cm !== "!");
+    return tree.filter(
+      (node) => !explicitPrefixes.some((prefix) => node.slug.startsWith(prefix))
+    );
+  }
+  return tree.filter((node) => node.slug.startsWith(categoryMatch));
+}
+export {
+  getCategoryOrder,
+  getNavSectionForSlug,
+  getNavSubtree
+};

package/dist/nav-source-cache/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Memoize a derived array (e.g. a locale merge or an `isNavVisible` filter)
+ * on the identity of its stable inputs plus a caller-supplied option
+ * signature.
+ *
+ * `inputs` MUST be the stable arrays returned by `stableDocs` (from the
+ * host's `pages/lib/_nav-source-cache.ts`) or arrays derived from them
+ * through this same helper — passing a fresh array defeats the memo.
+ * `optionSig` distinguishes call sites that differ only in filter options
+ * (e.g. `applyDefaultLocaleOnlyFilter`, `keepUnlisted`), so they never
+ * collide on the same key.
+ */
+export declare function memoizeDerived<T>(inputs: readonly object[], optionSig: string, compute: () => T): T;

package/dist/nav-source-cache/index.js

@@ -0,0 +1,28 @@
+const derivedMemo = /* @__PURE__ */ new WeakMap();
+const arrayId = /* @__PURE__ */ new WeakMap();
+let nextArrayId = 1;
+function idOf(arr) {
+  let id = arrayId.get(arr);
+  if (id === void 0) {
+    id = nextArrayId++;
+    arrayId.set(arr, id);
+  }
+  return id;
+}
+const EMPTY_INPUT_ANCHOR = {};
+function memoizeDerived(inputs, optionSig, compute) {
+  const primary = inputs[0] ?? EMPTY_INPUT_ANCHOR;
+  let sub = derivedMemo.get(primary);
+  if (!sub) {
+    sub = /* @__PURE__ */ new Map();
+    derivedMemo.set(primary, sub);
+  }
+  const key = `${inputs.map((a) => idOf(a)).join("/")}::${optionSig}`;
+  if (sub.has(key)) return sub.get(key);
+  const computed = compute();
+  sub.set(key, computed);
+  return computed;
+}
+export {
+  memoizeDerived
+};

package/dist/nav-source-docs/index.d.ts

@@ -0,0 +1,169 @@
+import type { CategoryMeta } from "../sidebar-tree/index.js";
+import type { DocPageEntry } from "../doc-page-props/index.js";
+export type { CategoryMeta, DocPageEntry };
+export interface NavSourceDocs {
+    /** Full doc list (merged + draft-filtered; unlisted retained per options). */
+    docs: DocPageEntry[];
+    /** `docs.filter(isNavVisible)` — stable instance for buildNavTree. */
+    navDocs: DocPageEntry[];
+    /** 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>;
+}
+/**
+ * How to filter the merged doc list.
+ */
+export interface NavSourceOptions {
+    /** Drop base docs matching `defaultLocaleOnlyPrefixes` (route/sidebar nav). */
+    applyDefaultLocaleOnlyFilter?: boolean;
+    /** Retain `unlisted: true` docs (route enumeration + nav). */
+    keepUnlisted?: boolean;
+}
+/**
+ * Optional locale config returned by `getLocaleConfig(lang)`.
+ * Structural interface so the package does not import the host's concrete type.
+ */
+export interface LocaleConfig {
+    /** Content directory path for this locale. */
+    dir?: string;
+}
+/**
+ * Optional version config entry from `settings.versions`.
+ * Structural interface for the package.
+ */
+export interface VersionConfigEntry {
+    slug: string;
+    docsDir?: string;
+    locales?: Record<string, {
+        dir?: string;
+    }>;
+}
+/**
+ * Injected context for `createNavSourceDocs`.
+ *
+ * All host-specific singletons are passed in so the package factory never
+ * imports `@/` aliases. The host stub calls `createNavSourceDocs(ctx)` once
+ * and re-exports the returned resolver functions.
+ */
+export interface NavSourceDocsContext {
+    /**
+     * Default locale code (served from the un-prefixed `/docs/...` routes).
+     * E.g. `"en"`.
+     */
+    defaultLocale: string;
+    /**
+     * The configured docs content directory (e.g. `"src/content/docs"`).
+     * Used as the base dir for `loadCategoryMeta`.
+     */
+    docsDir: string;
+    /**
+     * Getter for the configured versions list (or false if versioning is not
+     * active). Called on every `resolveNavSource` invocation so test code that
+     * mutates `settings.versions` between calls sees the updated value.
+     * Structural equivalent of a getter for `settings.versions`.
+     *
+     * Pass `() => settings.versions` from the host stub.
+     */
+    getVersions: () => VersionConfigEntry[] | false | undefined;
+    /**
+     * Look up locale-specific config (dir, etc.) for a locale code.
+     * Host passes `getLocaleConfig` from `@/config/i18n`.
+     */
+    getLocaleConfig: (lang: string) => LocaleConfig | undefined;
+    /**
+     * Load category metadata for a content dir.
+     * Host passes `loadCategoryMeta` from `@/utils/docs` (re-exported from
+     * `@takazudo/zudo-doc/sidebar-tree`).
+     */
+    loadCategoryMeta: (dir: string) => Map<string, CategoryMeta>;
+    /**
+     * Filter predicate: true when a doc should appear in navigation.
+     * Host passes `isNavVisible` from `@/utils/docs`.
+     */
+    isNavVisible: (doc: DocPageEntry) => boolean;
+    /**
+     * Returns true for paths that are only shown in the default locale.
+     * Host passes `isDefaultLocaleOnlyPath` from `@/utils/base`.
+     */
+    isDefaultLocaleOnlyPath: (path: string) => boolean;
+    /**
+     * Identity-stable, draft-filtered docs array for a collection.
+     * Host passes `stableDocs` from `pages/lib/_nav-source-cache.ts`.
+     * The function must anchor memoization on the zfb snapshot so the SAME
+     * array instance is returned on every call within one build.
+     */
+    stableDocs: (collectionName: string) => DocPageEntry[];
+}
+/**
+ * Result of `createNavSourceDocs`. Contains the resolver functions bound to
+ * the injected context.
+ */
+export interface NavSourceDocsAPI {
+    /**
+     * Identity-stable nav source for an EN/locale (optionally versioned) context.
+     * Every field is memoized so repeated calls with the same logical inputs
+     * return the same instances.
+     */
+    resolveNavSource: (lang: string, currentVersion: string | undefined, options?: NavSourceOptions) => NavSourceDocs;
+    /**
+     * Identity-stable nav source for a versioned non-default-locale context —
+     * locale-specific version collection over the version's EN base.
+     */
+    resolveVersionedLocaleSource: (versionSlug: string, versionDocsDir: string | undefined, lang: string, localeDir: string | undefined, options?: NavSourceOptions) => NavSourceDocs;
+    /**
+     * Per-page nav source for the desktop sidebar and mobile SidebarToggle.
+     *
+     * Thin adapter over `resolveNavSource` with the sidebar's filter options
+     * (`applyDefaultLocaleOnlyFilter`, `keepUnlisted`). Returns `navDocs`
+     * already filtered so callers pass it straight to `buildSidebarForSection`
+     * without a fresh `.filter(isNavVisible)` that would defeat the nav-tree
+     * fast-path.
+     */
+    loadNavSourceDocs: (lang: string, currentVersion: string | undefined) => NavSourceDocs;
+    /**
+     * Merge category metadata for two dirs (base + locale). Result is stable per
+     * (baseDir, localeDir) pair within a build.
+     */
+    stableMergeCategoryMeta: (baseDir: string, localeDir: string) => Map<string, CategoryMeta>;
+    /**
+     * `docs.filter(isNavVisible)`, memoized on the stable `docs` identity so the
+     * filtered array also has stable identity for the nav-tree fast-path.
+     */
+    stableNavDocs: <T extends DocPageEntry>(docs: T[]) => T[];
+}
+/**
+ * Create the identity-stable nav-source resolver functions bound to the host's
+ * injected context. Call this once from the host stub with the concrete
+ * singletons; re-export the returned functions.
+ *
+ * @example
+ * ```ts
+ * // pages/lib/_nav-source-docs.ts (thin stub)
+ * import { createNavSourceDocs } from "@takazudo/zudo-doc/nav-source-docs";
+ * import { settings } from "@/config/settings";
+ * import { defaultLocale, getLocaleConfig } from "@/config/i18n";
+ * import { loadCategoryMeta, isNavVisible } from "@/utils/docs";
+ * import { isDefaultLocaleOnlyPath } from "@/utils/base";
+ * import { stableDocs } from "./_nav-source-cache";
+ *
+ * export const {
+ *   resolveNavSource,
+ *   resolveVersionedLocaleSource,
+ *   loadNavSourceDocs,
+ *   stableMergeCategoryMeta,
+ *   stableNavDocs,
+ * } = createNavSourceDocs({
+ *   defaultLocale,
+ *   docsDir: settings.docsDir,
+ *   getVersions: () => settings.versions,
+ *   getLocaleConfig,
+ *   loadCategoryMeta,
+ *   isNavVisible,
+ *   isDefaultLocaleOnlyPath,
+ *   stableDocs,
+ * });
+ * ```
+ */
+export declare function createNavSourceDocs(ctx: NavSourceDocsContext): NavSourceDocsAPI;