@takazudo/zudo-doc 2.5.1 → 3.0.0

package/dist/theme/design-token-serde.js

@@ -1,7 +1,16 @@
 import {
   emptyOverrides
 } from "./design-token-types.js";
-const DESIGN_TOKEN_SCHEMA = "zudo-doc-design-tokens/v1";
+import {
+  SEMANTIC_KEYS,
+  SEMANTIC_RAMP_DEFAULTS,
+  STATE_ROLES
+} from "../color-scheme-utils.js";
+const DESIGN_TOKEN_SCHEMA = "zudo-doc-design-tokens/v3";
+const LEGACY_SCHEMA_V1 = "zudo-doc-design-tokens/v1";
+const LEGACY_SCHEMA_V2 = "zudo-doc-design-tokens/v2";
+const BASE_RAMP_LENGTH = 5;
+const ACCENT_RAMP_LENGTH = 3;
 class DesignTokenSchemaError extends Error {
   reason;
   actualSchema;
@@ -33,47 +42,12 @@ function serializeColor(color, opts) {
   const full = opts.includeDefaults === true;
   const out = {};
   let changed = false;
-  const paletteChanged = full || !baseline || baseline.palette.length !== color.palette.length || color.palette.some((c, i) => c !== baseline.palette[i]);
-  if (paletteChanged) {
-    out.palette = [...color.palette];
+  if (full || !baseline || !deepEqual(color.ramps, baseline.ramps)) {
+    out.ramps = cloneRamps(color.ramps);
     changed = true;
   }
-  const base = {};
-  let baseChanged = false;
-  const baseEntries = [
-    ["bg", color.background, baseline?.background],
-    ["fg", color.foreground, baseline?.foreground],
-    ["cursor", color.cursor, baseline?.cursor],
-    ["sel-bg", color.selectionBg, baseline?.selectionBg],
-    ["sel-fg", color.selectionFg, baseline?.selectionFg]
-  ];
-  for (const [key, value, baselineValue] of baseEntries) {
-    if (full || baseline === void 0 || value !== baselineValue) {
-      base[key] = value;
-      baseChanged = true;
-    }
-  }
-  if (baseChanged) {
-    out.base = base;
-    changed = true;
-  }
-  const semantic = {};
-  let semanticChanged = false;
-  const semKeys = /* @__PURE__ */ new Set([
-    ...Object.keys(color.semanticMappings),
-    ...baseline ? Object.keys(baseline.semanticMappings) : []
-  ]);
-  for (const key of semKeys) {
-    const cur = color.semanticMappings[key];
-    if (cur === void 0) continue;
-    const base2 = baseline?.semanticMappings[key];
-    if (full || base2 === void 0 || cur !== base2) {
-      semantic[key] = cur;
-      semanticChanged = true;
-    }
-  }
-  if (semanticChanged) {
-    out.semantic = semantic;
+  if (full || !baseline || !deepEqual(color.map, baseline.map)) {
+    out.map = cloneMap(color.map);
     changed = true;
   }
   return changed ? out : void 0;
@@ -116,7 +90,9 @@ function deserialize(input, opts) {
       `Missing "$schema" key. Expected "${DESIGN_TOKEN_SCHEMA}".`
     );
   }
-  if (schema !== DESIGN_TOKEN_SCHEMA) {
+  const legacyV1 = schema === LEGACY_SCHEMA_V1;
+  const legacyV2 = schema === LEGACY_SCHEMA_V2;
+  if (schema !== DESIGN_TOKEN_SCHEMA && !legacyV1 && !legacyV2) {
     throw new DesignTokenSchemaError(
       "schema-mismatch",
       `Unsupported "$schema" value: ${JSON.stringify(schema)}. Expected "${DESIGN_TOKEN_SCHEMA}".`,
@@ -126,7 +102,7 @@ function deserialize(input, opts) {
   const warnings = [];
   const unknownTokens = [];
   const baseline = opts.colorDefaults ?? neutralColorDefaults();
-  const color = deserializeColor(obj.color, baseline, warnings);
+  const color = deserializeColor(obj.color, baseline, warnings, legacyV1, legacyV2);
   const spacing = deserializeOverrides(
     obj.spacing,
     opts.manifest.spacing,
@@ -154,55 +130,114 @@ function deserialize(input, opts) {
     warnings
   };
 }
-function deserializeColor(raw, baseline, warnings) {
+function isLegacyColorPayload(raw) {
+  if (!raw || typeof raw !== "object") return false;
+  const c = raw;
+  return Array.isArray(c.palette) || c.base !== void 0;
+}
+function deserializeColor(raw, baseline, warnings, legacyV1, legacyV2) {
+  if (legacyV1 || isLegacyColorPayload(raw)) {
+    const msg = "Legacy v1 design-token color state detected; color was reset to the default scheme (the old 16-slot palette has no faithful ramp mapping).";
+    warnings.push(msg);
+    console.warn(`[zudo-doc] ${msg}`);
+    return cloneScheme(baseline);
+  }
+  if (legacyV2) {
+    const msg = "Legacy v2 design-token color state detected (pre-5/3-minimize ramps); color was reset to the default scheme.";
+    warnings.push(msg);
+    console.warn(`[zudo-doc] ${msg}`);
+    return cloneScheme(baseline);
+  }
   if (!raw || typeof raw !== "object") {
-    return { ...baseline, palette: [...baseline.palette], semanticMappings: { ...baseline.semanticMappings } };
+    return cloneScheme(baseline);
   }
   const c = raw;
-  let palette = [...baseline.palette];
-  if (Array.isArray(c.palette)) {
-    const parsed = c.palette.filter((v) => typeof v === "string");
-    if (parsed.length === 16 && parsed.length === c.palette.length) {
-      palette = parsed;
-    } else if (c.palette.length > 0) {
-      const detail = parsed.length < c.palette.length ? `${c.palette.length - parsed.length} non-string entries dropped, leaving ${parsed.length}` : `${c.palette.length} entries`;
-      warnings.push(
-        `color.palette: expected 16 string entries; got ${detail}. Palette ignored.`
-      );
-    }
+  const ramps = parseRamps(c.ramps, baseline.ramps, warnings);
+  const map = parseMap(c.map, baseline.map, warnings);
+  return { ramps, map };
+}
+function parseRamps(raw, baseline, warnings) {
+  if (raw === void 0) return cloneRamps(baseline);
+  if (!raw || typeof raw !== "object") {
+    warnings.push("color.ramps is not an object; kept baseline ramps.");
+    return cloneRamps(baseline);
   }
-  const base = c.base && typeof c.base === "object" ? c.base : {};
-  const background = numOr(base.bg, baseline.background);
-  const foreground = numOr(base.fg, baseline.foreground);
-  const cursor = numOr(base.cursor, baseline.cursor);
-  const selectionBg = numOr(base["sel-bg"], baseline.selectionBg);
-  const selectionFg = numOr(base["sel-fg"], baseline.selectionFg);
-  const semanticMappings = {
-    ...baseline.semanticMappings
-  };
-  if (c.semantic && typeof c.semantic === "object") {
-    for (const [key, val] of Object.entries(c.semantic)) {
-      if (typeof val === "number") {
-        semanticMappings[key] = val;
-      } else if (val === "bg" || val === "fg") {
-        semanticMappings[key] = val;
-      } else {
-        warnings.push(
-          `color.semantic.${key} has unsupported value ${JSON.stringify(val)}; kept baseline.`
-        );
+  const r = raw;
+  const base = parseOklchArray(r.base, BASE_RAMP_LENGTH, "color.ramps.base", warnings) ?? [...baseline.base];
+  const accent = parseOklchArray(r.accent, ACCENT_RAMP_LENGTH, "color.ramps.accent", warnings) ?? [...baseline.accent];
+  const state = parseState(r.state, baseline.state, warnings);
+  return { base, accent, state };
+}
+function parseOklchArray(raw, expectedLength, label, warnings) {
+  if (!Array.isArray(raw)) {
+    warnings.push(`${label}: expected an array of ${expectedLength} strings; kept baseline.`);
+    return null;
+  }
+  const strings = raw.filter((v) => typeof v === "string" && v.length > 0);
+  if (strings.length !== expectedLength || strings.length !== raw.length) {
+    warnings.push(
+      `${label}: expected ${expectedLength} non-empty string entries; got ${raw.length} (${strings.length} valid). Kept baseline.`
+    );
+    return null;
+  }
+  return strings;
+}
+function parseState(raw, baseline, warnings) {
+  const src = raw && typeof raw === "object" ? raw : {};
+  const out = {};
+  for (const role of STATE_ROLES) {
+    const v = src[role];
+    if (typeof v === "string" && v.length > 0) {
+      out[role] = v;
+    } else {
+      if (v !== void 0) {
+        warnings.push(`color.ramps.state.${role} is not a non-empty string; kept baseline.`);
       }
+      out[role] = baseline[role];
     }
   }
+  return out;
+}
+function parseMap(raw, baseline, warnings) {
+  if (raw === void 0) return cloneMap(baseline);
+  if (!raw || typeof raw !== "object") {
+    warnings.push("color.map is not an object; kept baseline map.");
+    return cloneMap(baseline);
+  }
+  const m = raw;
+  const semRaw = m.semantic && typeof m.semantic === "object" ? m.semantic : {};
+  const semantic = {};
+  for (const key of SEMANTIC_KEYS) {
+    semantic[key] = parseRef(semRaw[key], baseline.semantic[key], `color.map.semantic.${key}`, warnings);
+  }
   return {
-    palette,
-    background,
-    foreground,
-    cursor,
-    selectionBg,
-    selectionFg,
-    semanticMappings
+    bg: parseRef(m.bg, baseline.bg, "color.map.bg", warnings),
+    fg: parseRef(m.fg, baseline.fg, "color.map.fg", warnings),
+    selectionBg: parseRef(m.selectionBg, baseline.selectionBg, "color.map.selectionBg", warnings),
+    selectionFg: parseRef(m.selectionFg, baseline.selectionFg, "color.map.selectionFg", warnings),
+    semantic
   };
 }
+function parseRef(raw, fallback, label, warnings) {
+  if (raw === void 0) return cloneRef(fallback);
+  if (isValidRampRef(raw)) return cloneRef(raw);
+  warnings.push(`${label} is not a valid RampRef (${JSON.stringify(raw)}); kept baseline.`);
+  return cloneRef(fallback);
+}
+function isValidRampRef(v) {
+  if (typeof v === "string") return v.length > 0;
+  if (!v || typeof v !== "object") return false;
+  const o = v;
+  if ("base" in o) return isRampIndex(o.base);
+  if ("accent" in o) return isRampIndex(o.accent);
+  if ("state" in o) {
+    return typeof o.state === "string" && STATE_ROLES.includes(o.state);
+  }
+  return false;
+}
+function isRampIndex(v) {
+  return typeof v === "number" && Number.isInteger(v) && v >= 0;
+}
 function deserializeOverrides(raw, manifest, label, unknownTokens, warnings) {
   if (!raw || typeof raw !== "object") return emptyOverrides();
   const byVar = /* @__PURE__ */ new Map();
@@ -227,22 +262,80 @@ function deserializeOverrides(raw, manifest, label, unknownTokens, warnings) {
   }
   return out;
 }
-function numOr(v, fallback) {
-  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+function cloneRef(ref) {
+  return typeof ref === "string" ? ref : { ...ref };
+}
+function cloneRamps(ramps) {
+  return {
+    base: [...ramps.base],
+    accent: [...ramps.accent],
+    state: { ...ramps.state }
+  };
+}
+function cloneMap(map) {
+  const semantic = {};
+  for (const key of SEMANTIC_KEYS) {
+    semantic[key] = cloneRef(map.semantic[key]);
+  }
+  return {
+    bg: cloneRef(map.bg),
+    fg: cloneRef(map.fg),
+    selectionBg: cloneRef(map.selectionBg),
+    selectionFg: cloneRef(map.selectionFg),
+    semantic
+  };
+}
+function cloneScheme(scheme) {
+  return { ramps: cloneRamps(scheme.ramps), map: cloneMap(scheme.map) };
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (a && b && typeof a === "object" && typeof b === "object") {
+    const ao = a;
+    const bo = b;
+    const aKeys = Object.keys(ao);
+    const bKeys = Object.keys(bo);
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every((k) => Object.prototype.hasOwnProperty.call(bo, k) && deepEqual(ao[k], bo[k]));
+  }
+  return false;
 }
 function neutralColorDefaults() {
-  const palette = Array.from(
-    { length: 16 },
-    (_, i) => i === 0 ? "#000000" : i === 15 ? "#ffffff" : "#808080"
-  );
+  const base = [
+    "oklch(0.965 0 0)",
+    "oklch(0.705 0 0)",
+    "oklch(0.480 0 0)",
+    "oklch(0.300 0 0)",
+    "oklch(0.185 0 0)"
+  ];
+  const accent = [
+    "oklch(0.755 0 0)",
+    "oklch(0.700 0 0)",
+    "oklch(0.470 0 0)"
+  ];
   return {
-    palette,
-    background: 0,
-    foreground: 15,
-    cursor: 6,
-    selectionBg: 0,
-    selectionFg: 15,
-    semanticMappings: {}
+    ramps: {
+      base,
+      accent,
+      state: {
+        danger: "oklch(0.640 0.170 25)",
+        success: "oklch(0.680 0.145 145)",
+        warning: "oklch(0.760 0.135 82)",
+        info: "oklch(0.680 0.130 245)"
+      }
+    },
+    map: {
+      bg: { base: 4 },
+      fg: { base: 0 },
+      selectionBg: { base: 2 },
+      selectionFg: { base: 0 },
+      semantic: { ...SEMANTIC_RAMP_DEFAULTS }
+    }
   };
 }
 export {

package/dist/theme/design-token-types.d.ts

@@ -1,15 +1,11 @@
-export interface ColorTweakState {
-    palette: string[];
-    background: number;
-    foreground: number;
-    cursor: number;
-    selectionBg: number;
-    selectionFg: number;
-    semanticMappings: Record<string, number | "bg" | "fg">;
-}
+import type { ColorScheme } from "../color-scheme-utils.js";
+/** The per-scheme color state the design-token panel edits — a ramp-native
+ *  `ColorScheme`. Retained as a named alias so call sites reading
+ *  `ColorTweakState` keep compiling after the ramp restructure. */
+export type ColorTweakState = ColorScheme;
 export type TokenOverrides = Record<string, string>;
 export interface TweakState {
-    color: ColorTweakState;
+    color: ColorScheme;
     spacing: TokenOverrides;
     font: TokenOverrides;
     size: TokenOverrides;

package/dist/theme/index.d.ts

@@ -2,6 +2,6 @@ export { default as ThemeToggle } from "./theme-toggle.js";
 export { default as ColorSchemeProvider } from "./color-scheme-provider.js";
 export type { ColorSchemeProviderProps, ColorSchemeProviderColorMode, } from "./color-scheme-provider.js";
 export { default as ColorTweakExportModal } from "./color-tweak-export-modal.js";
-export { DESIGN_TOKEN_SCHEMA, DesignTokenSchemaError, deserialize, serialize, type DesignTokenJson, type DesignTokenJsonColor, type DesignTokenJsonColorBase, type DesignTokenJsonOverrides, type DesignTokenManifest, type DeserializeOptions, type DeserializeResult, type SerializeOptions, } from "./design-token-serde.js";
+export { DESIGN_TOKEN_SCHEMA, DesignTokenSchemaError, deserialize, serialize, type DesignTokenJson, type DesignTokenJsonColor, type DesignTokenJsonOverrides, type DesignTokenManifest, type DeserializeOptions, type DeserializeResult, type SerializeOptions, } from "./design-token-serde.js";
 export { emptyOverrides, type ColorTweakState, type TokenOverrides, type TweakState, } from "./design-token-types.js";
 export { BRIDGE_SOURCE, isBridgeMessage, installIframeReceiver, onIframeReady, sendApplyCssVars, sendClearCssVars, type BridgeMessage, type ApplyCssVarsMessage, type ClearCssVarsMessage, type ReadyMessage, type ErrorMessage, type CssVarPair, } from "./iframe-bridge.js";

package/dist/theme-toggle/color-scheme-sync.d.ts

@@ -14,19 +14,29 @@ export declare function readColorSchemeFromDom(defaultMode: ColorSchemeMode): Co
  *
  * Tweak-state reconciliation is intentionally NOT done here (#2037). The zdtp
  * panel owns its own storage lifecycle: it persists the unified tweak envelope
- * under `zudo-doc-tweak-state-v3` (auto-migrating the legacy
- * `zudo-doc-tweak-state-v2` / `zudo-doc-tweak-state` keys into it), and its own
- * `color-scheme-changed` listener clears applied inline styles and re-seeds the
- * color slice from the newly active scheme. An earlier version of this function
- * deleted `zudo-doc-tweak-state` + `-v2` on every toggle, which (a) targeted
- * stale keys after zdtp moved to v3 — so it no longer did anything — and
- * (b) when it did fire, wiped the whole envelope including scheme-independent
- * spacing/typography/size tweaks, contradicting the documented carry-over
- * guarantee. So the host no longer touches zdtp's private storage keys.
+ * under `zudo-doc-tweak-state-v4` (auto-migrating the legacy
+ * `zudo-doc-tweak-state-v3` / `-v2` / `zudo-doc-tweak-state` (v1) keys into
+ * it), and its own `color-scheme-changed` listener clears applied inline
+ * styles and re-seeds the color slice from the newly active scheme. An
+ * earlier version of this function deleted `zudo-doc-tweak-state` + `-v2` on
+ * every toggle, which (a) targeted stale keys after zdtp moved to v3 — so it
+ * no longer did anything — and (b) when it did fire, wiped the whole envelope
+ * including scheme-independent spacing/typography/size tweaks, contradicting
+ * the documented carry-over guarantee. So the host no longer touches zdtp's
+ * private storage keys.
  *
- * Whether palette tweaks should instead persist per-scheme (so a light/dark
- * round-trip keeps them) is a zdtp design question tracked upstream at
- * Takazudo/zudo-design-token-panel#343. See zudo-doc#2037.
+ * The design-token-panel bootstrap ALSO listens for this event and, on toggle,
+ * destroys + reconfigures the panel with the new mode's mode-scoped semantic
+ * DEFAULTS (see `design-token-panel-bootstrap.ts` + the host's
+ * `buildDesignTokenPanelConfig`, #2610). That keeps the panel's per-mode
+ * defaults faithful. A *saved* color OVERRIDE is still mode-agnostic here,
+ * though — not because zdtp can't key it per scheme (zdtp 0.4.5 ships
+ * per-scheme/per-mode keyed color persistence, v4 envelope,
+ * Takazudo/zudo-design-token-panel#500 / #509) but because THIS host's color
+ * cluster is scheme-less and switches modes externally (destroy + reconfigure
+ * above, not zdtp's own `colorMode` field), so zdtp always resolves the same
+ * single scheme identity and an override repaints both modes until Reset.
+ * See zudo-doc#2037 / #2610.
  */
 export declare function applyColorScheme(next: ColorSchemeMode): void;
 /**

package/eject/theme-toggle/color-scheme-sync.ts

@@ -42,19 +42,29 @@ export function readColorSchemeFromDom(
  *
  * Tweak-state reconciliation is intentionally NOT done here (#2037). The zdtp
  * panel owns its own storage lifecycle: it persists the unified tweak envelope
- * under `zudo-doc-tweak-state-v3` (auto-migrating the legacy
- * `zudo-doc-tweak-state-v2` / `zudo-doc-tweak-state` keys into it), and its own
- * `color-scheme-changed` listener clears applied inline styles and re-seeds the
- * color slice from the newly active scheme. An earlier version of this function
- * deleted `zudo-doc-tweak-state` + `-v2` on every toggle, which (a) targeted
- * stale keys after zdtp moved to v3 — so it no longer did anything — and
- * (b) when it did fire, wiped the whole envelope including scheme-independent
- * spacing/typography/size tweaks, contradicting the documented carry-over
- * guarantee. So the host no longer touches zdtp's private storage keys.
+ * under `zudo-doc-tweak-state-v4` (auto-migrating the legacy
+ * `zudo-doc-tweak-state-v3` / `-v2` / `zudo-doc-tweak-state` (v1) keys into
+ * it), and its own `color-scheme-changed` listener clears applied inline
+ * styles and re-seeds the color slice from the newly active scheme. An
+ * earlier version of this function deleted `zudo-doc-tweak-state` + `-v2` on
+ * every toggle, which (a) targeted stale keys after zdtp moved to v3 — so it
+ * no longer did anything — and (b) when it did fire, wiped the whole envelope
+ * including scheme-independent spacing/typography/size tweaks, contradicting
+ * the documented carry-over guarantee. So the host no longer touches zdtp's
+ * private storage keys.
  *
- * Whether palette tweaks should instead persist per-scheme (so a light/dark
- * round-trip keeps them) is a zdtp design question tracked upstream at
- * Takazudo/zudo-design-token-panel#343. See zudo-doc#2037.
+ * The design-token-panel bootstrap ALSO listens for this event and, on toggle,
+ * destroys + reconfigures the panel with the new mode's mode-scoped semantic
+ * DEFAULTS (see `design-token-panel-bootstrap.ts` + the host's
+ * `buildDesignTokenPanelConfig`, #2610). That keeps the panel's per-mode
+ * defaults faithful. A *saved* color OVERRIDE is still mode-agnostic here,
+ * though — not because zdtp can't key it per scheme (zdtp 0.4.5 ships
+ * per-scheme/per-mode keyed color persistence, v4 envelope,
+ * Takazudo/zudo-design-token-panel#500 / #509) but because THIS host's color
+ * cluster is scheme-less and switches modes externally (destroy + reconfigure
+ * above, not zdtp's own `colorMode` field), so zdtp always resolves the same
+ * single scheme identity and an override repaints both modes until Reset.
+ * See zudo-doc#2037 / #2610.
  */
 export function applyColorScheme(next: ColorSchemeMode): void {
   document.documentElement.setAttribute("data-theme", next);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takazudo/zudo-doc",
-  "version": "2.5.1",
+  "version": "3.0.0",
   "type": "module",
   "description": "zudo-doc framework primitives layer that sits on top of zfb's engine — sidebar, theme, TOC, breadcrumb, layouts, head injection, View Transitions, SSR-skip wrappers (per ADR-003).",
   "license": "MIT",
@@ -542,8 +542,8 @@
     "preact": "^10.29.1",
     "@takazudo/zfb": "^0.1.0-next.76",
     "@takazudo/zfb-runtime": "^0.1.0-next.76",
-    "@takazudo/zudo-doc-history-server": "^2.2.1",
-    "@takazudo/zdtp": "^0.4.2",
+    "@takazudo/zudo-doc-history-server": "^3.0.0",
+    "@takazudo/zdtp": "^0.4.5",
     "shiki": "^4.0.2",
     "zod": "^4.3.6",
     "katex": "^0.16.0",
@@ -586,7 +586,7 @@
     "zod": "^4.3.6",
     "@takazudo/zfb": "0.1.0-next.76",
     "@takazudo/zfb-runtime": "0.1.0-next.76",
-    "@takazudo/zudo-doc-history-server": "2.5.1"
+    "@takazudo/zudo-doc-history-server": "3.0.0"
   },
   "scripts": {
     "build": "tsup && tsc -p tsconfig.build.json",