@takazudo/zudo-doc 3.2.0 → 4.0.0

package/CHANGELOG.md

@@ -4,6 +4,67 @@ 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.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
+
+- **Minimal Scaffold (epic #2651).** `create-zudo-doc` now emits a locked ~12-file minimal manifest — a generated project is one config file (`zfb.config.ts` using the diff-from-defaults `zudoDoc({...})`) plus Markdown content, extended via eject. The package now owns the defaults that were previously copied into every scaffold: default `@theme` tokens ship as `@takazudo/zudo-doc/theme.css`, and i18n, color schemes, docs schema, z-index, frontmatter-preview, and directives ship as package-default data modules. (98a56931, 257fa9aa, 5f45bf15, 2056824f)
+- Added the `zudoDoc()` single-entry config API returning a full `ZfbConfig`; the showcase and generated scaffolds migrate their `zfb.config.ts` and the four doc-route stubs to the self-contained form. (a06f5990, 1fc470f0, 6e4a6d08)
+- Added the `defineChromeBindings` widening adapter — a typed helper that replaces chrome-binding casts; the generator now injects it instead of a `DocHistory` cast. (5915707b, aa29e479, 0e49a6ad)
+- Absorbed the Tauri find-in-page island (Cmd/Ctrl+F find bar) into `@takazudo/zudo-doc/find-in-page`, mounted from the package's body-end islands behind a new `findInPage` setting (default `false`). The island self-gates on `window.__TAURI_INTERNALS__`, so it stays a safe no-op outside a Tauri shell. `create-zudo-doc`'s tauri feature now emits `findInPage: true` for generated Tauri scaffolds. (97885c5d, cc1bc846, f5e4c953)
+- Added a package-owned `DesignTokenPanelBootstrap` island, mounted from the package's routes. (5f75a9ed, 105a3b40)
+- The package now ships `tsconfig.base`, a `zfb-config` shim, and generated virtual-module types. (3de2b209)
+
+### Bug Fixes
+
+- Corrected the `create-zudo-doc` Node engine floor and documented the built-in MDX components (#2702, #2703). (edf5cc4f)
+- Exported the `./find-in-page` subpath so hosts can mount `FindInPageInit`. (a4c4f8e5)
+- Stopped the generator dropping unlisted config keys and guarded `DEFAULT_MIRROR` drift. (ac0c6afa)
+- The i18n locale doc stub now threads `isFallback` and a per-locale content directory. (8355e537)
+- Routed package-manager script commands through a single `pmRunCommand` helper. (cb88bde6)
+- Made the `pages` typecheck project Preact-native. (a24dfef4)
+- Warn on a missing color scheme, and clarified the `zudoDoc` shallow-merge docs. (8f913319)
+- Tightened `frontmatterRenderers`/`buildFrontmatterPreviewEntries` slot types so drift is detected for real. (d9d9b828)
+- Fixed the default header chrome background. (f0245086)
+
+### Other Changes
+
+- Retired `packages/md-plugins` and dropped the showcase Design Token Panel config copy in favor of the package default. (e99ebe7d, c74c481a)
+- Patched transitive security advisories via pnpm overrides and bumped `@takazudo/zdtp` 0.4.5 → 0.4.6. (24013cd1, 731c8677)
+- Rewrote the core structure docs for the minimal→extend model (EN + JA). (f57d092e)
+
 ## [3.2.0] - 2026-07-08
 
 ### 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);
 }