create-zudo-doc 1.2.0 → 2.0.0

package/dist/api.d.ts

@@ -16,5 +16,11 @@ export interface CreateOptions {
     packageManager: "pnpm" | "npm" | "yarn" | "bun";
     /** Install dependencies after scaffolding (default: false) */
     install?: boolean;
+    /**
+     * Initialize a git repository + initial commit after scaffolding
+     * (default: false). The CLI defaults this on; the programmatic API defaults
+     * it off so automation / test callers never create unexpected repos.
+     */
+    git?: boolean;
 }
 export declare function createZudoDoc(options: CreateOptions): Promise<string>;

package/dist/api.js

@@ -1,8 +1,8 @@
 import path from "path";
 import { scaffold } from "./scaffold.js";
-import { installDependencies, validateProjectName } from "./utils.js";
+import { initGitRepo, installDependencies, validateProjectName } from "./utils.js";
 export async function createZudoDoc(options) {
-    const { install = false, ...rest } = options;
+    const { install = false, git = false, ...rest } = options;
     const nameError = validateProjectName(rest.projectName);
     if (nameError)
         throw new Error(`Invalid projectName: ${nameError}`);
@@ -12,5 +12,8 @@ export async function createZudoDoc(options) {
     if (install) {
         installDependencies(targetDir, choices.packageManager);
     }
+    if (git) {
+        initGitRepo(targetDir);
+    }
     return targetDir;
 }

package/dist/cli.d.ts

@@ -33,6 +33,8 @@ export interface CliArgs {
     preset?: string;
     pm?: "pnpm" | "npm" | "yarn" | "bun";
     install?: boolean;
+    /** Initialize a git repository + initial commit after scaffolding (default on). */
+    git?: boolean;
     yes?: boolean;
     help?: boolean;
 }

package/dist/cli.js

@@ -67,6 +67,8 @@ export function parseArgs(argv = process.argv.slice(2)) {
     }
     if (wasPassed("install"))
         args.install = raw["install"] !== false;
+    if (wasPassed("git"))
+        args.git = raw["git"] !== false;
     if (raw.yes || raw.y)
         args.yes = true;
     if (raw.help || raw.h)
@@ -95,6 +97,8 @@ ${featureHelp}
   --preset <path>              Load settings from a JSON preset file (use "-" for stdin)
   --pm <manager>               pnpm | npm | yarn | bun
   --[no-]install               Install dependencies after scaffolding
+  --[no-]git                   Initialize a git repository + initial commit
+                               (default: on; enables doc-history metadata)
   -y, --yes                    Use defaults for unspecified options, skip prompts
   -h, --help                   Show this help message
 

package/dist/index.js

@@ -6,7 +6,7 @@ import { FEATURES } from "./constants.js";
 import { loadPreset } from "./preset.js";
 import { runPrompts } from "./prompts.js";
 import { scaffold } from "./scaffold.js";
-import { installDependencies } from "./utils.js";
+import { installDependencies, initGitRepo } from "./utils.js";
 async function main() {
     const args = parseArgs();
     // Handle --help
@@ -144,6 +144,31 @@ async function main() {
             s2.stop("Installation failed. Run install manually.");
         }
     }
+    // Initialize a git repository (default on; --no-git to opt out). doc-history
+    // reads `git log` for each page's Created/Updated/Author block, so a project
+    // without git renders empty history. Runs after install so the lockfile is
+    // part of the initial commit; auto-skips if the target is already inside a
+    // repo or if git is unavailable.
+    const shouldInitGit = args.git ?? true;
+    if (shouldInitGit) {
+        const s3 = p.spinner();
+        s3.start("Initializing git repository...");
+        const result = initGitRepo(targetDir);
+        switch (result.status) {
+            case "ok":
+                s3.stop("Initialized git repository with an initial commit.");
+                break;
+            case "skipped-existing-repo":
+                s3.stop("Already inside a git repository — skipped git init.");
+                break;
+            case "skipped-no-git":
+                s3.stop("git not found — skipped git init.");
+                break;
+            case "failed":
+                s3.stop("Could not initialize git — continuing without it.");
+                break;
+        }
+    }
     p.outro(`${pc.green("Done!")} Your project is ready at ${pc.cyan(choices.projectName)}`);
     console.log();
     console.log(`  ${pc.bold("Next steps:")}`);

package/dist/scaffold.d.ts

@@ -11,5 +11,5 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export declare const ZUDO_DOC_PIN = "^1.2.0";
+export declare const ZUDO_DOC_PIN = "^2.0.0";
 export declare function scaffold(choices: UserChoices): Promise<void>;

package/dist/scaffold.js

@@ -18,7 +18,7 @@ export { getSecondaryLang };
  *
  * Bumped in lockstep by scripts/release-create-zudo-doc.sh.
  */
-export const ZUDO_DOC_PIN = "^1.2.0";
+export const ZUDO_DOC_PIN = "^2.0.0";
 /**
  * Files in `templates/base/**` that must never be copied into a generated
  * project. Each entry is matched against the path relative to `templates/base/`
@@ -477,13 +477,17 @@ function generatePackageJson(choices) {
         // No consumer-facing / CLI breaking change.
         // next.68: routine toolchain bump from next.67, adopted in
         // lockstep with the root package.json pins. No consumer-facing / CLI change.
-        // next.69 (current pin): routine toolchain bump from next.68, adopted in
+        // next.69: routine toolchain bump from next.68, adopted in
         // lockstep with the root package.json pins. No consumer-facing / CLI change.
-        "@takazudo/zfb": "0.1.0-next.69",
-        "@takazudo/zfb-runtime": "0.1.0-next.69",
+        // next.70 (current pin): routine toolchain bump from next.69, re-aligned
+        // with the root package.json pins (root was bumped in b5489acf; this
+        // scaffold pin lagged at next.69 and broke check-pin-parity). No
+        // consumer-facing / CLI change.
+        "@takazudo/zfb": "0.1.0-next.70",
+        "@takazudo/zfb-runtime": "0.1.0-next.70",
         // zfb-adapter-cloudflare — required for any route with `prerender = false`.
         // Pinned in lockstep with @takazudo/zfb.
-        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.69",
+        "@takazudo/zfb-adapter-cloudflare": "0.1.0-next.70",
         // @takazudo/zudo-doc — published from this monorepo via
         // .github/workflows/publish-zudo-doc.yml. The pin here is bumped in
         // lockstep by scripts/release-create-zudo-doc.sh whenever zudo-doc's
@@ -566,7 +570,7 @@ function generatePackageJson(choices) {
         // @takazudo/zudo-doc/integrations/doc-history which in turn imports
         // @takazudo/zudo-doc-history-server/git-history. Without this dep the
         // plugin host fails at init with ERR_MODULE_NOT_FOUND — W8A (#1739).
-        deps["@takazudo/zudo-doc-history-server"] = "^1.2.0";
+        deps["@takazudo/zudo-doc-history-server"] = "^2.0.0";
         // tsx is no longer needed here: the relocated package plugin imports the
         // runner directly (no `tsx -e` spawn) since the package ships compiled
         // dist/ — package-first migration #2321 (#2337).

package/dist/utils.d.ts

@@ -7,6 +7,33 @@
  */
 export declare function validateProjectName(name: string): string | null;
 export declare function installDependencies(dir: string, pm: string): void;
+export type GitInitResult = {
+    status: "ok";
+} | {
+    status: "skipped-existing-repo";
+} | {
+    status: "skipped-no-git";
+} | {
+    status: "failed";
+    message: string;
+};
+/**
+ * Initialize a git repository in `dir` and create an initial commit.
+ *
+ * Why: zudo-doc's doc-history feature reads `git log` for each page's
+ * Created/Updated/Author block. A scaffolded project with no git repo renders
+ * empty history — and on older `@takazudo/zudo-doc-history-server` it crashed
+ * `pnpm dev` outright (the preBuild hook ran `git rev-parse` and threw).
+ * Initializing git here makes the feature work out of the box.
+ *
+ * Safe by construction:
+ * - `skipped-no-git` when git is not installed;
+ * - `skipped-existing-repo` when `dir` is already inside a git work tree (e.g.
+ *   scaffolding into an existing monorepo) — never nest repositories;
+ * - the initial commit only falls back to a neutral identity when the user has
+ *   none configured, so a normal user's commit keeps their own identity.
+ */
+export declare function initGitRepo(dir: string): GitInitResult;
 export declare function capitalize(str: string): string;
 /** Get a short uppercase label for a language code (e.g. "en" → "EN", "zh-cn" → "ZH-CN"). */
 export declare function getLangLabel(langCode: string): string;

package/dist/utils.js

@@ -1,4 +1,4 @@
-import { execSync } from "child_process";
+import { execSync, execFileSync } from "child_process";
 import fs from "fs-extra";
 // Project-name grammar (locked by F4 — S4 #2013):
 // /^[a-z0-9][a-z0-9._-]*$/, max 214 chars, unscoped, used as both directory
@@ -36,6 +36,77 @@ export function installDependencies(dir, pm) {
     // Use pipe to avoid garbled output when used alongside spinner
     execSync(cmd, { cwd: dir, stdio: "pipe" });
 }
+/**
+ * Initialize a git repository in `dir` and create an initial commit.
+ *
+ * Why: zudo-doc's doc-history feature reads `git log` for each page's
+ * Created/Updated/Author block. A scaffolded project with no git repo renders
+ * empty history — and on older `@takazudo/zudo-doc-history-server` it crashed
+ * `pnpm dev` outright (the preBuild hook ran `git rev-parse` and threw).
+ * Initializing git here makes the feature work out of the box.
+ *
+ * Safe by construction:
+ * - `skipped-no-git` when git is not installed;
+ * - `skipped-existing-repo` when `dir` is already inside a git work tree (e.g.
+ *   scaffolding into an existing monorepo) — never nest repositories;
+ * - the initial commit only falls back to a neutral identity when the user has
+ *   none configured, so a normal user's commit keeps their own identity.
+ */
+export function initGitRepo(dir) {
+    // Is git available at all?
+    try {
+        execFileSync("git", ["--version"], { stdio: "ignore" });
+    }
+    catch {
+        return { status: "skipped-no-git" };
+    }
+    // Already inside a git work tree? Don't create a nested repository.
+    try {
+        const inside = execFileSync("git", ["rev-parse", "--is-inside-work-tree"], {
+            cwd: dir,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (inside === "true")
+            return { status: "skipped-existing-repo" };
+    }
+    catch {
+        // git exits non-zero when `dir` is not inside a repo — the expected case.
+    }
+    const COMMIT_MESSAGE = "Initial commit from create-zudo-doc";
+    try {
+        execFileSync("git", ["init", "-q"], { cwd: dir, stdio: "ignore" });
+        execFileSync("git", ["add", "-A"], { cwd: dir, stdio: "ignore" });
+        try {
+            execFileSync("git", ["commit", "-q", "-m", COMMIT_MESSAGE], {
+                cwd: dir,
+                stdio: "ignore",
+            });
+        }
+        catch {
+            // No git identity configured on this machine — retry with a neutral
+            // fallback so the initial commit still succeeds. Users with a configured
+            // identity never reach this branch (their identity is used above).
+            execFileSync("git", [
+                "-c",
+                "user.name=create-zudo-doc",
+                "-c",
+                "user.email=create-zudo-doc@users.noreply.github.com",
+                "commit",
+                "-q",
+                "-m",
+                COMMIT_MESSAGE,
+            ], { cwd: dir, stdio: "ignore" });
+        }
+        return { status: "ok" };
+    }
+    catch (err) {
+        return {
+            status: "failed",
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 export function capitalize(str) {
     return str.replace(/\b\w/g, (c) => c.toUpperCase());
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-zudo-doc",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "description": "Create a new zudo-doc documentation site",
   "license": "MIT",
   "author": "Takeshi Takatsudo",

package/templates/base/pages/index.tsx

@@ -28,10 +28,12 @@ import type { JSX } from "preact";
 import type { VNode } from "preact";
 import { Island } from "@takazudo/zfb";
 import { SiteTreeNav } from "@takazudo/zudo-doc/site-tree-nav-island";
-import { FooterWithDefaults } from "./lib/_footer-with-defaults";
-import { HeaderWithDefaults } from "./lib/_header-with-defaults";
-import { HeadWithDefaults } from "./lib/_head-with-defaults";
-import { composeMetaTitle } from "./lib/_compose-meta-title";
+import {
+  FooterWithDefaults,
+  HeaderWithDefaults,
+  HeadWithDefaults,
+  composeMetaTitle,
+} from "./lib/_chrome";
 import { BodyEndIslands } from "./lib/_body-end-islands";
 
 export const frontmatter = { title: "Home" };

package/templates/base/pages/lib/_chrome.ts

@@ -0,0 +1,166 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+// Host chrome adapter — THE single host adapter for the page-chrome surface
+// (epic Collapse Wiring Shells #2420; HOSTCOLLAPSE #2427 collapsed the former
+// per-component `pages/lib/_*` chrome shells into this one module).
+//
+// It builds the host's REAL bindings ONCE and threads them through the public
+// `createChrome(routeContext, hostBindings)` builder, then re-exports the wired
+// page-chrome barrel (renderDocPage, HeaderWithDefaults, FooterWithDefaults,
+// HeadWithDefaults, composeMetaTitle, …). Every doc route + homepage chrome
+// import resolves here.
+//
+//   - the reconstructed route context comes from the retained, vitest-safe
+//     `./_route-context` seam (settings + i18n + URL/nav/slug helpers +
+//     nav-source resolvers + route enumerators), fed the host content bridge
+//     (`stableDocs`) so the content read + nav enumeration stay byte-identical;
+//   - the genuinely host-bound slots (`hostBindings`): the real SearchWidget,
+//     git-history manifest, sidebars config, frontmatter renderers/builder,
+//     footer tag loader + vocabulary, body-end islands, DocHistory island, and
+//     the showcase MDX content overrides (`mdxExtras`).
+//
+// Island-scanner contract (load-bearing): this module MUST keep the STATIC
+// imports of DocHistory (`@takazudo/zudo-doc/doc-history`), BodyEndIslands
+// (`./_body-end-islands`) and PresetGeneratorFallback (`./_preset-generator`).
+// After the collapse the only page→island import chain is
+// `pages/docs/*.tsx → _chrome.ts → {DocHistory, BodyEndIslands, PresetGenerator}`;
+// if any of these became a type-only or dynamic import the zfb island scanner
+// would stop walking it and the marker/bundle would silently drop.
+
+import type { ComponentChildren } from "preact";
+import type { ChromeHostBindings } from "@takazudo/zudo-doc/factory-context";
+
+import { createChrome } from "@takazudo/zudo-doc/chrome";
+
+import { settings } from "@/config/settings";
+import { defaultLocale } from "@/config/i18n";
+import { tagVocabulary } from "@/config/tag-vocabulary";
+import sidebars from "@/config/sidebars";
+import { frontmatterRenderers } from "@/config/frontmatter-preview-renderers";
+import { collectTags } from "@/utils/tags";
+import { toRouteSlug } from "@/utils/slug";
+import type { DocsEntry } from "@/types/docs-entry";
+
+import { routeContext } from "./_route-context";
+import { stableDocs, memoizeDerived } from "./_nav-source-cache";
+import { mergeLocaleDocs } from "./locale-merge";
+import { SearchWidget } from "./_search-widget";
+import { BodyEndIslands as BodyEndIslandsSeam } from "./_body-end-islands";
+import { buildFrontmatterPreviewEntries } from "./_frontmatter-preview-data";
+import { DetailsWrapper } from "./_details";
+import { PresetGeneratorFallback } from "./_preset-generator";
+import { DocHistory } from "@takazudo/zudo-doc/doc-history";
+import { HtmlPreviewWrapper, type HtmlPreviewWrapperProps } from "@takazudo/zudo-doc/html-preview-wrapper";
+// SSR author + date metadata — `#doc-history-meta` is the build-time manifest
+// alias (esbuild-inlined, no fs). Static import is load-bearing for the island
+// scanner chain noted above.
+import docHistoryMeta from "#doc-history-meta";
+
+// ---------------------------------------------------------------------------
+// Footer tag loader (host-side; moved verbatim from the former
+// _chrome-context.ts / _footer-with-defaults.tsx). Reads collections via
+// stableDocs / memoizeDerived and aggregates tags per locale. Threaded as
+// hostBindings.loadTagsForLocale.
+// ---------------------------------------------------------------------------
+
+function loadTagsForLocale(lang: string) {
+  if (lang === defaultLocale) {
+    const baseDocs = stableDocs("docs");
+    return memoizeDerived([baseDocs], "footerTaglist;default", () => {
+      const docs: DocsEntry[] = baseDocs.filter(
+        (d) => !d.data.draft && !d.data.unlisted && !d.data.category_no_page,
+      );
+      const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+      return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
+    });
+  }
+  const baseDocs = stableDocs("docs");
+  const localeDocs = stableDocs(`docs-${lang}`);
+  return memoizeDerived([baseDocs, localeDocs], `footerTaglist;${lang}`, () => {
+    const result = mergeLocaleDocs({
+      baseDocs: baseDocs.filter((d) => !d.data.draft),
+      localeDocs: localeDocs.filter((d) => !d.data.draft),
+      applyDefaultLocaleOnlyFilter: true,
+    });
+    const docs: DocsEntry[] = result.docs.filter((d) => !d.data.category_no_page);
+    const tagMap = collectTags(docs, (id, data) => data.slug ?? toRouteSlug(id));
+    return [...tagMap.values()].sort((a, b) => a.tag.localeCompare(b.tag, lang));
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Showcase MDX content overrides (host-bound; identical to the former
+// pages/_mdx-components.ts `extras` block — kept in lockstep). Threaded via
+// hostBindings.mdxExtras; the package factory merges them over its defaults.
+// ---------------------------------------------------------------------------
+
+/** MDX-tag stub: renders nothing (Preact null-vnode path). */
+const MdxStub = (_props: unknown) => null;
+
+/** SSR pass-through for `<Island when=…>` — renders children, ignores `when`. */
+function IslandWrapper(props: {
+  when?: "load" | "idle" | "visible" | "media";
+  children?: ComponentChildren;
+}): ComponentChildren {
+  return props.children ?? null;
+}
+
+const HtmlPreviewWithGlobalConfig = (props: HtmlPreviewWrapperProps) =>
+  HtmlPreviewWrapper({ globalConfig: settings.htmlPreview ?? null, ...props });
+
+const mdxExtras = {
+  HtmlPreview: HtmlPreviewWithGlobalConfig,
+  Details: DetailsWrapper,
+  SmartBreak: MdxStub,
+  Island: IslandWrapper,
+  PresetGenerator: PresetGeneratorFallback,
+  Avatar: MdxStub,
+  Button: MdxStub,
+  Card: MdxStub,
+  MyComponent: MdxStub,
+  PageLayout: MdxStub,
+} as unknown as Record<string, (props: Record<string, unknown>) => unknown>;
+
+// ---------------------------------------------------------------------------
+// The host's real bindings (the 10 ChromeHostBindings slots).
+// ---------------------------------------------------------------------------
+
+const hostBindings: ChromeHostBindings = {
+  SearchWidget: SearchWidget as ChromeHostBindings["SearchWidget"],
+  docHistoryMeta: docHistoryMeta as Record<string, unknown>,
+  sidebarsConfig: sidebars as unknown as Record<string, unknown>,
+  frontmatterRenderers: frontmatterRenderers as unknown as ChromeHostBindings["frontmatterRenderers"],
+  buildFrontmatterPreviewEntries:
+    buildFrontmatterPreviewEntries as unknown as ChromeHostBindings["buildFrontmatterPreviewEntries"],
+  loadTagsForLocale: loadTagsForLocale as unknown as ChromeHostBindings["loadTagsForLocale"],
+  tagVocabulary,
+  BodyEndIslands: BodyEndIslandsSeam as unknown as ChromeHostBindings["BodyEndIslands"],
+  DocHistory: DocHistory as unknown as ChromeHostBindings["DocHistory"],
+  mdxExtras: mdxExtras as ChromeHostBindings["mdxExtras"],
+};
+
+// ---------------------------------------------------------------------------
+// Build the wired page-chrome surface ONCE from the route context + real host
+// bindings, and re-export the barrel. Every omitted slot falls back to the
+// package stub (byte-identical to the injected package-routes path); each REAL
+// slot above overrides it.
+// ---------------------------------------------------------------------------
+
+const chrome = createChrome(routeContext, hostBindings);
+
+export type { RenderDocPageOptions } from "@takazudo/zudo-doc/doc-page-renderer";
+
+export const {
+  composeMetaTitle,
+  HeadWithDefaults,
+  HeaderWithDefaults,
+  FooterWithDefaults,
+  SidebarWithDefaults,
+  renderDocPage,
+  VersionsPageView,
+  collectTagMapForLocale,
+  TagDetailPageView,
+  TagsIndexPageView,
+  SiteTreeNavWrapper,
+  BodyEndIslands,
+} = chrome;

package/templates/base/pages/lib/_doc-route-entries.ts

@@ -1,54 +1,10 @@
-// Thin stub — doc-route-entries moved to the package (epic #2344, S6).
-// Calls `createDocRouteEntries(ctx)` from @takazudo/zudo-doc/doc-route-entries
-// with the host utilities injected, then re-exports the resulting builder
-// function so all existing call sites continue to work unchanged.
+// Thin shim — the memoized doc-route-entry builder rides on the unified
+// ChromeContext now (epic Collapse Wiring Shells #2420, FACTORIES #2424).
+// `createRouteContext` (in _chrome-context.ts) assembles `buildDocRouteEntries`
+// as part of the route context; this module just re-exports it so the doc-route
+// page files keep importing it from here unchanged.
 
-import { createDocRouteEntries } from "@takazudo/zudo-doc/doc-route-entries";
-import type {
-  DocPageEntry,
-  DocNavNode,
-  BreadcrumbItem,
-} from "@takazudo/zudo-doc/doc-route-entries";
 export type { DocRouteEntry, BuildDocRouteEntriesArgs } from "@takazudo/zudo-doc/doc-route-entries";
-import {
-  buildNavTree,
-  buildBreadcrumbs,
-  collectAutoIndexNodes,
-  type NavNode,
-  type CategoryMeta,
-} from "@/utils/docs";
-import { getNavSectionForSlug, getNavSubtree } from "@/utils/nav-scope";
-import { toRouteSlug, toSlugParams } from "@/utils/slug";
-import type { DocsEntry } from "@/types/docs-entry";
-import type { Locale } from "@/config/i18n";
-import { extractHeadings } from "./_extract-headings";
+import { routeContext } from "./_route-context";
 
-export const { buildDocRouteEntries } = createDocRouteEntries({
-  // The factory describes its injected nav builders with the package's own
-  // structural counterparts (DocPageEntry / DocNavNode / Map<string, unknown>)
-  // and a plain `locale: string`. The host's buildNavTree / buildBreadcrumbs
-  // are typed against the concrete project types (DocsEntry / NavNode / the
-  // Locale union / Map<string, CategoryMeta>). They are runtime-identical, so
-  // the stub adapts them with thin wrappers that cast at the injection boundary
-  // where the host owns the type knowledge.
-  buildNavTree: (docs: DocPageEntry[], locale: string, categoryMeta: Map<string, unknown>) =>
-    buildNavTree(
-      docs as unknown as DocsEntry[],
-      locale as Locale,
-      categoryMeta as Map<string, CategoryMeta>,
-    ) as DocNavNode[],
-  buildBreadcrumbs: (
-    tree: DocNavNode[],
-    slug: string,
-    locale: string,
-    urlFor?: (slug: string) => string,
-  ): BreadcrumbItem[] =>
-    buildBreadcrumbs(tree as NavNode[], slug, locale as Locale, urlFor),
-  collectAutoIndexNodes: (tree: DocNavNode[]) =>
-    collectAutoIndexNodes(tree as NavNode[]) as DocNavNode[],
-  getNavSectionForSlug,
-  getNavSubtree,
-  toRouteSlug,
-  toSlugParams,
-  extractHeadings,
-});
+export const { buildDocRouteEntries } = routeContext;

package/templates/base/pages/lib/_nav-source-docs.ts

@@ -1,37 +1,17 @@
-// Thin stub — nav-source-docs moved to the package (epic #2344, S6).
-// Calls `createNavSourceDocs(ctx)` from @takazudo/zudo-doc/nav-source-docs
-// with the host singletons injected, then re-exports the resulting resolver
-// functions so all existing call sites continue to work unchanged.
+// Thin shim — nav-source resolvers ride on the unified ChromeContext now
+// (epic Collapse Wiring Shells #2420, FACTORIES #2424). The reconstructed
+// `createRouteContext` (in _chrome-context.ts) builds the identity-stable
+// nav-source API as part of the route context; this module just re-exports the
+// bindings so the existing call sites (route files, nav wrappers, _nav-data-prep,
+// route-enumerators) keep importing them from here unchanged.
 
-import { createNavSourceDocs } from "@takazudo/zudo-doc/nav-source-docs";
 export type { NavSourceDocs, NavSourceOptions } from "@takazudo/zudo-doc/nav-source-docs";
-import { defaultLocale, getLocaleConfig } from "@/config/i18n";
-import { settings } from "@/config/settings";
-import { loadCategoryMeta, isNavVisible } from "@/utils/docs";
-import { isDefaultLocaleOnlyPath } from "@/utils/base";
-import { stableDocs } from "./_nav-source-cache";
+import { routeContext } from "./_route-context";
 
-const {
+export const {
   resolveNavSource,
   resolveVersionedLocaleSource,
   loadNavSourceDocs,
   stableMergeCategoryMeta,
   stableNavDocs,
-} = createNavSourceDocs({
-  defaultLocale,
-  docsDir: settings.docsDir,
-  getVersions: () => settings.versions,
-  getLocaleConfig,
-  loadCategoryMeta,
-  isNavVisible,
-  isDefaultLocaleOnlyPath,
-  stableDocs,
-});
-
-export {
-  resolveNavSource,
-  resolveVersionedLocaleSource,
-  loadNavSourceDocs,
-  stableMergeCategoryMeta,
-  stableNavDocs,
-};
+} = routeContext;

package/templates/base/pages/lib/_route-context.ts

@@ -0,0 +1,32 @@
+// Host route context — the reconstructed RouteContext (settings + i18n + URL
+// helpers + nav/slug helpers + identity-stable nav-source resolvers + doc-route
+// + route enumerators), built ONCE via the public `createRouteContext`
+// (epic Collapse Wiring Shells #2420, FACTORIES #2424).
+//
+// Kept SEPARATE from `_chrome-context.ts` so the data shells (`_nav-source-docs`
+// / `_doc-route-entries` / `route-enumerators`) — and the unit tests that import
+// them — depend ONLY on this lightweight module, NOT on the chrome host bindings
+// (which pull the build-time `#doc-history-meta` alias + island components that
+// don't resolve under vitest).
+//
+// The host content bridge (`stableDocs`) is injected so the docs read + nav
+// enumeration match the project's existing `pages/*` paths() exactly (host
+// `bridgeDocsEntries` over the `zfb/content` snapshot), not the package default.
+
+import { createRouteContext } from "@takazudo/zudo-doc/route-context";
+import type { ColorScheme } from "@takazudo/zudo-doc/color-scheme-utils";
+import { settings } from "@/config/settings";
+import { translations } from "@/config/i18n";
+import { tagVocabulary } from "@/config/tag-vocabulary";
+import { colorSchemes } from "@/config/color-schemes";
+import { stableDocs } from "./_nav-source-cache";
+
+export const routeContext = createRouteContext(
+  {
+    settings,
+    translations,
+    tagVocabulary,
+    colorSchemes: colorSchemes as unknown as Record<string, ColorScheme>,
+  },
+  { stableDocs },
+);

package/templates/base/src/config/tag-vocabulary-types.ts

@@ -1,39 +1,4 @@
-/**
- * Tag governance enforcement level.
- *
- * - `"off"`   — no vocabulary-aware enforcement. The `tags` schema stays a
- *               free-form `string[]`. Identical to pre-vocabulary behaviour.
- * - `"warn"`  — `tags` schema stays free-form so builds pass, but the tag
- *               audit script (see Sub 2) reports unknown tags as warnings and
- *               exits non-zero under `--ci`.
- * - `"strict"` — `tags` schema is tightened to `z.enum([...allowedIds])`, so
- *                unknown tags fail `pnpm check` / `pnpm build`.
- *
- * Orthogonal to `tagVocabulary` (the on/off switch for consulting the
- * vocabulary file at runtime). See `settings-types.ts` for details.
- */
-export type TagGovernanceMode = "off" | "warn" | "strict";
-
-/**
- * A single entry in the tag vocabulary.
- *
- * - `id`         — canonical tag id. What content files should ideally use.
- * - `label`      — optional human-readable label (falls back to `id`).
- * - `description`— optional short description for tooling / tag index pages.
- * - `group`      — optional grouping key used by the grouped tag footer
- *                  (e.g. `"type"`, `"level"`, `"topic"`).
- * - `aliases`    — alternate strings that content files may use. Alias
- *                  resolution rewrites these to `id` before aggregation.
- * - `deprecated` — `true` marks the tag as deprecated with no redirect: the
- *                  canonical id is dropped from aggregation. Pass
- *                  `{ redirect: "<other-id>" }` to rewrite this tag to another
- *                  canonical id when it appears in content.
- */
-export interface TagVocabularyEntry {
-  id: string;
-  label?: string;
-  description?: string;
-  group?: string;
-  aliases?: readonly string[];
-  deprecated?: boolean | { redirect?: string };
-}
+// Re-export from the shared package — canonical definitions live in
+// @takazudo/zudo-doc/settings (epic #2321). Consumers that import from
+// this local path continue to work unchanged.
+export type { TagGovernanceMode, TagVocabularyEntry } from "@takazudo/zudo-doc/settings";