@takazudo/zudo-doc 0.2.22 → 1.0.0

package/bin/zudo-doc.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// @takazudo/zudo-doc/bin/zudo-doc.mjs
+//
+// Package bin: `zudo-doc eject <component>` swizzle CLI.
+//
+// Self-contained ESM — runs on plain `node` with NO `tsx` requirement. The eject
+// logic is imported from the package's COMPILED `../dist/eject/index.js`, and the
+// only runtime deps are `minimist` + `picocolors` (declared deps of this package,
+// so they are present transitively in any consumer's node_modules). This is the
+// key difference from the tsx-runner pattern used by `bin/tags-audit.mjs`:
+// tags-audit must load the *project's* TypeScript config files at runtime (hence
+// tsx), whereas eject only copies files + rewrites imports — no TS eval needed —
+// so it works in a default generated project that never installed tsx (#2367).
+//
+// Usage:
+//   zudo-doc eject <component>   # eject a component's TS source into the project
+//   zudo-doc --help              # show help
+
+import minimist from "minimist";
+import pc from "picocolors";
+import { eject, EJECTABLE } from "../dist/eject/index.js";
+
+const argv = minimist(process.argv.slice(2), {
+  boolean: ["help"],
+  alias: { h: "help" },
+});
+
+function printHelp() {
+  const validNames = Object.keys(EJECTABLE).sort().join(", ");
+  console.log(`
+${pc.bold("Usage:")} zudo-doc <subcommand> [options]
+
+${pc.bold("Subcommands:")}
+  eject <component>   Copy a component's TS source into your project and
+                      rewrite imports so it resolves locally.
+
+${pc.bold("Ejectable components:")}
+  ${validNames}
+
+${pc.bold("Options:")}
+  -h, --help   Show this help message
+
+${pc.bold("Examples:")}
+  ${pc.dim("# Eject the header component")}
+  zudo-doc eject header
+
+  ${pc.dim("# Eject the theme-toggle component")}
+  zudo-doc eject theme-toggle
+`);
+}
+
+async function main() {
+  if (argv["help"] || argv._.length === 0) {
+    printHelp();
+    process.exit(0);
+  }
+
+  const [subcommand, componentArg] = argv._;
+
+  if (subcommand !== "eject") {
+    console.error(
+      pc.red(`Unknown subcommand "${subcommand}".`) +
+        `\nRun \`zudo-doc --help\` for usage.`,
+    );
+    process.exit(1);
+  }
+
+  if (!componentArg) {
+    console.error(
+      pc.red(`Missing component name.`) +
+        `\nUsage: zudo-doc eject <component>` +
+        `\nRun \`zudo-doc --help\` for the list of ejectable components.`,
+    );
+    process.exit(1);
+  }
+
+  await eject(componentArg, { cwd: process.cwd() });
+}
+
+main().catch((err) => {
+  console.error(pc.red(String(err)));
+  process.exit(1);
+});

package/dist/eject/index.d.ts

@@ -0,0 +1,33 @@
+export interface EjectableEntry {
+    /** Package subpath, e.g. `@takazudo/zudo-doc/header` */
+    packageSubpath: string;
+    /** Local destination dir, project-relative POSIX (no trailing slash) */
+    localDir: string;
+}
+export declare const EJECTABLE: Record<string, EjectableEntry>;
+export interface ZudoDocJson {
+    /** @takazudo/zudo-doc version the ejected source came from */
+    packageVersion: string;
+    /** component name → local dir (project-relative POSIX, no trailing slash) */
+    ejected: Record<string, string>;
+}
+export interface EjectOptions {
+    /** Project root to eject into. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /**
+     * Injectable resolver for the installed `@takazudo/zudo-doc` package root.
+     * Defaults to resolving `@takazudo/zudo-doc/package.json` from `cwd`
+     * node_modules. Override in tests to point at a fixture.
+     */
+    resolvePackageRoot?: (cwd: string) => string;
+}
+/**
+ * Eject a single component into the project.
+ *
+ * - If already ejected (recorded in `.zudo-doc.json`): prints a notice and
+ *   exits cleanly (safe no-op — never clobbers local edits).
+ * - Otherwise: copies the TS source from the installed package's `eject/`
+ *   tree, rewires parent-relative imports, rewrites host call sites, and
+ *   records the entry in `.zudo-doc.json`.
+ */
+export declare function eject(component: string, options?: EjectOptions): Promise<void>;

package/dist/eject/index.js

@@ -0,0 +1,229 @@
+import fs from "fs-extra";
+import path from "path";
+import pc from "picocolors";
+const EJECTABLE = {
+  header: {
+    packageSubpath: "@takazudo/zudo-doc/header",
+    localDir: "src/components/zudo-doc/header"
+  },
+  footer: {
+    packageSubpath: "@takazudo/zudo-doc/footer",
+    localDir: "src/components/zudo-doc/footer"
+  },
+  breadcrumb: {
+    packageSubpath: "@takazudo/zudo-doc/breadcrumb",
+    localDir: "src/components/zudo-doc/breadcrumb"
+  },
+  toc: {
+    packageSubpath: "@takazudo/zudo-doc/toc",
+    localDir: "src/components/zudo-doc/toc"
+  },
+  sidebar: {
+    packageSubpath: "@takazudo/zudo-doc/sidebar",
+    localDir: "src/components/zudo-doc/sidebar"
+  },
+  "theme-toggle": {
+    packageSubpath: "@takazudo/zudo-doc/theme-toggle",
+    localDir: "src/components/zudo-doc/theme-toggle"
+  },
+  "page-loading": {
+    packageSubpath: "@takazudo/zudo-doc/page-loading",
+    localDir: "src/components/zudo-doc/page-loading"
+  },
+  "tab-item": {
+    packageSubpath: "@takazudo/zudo-doc/tab-item",
+    localDir: "src/components/zudo-doc/tab-item"
+  },
+  "doc-pager": {
+    packageSubpath: "@takazudo/zudo-doc/doc-pager",
+    localDir: "src/components/zudo-doc/doc-pager"
+  },
+  "content-admonition": {
+    packageSubpath: "@takazudo/zudo-doc/content-admonition",
+    localDir: "src/components/zudo-doc/content-admonition"
+  },
+  "code-group": {
+    packageSubpath: "@takazudo/zudo-doc/code-group",
+    localDir: "src/components/zudo-doc/code-group"
+  },
+  details: {
+    packageSubpath: "@takazudo/zudo-doc/details",
+    localDir: "src/components/zudo-doc/details"
+  }
+};
+async function rewireImports(dir) {
+  const re = /(from\s+)(["'])\.\.\/([\w-]+)\/[^"']+\2/g;
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) continue;
+    if (!/\.[cm]?[jt]sx?$/.test(entry.name)) continue;
+    const filePath = path.join(dir, entry.name);
+    const original = await fs.readFile(filePath, "utf8");
+    const rewritten = original.replace(re, (_, from, quote, seg) => {
+      return `${from}${quote}@takazudo/zudo-doc/${seg}${quote}`;
+    });
+    if (rewritten !== original) {
+      await fs.writeFile(filePath, rewritten, "utf8");
+    }
+  }
+}
+async function rewireHostCallSites(projectRoot, component, localDir) {
+  const packageSubpath = EJECTABLE[component].packageSubpath;
+  const escapedSubpath = packageSubpath.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&");
+  const re = new RegExp(`(from\\s+)(["'])${escapedSubpath}\\2`, "g");
+  const searchDirs = [
+    path.join(projectRoot, "src"),
+    path.join(projectRoot, "pages")
+  ];
+  let rewroteCount = 0;
+  for (const searchDir of searchDirs) {
+    if (!await fs.pathExists(searchDir)) continue;
+    const rewriteDir = async (dir, relFromProject) => {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        const abs = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          await rewriteDir(abs, path.join(relFromProject, entry.name));
+          continue;
+        }
+        if (!/\.[cm]?[jt]sx?$/.test(entry.name)) continue;
+        const original = await fs.readFile(abs, "utf8");
+        if (!original.includes(packageSubpath)) continue;
+        const fileDir = path.join(projectRoot, relFromProject);
+        const destAbs = path.join(projectRoot, localDir);
+        let rel = path.relative(fileDir, destAbs).split(path.sep).join("/");
+        if (!rel.startsWith(".")) rel = `./${rel}`;
+        const rewritten = original.replace(re, (_, from, quote) => {
+          return `${from}${quote}${rel}${quote}`;
+        });
+        if (rewritten !== original) {
+          await fs.writeFile(abs, rewritten, "utf8");
+          rewroteCount++;
+        }
+      }
+    };
+    const relBase = path.relative(projectRoot, searchDir);
+    await rewriteDir(searchDir, relBase);
+  }
+  return rewroteCount;
+}
+function defaultResolvePackageRoot(cwd) {
+  let dir = cwd;
+  while (true) {
+    const candidate = path.join(dir, "node_modules/@takazudo/zudo-doc");
+    if (fs.pathExistsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    `Could not find @takazudo/zudo-doc in node_modules from ${cwd}.
+Run \`pnpm install\` first.`
+  );
+}
+async function eject(component, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const resolvePackageRoot = options.resolvePackageRoot ?? defaultResolvePackageRoot;
+  if (!Object.prototype.hasOwnProperty.call(EJECTABLE, component)) {
+    const valid = Object.keys(EJECTABLE).sort().join(", ");
+    console.error(
+      pc.red(`Unknown component "${component}".`) + `
+Ejectable components: ${valid}`
+    );
+    process.exit(1);
+  }
+  const entry = EJECTABLE[component];
+  const localDir = entry.localDir;
+  const destAbs = path.join(cwd, localDir);
+  const provenancePath = path.join(cwd, ".zudo-doc.json");
+  let provenance = { packageVersion: "unknown", ejected: {} };
+  if (await fs.pathExists(provenancePath)) {
+    try {
+      provenance = await fs.readJson(provenancePath);
+    } catch {
+      provenance = { packageVersion: "unknown", ejected: {} };
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(provenance.ejected, component)) {
+    const recorded = provenance.ejected[component];
+    console.log(
+      pc.yellow(`already ejected at ${recorded}`) + ` \u2014 skipping (re-eject is a safe no-op)`
+    );
+    return;
+  }
+  if (await fs.pathExists(destAbs)) {
+    console.log(
+      pc.yellow(`Destination ${localDir} already exists`) + ` but is not recorded in .zudo-doc.json.
+Treating as already ejected \u2014 skipping to avoid clobbering local edits.
+If you want to re-eject, remove the directory and its .zudo-doc.json entry manually.`
+    );
+    return;
+  }
+  let pkgRoot;
+  try {
+    pkgRoot = resolvePackageRoot(cwd);
+  } catch (err) {
+    console.error(pc.red(String(err)));
+    process.exit(1);
+  }
+  const ejectSrcDir = path.join(pkgRoot, "eject", component);
+  if (!await fs.pathExists(ejectSrcDir)) {
+    const pkgJsonPath = path.join(pkgRoot, "package.json");
+    let version = "unknown";
+    try {
+      const pkgJson = await fs.readJson(pkgJsonPath);
+      version = pkgJson.version ?? "unknown";
+    } catch {
+    }
+    console.error(
+      pc.red(
+        `@takazudo/zudo-doc@${version} does not ship eject sources for "${component}".
+Bump @takazudo/zudo-doc to a version that includes the eject/ tree and retry.`
+      )
+    );
+    process.exit(1);
+  }
+  let installedVersion = provenance.packageVersion;
+  try {
+    const pkgJson = await fs.readJson(path.join(pkgRoot, "package.json"));
+    installedVersion = pkgJson.version ?? installedVersion;
+  } catch {
+  }
+  await fs.ensureDir(destAbs);
+  await fs.copy(ejectSrcDir, destAbs);
+  console.log(pc.green(`Copied ${component} source \u2192 ${localDir}`));
+  await rewireImports(destAbs);
+  console.log(pc.dim(`  Rewired cross-component imports in ${localDir}`));
+  const rewroteCount = await rewireHostCallSites(cwd, component, localDir);
+  if (rewroteCount > 0) {
+    console.log(
+      pc.dim(`  Rewrote ${rewroteCount} host file(s) to import from ${localDir}`)
+    );
+  } else {
+    console.log(
+      pc.dim(
+        `  No host call sites found for ${entry.packageSubpath}.
+  Update your imports manually: change the \`"${entry.packageSubpath}"\`
+  specifier to a local one, e.g. \`"@/${localDir}/index.js"\` or a relative path.`
+      )
+    );
+  }
+  provenance.packageVersion = installedVersion;
+  provenance.ejected[component] = localDir;
+  await fs.writeJson(provenancePath, provenance, { spaces: 2 });
+  console.log(pc.green(`Updated .zudo-doc.json`));
+  console.log(
+    pc.bold(
+      `
+${pc.green("\u2713")} Ejected ${component} from @takazudo/zudo-doc@${installedVersion}
+  Source:      node_modules/@takazudo/zudo-doc/eject/${component}/
+  Destination: ${localDir}/
+  Provenance:  .zudo-doc.json
+`
+    )
+  );
+}
+export {
+  EJECTABLE,
+  eject
+};

package/dist/plugins/routes.d.ts

@@ -0,0 +1,2 @@
+declare const plugin: import("@takazudo/zfb").ZfbPlugin;
+export default plugin;

package/dist/plugins/routes.js

@@ -0,0 +1,100 @@
+import { createRequire } from "node:module";
+import { existsSync, cpSync, rmSync, mkdirSync } from "node:fs";
+import { dirname, basename, join } from "node:path";
+import { definePlugin } from "@takazudo/zfb/plugins";
+function deriveRoutes(settings) {
+  const routes = [];
+  const localeCodes = Object.keys(settings.locales ?? {});
+  const hasVersions = Array.isArray(settings.versions) && settings.versions.length > 0;
+  const docTags = settings.docTags === true;
+  const aiAssistant = settings.aiAssistant === true;
+  routes.push({ pattern: "/404", entrypoint: "@takazudo/zudo-doc/routes/404" });
+  routes.push({ pattern: "/sitemap.xml", entrypoint: "@takazudo/zudo-doc/routes/sitemap.xml" });
+  routes.push({ pattern: "/robots.txt", entrypoint: "@takazudo/zudo-doc/routes/robots.txt" });
+  routes.push({ pattern: "/docs/[[...slug]]", entrypoint: "@takazudo/zudo-doc/routes/docs-slug" });
+  if (docTags) {
+    routes.push({ pattern: "/docs/tags", entrypoint: "@takazudo/zudo-doc/routes/docs-tags-index" });
+    routes.push({ pattern: "/docs/tags/[tag]", entrypoint: "@takazudo/zudo-doc/routes/docs-tags-tag" });
+  }
+  if (aiAssistant) {
+    routes.push({
+      pattern: "/api/ai-chat",
+      entrypoint: "@takazudo/zudo-doc/routes/api-ai-chat",
+      opts: { prerender: false }
+    });
+  }
+  if (hasVersions) {
+    routes.push({ pattern: "/docs/versions", entrypoint: "@takazudo/zudo-doc/routes/docs-versions" });
+    routes.push({ pattern: "/v/[version]/docs/[[...slug]]", entrypoint: "@takazudo/zudo-doc/routes/v-docs-slug" });
+    routes.push({ pattern: "/v/[version]/[locale]/docs/[[...slug]]", entrypoint: "@takazudo/zudo-doc/routes/v-locale-docs-slug" });
+  }
+  if (localeCodes.length > 0) {
+    routes.push({ pattern: "/[locale]", entrypoint: "@takazudo/zudo-doc/routes/locale-index" });
+    routes.push({ pattern: "/[locale]/docs/[[...slug]]", entrypoint: "@takazudo/zudo-doc/routes/locale-docs-slug" });
+    if (docTags) {
+      routes.push({ pattern: "/[locale]/docs/tags", entrypoint: "@takazudo/zudo-doc/routes/locale-docs-tags-index" });
+      routes.push({ pattern: "/[locale]/docs/tags/[tag]", entrypoint: "@takazudo/zudo-doc/routes/locale-docs-tags-tag" });
+    }
+    if (hasVersions) {
+      routes.push({ pattern: "/[locale]/docs/versions", entrypoint: "@takazudo/zudo-doc/routes/locale-docs-versions" });
+    }
+  }
+  return routes;
+}
+const plugin = definePlugin({
+  name: "@takazudo/zudo-doc/plugins/routes",
+  setup(ctx) {
+    const options = ctx.options;
+    const settings = options.settings ?? {};
+    const translations = options.translations ?? {};
+    const tagVocabulary = options.tagVocabulary ?? [];
+    ctx.addVirtualModule(
+      "virtual:zudo-doc-route-context",
+      () => `export const routeContext = ${JSON.stringify({
+        settings,
+        translations,
+        tagVocabulary
+      })};
+`
+    );
+    const require2 = createRequire(import.meta.url);
+    let stagedRoutesDir;
+    const ensureStaged = (routesSrcDir) => {
+      if (stagedRoutesDir) return stagedRoutesDir;
+      const dest = join(ctx.projectRoot, ".zudo-doc", "routes-src");
+      rmSync(dest, { recursive: true, force: true });
+      mkdirSync(dirname(dest), { recursive: true });
+      cpSync(routesSrcDir, dest, { recursive: true });
+      stagedRoutesDir = dest;
+      return dest;
+    };
+    for (const route of deriveRoutes(settings)) {
+      let resolvedEntrypoint;
+      try {
+        const compiledPath = require2.resolve(route.entrypoint);
+        const tsxName = basename(compiledPath).replace(/\.js$/, ".tsx");
+        const routesSrcDir = dirname(compiledPath).replace(
+          /dist[\\/]routes$/,
+          "routes-src"
+        );
+        const routesSrcPath = join(routesSrcDir, tsxName);
+        const srcPath = compiledPath.replace(/[\\/]dist[\\/]/, "/src/").replace(/\.js$/, ".tsx");
+        if (existsSync(routesSrcPath)) {
+          const underNodeModules = /[\\/]node_modules[\\/]/.test(routesSrcPath);
+          resolvedEntrypoint = underNodeModules ? join(ensureStaged(routesSrcDir), tsxName) : routesSrcPath;
+        } else if (existsSync(srcPath)) {
+          resolvedEntrypoint = srcPath;
+        } else {
+          resolvedEntrypoint = compiledPath;
+        }
+      } catch {
+        resolvedEntrypoint = route.entrypoint;
+      }
+      ctx.injectRoute(route.pattern, resolvedEntrypoint, route.opts);
+    }
+  }
+});
+var routes_default = plugin;
+export {
+  routes_default as default
+};

package/dist/preset.d.ts

@@ -72,6 +72,18 @@ export interface PresetSettings {
     claudeResources?: PresetClaudeResourcesConfig | false;
     /** "owner/repo" — when set, enables `#123` / SHA autolinks in markdown. Omit to disable entirely. */
     githubAutolinksRepo?: string;
+    /** When `true`, the preset adds the package-owned route-injection plugin
+     *  (`@takazudo/zudo-doc/plugins/routes`). On by default since the fast-follow
+     *  (#2372): the showcase and create-zudo-doc both EMIT `packageOwnedRoutes: true`
+     *  into their generated `settings.ts`. `buildPlugins` reads this value truthily
+     *  and does NO central defaulting — a hand-written settings object that OMITS the
+     *  field is treated as off; set it explicitly to control injection.
+     *  See `docs/adr/route-injection-seam.md`. */
+    packageOwnedRoutes?: boolean;
+    /** Gate for the `/docs/tags` + `/docs/tags/[tag]` injected routes. */
+    docTags?: boolean;
+    /** Gate for the SSR `/api/ai-chat` injected route (`prerender: false`). */
+    aiAssistant?: boolean;
 }
 /**
  * The directives recipe map (`markdown.features.directives`): directive name →
@@ -81,6 +93,29 @@ export interface PresetSettings {
  * the canonical seven (note/tip/info/warning/danger/caution/details).
  */
 export type DirectiveVocabulary = Record<string, string>;
+/**
+ * The UI-string translation table (`src/config/i18n.ts` `translations`).
+ * Locale code → key → translated string. Passed (not imported) so the preset's
+ * import graph stays node-builtin-free; rides into the route-context virtual
+ * module verbatim when `packageOwnedRoutes` is on. Optional — only consumed by
+ * the routes plugin; omitting it makes the virtual module carry `{}`.
+ */
+export type PresetTranslations = Record<string, Record<string, string>>;
+/**
+ * The tag vocabulary entries (`src/config/tag-vocabulary.ts`). Serializable
+ * data, threaded into the route-context virtual module when
+ * `packageOwnedRoutes` is on. Optional — only consumed by the routes plugin.
+ */
+export type PresetTagVocabularyEntry = {
+    id: string;
+    label?: string;
+    description?: string;
+    group?: string;
+    aliases?: readonly string[];
+    deprecated?: boolean | {
+        redirect?: string;
+    };
+};
 /** Arguments to `zudoDocPreset`. */
 export interface ZudoDocPresetArgs {
     /** The project's `settings` object (structurally `PresetSettings`). */
@@ -97,6 +132,17 @@ export interface ZudoDocPresetArgs {
      * The directives recipe map. See {@link DirectiveVocabulary}.
      */
     directiveVocabulary: DirectiveVocabulary;
+    /**
+     * The host's UI-string translation table. Only consumed when
+     * `settings.packageOwnedRoutes` is true (rides into the route-context virtual
+     * module). Optional — defaults to `{}`. See {@link PresetTranslations}.
+     */
+    translations?: PresetTranslations;
+    /**
+     * The host's tag vocabulary entries. Only consumed when
+     * `settings.packageOwnedRoutes` is true. Optional — defaults to `[]`.
+     */
+    tagVocabulary?: readonly PresetTagVocabularyEntry[];
 }
 export interface PresetCollection {
     name: string;
@@ -149,4 +195,4 @@ export interface ZudoDocPresetResult {
  * });
  * ```
  */
-export declare function zudoDocPreset({ settings, buildDocsSchema, directiveVocabulary, }: ZudoDocPresetArgs): ZudoDocPresetResult;
+export declare function zudoDocPreset({ settings, buildDocsSchema, directiveVocabulary, translations, tagVocabulary, }: ZudoDocPresetArgs): ZudoDocPresetResult;

package/dist/preset.js

@@ -2,12 +2,14 @@ import { z } from "zod";
 function zudoDocPreset({
   settings,
   buildDocsSchema,
-  directiveVocabulary
+  directiveVocabulary,
+  translations,
+  tagVocabulary
 }) {
   const docsSchemaJson = z.toJSONSchema(buildDocsSchema());
   return {
     collections: buildCollections(settings, docsSchemaJson),
-    plugins: buildPlugins(settings),
+    plugins: buildPlugins(settings, { translations, tagVocabulary }),
     markdown: { features: buildMarkdownFeatures(settings, directiveVocabulary) },
     // Dual-theme syntect (zfb >= 0.1.0-next.45). Theme names are SYNTECT
     // built-ins, NOT Shiki names. Tokens emit `--shiki-light`/`--shiki-dark`
@@ -103,7 +105,7 @@ function buildMarkdownFeatures(settings, directiveVocabulary) {
     headingIds: { strategy: settings.headingIdStrategy }
   };
 }
-function buildPlugins(settings) {
+function buildPlugins(settings, routeContext) {
   const localeArray = Object.entries(settings.locales).map(([code, locale]) => ({
     code,
     dir: locale.dir
@@ -112,6 +114,29 @@ function buildPlugins(settings) {
     Object.entries(settings.locales).map(([code, locale]) => [code, { dir: locale.dir }])
   );
   return [
+    // Package-owned route injection — dormant by default (Decision 4). The
+    // descriptor is a BARE SPECIFIER, never an imported plugin function: the
+    // preset's node-free eval-graph guard (preset.test.ts) bundles this module
+    // under --platform=neutral, and importing the plugin would drag its
+    // `injectRoute`/`node:*` graph into the config eval. The plugin's `setup`
+    // hook reads `options` to (a) emit the route-context virtual module
+    // (serializable settings/translations/tagVocabulary only) and (b) derive
+    // the route catalog from `settings.locales` / `settings.versions`. Listed
+    // FIRST so an injected route is registered before the other plugins'
+    // preBuild work runs (ordering is cosmetic — injection happens in `setup`).
+    ...settings.packageOwnedRoutes ? [
+      {
+        name: "@takazudo/zudo-doc/plugins/routes",
+        options: {
+          // Serializable project settings — JSON.stringify-d verbatim into
+          // the virtual module. No function-valued fields (verified in
+          // src/config/settings.ts), so it round-trips losslessly.
+          settings,
+          translations: routeContext.translations ?? {},
+          tagVocabulary: routeContext.tagVocabulary ?? []
+        }
+      }
+    ] : [],
     ...settings.claudeResources ? [
       {
         name: "@takazudo/zudo-doc/plugins/claude-resources",
@@ -152,16 +177,7 @@ function buildPlugins(settings) {
           locales: localeArray
         }
       }
-    ] : [],
-    // copy-public stays a PROJECT-relative descriptor (NOT relocated in S3).
-    // Native zfb copy_public_dir is not yet validated for base="/", so the
-    // host plugin remains until that lands; deleted in place in a later epic.
-    {
-      name: "./plugins/copy-public-plugin.mjs",
-      options: {
-        publicDir: "public"
-      }
-    }
+    ] : []
   ];
 }
 export {

package/dist/routes/404.d.ts

@@ -0,0 +1,7 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+export declare const frontmatter: {
+    title: string;
+};
+export default function NotFoundPage(): JSX.Element;

package/dist/routes/404.js

@@ -0,0 +1,47 @@
+import { Fragment, jsx, jsxs } from "preact/jsx-runtime";
+import { DocLayoutWithDefaults } from "../doclayout/index.js";
+import { settings, defaultLocale, withBase } from "./_context.js";
+import {
+  HeadWithDefaults,
+  HeaderWithDefaults,
+  FooterWithDefaults,
+  BodyEndIslandsStub,
+  composeMetaTitle
+} from "./_chrome.js";
+const frontmatter = { title: "404" };
+function NotFoundPage() {
+  const locale = defaultLocale;
+  const title = "Page Not Found";
+  return /* @__PURE__ */ jsx(
+    DocLayoutWithDefaults,
+    {
+      title: composeMetaTitle(title),
+      head: /* @__PURE__ */ jsx(HeadWithDefaults, { title }),
+      lang: locale,
+      noindex: true,
+      hideSidebar: true,
+      hideToc: true,
+      sidebarOverride: /* @__PURE__ */ jsx(Fragment, {}),
+      headerOverride: /* @__PURE__ */ jsx(HeaderWithDefaults, { lang: locale }),
+      footerOverride: /* @__PURE__ */ jsx(FooterWithDefaults, { lang: locale }),
+      bodyEndComponents: /* @__PURE__ */ jsx(BodyEndIslandsStub, { basePath: settings.base ?? "/" }),
+      enableClientRouter: settings.dynamicPageTransition,
+      children: /* @__PURE__ */ jsxs("div", { class: "min-h-[60vh] flex flex-col items-center justify-center px-hsp-2xl py-vsp-xl", children: [
+        /* @__PURE__ */ jsx("h1", { class: "text-display font-bold mb-vsp-md", children: "404" }),
+        /* @__PURE__ */ jsx("p", { class: "text-title text-muted mb-vsp-xl", children: "Page not found." }),
+        /* @__PURE__ */ jsx(
+          "a",
+          {
+            href: withBase("/"),
+            class: "bg-accent px-hsp-lg py-vsp-xs font-medium text-bg hover:bg-accent-hover",
+            children: "Back to Home"
+          }
+        )
+      ] })
+    }
+  );
+}
+export {
+  NotFoundPage as default,
+  frontmatter
+};