@takazudo/zudo-doc 4.2.1 → 4.4.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@ 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.4.0] - 2026-07-22
+
+### Features
+
+- Theme Batch 5 adds 10 new theme packs — academia, bauhaus, blueprint, botanica, eink, riso, sakura, scandi, tidepool, and timberline — bringing the catalog to 31 packs, each with full admonition/code/sidebar coverage and a rendered WCAG contrast audit (29bb3497f, 12665cdf1)
+- A new `logo` setting renders a generated "auto" home-hero logo by default, alongside a `zudo-doc eject logo` CLI subcommand for taking full ownership of the logo markup (a2ba5188a, 3cedbee04)
+- `scripts/theme-a11y-audit.ts` adds a rendered per-pack contrast audit tool, now wired into the nightly exam and documented for theme authors (4c969cd4a, 8ed913f9d)
+- The top-page Tags section now renders tag chips, and the home hero gained a `heroLink` prop with an inline extras row (55be502c2, fc865e6be)
+- Header, sidebar, overflow-dropdown, and doc-pager non-active nav elements now consistently turn accent color on hover/focus, with a shared class-token source of truth for the header nav (fafecc154, 274a8641f)
+
+### Bug Fixes
+
+- Resolved 10 rendered-a11y audit findings across 5 existing theme packs, plus follow-up contrast fixes for blueprint/sakura/tidepool and five additional deep-review findings (b694708dc, 2c2dcc858, 12f7964f9)
+- Theme-CLI config scanning now correctly decodes `\uXXXX`, `\u{...}`, and `\xXX` escapes (2e58e3dc0)
+- The default title-rule border is reset only where a theme pack owns its own title styling, keeping custom pack titles from double-bordering (9043b9439)
+- Doc-history anchors now point at the actual generated heading slugs (9e3e62655)
+
+### Other Changes
+
+- Re-baselined the route-injection parity test's normalized-HTML sha256 snapshots twice this cycle, attributing every changed byte to its originating merged PR (5e46831d4, 4fd642c3b)
+- Bumped the `@takazudo/zfb` family to `0.1.0-next.90`
+- Expanded English and Japanese documentation for the logo/eject-logo feature, the Theme Gallery (31 packs), and the hover-accent interactive color rule
+
+## [4.3.0] - 2026-07-19
+
+### Features
+
+- Syntax highlighting is now driven by semantic design tokens across document code fences and `HtmlPreview`. Browser previews lazily load the public zfb WASM highlighter, existing color schemes inherit compatible semantic aliases, and project-owned Shiki dependencies and theme-name configuration are no longer required (178f23321)
+- Home pages can opt into the wide content layout with `home.wide`; the setting applies consistently to package-owned root and localized home routes (d068ac346)
+- Doc history can exclude selected pages through configuration, with matching behavior threaded through rendering, history generation, package settings, and generated-project configuration (e18c2e528)
+- The Hearth theme now provides complete admonition icon coverage (736c6c5e1)
+
+### Bug Fixes
+
+- Frontmatter status pills now meet WCAG contrast requirements across every shipped theme pack, light/dark mode, and semantic role while preserving their tinted backgrounds (2986d87c4)
+- The showcase now consumes the package-owned theme contract correctly and emits literal semantic z-index utilities (2ca79ca6b, 8fb517df6)
+- Theme-pack font validation is stricter, and the generated setup skill resolves main-worktree paths reliably (f9dd94d53, 4c2a508bb)
+
+### Other Changes
+
+- Expanded English and Japanese documentation for syntax-token migration, wide home layouts, doc-history exclusions, theme development, and network exposure caveats
+- Added browser-level highlighting coverage, exact pill contrast checks, settings parity tests, and compatibility-contract guards
+
 ## [4.2.1] - 2026-07-19
 
 ### Other Changes

package/README.md

@@ -18,12 +18,12 @@ This package provides the missing-by-design framework concerns:
 - **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
+## Optional peer dependency: `@takazudo/zfb-md-wasm`
 
-`./html-preview-wrapper`'s `<HighlightedCode>` lazily `import("shiki")`s at runtime for client-side syntax highlighting. `shiki` is declared as an **optional peerDependency** — install it in your project if you use that subpath:
+`./html-preview-wrapper`'s `<HighlightedCode>` lazily imports the package root and calls `highlightCode()` for client-side semantic syntax highlighting. `@takazudo/zfb-md-wasm` is declared as an **optional peerDependency** — install the same prerelease version as the rest of your zfb packages if you use that subpath:
 
 ```sh
-pnpm add shiki
+pnpm add @takazudo/zfb-md-wasm
 ```
 
 Projects scaffolded by `create-zudo-doc` already include it. If you never render `<HtmlPreview>` / `<HighlightedCode>`, you can omit it.

package/bin/zudo-doc.mjs

@@ -3,21 +3,28 @@
 //
 // Package bin: `zudo-doc eject <component>` swizzle CLI, plus
 // `zudo-doc theme list|apply <slug>` (issue #2824; ADR
-// docs/adr/theme-packs.md).
+// docs/adr/theme-packs.md), plus `zudo-doc eject logo` (issue #3050; epic
+// #3047).
 //
-// Self-contained ESM — runs on plain `node` with NO `tsx` requirement. Both
-// the eject and theme-cli logic are imported from the package's COMPILED
-// `../dist/eject/index.js` / `../dist/theme-cli/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/theme-cli only copy files / rewrite text — no TS eval
-// needed — so both work in a default generated project that never installed
-// tsx (#2367).
+// Self-contained ESM — runs on plain `node` with NO `tsx` requirement. The
+// eject, theme-cli, and eject-logo logic are imported from the package's
+// COMPILED `../dist/eject/index.js` / `../dist/theme-cli/index.js` /
+// `../dist/eject-logo/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/theme-cli/eject-logo only copy files / rewrite text — no TS
+// eval needed — so all three work in a default generated project that never
+// installed tsx (#2367).
+//
+// `eject logo` is special-cased below, BEFORE the EJECTABLE lookup — it is
+// NOT a source-copy swizzle (EJECTABLE's contract), it renders a fresh SVG
+// and rewrites a config field, so it does not belong in that map.
 //
 // Usage:
 //   zudo-doc eject <component>   # eject a component's TS source into the project
+//   zudo-doc eject logo          # render public/img/logo.svg + rewrite the logo field
 //   zudo-doc theme list          # list installed theme packs + the active one
 //   zudo-doc theme apply <slug>  # rewrite zfb.config.ts's themePack field
 //   zudo-doc --help              # show help
@@ -25,10 +32,12 @@
 import minimist from "minimist";
 import pc from "picocolors";
 import { eject, EJECTABLE } from "../dist/eject/index.js";
+import { ejectLogo } from "../dist/eject-logo/index.js";
 import { applyThemePack, formatThemeList, listThemePacks } from "../dist/theme-cli/index.js";
 
 const argv = minimist(process.argv.slice(2), {
-  boolean: ["help"],
+  string: ["seed"],
+  boolean: ["help", "force"],
   alias: { h: "help" },
 });
 
@@ -40,6 +49,9 @@ ${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.
+  eject logo [--seed <name>] [--force]
+                       Render public/img/logo.svg and rewrite zfb.config.ts's
+                       logo field to point at it.
   theme list           List the installed theme packs and which one is active.
   theme apply <slug>   Rewrite zfb.config.ts's themePack field to <slug>.
 
@@ -47,7 +59,9 @@ ${pc.bold("Ejectable components:")}
   ${validNames}
 
 ${pc.bold("Options:")}
-  -h, --help   Show this help message
+  -h, --help     Show this help message
+  --seed <name>  (eject logo) Seed for the generated logo, overriding siteName
+  --force        (eject logo) Overwrite an existing public/img/logo.svg
 
 ${pc.bold("Examples:")}
   ${pc.dim("# Eject the header component")}
@@ -56,6 +70,9 @@ ${pc.bold("Examples:")}
   ${pc.dim("# Eject the theme-toggle component")}
   zudo-doc eject theme-toggle
 
+  ${pc.dim("# Eject the logo as a standalone SVG")}
+  zudo-doc eject logo
+
   ${pc.dim("# List installed theme packs")}
   zudo-doc theme list
 
@@ -77,6 +94,29 @@ async function runEject(componentArg) {
   await eject(componentArg, { cwd: process.cwd() });
 }
 
+async function runEjectLogo() {
+  const hasSeedFlag = Object.prototype.hasOwnProperty.call(argv, "seed");
+  if (hasSeedFlag && argv.seed.length === 0) {
+    console.error(
+      pc.red(`Missing value for --seed.`) +
+        `\nUsage: zudo-doc eject logo [--seed <name>] [--force]`,
+    );
+    process.exit(1);
+  }
+
+  const result = await ejectLogo({
+    cwd: process.cwd(),
+    seed: hasSeedFlag ? argv.seed : undefined,
+    force: argv.force,
+  });
+
+  if (!result.ok) {
+    console.error(pc.red(result.message));
+    process.exit(1);
+  }
+  console.log(pc.green(result.message));
+}
+
 async function runThemeList() {
   const result = await listThemePacks({ cwd: process.cwd() });
   console.log(formatThemeList(result));
@@ -120,6 +160,7 @@ async function main() {
 
   const [subcommand, ...rest] = argv._;
 
+  if (subcommand === "eject" && rest[0] === "logo") return runEjectLogo();
   if (subcommand === "eject") return runEject(rest[0]);
   if (subcommand === "theme") return runTheme(rest);
 

package/dist/auto-logo/index.d.ts

@@ -0,0 +1,18 @@
+/** @jsxRuntime automatic */
+/** @jsxImportSource preact */
+import type { JSX } from "preact";
+import { pickGlyphName } from "./shapes.js";
+export { pickGlyphName };
+export { renderAutoLogoStandaloneSvg } from "./standalone.js";
+/** Props for {@link AutoLogo}. */
+export interface AutoLogoProps {
+    /** Deterministic seed — pass `settings.siteName`. */
+    seed: string;
+    /** Class list for the root `<svg>` (sizing/color, e.g. `w-[320px] text-fg`). */
+    class?: string;
+}
+/**
+ * Generated "decorated plate" logo — plate + frame + corner rays + disc +
+ * seeded line-art glyph. Server-rendered, deterministic per seed.
+ */
+export declare function AutoLogo({ seed, class: className }: AutoLogoProps): JSX.Element;

package/dist/auto-logo/index.js

@@ -0,0 +1,33 @@
+import { jsx, jsxs } from "preact/jsx-runtime";
+import { h } from "preact";
+import {
+  W,
+  H,
+  PLATE_SHAPE,
+  INNER_FRAME_SHAPE,
+  RAY_SHAPES,
+  DISC_SHAPE,
+  GLYPH_SHAPES,
+  GLYPH_TRANSFORM,
+  pickGlyphName
+} from "./shapes.js";
+import { renderAutoLogoStandaloneSvg } from "./standalone.js";
+function renderShape({ el, attrs }, key) {
+  return h(el, key !== void 0 ? { ...attrs, key } : attrs);
+}
+function AutoLogo({ seed, class: className }) {
+  const glyphName = pickGlyphName(seed);
+  const glyphShapes = GLYPH_SHAPES[glyphName];
+  return /* @__PURE__ */ jsxs("svg", { viewBox: `0 0 ${W} ${H}`, fill: "currentColor", class: className, "data-auto-logo": glyphName, "aria-hidden": "true", children: [
+    renderShape(PLATE_SHAPE),
+    renderShape(INNER_FRAME_SHAPE),
+    RAY_SHAPES.map((ray, i) => renderShape(ray, i)),
+    renderShape(DISC_SHAPE),
+    /* @__PURE__ */ jsx("g", { transform: GLYPH_TRANSFORM, children: glyphShapes.map((shape, i) => renderShape(shape, i)) })
+  ] });
+}
+export {
+  AutoLogo,
+  pickGlyphName,
+  renderAutoLogoStandaloneSvg
+};

package/dist/auto-logo/shapes.d.ts

@@ -0,0 +1,32 @@
+/** One SVG primitive as plain data: element name + its attributes. */
+export interface ShapePrimitive {
+    el: "path" | "line" | "circle" | "rect";
+    attrs: Record<string, string | number>;
+}
+export declare const W = 200;
+export declare const H = 105;
+export declare const INSET = 6;
+export declare const CX: number;
+export declare const CY: number;
+export declare const DISC_R = 34;
+/** Full-bleed plate rect. */
+export declare const PLATE_SHAPE: ShapePrimitive;
+/** Thin inner frame stroke, knocked out against the page background. */
+export declare const INNER_FRAME_SHAPE: ShapePrimitive;
+/** 4 diagonal corner rays, each stopping just short of the disc edge. */
+export declare const RAY_SHAPES: ShapePrimitive[];
+/** Centered disc, knocked out against the page background. */
+export declare const DISC_SHAPE: ShapePrimitive;
+/** Scale + translate that centers a glyph's 100×100 box onto the disc
+ *  (slight overscan reads better). */
+export declare const GLYPH_SCALE: number;
+export declare const GLYPH_TRANSFORM = "translate(64.3, 16.799999999999997) scale(0.7140000000000001)";
+/** Line-art glyphs drawn in a 100×100 box centered at (50,50), as plain
+ *  shape data. The original JSX wrapped each glyph (and some repeated
+ *  groups) in a `<g>` that carried no attributes of its own — only React
+ *  `key`s for list rendering — so flattening into a single primitive array
+ *  per glyph loses no visual information. */
+export declare const GLYPH_SHAPES: Record<string, ShapePrimitive[]>;
+export declare const GLYPH_NAMES: string[];
+/** Deterministic glyph name for a seed. */
+export declare function pickGlyphName(seed: string): string;

package/dist/auto-logo/shapes.js

@@ -0,0 +1,183 @@
+const W = 200;
+const H = 105;
+const INSET = 6;
+const CX = W / 2;
+const CY = H / 2;
+const DISC_R = 34;
+const KO = "var(--color-bg)";
+const PLATE_SHAPE = {
+  el: "rect",
+  attrs: { x: 0, y: 0, width: W, height: H, fill: "currentColor" }
+};
+const INNER_FRAME_SHAPE = {
+  el: "rect",
+  attrs: {
+    x: INSET,
+    y: INSET,
+    width: W - INSET * 2,
+    height: H - INSET * 2,
+    fill: "none",
+    stroke: KO,
+    "stroke-width": 1.6
+  }
+};
+const RAY_SHAPES = [
+  [INSET, INSET],
+  [W - INSET, INSET],
+  [INSET, H - INSET],
+  [W - INSET, H - INSET]
+].map(([x, y]) => {
+  const dx = CX - x;
+  const dy = CY - y;
+  const len = Math.hypot(dx, dy);
+  const stop = (len - DISC_R - 7) / len;
+  return {
+    el: "line",
+    attrs: { x1: x, y1: y, x2: x + dx * stop, y2: y + dy * stop, stroke: KO, "stroke-width": 1.4 }
+  };
+});
+const DISC_SHAPE = {
+  el: "circle",
+  attrs: { cx: CX, cy: CY, r: DISC_R, fill: KO }
+};
+const GLYPH_SCALE = DISC_R * 2 / 100 * 1.05;
+const GLYPH_TRANSFORM = `translate(${CX - 50 * GLYPH_SCALE}, ${CY - 50 * GLYPH_SCALE}) scale(${GLYPH_SCALE})`;
+const GLYPH_SHAPES = {
+  book: [
+    {
+      el: "path",
+      attrs: {
+        d: "M50 30 C42 24, 30 23, 22 26 L22 68 C30 65, 42 66, 50 72 C58 66, 70 65, 78 68 L78 26 C70 23, 58 24, 50 30 Z",
+        fill: "none",
+        stroke: "currentColor",
+        "stroke-width": 6,
+        "stroke-linejoin": "round"
+      }
+    },
+    { el: "line", attrs: { x1: 50, y1: 30, x2: 50, y2: 72, stroke: "currentColor", "stroke-width": 5 } },
+    ...[0, 1, 2].flatMap(
+      (i) => [
+        {
+          el: "line",
+          attrs: {
+            x1: 29,
+            y1: 38 + i * 10,
+            x2: 43,
+            y2: 40 + i * 10,
+            stroke: "currentColor",
+            "stroke-width": 4,
+            "stroke-linecap": "round"
+          }
+        },
+        {
+          el: "line",
+          attrs: {
+            x1: 57,
+            y1: 40 + i * 10,
+            x2: 71,
+            y2: 38 + i * 10,
+            stroke: "currentColor",
+            "stroke-width": 4,
+            "stroke-linecap": "round"
+          }
+        }
+      ]
+    )
+  ],
+  doc: [
+    {
+      el: "path",
+      attrs: { d: "M32 22 L60 22 L70 32 L70 78 L32 78 Z", fill: "none", stroke: "currentColor", "stroke-width": 6, "stroke-linejoin": "round" }
+    },
+    {
+      el: "path",
+      attrs: { d: "M60 22 L60 32 L70 32", fill: "none", stroke: "currentColor", "stroke-width": 5, "stroke-linejoin": "round" }
+    },
+    ...[0, 1, 2].map(
+      (i) => ({
+        el: "line",
+        attrs: { x1: 40, y1: 44 + i * 11, x2: 62, y2: 44 + i * 11, stroke: "currentColor", "stroke-width": 4, "stroke-linecap": "round" }
+      })
+    )
+  ],
+  bookmark: [
+    {
+      el: "path",
+      attrs: { d: "M34 22 L66 22 L66 78 L50 64 L34 78 Z", fill: "none", stroke: "currentColor", "stroke-width": 6, "stroke-linejoin": "round" }
+    },
+    { el: "line", attrs: { x1: 42, y1: 36, x2: 58, y2: 36, stroke: "currentColor", "stroke-width": 4, "stroke-linecap": "round" } }
+  ],
+  compass: [
+    { el: "circle", attrs: { cx: 50, cy: 50, r: 26, fill: "none", stroke: "currentColor", "stroke-width": 6 } },
+    { el: "path", attrs: { d: "M60 40 L54 56 L40 60 L46 44 Z", fill: "currentColor" } }
+  ],
+  terminal: [
+    { el: "rect", attrs: { x: 24, y: 30, width: 52, height: 40, rx: 5, fill: "none", stroke: "currentColor", "stroke-width": 6 } },
+    {
+      el: "path",
+      attrs: { d: "M33 42 L41 50 L33 58", fill: "none", stroke: "currentColor", "stroke-width": 5, "stroke-linecap": "round", "stroke-linejoin": "round" }
+    },
+    { el: "line", attrs: { x1: 47, y1: 58, x2: 60, y2: 58, stroke: "currentColor", "stroke-width": 5, "stroke-linecap": "round" } }
+  ],
+  bulb: [
+    {
+      el: "path",
+      attrs: {
+        d: "M50 22 C37 22, 30 32, 30 41 C30 49, 35 53, 39 58 L39 64 L61 64 L61 58 C65 53, 70 49, 70 41 C70 32, 63 22, 50 22 Z",
+        fill: "none",
+        stroke: "currentColor",
+        "stroke-width": 6,
+        "stroke-linejoin": "round"
+      }
+    },
+    { el: "line", attrs: { x1: 42, y1: 71, x2: 58, y2: 71, stroke: "currentColor", "stroke-width": 5, "stroke-linecap": "round" } },
+    { el: "line", attrs: { x1: 45, y1: 78, x2: 55, y2: 78, stroke: "currentColor", "stroke-width": 5, "stroke-linecap": "round" } }
+  ],
+  chat: [
+    {
+      el: "path",
+      attrs: { d: "M26 28 L74 28 L74 62 L48 62 L36 74 L36 62 L26 62 Z", fill: "none", stroke: "currentColor", "stroke-width": 6, "stroke-linejoin": "round" }
+    },
+    ...[0, 1, 2].map((i) => ({ el: "circle", attrs: { cx: 38 + i * 12, cy: 45, r: 3, fill: "currentColor" } }))
+  ],
+  layers: [
+    { el: "path", attrs: { d: "M50 22 L78 36 L50 50 L22 36 Z", fill: "none", stroke: "currentColor", "stroke-width": 6, "stroke-linejoin": "round" } },
+    {
+      el: "path",
+      attrs: { d: "M25 47 L50 60 L75 47", fill: "none", stroke: "currentColor", "stroke-width": 6, "stroke-linecap": "round", "stroke-linejoin": "round" }
+    },
+    {
+      el: "path",
+      attrs: { d: "M25 58 L50 71 L75 58", fill: "none", stroke: "currentColor", "stroke-width": 6, "stroke-linecap": "round", "stroke-linejoin": "round" }
+    }
+  ]
+};
+const GLYPH_NAMES = Object.keys(GLYPH_SHAPES);
+function hashString(str) {
+  let h = 2166136261 >>> 0;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+function pickGlyphName(seed) {
+  return GLYPH_NAMES[hashString(seed) % GLYPH_NAMES.length];
+}
+export {
+  CX,
+  CY,
+  DISC_R,
+  DISC_SHAPE,
+  GLYPH_NAMES,
+  GLYPH_SCALE,
+  GLYPH_SHAPES,
+  GLYPH_TRANSFORM,
+  H,
+  INNER_FRAME_SHAPE,
+  INSET,
+  PLATE_SHAPE,
+  RAY_SHAPES,
+  W,
+  pickGlyphName
+};

package/dist/auto-logo/standalone.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Render the deterministic AutoLogo design as a standalone, mask-friendly
+ * SVG string. Same seed always produces byte-identical output; glyph
+ * selection reuses {@link pickGlyphName} so an ejected file shows the same
+ * glyph as `logo: "auto"` mode.
+ */
+export declare function renderAutoLogoStandaloneSvg(seed: string): string;

package/dist/auto-logo/standalone.js

@@ -0,0 +1,35 @@
+import {
+  W,
+  H,
+  PLATE_SHAPE,
+  INNER_FRAME_SHAPE,
+  RAY_SHAPES,
+  DISC_SHAPE,
+  GLYPH_SHAPES,
+  GLYPH_TRANSFORM,
+  pickGlyphName
+} from "./shapes.js";
+const MASK_ID = "auto-logo-mask";
+const MASK_COLORS = {
+  currentColor: "#fff",
+  "var(--color-bg)": "#000"
+};
+function escapeAttr(value) {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+function renderShape(shape) {
+  const attrs = Object.entries(shape.attrs).map(([key, value]) => {
+    const resolved = typeof value === "string" && value in MASK_COLORS ? MASK_COLORS[value] : value;
+    return `${key}="${escapeAttr(String(resolved))}"`;
+  }).join(" ");
+  return `<${shape.el} ${attrs} />`;
+}
+function renderAutoLogoStandaloneSvg(seed) {
+  const glyphName = pickGlyphName(seed);
+  const glyphShapes = GLYPH_SHAPES[glyphName];
+  const maskContent = renderShape(PLATE_SHAPE) + renderShape(INNER_FRAME_SHAPE) + RAY_SHAPES.map(renderShape).join("") + renderShape(DISC_SHAPE) + `<g transform="${escapeAttr(GLYPH_TRANSFORM)}">${glyphShapes.map(renderShape).join("")}</g>`;
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" data-auto-logo="${glyphName}"><mask id="${MASK_ID}" mask-type="luminance" maskUnits="userSpaceOnUse" maskContentUnits="userSpaceOnUse" x="0" y="0" width="${W}" height="${H}">` + maskContent + `</mask><rect x="0" y="0" width="${W}" height="${H}" fill="#000" mask="url(#${MASK_ID})" /></svg>`;
+}
+export {
+  renderAutoLogoStandaloneSvg
+};

package/dist/color-scheme-utils.d.ts

@@ -74,9 +74,10 @@ export interface ModeMap {
     selectionBg: RampRef;
     selectionFg: RampRef;
     semantic: Record<SemanticKey, RampRef>;
-    /** Syntax-specific overrides. The map is required, while omitted roles
-     *  inherit the aliases in `SYNTAX_SEMANTIC_ALIASES`. */
-    syntax: Partial<Record<SyntaxSemanticKey, RampRef>>;
+    /** Optional syntax-specific overrides. An absent map and omitted roles
+     *  inherit the aliases in `SYNTAX_SEMANTIC_ALIASES`, preserving schemes
+     *  authored before syntax tokens existed. */
+    syntax?: Partial<Record<SyntaxSemanticKey, RampRef>>;
 }
 /** A complete color scheme — shared Tier-1 ramps + per-mode Tier-2 wiring. */
 export interface ColorScheme {

package/dist/color-scheme-utils.js

@@ -207,7 +207,7 @@ function resolveSyntaxPalette(scheme) {
   );
   const emergencyColor = tryResolveRampRef(emergencyRef, ramps) ?? "currentColor";
   for (const key of SYNTAX_SEMANTIC_KEYS) {
-    const explicitRef = map.syntax[key];
+    const explicitRef = map.syntax?.[key];
     const explicitColor = tryResolveRampRef(explicitRef, ramps);
     const inheritedRef = map.semantic[SYNTAX_SEMANTIC_ALIASES[key]];
     const inheritedColor = tryResolveRampRef(inheritedRef, ramps);

package/dist/config/component-tokens.js

@@ -343,7 +343,7 @@ const COMPONENT_TOKENS = [
     component: "sidebar",
     surface: "chrome",
     category: "typography",
-    description: "Font family of the navigation sidebar \u2014 covers BOTH the desktop `#desktop-sidebar` rail and the mobile drawer, so one override styles both viewports and neither drifts onto a different face. Defaults to the `--zdc-chrome-font` seam (a no-op until redefined)."
+    description: "Font family of the navigation sidebar \u2014 covers BOTH the desktop `#desktop-sidebar` rail and the mobile drawer, so one override styles both viewports and neither drifts onto a different face. Defaults to the `--zdc-chrome-font` seam (a no-op until redefined). Verify granular MOBILE chrome-font overrides with `zfb build`/preview, not `pnpm dev`: the current zfb dev server strips island-root `data-*` attributes, so the mobile selector silently does not match."
   },
   {
     cssVar: "--zdc-toc-font",
@@ -353,7 +353,7 @@ const COMPONENT_TOKENS = [
     component: "toc",
     surface: "chrome",
     category: "typography",
-    description: "Font family of the table of contents \u2014 covers BOTH the desktop right rail and the mobile collapsible TOC, so one override styles both viewports. Defaults to the `--zdc-chrome-font` seam (a no-op until redefined), which also keeps the mobile TOC on the chrome font rather than the prose font of the `.zd-content` it renders inside."
+    description: "Font family of the table of contents \u2014 covers BOTH the desktop right rail and the mobile collapsible TOC, so one override styles both viewports. Defaults to the `--zdc-chrome-font` seam (a no-op until redefined), which also keeps the mobile TOC on the chrome font rather than the prose font of the `.zd-content` it renders inside. Verify granular MOBILE chrome-font overrides with `zfb build`/preview, not `pnpm dev`: the current zfb dev server strips island-root `data-*` attributes, so the mobile selector silently does not match."
   }
 ];
 export {

package/dist/config.d.ts

@@ -62,7 +62,7 @@ import type { ZfbConfig, BundleConfig } from "@takazudo/zfb/config";
 import type { ZodType } from "zod";
 import type { DirectiveVocabulary, PresetTranslations, PresetTagVocabularyEntry } from "./preset.js";
 import type { ColorScheme } from "./color-scheme-utils.js";
-import type { Settings, ColorModeConfig, LocaleConfig, MetaTagsConfig, SiteHeadConfig, TagPlacement, TagGovernanceMode, VersionConfig, FooterConfig, HeaderNavItem, HeaderRightItem, FrontmatterPreviewConfig, BodyFootUtilAreaConfig, HtmlPreviewConfig } from "./settings.js";
+import type { Settings, ColorModeConfig, LocaleConfig, MetaTagsConfig, SiteHeadConfig, TagPlacement, TagGovernanceMode, VersionConfig, FooterConfig, HeaderNavItem, HeaderRightItem, HomeConfig, FrontmatterPreviewConfig, BodyFootUtilAreaConfig, HtmlPreviewConfig } from "./settings.js";
 /** The `settings.claudeResources` block (or `false` when disabled). */
 type ClaudeResourcesConfig = {
     claudeDir: string;
@@ -92,6 +92,14 @@ export interface ZudoDocConfig {
      * @default ""
      */
     siteDescription?: string;
+    /**
+     * Home-hero logo. `"auto"` renders a generated deterministic SVG seeded by
+     * `siteName` (no asset needed); a path string (e.g. `"/img/logo.svg"`)
+     * renders that asset as a theme-adaptive CSS mask; `false` hides the logo
+     * block entirely.
+     * @default "auto"
+     */
+    logo?: string | false;
     /**
      * Public URL sub-path prefix mounted in front of every absolute asset URL
      * (e.g. `"/pj/my-site/"`). `"/"` = root-mounted.
@@ -103,6 +111,12 @@ export interface ZudoDocConfig {
      * @default false
      */
     trailingSlash?: boolean;
+    /**
+     * Package-owned home-page layout. Set `wide: true` to let the category grid
+     * fill most of the viewport on both `/` and locale home routes.
+     * @default { wide: false }
+     */
+    home?: HomeConfig;
     /**
      * Minify production HTML output from `zfb build`.
      * @default true
@@ -300,6 +314,14 @@ export interface ZudoDocConfig {
      * @default false
      */
     docHistory?: boolean;
+    /**
+     * Glob patterns matched against the doc slug (path minus extension, `/index`
+     * stripped, root = `index`) that exclude matching pages from git-history
+     * capture entirely. Excluded pages have no dropdown JSON or
+     * Created/Updated/Author block; matching is locale/version-independent.
+     * @default []
+     */
+    docHistoryExclude?: string[];
     /**
      * Body-foot utility area (doc-history / view-source), or `false` to disable.
      * @default false

package/dist/config.js

@@ -13,8 +13,10 @@ const DEFAULT_SETTINGS = {
   },
   siteName: "Docs",
   siteDescription: "",
+  logo: "auto",
   base: "/",
   trailingSlash: false,
+  home: { wide: false },
   minifyHtml: true,
   docsDir: "src/content/docs",
   defaultLocale: "en",
@@ -58,6 +60,7 @@ const DEFAULT_SETTINGS = {
   dynamicPageTransition: false,
   frontmatterPreview: false,
   docHistory: false,
+  docHistoryExclude: [],
   bodyFootUtilArea: false,
   htmlPreview: void 0,
   versions: false,

package/dist/content.css

@@ -144,12 +144,13 @@
 /* ── Links ── */
 
 /* Link reset inside site-nav (component can't detect ancestor context) */
-.zd-content [data-site-nav] a {
+/* Reset must stay specificity-0 (:where()) so island utility classes like hover:text-accent control color */
+:where(.zd-content [data-site-nav] a) {
   color: inherit;
   text-decoration: none;
 }
-.zd-content [data-site-nav] a:hover,
-.zd-content [data-site-nav] a:focus-visible {
+:where(.zd-content [data-site-nav] a):hover,
+:where(.zd-content [data-site-nav] a):focus-visible {
   text-decoration: underline;
 }
 

package/dist/doc-content-header/index.js

@@ -19,7 +19,7 @@ function createDocContentHeader(ctx) {
     version
   }) {
     return /* @__PURE__ */ jsxs(Fragment, { children: [
-      /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold mb-vsp-xs", children: entry.data.title }),
+      /* @__PURE__ */ jsx("h1", { class: "text-heading font-bold border-b border-fg pb-vsp-xs mb-vsp-xs", children: entry.data.title }),
       docContentHeaderExtras?.({
         entry,
         slug,

package/dist/doc-history/index.js

@@ -339,7 +339,7 @@ function DocHistory({ slug, locale, basePath = "/" }) {
       {
         type: "button",
         onClick: handleOpen,
-        className: "doc-history-trigger flex items-center gap-hsp-xs px-hsp-md py-vsp-xs rounded-lg bg-surface border border-muted text-muted hover:text-fg hover:border-fg transition-colors",
+        className: "doc-history-trigger flex items-center gap-hsp-xs px-hsp-md py-vsp-xs rounded-lg bg-surface border border-muted text-muted hover:text-accent hover:border-accent focus-visible:text-accent focus-visible:border-accent transition-colors",
         "aria-label": "View document history",
         children: [
           /* @__PURE__ */ jsx(History, { className: "h-icon-md w-icon-md" }),