@takazudo/zudo-doc 0.2.21 → 1.0.0

package/dist/routes/_chrome.js

@@ -0,0 +1,365 @@
+import { Fragment, jsx } from "preact/jsx-runtime";
+import {
+  settings,
+  defaultLocale,
+  locales,
+  t,
+  withBase,
+  stripBase,
+  docsUrl,
+  versionedDocsUrl,
+  absoluteUrl,
+  navHref,
+  buildLocaleLinks,
+  getNavSectionForSlug,
+  getCategoryOrder,
+  toRouteSlug,
+  resolveNavSource,
+  loadNavSourceDocs,
+  buildNavTree,
+  groupSatelliteNodes,
+  collectAutoIndexNodes,
+  findNode,
+  firstRoutedHref,
+  collectTags,
+  stableDocs
+} from "./_context.js";
+import { createComposeMetaTitle } from "../compose-meta-title/index.js";
+import {
+  generateCssCustomProperties,
+  generateLightDarkCssProperties
+} from "../color-scheme-utils.js";
+import { createHeadWithDefaults } from "../head-with-defaults/index.js";
+import { createHeaderWithDefaults } from "../header-with-defaults/index.js";
+import { createFooterWithDefaults } from "../footer-with-defaults/index.js";
+import { createSidebarWithDefaults } from "../sidebar-with-defaults/index.js";
+import { createSidebarPrepaint } from "../sidebar-prepaint/index.js";
+import { createDocBodyEnd } from "../doc-body-end/index.js";
+import { createDocPager } from "../doc-pager/index.js";
+import { createDocPageShell } from "../doc-page-shell/index.js";
+import { createDocContentHeader } from "../doc-content-header/index.js";
+import { createDocMetainfoArea } from "../doc-metainfo-area/index.js";
+import { createDocTagsArea } from "../doc-tags-area/index.js";
+import { createDocHistoryArea } from "../doc-history-area/index.js";
+import { createInlineVersionSwitcher } from "../inline-version-switcher/index.js";
+import { createRenderDocPage } from "../doc-page-renderer/index.js";
+import { createVersionsPageView } from "../versions-page/index.js";
+import { createTagPages } from "../tag-pages/index.js";
+import { createMdxComponents } from "../mdx-components/index.js";
+import { createCategoryNavWrapper } from "../category-nav/index.js";
+import { createCategoryTreeNavWrapper } from "../category-tree-nav/index.js";
+import { createSiteTreeNavWrapper } from "../site-tree-nav/index.js";
+import { getTocTitle } from "../toc/index.js";
+import { SearchWidget } from "../search-widget/index.js";
+import { buildGitHubRepoUrl, buildGitHubSourceUrl } from "../github-helpers/index.js";
+import { toHistorySlug } from "../slug/index.js";
+import {
+  buildRootMenuItems as buildRootMenuItemsBase,
+  buildLocaleLinksForNav as buildLocaleLinksForNavBase,
+  remapVersionedHrefs,
+  getThemeDefaultMode as getThemeDefaultModeBase
+} from "../nav-data-prep/index.js";
+import { buildSidebarForSection } from "../sidebar-utils/index.js";
+const GREY_RAMP = [
+  "#000000",
+  "#1a1a1a",
+  "#333333",
+  "#4d4d4d",
+  "#666666",
+  "#808080",
+  "#999999",
+  "#b3b3b3",
+  "#cccccc",
+  "#d9d9d9",
+  "#e6e6e6",
+  "#f2f2f2",
+  "#ff5555",
+  "#50fa7b",
+  "#f1fa8c",
+  "#8be9fd"
+];
+const DEFAULT_SCHEME = {
+  background: "#000000",
+  foreground: "#ffffff",
+  cursor: "#ffffff",
+  selectionBg: "#444444",
+  selectionFg: "#ffffff",
+  palette: GREY_RAMP
+};
+const docHistoryMeta = {};
+const sidebarsConfig = {};
+function BodyEndIslandsStub(_props) {
+  return /* @__PURE__ */ jsx(Fragment, {});
+}
+function DocHistoryStub(_props) {
+  return /* @__PURE__ */ jsx(Fragment, {});
+}
+function SearchWidgetBound(props) {
+  return SearchWidget({ ...props, base: withBase("/") });
+}
+const composeMetaTitle = createComposeMetaTitle(settings.siteName);
+const HeadWithDefaults = createHeadWithDefaults({
+  settings,
+  composeMetaTitle,
+  withBase,
+  absoluteUrl,
+  generateCssCustomProperties: () => generateCssCustomProperties(DEFAULT_SCHEME),
+  generateLightDarkCssProperties: () => generateLightDarkCssProperties(DEFAULT_SCHEME, DEFAULT_SCHEME)
+});
+function buildRootMenuItems(lang, currentVersion) {
+  return buildRootMenuItemsBase(
+    lang,
+    currentVersion,
+    settings.headerNav,
+    (key, l) => t(key, l),
+    (path, l, v) => navHref(path, l, v)
+  );
+}
+function buildLocaleLinksForNav(currentPath, lang, localeCount) {
+  return buildLocaleLinksForNavBase(
+    currentPath,
+    lang,
+    localeCount,
+    (path, l) => buildLocaleLinks(path, l)
+  );
+}
+function buildSidebarNodes(lang, navSection, currentVersion, emptyWhenUnsectioned = true) {
+  if (navSection === void 0 && emptyWhenUnsectioned) return [];
+  const { navDocs, categoryMeta } = loadNavSourceDocs(lang, currentVersion);
+  const explicitPrefixes = getCategoryOrder().filter((cm) => cm !== "!");
+  const rawNodes = buildSidebarForSection(
+    navDocs,
+    lang,
+    navSection,
+    categoryMeta,
+    sidebarsConfig,
+    (d, l, meta) => buildNavTree(
+      d,
+      l,
+      meta,
+      (slug, loc) => docsUrl(slug, loc)
+    ),
+    explicitPrefixes
+  );
+  return currentVersion ? remapVersionedHrefs(
+    rawNodes,
+    currentVersion,
+    lang,
+    (slug, v, l) => versionedDocsUrl(slug, v, l)
+  ) : rawNodes;
+}
+function getThemeDefaultMode() {
+  return getThemeDefaultModeBase(settings.colorMode);
+}
+const HeaderWithDefaults = createHeaderWithDefaults({
+  settings,
+  defaultLocale,
+  locales,
+  t,
+  withBase,
+  stripBase,
+  docsUrl,
+  navHref,
+  versionedDocsUrl,
+  buildLocaleLinksForNav,
+  buildRootMenuItems,
+  buildSidebarNodes,
+  getThemeDefaultMode,
+  buildGitHubRepoUrl: () => buildGitHubRepoUrl(settings.githubUrl),
+  SearchWidget: SearchWidgetBound
+});
+const FooterWithDefaults = createFooterWithDefaults({
+  settings,
+  defaultLocale,
+  tagVocabulary: [],
+  isExternal: (href) => /^https?:\/\//.test(href),
+  resolveHref: (href) => /^https?:\/\//.test(href) ? href : withBase(href),
+  withBase,
+  // The footer taglist is host-bound (project tag aggregation); package default
+  // renders no tag columns.
+  loadTagsForLocale: () => []
+});
+const SidebarWithDefaults = createSidebarWithDefaults({
+  defaultLocale,
+  localeCount: locales.length,
+  buildRootMenuItems,
+  buildLocaleLinksForNav,
+  buildSidebarNodes,
+  getThemeDefaultMode,
+  t
+});
+const SidebarPrepaint = createSidebarPrepaint({ sidebarToggle: settings.sidebarToggle });
+const DocBodyEnd = createDocBodyEnd({ settings, BodyEndIslands: BodyEndIslandsStub });
+const DocPager = createDocPager({ t });
+const DocMetainfoArea = createDocMetainfoArea({
+  settings,
+  defaultLocale,
+  docHistoryMeta,
+  t,
+  toHistorySlug
+});
+const DocTagsArea = createDocTagsArea({
+  settings,
+  defaultLocale,
+  tagVocabularyEntries: [],
+  tagHref: (tag, locale) => {
+    const encoded = encodeURIComponent(tag);
+    return withBase(
+      locale === defaultLocale ? `/docs/tags/${encoded}` : `/${locale}/docs/tags/${encoded}`
+    );
+  },
+  t
+});
+const DocContentHeader = createDocContentHeader({
+  t,
+  buildFrontmatterPreviewEntries: () => [],
+  frontmatterRenderers: {},
+  DocMetainfoArea,
+  DocTagsArea
+});
+const DocHistoryArea = createDocHistoryArea({
+  settings,
+  defaultLocale,
+  docHistoryMeta,
+  t,
+  toHistorySlug,
+  buildGitHubSourceUrl: (contentDir, entryId) => buildGitHubSourceUrl(settings.githubUrl, contentDir, entryId),
+  DocHistory: DocHistoryStub
+});
+const buildInlineVersionSwitcher = createInlineVersionSwitcher({
+  settings,
+  defaultLocale,
+  t,
+  docsUrl,
+  versionedDocsUrl,
+  withBase
+});
+const CategoryNavWrapper = createCategoryNavWrapper({
+  defaultLocale,
+  resolveNavSource,
+  buildNavTree: ((docs, locale, categoryMeta) => buildNavTree(
+    docs,
+    locale,
+    categoryMeta,
+    (slug, loc) => docsUrl(slug, loc)
+  )),
+  findNode,
+  firstRoutedHref
+});
+const CategoryTreeNavWrapper = createCategoryTreeNavWrapper({
+  defaultLocale,
+  resolveNavSource,
+  buildNavTree: ((docs, locale, categoryMeta) => buildNavTree(
+    docs,
+    locale,
+    categoryMeta,
+    (slug, loc) => docsUrl(slug, loc)
+  )),
+  groupSatelliteNodes,
+  findNode
+});
+const SiteTreeNavWrapper = createSiteTreeNavWrapper({
+  defaultLocale,
+  resolveNavSource,
+  buildNavTree: ((docs, locale, categoryMeta) => buildNavTree(
+    docs,
+    locale,
+    categoryMeta,
+    (slug, loc) => docsUrl(slug, loc)
+  )),
+  groupSatelliteNodes,
+  getCategoryOrder
+});
+function createMdxComponentsBound(lang = defaultLocale) {
+  return createMdxComponents({
+    settings,
+    locale: lang,
+    navData: {
+      CategoryNav: CategoryNavWrapper,
+      CategoryTreeNav: CategoryTreeNavWrapper,
+      SiteTreeNav: SiteTreeNavWrapper
+    },
+    // PresetGenerator and other showcase-only slots resolve to a package stub
+    // (render nothing) — they are project-bound and not in the package.
+    extras: {
+      PresetGenerator: (_props) => null
+    }
+  });
+}
+const DocPageShell = createDocPageShell({
+  settings,
+  composeMetaTitle,
+  getTocTitle,
+  HeadWithDefaults,
+  SidebarWithDefaults,
+  HeaderWithDefaults,
+  FooterWithDefaults,
+  SidebarPrepaint,
+  DocBodyEnd,
+  DocPager
+});
+const renderDocPage = createRenderDocPage({
+  docsUrl,
+  versionedDocsUrl,
+  absoluteUrl,
+  getNavSectionForSlug,
+  toRouteSlug,
+  createMdxComponents: createMdxComponentsBound,
+  t,
+  buildInlineVersionSwitcher,
+  DocPageShell,
+  DocContentHeader,
+  DocMetainfoArea,
+  DocHistoryArea
+});
+const VersionsPageView = createVersionsPageView({
+  settings,
+  defaultLocale,
+  t,
+  withBase,
+  composeMetaTitle,
+  components: {
+    HeadWithDefaults,
+    HeaderWithDefaults,
+    FooterWithDefaults,
+    BodyEndIslands: BodyEndIslandsStub
+  }
+});
+const tagPages = createTagPages({
+  settings,
+  defaultLocale,
+  t,
+  withBase,
+  docsUrl,
+  composeMetaTitle,
+  collectTags,
+  stableDocs,
+  isDefaultLocaleOnlyPath: void 0,
+  components: {
+    HeadWithDefaults,
+    HeaderWithDefaults,
+    FooterWithDefaults,
+    BodyEndIslands: BodyEndIslandsStub,
+    DocHistoryArea
+  }
+});
+const { collectTagMapForLocale, TagDetailPageView, TagsIndexPageView } = tagPages;
+import {
+  buildDocRouteEntries
+} from "./_context.js";
+export {
+  BodyEndIslandsStub,
+  FooterWithDefaults,
+  HeadWithDefaults,
+  HeaderWithDefaults,
+  SidebarWithDefaults,
+  SiteTreeNavWrapper,
+  TagDetailPageView,
+  TagsIndexPageView,
+  VersionsPageView,
+  buildDocRouteEntries,
+  collectTagMapForLocale,
+  composeMetaTitle,
+  createMdxComponentsBound,
+  renderDocPage
+};

package/dist/routes/_context.d.ts

@@ -0,0 +1,56 @@
+import type { Settings } from "../settings.js";
+import type { FactoryI18n } from "../factory-context/index.js";
+import { type UrlHelpers } from "../url-helpers/index.js";
+import { toRouteSlug, toSlugParams } from "../slug/index.js";
+import { type TagVocabularyEntry } from "../tag-helpers/index.js";
+import type { DocNavNode } from "../doc-page-props/index.js";
+import type { HeadingItem } from "../extract-headings/index.js";
+import { stableDocs, isNavVisible, buildNavTree, collectAutoIndexNodes, groupSatelliteNodes, findNode, firstRoutedHref } from "./_docs-helpers.js";
+export interface RouteContextPayload {
+    settings: Settings;
+    translations: Record<string, Record<string, string>>;
+    tagVocabulary: readonly TagVocabularyEntry[];
+}
+/** The serializable route-context (from the virtual module). */
+export declare const ctx: RouteContextPayload;
+export declare const settings: Settings;
+export declare const defaultLocale: string;
+export declare const locales: readonly string[];
+export declare function getLocaleConfig(locale: string): {
+    label: string;
+    dir: string;
+} | undefined;
+export declare function getLocaleLabel(locale: string): string;
+export declare function t(key: string, locale?: string): string;
+export declare const i18n: FactoryI18n;
+export declare const urlHelpers: UrlHelpers;
+export declare const withBase: (path: string) => string, stripBase: (path: string) => string, docsUrl: (slug: string, lang?: string) => string, versionedDocsUrl: (slug: string, versionSlug: string, lang?: string) => string, navHref: (path: string, lang: string | undefined, currentVersion: string | undefined) => string, isDefaultLocaleOnlyPath: (path: string) => boolean, absoluteUrl: (pageUrl: string) => string | undefined, isExternal: (href: string) => boolean, resolveHref: (href: string) => string, buildLocaleLinks: (currentPath: string, currentLang: string) => import("../url-helpers/index.js").LocaleLink[];
+export declare function getCategoryOrder(): string[];
+export declare function getNavSectionForSlug(slug: string): string | undefined;
+export declare function getNavSubtree(tree: DocNavNode[], categoryMatch?: string): DocNavNode[];
+export declare function extractHeadings(body: string): HeadingItem[];
+export interface TagInfo {
+    tag: string;
+    count: number;
+    docs: {
+        slug: string;
+        title: string;
+        description?: string;
+    }[];
+}
+export declare function resolveTagBound(raw: string): import("../tag-helpers/index.js").ResolvedTag;
+export declare function collectTags(entries: ReadonlyArray<{
+    id: string;
+    data: {
+        slug?: string;
+        title?: string;
+        description?: string;
+        tags?: string[];
+    };
+}>, slugFn: (id: string, data: {
+    slug?: string;
+}) => string): Map<string, TagInfo>;
+export declare const resolveNavSource: (lang: string, currentVersion: string | undefined, options?: import("../nav-source-docs/index.js").NavSourceOptions) => import("../nav-source-docs/index.js").NavSourceDocs, resolveVersionedLocaleSource: (versionSlug: string, versionDocsDir: string | undefined, lang: string, localeDir: string | undefined, options?: import("../nav-source-docs/index.js").NavSourceOptions) => import("../nav-source-docs/index.js").NavSourceDocs, loadNavSourceDocs: (lang: string, currentVersion: string | undefined) => import("../nav-source-docs/index.js").NavSourceDocs;
+export declare const buildDocRouteEntries: (args: import("../doc-route-entries/index.js").BuildDocRouteEntriesArgs) => import("../doc-route-entries/index.js").DocRouteEntry[];
+export declare const enumerateDocsRoutes: (locale: string) => string[], enumerateTagsRoutes: (locale: string) => string[], enumerateVersionedRoutes: (version: import("../route-enumerators/index.js").VersionConfigForEnum, locale: string) => string[], enumerateAllRoutes: () => Map<string, string>;
+export { buildNavTree, groupSatelliteNodes, findNode, firstRoutedHref, collectAutoIndexNodes, isNavVisible, stableDocs, toRouteSlug, toSlugParams, };

package/dist/routes/_context.js

@@ -0,0 +1,222 @@
+import { routeContext } from "virtual:zudo-doc-route-context";
+import { makeUrlHelpers } from "../url-helpers/index.js";
+import {
+  loadCategoryMeta
+} from "../sidebar-tree/index.js";
+import { extractHeadings as extractHeadingsBase } from "../extract-headings/index.js";
+import { toRouteSlug, toSlugParams } from "../slug/index.js";
+import { resolveTag } from "../tag-helpers/index.js";
+import {
+  getCategoryOrder as getCategoryOrderBase,
+  getNavSectionForSlug as getNavSectionForSlugBase,
+  getNavSubtree as getNavSubtreeBase
+} from "../nav-scope/index.js";
+import { mergeLocaleDocs } from "../locale-merge/index.js";
+import {
+  createNavSourceDocs
+} from "../nav-source-docs/index.js";
+import {
+  createDocRouteEntries
+} from "../doc-route-entries/index.js";
+import {
+  createRouteEnumerators
+} from "../route-enumerators/index.js";
+import {
+  stableDocs,
+  isNavVisible,
+  buildNavTree,
+  buildBreadcrumbs,
+  collectAutoIndexNodes,
+  groupSatelliteNodes,
+  findNode,
+  firstRoutedHref
+} from "./_docs-helpers.js";
+const ctx = routeContext;
+const settings = ctx.settings;
+const translations = ctx.translations;
+const tagVocabulary = ctx.tagVocabulary;
+const defaultLocale = settings.defaultLocale;
+const locales = [
+  defaultLocale,
+  ...Object.keys(settings.locales)
+];
+function getLocaleConfig(locale) {
+  return settings.locales[locale];
+}
+function getLocaleLabel(locale) {
+  if (locale === defaultLocale) return defaultLocale.toUpperCase();
+  return getLocaleConfig(locale)?.label ?? locale.toUpperCase();
+}
+function t(key, locale = defaultLocale) {
+  return translations[locale]?.[key] ?? translations[defaultLocale]?.[key] ?? key;
+}
+const i18n = {
+  defaultLocale,
+  locales,
+  getLocaleLabel,
+  t
+};
+const urlHelpers = makeUrlHelpers(settings, i18n);
+const {
+  withBase,
+  stripBase,
+  docsUrl,
+  versionedDocsUrl,
+  navHref,
+  isDefaultLocaleOnlyPath,
+  absoluteUrl,
+  isExternal,
+  resolveHref,
+  buildLocaleLinks
+} = urlHelpers;
+function getCategoryOrder() {
+  return getCategoryOrderBase(settings.headerNav);
+}
+function getNavSectionForSlug(slug) {
+  return getNavSectionForSlugBase(slug, settings.headerNav);
+}
+function getNavSubtree(tree, categoryMatch) {
+  return getNavSubtreeBase(tree, categoryMatch, settings.headerNav);
+}
+function extractHeadings(body) {
+  return extractHeadingsBase(body, {
+    tocMinDepth: settings.tocMinDepth,
+    tocMaxDepth: settings.tocMaxDepth,
+    strategy: settings.headingIdStrategy
+  });
+}
+function getVocab() {
+  return settings.tagVocabulary ? tagVocabulary : false;
+}
+function resolveTagBound(raw) {
+  return resolveTag(raw, getVocab(), settings.tagGovernance);
+}
+function collectTags(entries, slugFn) {
+  const tagMap = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const rawTags = entry.data.tags ?? [];
+    const slug = slugFn(entry.id, entry.data);
+    const seen = /* @__PURE__ */ new Set();
+    for (const raw of rawTags) {
+      const resolved = resolveTagBound(raw);
+      if (resolved.deprecated) continue;
+      if (seen.has(resolved.canonical)) continue;
+      seen.add(resolved.canonical);
+      if (!tagMap.has(resolved.canonical)) {
+        tagMap.set(resolved.canonical, { tag: resolved.canonical, count: 0, docs: [] });
+      }
+      const info = tagMap.get(resolved.canonical);
+      info.count++;
+      info.docs.push({
+        slug,
+        title: entry.data.title ?? "",
+        description: entry.data.description
+      });
+    }
+  }
+  return tagMap;
+}
+const navSourceDocs = createNavSourceDocs({
+  defaultLocale,
+  docsDir: settings.docsDir,
+  getVersions: () => settings.versions,
+  getLocaleConfig,
+  loadCategoryMeta,
+  isNavVisible,
+  isDefaultLocaleOnlyPath,
+  stableDocs
+});
+const {
+  resolveNavSource,
+  resolveVersionedLocaleSource,
+  loadNavSourceDocs
+} = navSourceDocs;
+const docRouteEntries = createDocRouteEntries({
+  buildNavTree: (docs, locale, categoryMeta) => buildNavTree(
+    docs,
+    locale,
+    categoryMeta,
+    (slug, loc) => docsUrl(slug, loc)
+  ),
+  buildBreadcrumbs: (tree, slug, locale, urlFor) => buildBreadcrumbs(
+    tree,
+    slug,
+    locale === defaultLocale ? withBase("/") : withBase(`/${locale}/`),
+    urlFor
+  ),
+  collectAutoIndexNodes,
+  getNavSectionForSlug,
+  getNavSubtree,
+  toRouteSlug,
+  toSlugParams,
+  extractHeadings
+});
+const { buildDocRouteEntries } = docRouteEntries;
+const routeEnumerators = createRouteEnumerators({
+  defaultLocale,
+  getLocaleKeys: () => Object.keys(settings.locales),
+  getVersions: () => settings.versions,
+  getDocTags: () => settings.docTags,
+  docsUrl,
+  versionedDocsUrl,
+  withBase,
+  loadDocs: (collectionName) => stableDocs(collectionName),
+  isDefaultLocaleOnlyPath,
+  collectTags: (docs, slugFn) => collectTags(docs, slugFn),
+  toRouteSlug,
+  buildNavTree: (docs, locale, categoryMeta) => buildNavTree(docs, locale, categoryMeta, (slug, loc) => docsUrl(slug, loc)),
+  collectAutoIndexNodes,
+  resolveNavSource,
+  resolveVersionedLocaleSource,
+  mergeLocaleDocs
+});
+const {
+  enumerateDocsRoutes,
+  enumerateTagsRoutes,
+  enumerateVersionedRoutes,
+  enumerateAllRoutes
+} = routeEnumerators;
+export {
+  absoluteUrl,
+  buildDocRouteEntries,
+  buildLocaleLinks,
+  buildNavTree,
+  collectAutoIndexNodes,
+  collectTags,
+  ctx,
+  defaultLocale,
+  docsUrl,
+  enumerateAllRoutes,
+  enumerateDocsRoutes,
+  enumerateTagsRoutes,
+  enumerateVersionedRoutes,
+  extractHeadings,
+  findNode,
+  firstRoutedHref,
+  getCategoryOrder,
+  getLocaleConfig,
+  getLocaleLabel,
+  getNavSectionForSlug,
+  getNavSubtree,
+  groupSatelliteNodes,
+  i18n,
+  isDefaultLocaleOnlyPath,
+  isExternal,
+  isNavVisible,
+  loadNavSourceDocs,
+  locales,
+  navHref,
+  resolveHref,
+  resolveNavSource,
+  resolveTagBound,
+  resolveVersionedLocaleSource,
+  settings,
+  stableDocs,
+  stripBase,
+  t,
+  toRouteSlug,
+  toSlugParams,
+  urlHelpers,
+  versionedDocsUrl,
+  withBase
+};

package/dist/routes/_docs-helpers.d.ts

@@ -0,0 +1,43 @@
+import { type CategoryMeta } from "../sidebar-tree/index.js";
+import type { DocNavNode, DocPageEntry } from "../doc-page-props/index.js";
+export type { CategoryMeta, DocNavNode, DocPageEntry };
+/**
+ * Identity-stable, draft-filtered `DocPageEntry[]` for a collection. Returns the
+ * SAME array instance on every call within one build (anchored on the snapshot
+ * array); the no-snapshot (fs-fallback / unit-test) path computes fresh and is
+ * deliberately unmemoized. Passed as `stableDocs` to `createNavSourceDocs`.
+ */
+export declare function stableDocs(collectionName: string): DocPageEntry[];
+/** Filter predicate: true when a doc should appear in navigation. */
+export declare function isNavVisible(doc: DocPageEntry): boolean;
+/** A docs-href builder: `(slug, locale) => url`. */
+export type BuildHref = (slug: string, locale: string) => string;
+export interface BuildNavTreeOptions {
+    buildHref?: BuildHref;
+}
+/**
+ * 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: DocPageEntry[], locale: string, categoryMeta: Map<string, CategoryMeta> | undefined, buildHref: BuildHref, options?: BuildNavTreeOptions): 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[];
+export interface BreadcrumbItem {
+    label: string;
+    href?: string;
+}
+/** 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[];