@takazudo/zudo-doc 3.3.0 → 4.1.0

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

@@ -55,6 +55,16 @@ export interface Ramps {
 export type SemanticKey = "surface" | "muted" | "accent" | "accentHover" | "codeBg" | "codeFg" | "success" | "danger" | "warning" | "info" | "mermaidNodeBg" | "mermaidText" | "mermaidLine" | "mermaidLabelBg" | "mermaidNoteBg" | "chatUserBg" | "chatUserText" | "chatAssistantBg" | "chatAssistantText" | "imageOverlayBg" | "imageOverlayFg" | "matchedKeywordBg" | "matchedKeywordFg";
 /** Canonical order of the 23 semantic roles — used for `--zd-*` emit. */
 export declare const SEMANTIC_KEYS: readonly SemanticKey[];
+/**
+ * Compact Tier-2 syntax vocabulary. zfb's fixed 18-role renderer taxonomy is
+ * intentionally collapsed onto these nine public design decisions; see
+ * `ZFB_HIGHLIGHT_ROLE_TO_ZUDO_TOKEN` below.
+ */
+export declare const SYNTAX_SEMANTIC_KEYS: readonly ["syntaxComment", "syntaxString", "syntaxNumber", "syntaxKeyword", "syntaxCallable", "syntaxType", "syntaxName", "syntaxInserted", "syntaxDeleted"];
+export type SyntaxSemanticKey = (typeof SYNTAX_SEMANTIC_KEYS)[number];
+/** Existing semantic role inherited when a syntax role has no explicit map. */
+export declare const SYNTAX_SEMANTIC_ALIASES: Readonly<Record<SyntaxSemanticKey, SemanticKey>>;
+export declare const SYNTAX_CSS_NAMES: Readonly<Record<SyntaxSemanticKey, string>>;
 /** The per-mode wiring: each UI role points at a ramp stop (or literal OKLCH)
  *  via a `RampRef`. Two `ColorScheme`s (light + dark) share `ramps` but carry
  *  their own `ModeMap`. */
@@ -64,6 +74,9 @@ 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>>;
 }
 /** A complete color scheme — shared Tier-1 ramps + per-mode Tier-2 wiring. */
 export interface ColorScheme {
@@ -75,6 +88,45 @@ export interface ColorScheme {
  *  where a mode needs a different stop (or a per-mode AA-tuned literal). */
 export declare const SEMANTIC_RAMP_DEFAULTS: Record<SemanticKey, RampRef>;
 export declare const SEMANTIC_CSS_NAMES: Record<SemanticKey, string>;
+/**
+ * Canonical renderer-role contraction shared by native zfb fenced code and
+ * `@takazudo/zfb-md-wasm` HTML Preview output. Values name zudo-doc semantic
+ * tokens, never palette stops, so renderer/component CSS stays downstream of
+ * the theme tier.
+ */
+export declare const ZFB_HIGHLIGHT_ROLE_TO_ZUDO_TOKEN: {
+    readonly foreground: "codeFg";
+    readonly background: "codeBg";
+    readonly escape: "syntaxString";
+    readonly operator: "codeFg";
+    readonly comment: "syntaxComment";
+    readonly string: "syntaxString";
+    readonly number: "syntaxNumber";
+    readonly constant: "syntaxNumber";
+    readonly keyword: "syntaxKeyword";
+    readonly function: "syntaxCallable";
+    readonly type: "syntaxType";
+    readonly namespace: "syntaxType";
+    readonly property: "syntaxName";
+    readonly variable: "syntaxName";
+    readonly tag: "syntaxName";
+    readonly attribute: "syntaxName";
+    readonly punctuation: "codeFg";
+    readonly inserted: "syntaxInserted";
+    readonly deleted: "syntaxDeleted";
+    readonly heading: "syntaxKeyword";
+};
+export type ZfbHighlightRole = keyof typeof ZFB_HIGHLIGHT_ROLE_TO_ZUDO_TOKEN;
+/** Percentage of the inserted/deleted foreground mixed into `codeBg`. */
+export declare const SYNTAX_DIFF_BACKGROUND_MIX_PERCENT = 15;
+/**
+ * Component-token values for zfb's inserted/deleted background variables.
+ * They deliberately do not create public `--zd-syntax-*-bg` roles.
+ */
+export declare const SYNTAX_DIFF_BACKGROUND_CSS: {
+    readonly inserted: `color-mix(in srgb, var(${string}) 15%, var(${string}))`;
+    readonly deleted: `color-mix(in srgb, var(${string}) 15%, var(${string}))`;
+};
 /**
  * Resolve a `RampRef` to a concrete color string against the given `ramps`.
  *   - `{ base: n }`   → `ramps.base[n]`
@@ -90,6 +142,21 @@ export declare function resolveRampRef(ref: RampRef, ramps: Ramps): string;
 /** Resolve every semantic role to a concrete color string via the scheme's
  *  per-mode `map.semantic` wiring. Returns all 23 keys. */
 export declare function resolveSemanticColors(scheme: ColorScheme): Record<SemanticKey, string>;
+export interface ResolvedSyntaxPalette {
+    /** Effective refs retain ramp identity for design-token-panel rows. */
+    refs: Record<SyntaxSemanticKey, RampRef>;
+    /** Concrete colors used by generated CSS and contrast validation. */
+    colors: Record<SyntaxSemanticKey, string>;
+}
+/**
+ * Canonical complete syntax resolver. Explicit partial overrides win; missing
+ * or invalid overrides inherit the scheme's semantic alias. A defensive
+ * `codeFg` / `fg` / first-ramp chain keeps runtime-authored data non-throwing
+ * even when it bypasses TypeScript or serde validation.
+ */
+export declare function resolveSyntaxPalette(scheme: ColorScheme): ResolvedSyntaxPalette;
+/** Convenience view of the canonical syntax palette's concrete colors. */
+export declare function resolveSyntaxColors(scheme: ColorScheme): Record<SyntaxSemanticKey, string>;
 export interface TierItem {
     /** Stable id used as the Record key in persisted state (e.g. `surface`). */
     id: string;
@@ -120,10 +187,10 @@ export interface TierItem {
  */
 export declare function rampRefToPanelDefault(ref: RampRef): string;
 /**
- * Build the 27-row mode-scoped semantic tier's `items` for the design-token
+ * Build the 36-row mode-scoped semantic tier's `items` for the design-token
  * panel, from a single (already mode-resolved) `ColorScheme`: 4 base roles
  * (`bg`, `fg`, `selection-bg`, `selection-fg`) followed by the 23
- * `SEMANTIC_KEYS` rows, in that order. Every row's `default` is
+ * `SEMANTIC_KEYS` rows and 9 syntax rows, in that order. Every row's `default` is
  * `rampRefToPanelDefault` of the scheme's `map` entry for that role — never a
  * resolved literal color — so the panel's grouped ramp dropdown can decode it
  * back to a ramp reference (the no-snapping guarantee: a scheme with no
@@ -134,7 +201,7 @@ export declare function buildSemanticTierItems(scheme: ColorScheme): TierItem[];
 /** Which tiers a `schemeToCssPairs` call emits:
  *   - `"all"` (default) — base roles + `--palette-*` + `--zd-*` semantic
  *   - `"palette"`       — only the bare Tier-1 `--palette-*` pairs
- *   - `"roles"`         — base roles + the 23 `--zd-*` semantic pairs
+ *   - `"roles"`         — base roles + the 23 UI and 9 syntax semantic pairs
  *
  * The split lets `generateLightDarkCssProperties` emit the shared `--palette-*`
  * once (bare) while wrapping the per-mode `--zd-*` roles in `light-dark(…)`.
@@ -150,6 +217,7 @@ export type CssEmitScope = "all" | "palette" | "roles";
  *   - Tier-1 ramps: `--palette-base-0..4`, `--palette-accent-0..2`,
  *     `--palette-state-{danger,success,warning,info}`
  *   - the 23 Tier-2 `--zd-{role}` semantic tokens
+ *   - the 9 Tier-2 `--zd-syntax-*` semantic tokens
  *
  * It intentionally does NOT emit the retired `--zd-0..15` slots or `--zd-cursor`.
  */

package/dist/color-scheme-utils.js

@@ -24,6 +24,39 @@ const SEMANTIC_KEYS = [
   "matchedKeywordBg",
   "matchedKeywordFg"
 ];
+const SYNTAX_SEMANTIC_KEYS = [
+  "syntaxComment",
+  "syntaxString",
+  "syntaxNumber",
+  "syntaxKeyword",
+  "syntaxCallable",
+  "syntaxType",
+  "syntaxName",
+  "syntaxInserted",
+  "syntaxDeleted"
+];
+const SYNTAX_SEMANTIC_ALIASES = {
+  syntaxComment: "muted",
+  syntaxString: "success",
+  syntaxNumber: "warning",
+  syntaxKeyword: "accent",
+  syntaxCallable: "info",
+  syntaxType: "warning",
+  syntaxName: "codeFg",
+  syntaxInserted: "success",
+  syntaxDeleted: "danger"
+};
+const SYNTAX_CSS_NAMES = {
+  syntaxComment: "--zd-syntax-comment",
+  syntaxString: "--zd-syntax-string",
+  syntaxNumber: "--zd-syntax-number",
+  syntaxKeyword: "--zd-syntax-keyword",
+  syntaxCallable: "--zd-syntax-callable",
+  syntaxType: "--zd-syntax-type",
+  syntaxName: "--zd-syntax-name",
+  syntaxInserted: "--zd-syntax-inserted",
+  syntaxDeleted: "--zd-syntax-deleted"
+};
 const SEMANTIC_RAMP_DEFAULTS = {
   // Re-pointed for the 5-base / 3-accent minimized ramp (#2602); mirrors the
   // Default Dark reference wiring (surface/chatAssistantBg/imageOverlayBg merged
@@ -79,6 +112,33 @@ const SEMANTIC_CSS_NAMES = {
   matchedKeywordBg: "--zd-matched-keyword-bg",
   matchedKeywordFg: "--zd-matched-keyword-fg"
 };
+const ZFB_HIGHLIGHT_ROLE_TO_ZUDO_TOKEN = {
+  foreground: "codeFg",
+  background: "codeBg",
+  escape: "syntaxString",
+  operator: "codeFg",
+  comment: "syntaxComment",
+  string: "syntaxString",
+  number: "syntaxNumber",
+  constant: "syntaxNumber",
+  keyword: "syntaxKeyword",
+  function: "syntaxCallable",
+  type: "syntaxType",
+  namespace: "syntaxType",
+  property: "syntaxName",
+  variable: "syntaxName",
+  tag: "syntaxName",
+  attribute: "syntaxName",
+  punctuation: "codeFg",
+  inserted: "syntaxInserted",
+  deleted: "syntaxDeleted",
+  heading: "syntaxKeyword"
+};
+const SYNTAX_DIFF_BACKGROUND_MIX_PERCENT = 15;
+const SYNTAX_DIFF_BACKGROUND_CSS = {
+  inserted: `color-mix(in srgb, var(${SYNTAX_CSS_NAMES.syntaxInserted}) ${SYNTAX_DIFF_BACKGROUND_MIX_PERCENT}%, var(${SEMANTIC_CSS_NAMES.codeBg}))`,
+  deleted: `color-mix(in srgb, var(${SYNTAX_CSS_NAMES.syntaxDeleted}) ${SYNTAX_DIFF_BACKGROUND_MIX_PERCENT}%, var(${SEMANTIC_CSS_NAMES.codeBg}))`
+};
 function resolveRampRef(ref, ramps) {
   if (typeof ref === "string") return ref;
   if ("base" in ref) {
@@ -105,6 +165,61 @@ function resolveSemanticColors(scheme) {
   }
   return out;
 }
+function tryResolveRampRef(ref, ramps) {
+  if (typeof ref === "string") return ref.trim().length > 0 ? ref : void 0;
+  if (!ref || typeof ref !== "object") return void 0;
+  const candidate = ref;
+  if ("base" in candidate) {
+    const index = candidate.base;
+    if (typeof index !== "number" || !Number.isInteger(index) || index < 0) return void 0;
+    const value = ramps.base[index];
+    return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+  }
+  if ("accent" in candidate) {
+    const index = candidate.accent;
+    if (typeof index !== "number" || !Number.isInteger(index) || index < 0) return void 0;
+    const value = ramps.accent[index];
+    return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+  }
+  if ("state" in candidate) {
+    const state = candidate.state;
+    if (typeof state !== "string" || !STATE_ROLES.includes(state)) return void 0;
+    const value = ramps.state[state];
+    return typeof value === "string" && value.trim().length > 0 ? value : void 0;
+  }
+  return void 0;
+}
+function copyRampRef(ref) {
+  return typeof ref === "string" ? ref : { ...ref };
+}
+function resolveSyntaxPalette(scheme) {
+  const { ramps, map } = scheme;
+  const refs = {};
+  const colors = {};
+  const emergencyCandidates = [
+    map.semantic.codeFg,
+    map.fg,
+    ramps.base.find((value) => typeof value === "string" && value.trim().length > 0),
+    "currentColor"
+  ];
+  const emergencyRef = emergencyCandidates.find(
+    (candidate) => tryResolveRampRef(candidate, ramps) !== void 0
+  );
+  const emergencyColor = tryResolveRampRef(emergencyRef, ramps) ?? "currentColor";
+  for (const key of SYNTAX_SEMANTIC_KEYS) {
+    const explicitRef = map.syntax[key];
+    const explicitColor = tryResolveRampRef(explicitRef, ramps);
+    const inheritedRef = map.semantic[SYNTAX_SEMANTIC_ALIASES[key]];
+    const inheritedColor = tryResolveRampRef(inheritedRef, ramps);
+    const effectiveRef = explicitColor !== void 0 ? explicitRef : inheritedColor !== void 0 ? inheritedRef : emergencyRef;
+    refs[key] = copyRampRef(effectiveRef);
+    colors[key] = explicitColor ?? inheritedColor ?? emergencyColor;
+  }
+  return { refs, colors };
+}
+function resolveSyntaxColors(scheme) {
+  return resolveSyntaxPalette(scheme).colors;
+}
 function rampRefToPanelDefault(ref) {
   if (typeof ref === "string") return ref;
   if ("base" in ref) return `base:base-${ref.base}`;
@@ -113,6 +228,7 @@ function rampRefToPanelDefault(ref) {
 }
 function buildSemanticTierItems(scheme) {
   const { map } = scheme;
+  const syntax = resolveSyntaxPalette(scheme);
   const items = [
     {
       id: "bg",
@@ -152,6 +268,15 @@ function buildSemanticTierItems(scheme) {
       type: { kind: "color", format: "oklch" }
     });
   }
+  for (const key of SYNTAX_SEMANTIC_KEYS) {
+    items.push({
+      id: key,
+      cssVar: SYNTAX_CSS_NAMES[key],
+      label: key,
+      default: rampRefToPanelDefault(syntax.refs[key]),
+      type: { kind: "color", format: "oklch" }
+    });
+  }
   return items;
 }
 function schemeToCssPairs(scheme, scope = "all") {
@@ -177,6 +302,10 @@ function schemeToCssPairs(scheme, scope = "all") {
     for (const key of SEMANTIC_KEYS) {
       pairs.push([SEMANTIC_CSS_NAMES[key], sem[key]]);
     }
+    const syntax = resolveSyntaxColors(scheme);
+    for (const key of SYNTAX_SEMANTIC_KEYS) {
+      pairs.push([SYNTAX_CSS_NAMES[key], syntax[key]]);
+    }
   }
   return pairs;
 }
@@ -212,11 +341,19 @@ export {
   SEMANTIC_KEYS,
   SEMANTIC_RAMP_DEFAULTS,
   STATE_ROLES,
+  SYNTAX_CSS_NAMES,
+  SYNTAX_DIFF_BACKGROUND_CSS,
+  SYNTAX_DIFF_BACKGROUND_MIX_PERCENT,
+  SYNTAX_SEMANTIC_ALIASES,
+  SYNTAX_SEMANTIC_KEYS,
+  ZFB_HIGHLIGHT_ROLE_TO_ZUDO_TOKEN,
   buildSemanticTierItems,
   generateCssCustomProperties,
   generateLightDarkCssProperties,
   rampRefToPanelDefault,
   resolveRampRef,
   resolveSemanticColors,
+  resolveSyntaxColors,
+  resolveSyntaxPalette,
   schemeToCssPairs
 };

package/dist/color-schemes-defaults/index.js

@@ -64,6 +64,13 @@ const darkMap = {
     // the amber bg — matched-keyword at threshold+0.1; carried from #2593.
     matchedKeywordBg: "oklch(.700 .158 62)",
     matchedKeywordFg: "oklch(.300 .003 65)"
+  },
+  // Diff foregrounds are checked against their actual 15% foreground tint on
+  // codeBg. The ordinary success/danger aliases are not light enough on that
+  // derived dark background, so only these two syntax roles need overrides.
+  syntax: {
+    syntaxInserted: "oklch(.750 .145 145)",
+    syntaxDeleted: "oklch(.820 .100 25)"
   }
 };
 const lightMap = {
@@ -110,6 +117,12 @@ const lightMap = {
     // Default Dark (an amber-on-white highlight reads identically in both modes).
     matchedKeywordBg: "oklch(.700 .158 62)",
     matchedKeywordFg: "oklch(.300 .003 65)"
+  },
+  // Slightly darker than the shared success/danger aliases so the foregrounds
+  // retain >= 4.6:1 on their own 15% tints over the light code background.
+  syntax: {
+    syntaxInserted: "oklch(.460 .140 145)",
+    syntaxDeleted: "oklch(.490 .170 25)"
   }
 };
 const defaultColorSchemes = {

package/dist/config/component-tokens.d.ts

@@ -16,7 +16,7 @@ export type ComponentTokenSurface = "content" | "chrome";
  * Provides autocomplete when a consumer iterates or references individual tokens.
  * Must be kept in sync with the `cssVar` values in `COMPONENT_TOKENS` below.
  */
-export type ComponentTokenName = "--zdc-doc-title-font" | "--zdc-doc-title-weight" | "--zdc-doc-title-tracking" | "--zdc-doc-h2-font" | "--zdc-doc-h2-weight" | "--zdc-doc-h2-tracking" | "--zdc-doc-h3-weight" | "--zdc-doc-h4-weight" | "--zdc-doc-prose-font" | "--zdc-doc-link-decoration" | "--zdc-admonition-radius" | "--zdc-admonition-border-width" | "--zdc-card-radius" | "--zdc-content-max-width" | "--zdc-toc-width" | "--zdc-nav-active-indicator-color" | "--zdc-nav-active-weight";
+export type ComponentTokenName = "--zdc-doc-title-font" | "--zdc-doc-title-weight" | "--zdc-doc-title-tracking" | "--zdc-doc-h2-font" | "--zdc-doc-h2-weight" | "--zdc-doc-h2-tracking" | "--zdc-doc-h3-weight" | "--zdc-doc-h4-weight" | "--zdc-doc-prose-font" | "--zdc-doc-link-decoration" | "--zdc-admonition-radius" | "--zdc-admonition-border-width" | "--zdc-card-radius" | "--zdc-content-max-width" | "--zdc-toc-width" | "--zdc-nav-active-indicator-color" | "--zdc-nav-active-weight" | "--zdc-chrome-font" | "--zdc-header-font" | "--zdc-sidebar-font" | "--zdc-toc-font";
 export interface ComponentToken {
     /**
      * The CSS custom-property name the consumer redefines in `:root`, e.g.

package/dist/config/component-tokens.js

@@ -98,11 +98,17 @@ const COMPONENT_TOKENS = [
   },
   // ── Content prose font (.zd-content, #2460) ────────────────────────────────
   // Sets font-family on the content root so every element inside inherits it by
-  // default. The headings whose `--zdc-doc-*-font` default to `inherit` will
-  // inherit this value — safe because the current computed heading family already
-  // resolves to `var(--font-sans)` (Tailwind preflight sets it on `html`).
-  // Byte-identical: `.zd-content` currently carries no explicit font-family, so
-  // setting it to `var(--font-sans)` produces the same computed value.
+  // default. The headings whose `--zdc-doc-*-font` default to `inherit` inherit
+  // this value.
+  // NOT byte-identical, by design (#2887 corrects the original claim here): this
+  // project imports only `tailwindcss/preflight` + `utilities` and never defines
+  // `--default-font-family`, so preflight's `html, :host` rule compiles its
+  // `--theme(--default-font-family, ui-sans-serif, system-ui, …)` down to the
+  // LITERAL fallback stack — it does NOT resolve to `var(--font-sans)`. Pointing
+  // `.zd-content` at `var(--font-sans)` therefore moved prose off that literal
+  // onto the token (`system-ui, sans-serif` by default) — the same system UI face
+  // on every major platform, which is why the delta went unnoticed. `body` takes
+  // the identical step for the app shell — see `--zdc-chrome-font` below.
   {
     cssVar: "--zdc-doc-prose-font",
     selector: ".zd-content",
@@ -255,6 +261,99 @@ const COMPONENT_TOKENS = [
     surface: "chrome",
     category: "typography",
     description: "Font weight of the active sidebar nav link (non-root leaf, the current page). Defaults to `var(--font-weight-medium)` (byte-identical to the current `font-medium` utility). Redefine in :root to use semibold or bold for stronger active emphasis."
+  },
+  // ── Chrome font seam (body, #2887 / epic #2886) ───────────────────────────
+  // THE foundation the chrome-font epic stacks on. Every app-shell surface —
+  // header, desktop sidebar, mobile drawer, right-rail TOC, mobile TOC,
+  // breadcrumb, footer — sets NO font-family of its own, so all of them inherit
+  // Tailwind preflight's `html, :host` rule. Because this project imports only
+  // `tailwindcss/preflight` + `utilities` and never defines
+  // `--default-font-family`, that rule's `--theme(--default-font-family,
+  // ui-sans-serif, system-ui, …)` compiles to the HARDCODED LITERAL fallback
+  // stack. A theme pack's `--font-sans` override therefore had no path to any of
+  // those surfaces at all — only `.zd-content` prose consumed the token.
+  //
+  // This rule is that path: `body` is UNLAYERED here, so it beats preflight
+  // (which the consumer imports into `layer(zd-preflight)`), and every chrome
+  // surface inherits `var(--font-sans)` — including any surface a future
+  // component adds, since inheritance is the mechanism.
+  //
+  // NOT byte-identical — the ONE deliberate exception in this registry. Chrome
+  // falls from preflight's `ui-sans-serif, system-ui, …` literal to whatever
+  // `--font-sans` resolves to (`system-ui, sans-serif` by default): the same
+  // system UI face on every major platform, and the identical step `.zd-content`
+  // already took in #2460 (see `--zdc-doc-prose-font` above). Accepted per #2887.
+  //
+  // Deliberately NO `--font-mono` counterpart: every code surface (`code`, `pre`,
+  // `.hi-root`, the diff viewer, …) sets `font-family: var(--font-mono)` on
+  // itself explicitly, so the mono token already reaches all of them.
+  {
+    cssVar: "--zdc-chrome-font",
+    selector: "body",
+    property: "font-family",
+    default: "var(--font-sans)",
+    component: "chrome",
+    surface: "chrome",
+    category: "typography",
+    description: "Base font family for the whole document, and the seam that lets `--font-sans` reach the app shell (header/sidebar/TOC/breadcrumb/footer) at all \u2014 without it those surfaces inherit Tailwind preflight's hardcoded literal stack instead of the token. Defaults to `var(--font-sans)`. Redefine `--font-sans` (the usual theme-pack route) to restyle everything, or `--zdc-chrome-font` to move the shell independently of prose."
+  },
+  // ── Per-surface chrome font knobs (#2887 / epic #2886) ────────────────────
+  // Each lets a pack give ONE shell surface its own face (e.g. a display font in
+  // the header while nav and TOC stay on the body font) without ejecting
+  // anything. Each selector deliberately covers BOTH the desktop and the mobile
+  // emitter of its surface, so one override lands on both viewports. The mobile
+  // hooks (`data-zd-mobile-sidebar`, `data-zd-mobile-toc`) were added in #2887
+  // for exactly this — the mobile drawer and the mobile TOC previously had no
+  // stable anchor at all, and the mobile TOC does NOT reuse `nav[data-zd-toc]`
+  // (it emits its own `<div>` markup).
+  //
+  // ── Why the default is the chrome seam, NOT `inherit` ─────────────────────
+  // These three chain to `var(--zdc-chrome-font, var(--font-sans))` — the same
+  // value the `body` seam above resolves to — rather than to `inherit` like the
+  // content-surface `-font` tokens do. `inherit` is the WRONG default here
+  // because a surface's two emitters live in DIFFERENT parts of the DOM, so
+  // `inherit` resolves them against different ancestors and silently splits them:
+  //   - The mobile drawer renders INSIDE `header[data-header]` (Header projects
+  //     `SidebarToggle` into its `sidebarToggle` slot). Under `inherit`, a pack
+  //     setting ONLY `--zdc-header-font` would leak that face into the drawer
+  //     while `#desktop-sidebar` — which inherits from `body` — kept the body
+  //     font. One "sidebar", two fonts.
+  //   - The mobile TOC renders inside `.zd-content`, so under `inherit` it would
+  //     follow `--zdc-doc-prose-font` while the desktop rail followed the chrome
+  //     font. The TOC is navigation, not prose; it belongs on the chrome font.
+  // Anchoring to the seam makes each knob depend only on its own value and the
+  // chrome font — never on where the component happens to be mounted. Still a
+  // no-op by default: the resolved value is identical to what `inherit` produced
+  // when nothing is overridden (both land on `var(--font-sans)`).
+  {
+    cssVar: "--zdc-header-font",
+    selector: "header[data-header]",
+    property: "font-family",
+    default: "var(--zdc-chrome-font, var(--font-sans))",
+    component: "header",
+    surface: "chrome",
+    category: "typography",
+    description: "Font family of the site header. Defaults to the `--zdc-chrome-font` seam (a no-op until redefined); set in :root to give the header its own face, e.g. a display font for the wordmark and nav. Scoped to the header itself \u2014 it does not leak into the mobile sidebar drawer that the header hosts."
+  },
+  {
+    cssVar: "--zdc-sidebar-font",
+    selector: "#desktop-sidebar, aside[data-zd-mobile-sidebar]",
+    property: "font-family",
+    default: "var(--zdc-chrome-font, var(--font-sans))",
+    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)."
+  },
+  {
+    cssVar: "--zdc-toc-font",
+    selector: "nav[data-zd-toc], div[data-zd-mobile-toc]",
+    property: "font-family",
+    default: "var(--zdc-chrome-font, var(--font-sans))",
+    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."
   }
 ];
 export {

package/dist/config.d.ts

@@ -192,8 +192,8 @@ export interface ZudoDocConfig {
      */
     tagGovernance?: TagGovernanceMode;
     /**
-     * Whether the tag vocabulary is consulted at runtime (alias resolution,
-     * deprecation filtering, grouped footer). Orthogonal to `tagGovernance`.
+     * Whether the canonical tag vocabulary is consulted at runtime (validation
+     * and grouped footer rendering). Orthogonal to `tagGovernance`.
      * The vocabulary ENTRIES are supplied separately via `tagVocabularyEntries`.
      * @default false
      */
@@ -229,8 +229,8 @@ export interface ZudoDocConfig {
      */
     aiAssistant?: boolean;
     /**
-     * Short-circuit `/api/ai-chat` with a fixed "disabled" reply (no API key /
-     * KV / rate limiter touched).
+     * Short-circuit `/api/ai-chat` with a fixed "disabled" reply (no API key,
+     * KV/DO binding, or rate limiter touched).
      * @default false
      */
     aiChatDemoMode?: boolean;
@@ -241,8 +241,9 @@ export interface ZudoDocConfig {
      */
     aiChatAllowedOrigins?: string[];
     /**
-     * Global daily request ceiling across all IPs for `/api/ai-chat`, or `false`
-     * to disable the ceiling.
+     * Exact UTC-day paid-call admission cap across all IPs for `/api/ai-chat`,
+     * or `false` to disable it. Admissions are not refunded after provider
+     * failure and are not provider-confirmed spend accounting.
      * @default false
      */
     aiChatGlobalDailyLimit?: number | false;
@@ -261,12 +262,6 @@ export interface ZudoDocConfig {
      * @default 4
      */
     tocMaxDepth?: number;
-    /**
-     * Heading-ID (anchor) strategy. `"hierarchical"` prefixes each anchor with
-     * its ancestor chain; `"flat"` is zfb's legacy github-slugger scheme.
-     * @default "hierarchical"
-     */
-    headingIdStrategy?: "flat" | "hierarchical";
     /**
      * Enable the draggable sidebar resizer.
      * @default false
@@ -374,6 +369,27 @@ export interface ZudoDocConfig {
      * @default undefined (package-default builder is used)
      */
     designTokenPanelConfigModule?: string;
+    /**
+     * Active theme pack slug. "default" is the stock zudo-doc look (no pack
+     * stylesheet loaded). Must be a member of the resolved `themePacks` list;
+     * an unknown slug fails the build loudly at plugin setup.
+     * @default "default"
+     */
+    themePack?: string;
+    /**
+     * Mount the bottom-right theme-pack switcher flyout (and its browse-all
+     * dialog) on every page.
+     * @default false
+     */
+    themePackSwitcher?: boolean;
+    /**
+     * Enabled pack slugs, in switcher order. `undefined` = all bundled packs:
+     * "default" first, then the bundled registry in canonical
+     * (alphabetical-by-slug) order. An explicit list is authoritative — may omit
+     * "default", reorder freely; duplicates/unknown slugs fail loudly.
+     * @default undefined
+     */
+    themePacks?: string[];
     /**
      * Replace the default docs-frontmatter zod schema builder entirely. When
      * omitted, `zudoDoc()` builds the default schema

package/dist/config.js

@@ -45,11 +45,12 @@ const DEFAULT_SETTINGS = {
   aiAssistant: false,
   aiChatDemoMode: false,
   aiChatAllowedOrigins: [],
+  // Exact UTC-day paid-call admission cap; false disables it. An admission is
+  // consumed before provider fetch and is not provider-confirmed accounting.
   aiChatGlobalDailyLimit: false,
   designTokenPanel: false,
   tocMinDepth: 2,
   tocMaxDepth: 4,
-  headingIdStrategy: "hierarchical",
   sidebarResizer: false,
   sidebarToggle: false,
   imageEnlarge: false,
@@ -65,9 +66,17 @@ const DEFAULT_SETTINGS = {
   footer: false,
   headerNav: [],
   headerRightItems: [{ type: "component", component: "theme-toggle" }],
-  packageOwnedRoutes: true
+  packageOwnedRoutes: true,
+  themePack: "default",
+  themePackSwitcher: false,
+  themePacks: void 0
 };
 function zudoDoc(user = {}) {
+  if ("headingIdStrategy" in user) {
+    throw new TypeError(
+      "headingIdStrategy is no longer supported; heading IDs are always hierarchical"
+    );
+  }
   const {
     port,
     adapter,

package/dist/content/component-map.d.ts

@@ -16,22 +16,6 @@ import { ContentCode } from "./content-code.js";
  * into a larger components object that also includes admonition overrides,
  * custom shortcodes, etc.) at the Astro page layer.
  */
-export declare const htmlOverrides: {
-    h2: typeof HeadingH2;
-    h3: typeof HeadingH3;
-    h4: typeof HeadingH4;
-    p: typeof ContentParagraph;
-    a: typeof ContentLink;
-    strong: typeof ContentStrong;
-    blockquote: typeof ContentBlockquote;
-    ul: typeof ContentUl;
-    ol: typeof ContentOl;
-    table: typeof ContentTable;
-    code: typeof ContentCode;
-};
-/**
- * Alias for `htmlOverrides`. Prefer this name in new consumer code.
- */
 export declare const defaultComponents: {
     h2: typeof HeadingH2;
     h3: typeof HeadingH3;

package/dist/content/component-map.js

@@ -9,7 +9,7 @@ import { ContentUl } from "./content-ul.js";
 import { ContentOl } from "./content-ol.js";
 import { ContentTable } from "./content-table.js";
 import { ContentCode } from "./content-code.js";
-const htmlOverrides = {
+const defaultComponents = {
   h2: HeadingH2,
   h3: HeadingH3,
   h4: HeadingH4,
@@ -22,8 +22,6 @@ const htmlOverrides = {
   table: ContentTable,
   code: ContentCode
 };
-const defaultComponents = htmlOverrides;
 export {
-  defaultComponents,
-  htmlOverrides
+  defaultComponents
 };

package/dist/content/index.d.ts

@@ -26,4 +26,4 @@ export { ContentUl } from "./content-ul.js";
 export { ContentOl } from "./content-ol.js";
 export { ContentTable } from "./content-table.js";
 export { ContentCode } from "./content-code.js";
-export { htmlOverrides, defaultComponents } from "./component-map.js";
+export { defaultComponents } from "./component-map.js";

package/dist/content/index.js

@@ -9,7 +9,7 @@ import { ContentUl } from "./content-ul.js";
 import { ContentOl } from "./content-ol.js";
 import { ContentTable } from "./content-table.js";
 import { ContentCode } from "./content-code.js";
-import { htmlOverrides, defaultComponents } from "./component-map.js";
+import { defaultComponents } from "./component-map.js";
 export {
   ContentBlockquote,
   ContentCode,
@@ -22,6 +22,5 @@ export {
   HeadingH2,
   HeadingH3,
   HeadingH4,
-  defaultComponents,
-  htmlOverrides
+  defaultComponents
 };

package/dist/content.css

@@ -10,7 +10,7 @@
  * drift). See zudolab/zudo-doc#2188.
  *
  * Component-first split: the major elements (h2–h4, p, a, strong, blockquote,
- * ul, ol, table) get their VISUALS from the package's `htmlOverrides` Preact
+ * ul, ol, table) get their VISUALS from the package's `defaultComponents` Preact
  * components (Tailwind classes + inline styles), whose utilities ship in
  * `dist/safelist.css`. This file owns only what those components do NOT emit:
  * the flow-space vertical rhythm, heading `--flow-space` + tightening, the