@takazudo/zudo-doc 3.3.0 → 4.1.0

package/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to `@takazudo/zudo-doc` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [4.1.0] - 2026-07-18
+
+### Features
+
+- Theme-pack fonts now reach the app shell (header, sidebar, TOC, breadcrumb, pager) via a global body font seam, with per-surface chrome font tokens for finer control (f84b2bd2)
+
+### Bug Fixes
+
+- Per-surface chrome font knobs anchor to the seam token instead of relying on inheritance (dbd95365)
+- Docs: corrected the false claim that mobile chrome strips theme-pack font tokens — mobile hooks receive them like desktop (3cbe0d45, 493f76dc)
+- E2E: theme-pack font specs assert the body font-family directly, target the bundled foundry pack, and wait for switcher hydration (d88e4c5a, 218e8844)
+- Reverted a hand-edited generated CHANGELOG.md — it is corpus-generated (ef43274c)
+
+### Other Changes
+
+- Toolchain: @takazudo/zfb family (zfb, zfb-runtime, zfb-adapter-cloudflare, zfb-md-wasm) adopted through 0.1.0-next.89 (02268414)
+- Bilingual docs for the chrome font seam tokens and the mobile reach caveat (58cf6fc2)
+- Durable e2e regression spec for the chrome font seam (69af425e)
+
+## [4.0.0] - 2026-07-17
+
+### Breaking Changes
+
+- Current-only compatibility contract: legacy integration subpaths, the tag alias/deprecation runtime, legacy token storage bridges, legacy Syntect markup support, legacy doc-history contracts, and the legacy link-checker entrypoints are removed (c8b6d3da, 08338a8f, 701b4aea, 16edbe8b, e8ce8929, cc2bb792, f2c9b925)
+- Heading IDs are hierarchical-only; the legacy flat-ID fallback is gone (390064ff)
+- Doc entries use the current zfb entry model exclusively (df048e30)
+
+### Features
+
+- Theme pack system: pack registry with config census and validator, asset delivery pipeline (build, npm tarball, dev), runtime switching engine with FOUC-safe bootstrap, bottom-right switcher flyout, browse-all theme grid dialog, and a `zudo-doc theme list|apply` CLI (aab0014f, 9eddd9ba, f5f83b43, adf81c9a, 07b77eb1, a33f66ef)
+- 20 official theme packs shipped across four batches — foundry, swissgrid, broadsheet, ledger, manuscript, futura-editorial, washi, sumi, matcha, hearth, hollow, fjord, nocturne, drift, onyx, phosphor, observatory, solar, beacon, brutalist — with the full 21-pack catalog (including default) synced into create-zudo-doc and the preset generator (487b1761)
+- Stable DOM hooks for theme packs: `data-footer`, `data-doc-pager`, `data-doc-description`, and `data-theme-pack-switcher` / `data-switcher-card` / `data-switcher-launcher`; all 20 packs retargeted onto the hooks and every changed pack's `meta.json` version bumped for the stylesheet cache buster (c8bb4421, ac654a8a, 2b2a46d5, b5fffb01, d7c67ca7)
+- Restored pack styling that previously lacked hooks: foundry's pager hover wash and broadsheet's classified-ad flyout frame (850a30fb)
+- Semantic syntax-highlight class mode: document fences render `hi-*` token classes with a stable token contract, mapped by `features.css` (c1237dcd, c305fdf8, 920be3d2)
+- AI chat exact daily spend cap enforced via a Durable Object, with paid-call admission control and an operations runbook (0b46e23c, 15e3b891, 491116c5)
+- Chrome customization: typed primary replacement slots (`Header`, `Footer`, `Sidebar`, `Toc`, `Breadcrumb`, `DocPager`), a named header-component registry, binding-aware eject warnings, and end-to-end proof (a3ae76cc, 9d8e7901, 5346b2ef, 0e92dbc2)
+- create-zudo-doc: `footerCopyright` feature defaults to on; theme-pack scaffold prompt and programmatic `themePack` option (51307cd4, acf20690, b287e94d)
+
+### Bug Fixes
+
+- onyx: the decorative gold outline on the switcher card and browse-all dialog no longer masks the keyboard focus-visible ring (11d5cc0f)
+- ledger: DocPager selector no longer over-matches NavCardGrid on auto-index pages (eff8e1b8)
+- Light-mode WCAG contrast corrections across several packs after review (46e1e6b2)
+
+### Other Changes
+
+- Theme pack architecture ADR, hardened Decisions 6.5/6.6 (stable-hook list, h2–h4 gradient carve-out), and a new durable `theme-pack-authoring.md` pack-author reference (4f5cc90c, ed287e1a, 4856c44b)
+- Theme gallery reference docs (EN+JA) covering the full pack catalog (2b73cffa, 3068fbca)
+- Scaffold customization docs overhaul: customization ladder, chrome bindings, custom components guide, route injection, color-token guidance (8a54b3df)
+- Toolchain: zfb family adopted through next.87; zdtp 0.4.8 (151f09bb, efc3afdc)
+
 ## [3.3.0] - 2026-07-12
 
 ### Features

package/README.md

@@ -8,14 +8,14 @@ instead of editing the generated markdown directly.
 
 This package provides the missing-by-design framework concerns:
 
-- **Sidebar tree builder** (`./sidebar-tree`) — turns collection entries + `_category_.json` into a sidebar `SidebarNode[]`.
+- **Sidebar tree builder** (`./sidebar-tree`) — turns collection entries + `_category_.json` into breadcrumb/navigation nodes.
 - **Theme controls** (`./theme`) — color scheme provider + design-token tweak panel (Preact island that wraps an iframe).
 - **Theme toggle (bare)** (`./theme-toggle`) — the un-wrapped ThemeToggle component for call sites that compose their own `<Island>` (the `./theme` barrel exports an Island-wrapped variant of the same component).
 - **TOC** (`./toc`) — desktop and mobile TOC Preact islands fed by MDX `headings` export.
 - **Breadcrumb** (`./breadcrumb`) — JSX breadcrumb fed by the sidebar tree.
 - **DocLayout** (`./doclayout`) — composable layout shell with explicit `<Header>`, `<Sidebar>`, `<Main>`, `<Toc>`, `<Footer>` props; ships a `<DocLayoutWithDefaults>` wrapper that holds the 16 `create-zudo-doc` injection anchors.
 - **View Transitions** (`./transitions`) — native View Transitions API shim (Chrome/Edge/Safari 18+); persistent regions via `view-transition-name`. No-op fallback in Firefox.
-- **Head injection** (`./head`) — canonical, og:\*, twitter:\*, robots, preload hints, RSS link, sitemap link, theme-color — byte-equal to today's legacy doc-layout output.
+- **Head injection** (`./head`) — canonical, og:\*, twitter:\*, robots, preload hints, RSS link, sitemap link, and theme-color output.
 - **SSR-skip wrappers** (`./ssr-skip`) — `<AiChatModalIsland>`, `<ImageEnlargeIsland>`, `<DesignTokenTweakPanelIsland>`, `<MockInitIsland>` — wrap zfb's `<Island ssrFallback>` with the right fallback markup so doc pages don't have to re-implement the SSR-skip pattern.
 
 ## Optional peer dependency: shiki

package/bin/tag-cli-config.ts

@@ -0,0 +1,126 @@
+import { pathToFileURL } from "node:url";
+import { isAbsolute, resolve } from "node:path";
+
+import type { TagCliConfig } from "@takazudo/zudo-doc/tags-audit";
+
+const GOVERNANCE_MODES = new Set(["off", "warn", "strict"]);
+
+function invalidConfig(configPath: string, detail: string): Error {
+  return new Error(`Invalid tag CLI config "${configPath}": ${detail}`);
+}
+
+function validateConfig(value: unknown, configPath: string): TagCliConfig {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw invalidConfig(configPath, "the module must default-export an object");
+  }
+
+  const config = value as Record<string, unknown>;
+  if (
+    !Array.isArray(config.contentDirs) ||
+    config.contentDirs.length === 0 ||
+    config.contentDirs.some(
+      (dir) =>
+        typeof dir !== "string" ||
+        dir.trim().length === 0 ||
+        isAbsolute(dir),
+    )
+  ) {
+    throw invalidConfig(
+      configPath,
+      "`contentDirs` must be a non-empty array of project-relative paths",
+    );
+  }
+  if (
+    !Array.isArray(config.vocabulary) ||
+    config.vocabulary.some(
+      (entry) =>
+        entry === null ||
+        typeof entry !== "object" ||
+        typeof (entry as { id?: unknown }).id !== "string" ||
+        (entry as { id: string }).id.trim().length === 0,
+    )
+  ) {
+    throw invalidConfig(
+      configPath,
+      "`vocabulary` must be an array of entries with non-empty string ids",
+    );
+  }
+  if (
+    typeof config.governance !== "string" ||
+    !GOVERNANCE_MODES.has(config.governance)
+  ) {
+    throw invalidConfig(
+      configPath,
+      "`governance` must be one of \"off\", \"warn\", or \"strict\"",
+    );
+  }
+  if (typeof config.vocabularyActive !== "boolean") {
+    throw invalidConfig(configPath, "`vocabularyActive` must be a boolean");
+  }
+
+  return config as unknown as TagCliConfig;
+}
+
+export async function loadTagCliConfig(
+  configInput: string | undefined,
+  cwd = process.cwd(),
+): Promise<{ config: TagCliConfig; configPath: string }> {
+  if (!configInput || configInput.trim().length === 0) {
+    throw new Error(
+      "Missing required tag CLI config. Pass `--config <path>` to a module that default-exports TagCliConfig.",
+    );
+  }
+
+  const configPath = isAbsolute(configInput)
+    ? resolve(configInput)
+    : resolve(cwd, configInput);
+
+  let loaded: { default?: unknown };
+  try {
+    loaded = (await import(pathToFileURL(configPath).href)) as {
+      default?: unknown;
+    };
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`Could not load tag CLI config "${configPath}": ${detail}`);
+  }
+
+  return {
+    config: validateConfig(loaded.default, configPath),
+    configPath,
+  };
+}
+
+/** Package-manager `--` separators must not hide CLI options from the runner. */
+export function withoutForwardingSeparators(argv: string[]): string[] {
+  return argv.filter((arg) => arg !== "--");
+}
+
+export function takeTagCliConfigInput(argv: string[]): {
+  configInput: string | undefined;
+  argv: string[];
+} {
+  const normalized = withoutForwardingSeparators(argv);
+  const rest: string[] = [];
+  let configInput: string | undefined;
+
+  for (let index = 0; index < normalized.length; index++) {
+    const arg = normalized[index]!;
+    if (arg === "--config" || arg === "-c") {
+      const value = normalized[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error(`Option \`${arg}\` requires a path.`);
+      }
+      configInput = value;
+      index++;
+      continue;
+    }
+    if (arg.startsWith("--config=")) {
+      configInput = arg.slice("--config=".length);
+      continue;
+    }
+    rest.push(arg);
+  }
+
+  return { configInput, argv: rest };
+}

package/bin/tags-audit-runner.ts

@@ -6,20 +6,18 @@
  * bin/tags-audit.mjs via tsx so it can:
  *   1. Import the compiled core logic from this package
  *      (@takazudo/zudo-doc/tags-audit).
- *   2. Dynamically import the project's TypeScript config files
- *      (src/config/settings.ts, src/config/tag-vocabulary.ts)
+ *   2. Load the one project config module explicitly passed with `--config`
  *      via tsx's TypeScript-aware loader.
  *
  * This file is published as-is in the package's `bin/` directory.
  * Do NOT compile it — it is only ever run through tsx.
  *
  * Flags:
- *   --fix    rewrite alias tags to canonical ids, byte-stable
  *   --ci     force non-zero exit on any hard issue regardless of governance
  *   --json   emit the report as JSON instead of colorized text
  */
 
-import { join, resolve } from "node:path";
+import { resolve } from "node:path";
 
 import pc from "picocolors";
 import pluralize from "pluralize";
@@ -27,100 +25,86 @@ import stringSimilarity from "string-similarity";
 
 import {
   audit,
-  applyFixes,
-  computeRewrites,
   formatTextReport,
   hasHardIssues,
   type AuditOptions,
 } from "@takazudo/zudo-doc/tags-audit";
+import {
+  loadTagCliConfig,
+  takeTagCliConfigInput,
+} from "./tag-cli-config.ts";
 
 // ── Project root ───────────────────────────────────────────────────────────
 
 const ROOT_DIR = process.cwd();
 
-// ── Dynamic import of project-specific TypeScript config ───────────────────
-// tsx (which runs this file) handles the TypeScript imports below.
+// ── CLI flags ──────────────────────────────────────────────────────────────
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const settingsModule = await import(resolve(ROOT_DIR, "src/config/settings.ts")) as any;
-const settings = settingsModule.settings as {
-  docsDir: string;
-  tagGovernance: "off" | "warn" | "strict";
-  tagVocabulary: boolean;
-  locales?: Record<string, { label?: string; dir: string }>;
-};
+async function main(): Promise<void> {
+  const parsed = takeTagCliConfigInput(process.argv.slice(2));
+  const argv = parsed.argv;
+  const flags = {
+    ci: argv.includes("--ci"),
+    json: argv.includes("--json"),
+  };
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const vocabModule = await import(resolve(ROOT_DIR, "src/config/tag-vocabulary.ts")) as any;
-const tagVocabulary: readonly { id: string; [k: string]: unknown }[] =
-  vocabModule.tagVocabulary ?? [];
+  const unknownArgs = argv.filter(
+    (arg) => arg !== "--ci" && arg !== "--json",
+  );
+  if (unknownArgs.length > 0) {
+    throw new Error(`Unknown option: ${unknownArgs[0]}`);
+  }
 
-// ── CLI flags ──────────────────────────────────────────────────────────────
+  const { config } = await loadTagCliConfig(parsed.configInput, ROOT_DIR);
 
-const argv = process.argv.slice(2);
-const flags = {
-  fix: argv.includes("--fix"),
-  ci: argv.includes("--ci"),
-  json: argv.includes("--json"),
-};
+  // ── Resolve content directories from explicit config ─────────────────────
 
-// ── Resolve content directories from settings ──────────────────────────────
+  const contentDirs = config.contentDirs.map((dir) => resolve(ROOT_DIR, dir));
 
-const docsDir = join(ROOT_DIR, settings.docsDir);
-const localeDirs = Object.values(settings.locales ?? {}).map((l) =>
-  join(ROOT_DIR, l.dir),
-);
-const contentDirs = [docsDir, ...localeDirs];
+  // ── Audit mode ───────────────────────────────────────────────────────────
 
-const vocabularyActive =
-  Boolean(settings.tagVocabulary) && settings.tagGovernance !== "off";
+  const opts: AuditOptions = {
+    rootDir: ROOT_DIR,
+    contentDirs,
+    vocabulary: config.vocabulary,
+    governance: config.governance,
+    vocabularyActive: config.vocabularyActive,
+    nearDupHelpers: {
+      singular: pluralize.singular,
+      compareTwoStrings: stringSimilarity.compareTwoStrings,
+    },
+  };
 
-// ── Fix mode ───────────────────────────────────────────────────────────────
+  const report = await audit(opts);
 
-if (flags.fix) {
-  const rewrites = computeRewrites(tagVocabulary);
-  const touched = await applyFixes(contentDirs, rewrites, ROOT_DIR);
   if (flags.json) {
-    process.stdout.write(JSON.stringify({ fixed: touched }, null, 2) + "\n");
-  } else if (touched.length === 0) {
-    console.log(pc.green("✓ No alias rewrites needed"));
+    process.stdout.write(JSON.stringify(report, null, 2) + "\n");
   } else {
-    console.log(pc.green(`✓ Rewrote aliases in ${touched.length} file(s):`));
-    for (const f of touched) console.log(`  ${f}`);
+    console.log(
+      formatTextReport(
+        report,
+        config.governance,
+        config.vocabularyActive,
+        pc,
+      ),
+    );
   }
-  process.exit(0);
-}
 
-// ── Audit mode ─────────────────────────────────────────────────────────────
-
-const opts: AuditOptions = {
-  rootDir: ROOT_DIR,
-  contentDirs,
-  vocabulary: tagVocabulary,
-  governance: settings.tagGovernance,
-  vocabularyActive,
-  nearDupHelpers: {
-    singular: pluralize.singular,
-    compareTwoStrings: stringSimilarity.compareTwoStrings,
-  },
-};
-
-const report = await audit(opts);
-
-if (flags.json) {
-  process.stdout.write(JSON.stringify(report, null, 2) + "\n");
-} else {
-  console.log(formatTextReport(report, settings.tagGovernance, vocabularyActive, pc));
+  const hardIssues = hasHardIssues(report);
+  if (hardIssues && (flags.ci || config.governance === "strict")) {
+    process.exit(1);
+  }
+  if (hardIssues) {
+    console.error(
+      pc.yellow(
+        "Note: tag issues found but running in non-strict mode (exit 0). Use --ci to fail.",
+      ),
+    );
+  }
 }
 
-const hardIssues = hasHardIssues(report);
-if (hardIssues && (flags.ci || settings.tagGovernance === "strict")) {
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  process.stderr.write(`[tags-audit] ERROR: ${message}\n`);
   process.exit(1);
-}
-if (hardIssues) {
-  console.error(
-    pc.yellow(
-      "Note: tag issues found but running in non-strict mode (exit 0). Use --ci to fail.",
-    ),
-  );
-}
+});

package/bin/tags-audit.mjs

@@ -3,24 +3,18 @@
 //
 // Package bin: vocabulary-aware audit of frontmatter tags.
 //
-// Spawns tsx (from the project's node_modules) to run the TypeScript runner
+// Spawns the package-owned tsx dependency to run the TypeScript runner
 // (bin/tags-audit-runner.ts) which imports the compiled core logic from this
-// package plus the project's TypeScript config files (settings.ts,
-// tag-vocabulary.ts) via dynamic import.
-//
-// Requires tsx in the project's devDependencies. pnpm puts ./node_modules/.bin
-// in PATH for npm scripts, so `pnpm run tags:audit` always finds tsx.
+// package plus the one project config module explicitly passed with --config.
 //
 // Usage (via package.json scripts):
-//   tags-audit          # report only (exit 0 in warn mode)
-//   tags-audit --fix    # rewrite alias tags in place
-//   tags-audit --ci     # force exit 1 on any hard issue
-//   tags-audit --json   # emit JSON report
+//   tags-audit --config ./src/config/tag-vocabulary.ts
+//   tags-audit --config ./src/config/tag-vocabulary.ts --ci
+//   tags-audit --config ./src/config/tag-vocabulary.ts -- --json
 
 import { spawnSync } from "node:child_process";
 import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { existsSync } from "node:fs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -28,35 +22,22 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // tsx treats it as a TypeScript file and handles the import graph.
 const RUNNER_PATH = resolve(__dirname, "tags-audit-runner.ts");
 
-// Locate tsx in the project's node_modules/.bin.
-// Walk up from cwd to handle monorepo setups where node_modules is hoisted.
-function findTsxBin() {
-  let dir = process.cwd();
-  for (let i = 0; i < 10; i++) {
-    const candidate = resolve(dir, "node_modules/.bin/tsx");
-    if (existsSync(candidate)) return candidate;
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  // Last resort: tsx on PATH (e.g. globally installed or nix-shell)
-  return "tsx";
-}
-
-const tsxBin = findTsxBin();
+const tsxCli = fileURLToPath(import.meta.resolve("tsx/cli"));
 
-const result = spawnSync(tsxBin, [RUNNER_PATH, ...process.argv.slice(2)], {
-  stdio: "inherit",
-  env: process.env,
-  cwd: process.cwd(),
-});
+const result = spawnSync(
+  process.execPath,
+  [tsxCli, RUNNER_PATH, ...process.argv.slice(2)],
+  {
+    stdio: "inherit",
+    env: process.env,
+    cwd: process.cwd(),
+  },
+);
 
 if (result.error) {
-  // tsx binary not found or failed to spawn
   process.stderr.write(
-    `\n[tags-audit] ERROR: Could not run tsx to execute the tags-audit runner.\n` +
-      `  Ensure tsx is in your project's devDependencies and run \`pnpm install\`.\n` +
-      `  tsx searched for: ${tsxBin}\n\n`,
+    `\n[tags-audit] ERROR: Could not start the package tag-audit runner.\n` +
+      `  Reinstall @takazudo/zudo-doc and try again.\n\n`,
   );
   process.exit(1);
 }