@takazudo/zudo-doc 3.3.0 → 4.0.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.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

package/dist/design-token-panel-bootstrap.d.ts

@@ -6,25 +6,17 @@
  *
  * `bootstrapDesignTokenPanel` is a callable that configures zdtp's panel and
  * wires its lifecycle hooks to zfb's navigation events via
- * `setLifecycleAdapter()`. Projects import it with their own PanelConfig
- * DATA — which stays project-side (or, since #2658, the PACKAGE-DEFAULT data
- * from `@takazudo/zudo-doc/design-token-panel-config`).
+ * `setLifecycleAdapter()`. It receives a mode-scoped PanelConfig builder —
+ * either a project override or the package default from
+ * `@takazudo/zudo-doc/design-token-panel-config`.
  *
- * Two calling shapes (both supported):
+ * The current call shape is a mode-scoped builder. It rebuilds the panel per
+ * light/dark mode on every `color-scheme-changed` toggle:
  *
- *   // Mode-scoped builder — rebuilds the panel per light/dark mode on every
- *   // `color-scheme-changed` toggle:
  *   import { bootstrapDesignTokenPanel } from "@takazudo/zudo-doc/design-token-panel-bootstrap";
  *   import { buildDesignTokenPanelConfig } from "@/config/design-token-panel-config";
  *   bootstrapDesignTokenPanel(buildDesignTokenPanelConfig);
  *
- *   // Plain config (back-compat — generated projects on the old shape):
- *   import { designTokenPanelConfig } from "@/config/design-token-panel-config";
- *   bootstrapDesignTokenPanel(designTokenPanelConfig);
- *
- * A plain-config caller gets NO toggle listener (a static config has nothing to
- * rebuild), so existing generated projects keep working with zero changes.
- *
  * `DesignTokenPanelBootstrap` (below) is the PACKAGE-OWNED island component
  * that wires the mode-scoped builder for package-owned routes with no host
  * config file — the #2658 "Approach (a)" package default. It resolves its
@@ -32,27 +24,25 @@
  * module the routes plugin registers (`../plugins/routes.ts`): absent a host
  * `designTokenPanelConfigModule` override, that resolves to
  * `@takazudo/zudo-doc/design-token-panel-config`'s `buildDesignTokenPanelConfig`.
- * `packages/zudo-doc/src/routes/_chrome.tsx` statically imports it so zfb's
- * island scanner walks route → `_chrome` → here (mirrors the DocHistory
- * #2480 static-import chain). A host that ejects entirely (its own
- * `src/lib/*` + `src/components/*`, like the pre-#2658 showcase) never
- * reaches this component — it only calls `bootstrapDesignTokenPanel` itself,
- * same as always.
+ * `packages/zudo-doc/src/chrome/derive.tsx` statically imports it so zfb's
+ * island scanner walks route → chrome → derive → here (mirrors the DocHistory
+ * #2480 static-import contract). A host that ejects entirely can call
+ * `bootstrapDesignTokenPanel` with its own builder, but current package-owned
+ * routes use this component directly.
  *
  * KNOWN COUPLING: `DesignTokenPanelBootstrap`'s top-level import of
  * `virtual:zudo-doc-design-token-panel-config` requires the routes plugin
  * (`settings.packageOwnedRoutes`, default `true`) to be active in the
  * consuming project, since that plugin is what registers the virtual module.
  * A project that explicitly sets `packageOwnedRoutes: false` AND wants to
- * reuse the bare `bootstrapDesignTokenPanel` export for its own hand-wired
- * component (as every current consumer's `src/lib/design-token-panel-bootstrap.ts`
- * does) is unaffected — that import graph never reaches `DesignTokenPanelBootstrap`
- * — but a `packageOwnedRoutes: false` project must not import
- * `DesignTokenPanelBootstrap` itself.
+ * reuse the bare `bootstrapDesignTokenPanel` export for its own component is
+ * unaffected — that import graph never reaches `DesignTokenPanelBootstrap` —
+ * but a `packageOwnedRoutes: false` project must not import the package island
+ * component itself.
  *
- * Moved from the host's `src/lib/design-token-panel-bootstrap.ts` as part of
- * the package-first migration (S9a zudolab/zudo-doc#2333); mode-scoped rebuild
- * wiring added in zudolab/zudo-doc#2610; package-default island added in #2658.
+ * Package-first wiring landed in S9a zudolab/zudo-doc#2333; mode-scoped rebuild
+ * wiring was added in zudolab/zudo-doc#2610 and the package-default island in
+ * #2658.
  *
  * CSS is pulled via `@import "@takazudo/zdtp/styles.css"` in the project's
  * `src/styles/global.css` so the panel chrome lands in the main page CSS
@@ -65,28 +55,43 @@ import { type PanelConfig } from "@takazudo/zdtp";
 /** Active color-scheme mode, read from `<html data-theme>`. */
 type ColorSchemeMode = "light" | "dark";
 /**
- * A per-mode PanelConfig factory. Supplied by hosts that want the panel's
- * defaults to follow the live light/dark mode (see `buildDesignTokenPanelConfig`
- * in the host's `design-token-panel-config.ts`).
+ * A per-mode PanelConfig factory. The package default and host overrides use
+ * this same shape so panel defaults follow the live light/dark mode.
  */
 export type PanelConfigBuilder = (mode: ColorSchemeMode) => PanelConfig;
+/**
+ * Theme-pack storage-prefix rule (ADR theme-packs.md Decision 4), enforced
+ * CENTRALLY here — never per-builder, so host builders supplied via
+ * `designTokenPanelConfigModule` cannot cross-contaminate namespaces even if
+ * unaware of packs:
+ *
+ * - active pack `default` → the builder's `storagePrefix` stays BYTE-UNCHANGED
+ *   (the existing-user carry-over guarantee: `zudo-doc-tweak` keys keep
+ *   working on the stock look).
+ * - any other pack → `${storagePrefix}--<slug>` (double hyphen avoids
+ *   colliding with zdtp's own `-open`/version suffixes). zdtp derives every
+ *   key — including the `${prefix}-open` open-state mirror — from the prefix,
+ *   so tweaks saved under pack A are invisible under pack B and restored
+ *   verbatim on switch-back.
+ *
+ * The `PanelConfigBuilder` signature stays `(mode) => PanelConfig` — this is a
+ * post-process of the RETURNED config, not a builder-contract change.
+ */
+export declare function withPackScopedStoragePrefix(config: PanelConfig, activePack: string): PanelConfig;
 /**
  * Bootstrap zdtp for a project. Configures the panel, drains any pre-hydration
  * click queue, and wires the zdtp lifecycle adapter to zfb's navigation events
  * so persisted token overrides re-apply on every soft navigation.
  *
- * When passed a `PanelConfigBuilder`, also wires a `color-scheme-changed`
- * listener that rebuilds the panel per light/dark mode (see the toggle sequence
- * below). When passed a plain `PanelConfig`, no toggle listener is registered.
- *
- * Call this once, as a side-effect import from the project's island wrapper
- * (`src/components/design-token-panel-bootstrap.tsx`).
+ * Wires a `color-scheme-changed` listener that rebuilds the panel per
+ * light/dark mode (see the toggle sequence below), and a parallel
+ * `theme-pack-changed` listener that rebuilds it per theme pack with a
+ * pack-scoped storage prefix (ADR theme-packs.md Decision 4, #2822).
  *
- * @param configOrBuilder - The project's `PanelConfig`, or a `(mode) =>
- *   PanelConfig` builder for mode-scoped rebuilds. DATA stays project-side in
- *   `src/config/design-token-panel-config.ts`.
+ * @param buildConfig - The project's `(mode) => PanelConfig` builder for
+ *   mode-scoped rebuilds.
  */
-export declare function bootstrapDesignTokenPanel(configOrBuilder: PanelConfig | PanelConfigBuilder): void;
+export declare function bootstrapDesignTokenPanel(buildConfig: PanelConfigBuilder): void;
 /**
  * The package-default `<DesignTokenPanelBootstrap/>` island: mounted (via
  * `Island({ when: "load" })`, no `ssrFallback` — it renders nothing on either