@takazudo/zdtp 0.4.4 → 0.4.6

package/dist/server/create-apply-handler.d.ts

@@ -22,6 +22,12 @@ export interface PerFileResult {
     changed: string[];
     unchanged: string[];
     unknown: string[];
+    /**
+     * Subset of `unknown` (#508): declared somewhere in the file but outside
+     * the scanned `:root`/`@theme` blocks — see `ApplyResult.unknownOutsideBlock`
+     * in `apply-token-overrides.ts` for the full classification rules.
+     */
+    unknownOutsideBlock: string[];
 }
 /**
  * Create a framework-agnostic Fetch API handler for the design-token apply

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { C as s, c as i, i as l, a as r, l as t, s as o, v as d } from "../load-routing-DtNTKoLW.js";
+import { C as s, c as i, i as l, a as r, l as t, s as o, v as d } from "../load-routing-LJ72261l.js";
 export {
   s as CSS_VAR_NAME_RE,
   i as createApplyHandler,

package/dist/state/tweak-state.d.ts

@@ -80,6 +80,12 @@ export type { TabOverrides } from '../apply/tier-resolver';
 export declare function getStorageKeyV1(cfg?: PanelConfig): string;
 export declare function getStorageKeyV2(cfg?: PanelConfig): string;
 export declare function getStorageKeyV3(cfg?: PanelConfig): string;
+/**
+ * v4 unified envelope key — the per-scheme-keyed color format (#500/#509).
+ * See `storageKey_stateV4` for the shape rationale. Read first by
+ * `loadPersistedState`; v1/v2/v3 migrate into it on first load.
+ */
+export declare function getStorageKeyV4(cfg?: PanelConfig): string;
 export declare function getOpenKey(cfg?: PanelConfig): string;
 export declare function getPositionKey(cfg?: PanelConfig): string;
 export declare function getSizeKey(cfg?: PanelConfig): string;
@@ -258,6 +264,32 @@ export interface TweakState {
     /** Generic tab overrides keyed by tab id. Added in v3 envelope. */
     tabs?: Record<string, TabOverrides>;
 }
+/**
+ * On-disk v4 persist envelope (#500/#509). Same top-level slices as the runtime
+ * `TweakState`, EXCEPT the `color` and `secondary` slices are identity-keyed
+ * sub-objects: one `ColorTweakState` slot per active-color IDENTITY (see
+ * `getActiveColorIdentity`). This is what lets a per-scheme color tweak survive
+ * a scheme toggle — editing under scheme A never touches scheme B's slot.
+ *
+ * The non-color slices (`spacing` / `typography` / `size` / `tabs`) stay global
+ * and unkeyed, exactly as in v1–v3: a light/dark toggle does not change them.
+ *
+ * `secondary` slots are keyed by the SAME primary identity — the secondary
+ * cluster has no scheme of its own but reseeds on the same `color-scheme-changed`
+ * event, so it follows the primary's identity.
+ *
+ * `loadPersistedState` selects the active identity's slots into a runtime
+ * `TweakState`; `savePersistedState` merge-saves the active slots while
+ * preserving every inactive identity's slot.
+ */
+export interface PersistedEnvelopeV4 {
+    color: Record<string, ColorTweakState>;
+    secondary?: Record<string, ColorTweakState>;
+    spacing: TokenOverrides;
+    typography: TokenOverrides;
+    size: TokenOverrides;
+    tabs?: Record<string, TabOverrides>;
+}
 /** Produce an empty overrides map — `TweakState` default for new tabs. */
 export declare function emptyOverrides(): TokenOverrides;
 /**
@@ -360,6 +392,24 @@ export declare function getActiveSchemeName(cluster?: ColorClusterDataConfig, cf
  *   is the correct behavior for non-sink instances but wrong for sinks.
  */
 export declare function initColorFromScheme(cluster?: ColorClusterDataConfig, cfg?: PanelConfig): ColorTweakState;
+/**
+ * Derive the active-color IDENTITY — the key under which the v4 envelope files
+ * this instance's `color` / `secondary` slots (#500/#509).
+ *
+ * The identity is EXACTLY the active scheme name `initColorFromScheme` resolves
+ * for the primary cluster via `getActiveSchemeName` (the active scheme, with the
+ * light/dark mode already folded into the resolved name where the cluster
+ * `panelSettings.colorMode` distinguishes modes). This is deliberate: the same
+ * inputs whose change triggers a reseed today produce the identity, so the
+ * invariant holds — *the same identity that causes a reseed selects its own
+ * persisted slot*. A colorMode-less cluster resolves a constant identity (one
+ * slot); a light/dark cluster resolves distinct identities per side.
+ *
+ * The secondary cluster has no scheme concept of its own but reseeds on the same
+ * `color-scheme-changed` event, so its slots are keyed by this SAME primary
+ * identity — callers pass the PRIMARY cluster here for both slices.
+ */
+export declare function getActiveColorIdentity(cluster?: ColorClusterDataConfig, cfg?: PanelConfig): string;
 /**
  * Palette entry sanitiser. Raw `oklch(...)` values are preserved verbatim so
  * wide-gamut chroma survives (and they never touch the canvas → no '#000000'
@@ -438,8 +488,17 @@ export declare function resolveSemanticPreviewColor(mapping: SemanticValue, stat
  * for an unresolvable ref rather than throwing, and this function skips a
  * `null` (leaving the token at its stylesheet default) rather than painting
  * a fallback color.
+ *
+ * `ownerPrefix` (#501) is the instance `storagePrefix` this apply belongs to.
+ * When supplied AND this cluster emits a per-mode `light-dark()` literal (so
+ * `color-scheme: light dark` is written to the apply target — either
+ * `document.documentElement` or the sink's root), the instance is recorded as
+ * the owner of that inline `color-scheme` so the clear paths can later remove
+ * it without ever wiping a host-owned `<html style="color-scheme">`. Omitting
+ * it (direct callers with no instance context, e.g. some tests) skips the
+ * bookkeeping only — the actual CSS write is unchanged.
  */
-export declare function applyColorState(state: ColorTweakState, cluster?: ColorClusterDataConfig, sink?: ApplySink, currentTab?: TabConfig, tabs?: readonly TabConfig[]): void;
+export declare function applyColorState(state: ColorTweakState, cluster?: ColorClusterDataConfig, sink?: ApplySink, currentTab?: TabConfig, tabs?: readonly TabConfig[], ownerPrefix?: string): void;
 /**
  * Apply a `TokenOverrides` map for a given manifest — writes inline
  * `--css-var: value` on `:root` for every overridden token, and removes the
@@ -450,6 +509,31 @@ export declare function applyColorState(state: ColorTweakState, cluster?: ColorC
  * in the UI and are never written to storage.
  */
 export declare function applyTokenOverrides(tokens: readonly TokenDef[], overrides: TokenOverrides, sink?: ApplySink): void;
+/**
+ * Apply ONLY the color slices — primary color cluster + optional secondary
+ * cluster + the aggregate `color-scheme` decision — leaving spacing / font /
+ * size / generic-tab vars untouched.
+ *
+ * Extracted from `applyFullState` (#500/#509) so the scheme-change handler can
+ * re-paint the new identity's persisted color overrides after
+ * `clearAppliedColorStyles` WITHOUT re-writing (or clearing) the scheme-
+ * independent non-color vars that must survive a light/dark toggle (#347).
+ *
+ * `color-scheme` is managed as an AGGREGATE across the primary + secondary
+ * clusters, not per-cluster (#482 D3): `applyColorState` only ever SETS
+ * `color-scheme: light dark` when its OWN cluster needs it, it never clears
+ * it, so demoting the last per-mode-literal row (in either cluster) would
+ * otherwise leave the previous apply's value stale. A naive per-cluster
+ * clear inside `applyColorState` would let a per-mode-free secondary undo
+ * what the primary just required (or vice versa), so the clear-when-neither-
+ * needs-it decision is made here, once, after both clusters have applied.
+ *
+ * #501 — the `document.documentElement` clear is scoped to a color-scheme THIS
+ * instance actually wrote (`clearOwnedColorSchemeFromDocument`) so a host that
+ * owns `<html style="color-scheme">` is never clobbered; the sink path stays
+ * unconditional (sink targets are panel-owned) but drops the ownership claim.
+ */
+export declare function applyColorSlices(color: ColorTweakState, secondary: ColorTweakState | undefined, cfg?: PanelConfig): void;
 /**
  * Apply the full unified `TweakState` — primary color cluster + token
  * overrides + optional secondary cluster.
@@ -462,16 +546,26 @@ export declare function applyTokenOverrides(tokens: readonly TokenDef[], overrid
  * CSS-var writes for this instance. Omitting `cfg` uses the default active
  * config (single-panel path, unchanged behavior).
  *
- * `color-scheme` is managed as an AGGREGATE across the primary + secondary
- * clusters, not per-cluster (#482 D3): `applyColorState` only ever SETS
- * `color-scheme: light dark` when its OWN cluster needs it, it never clears
- * it, so demoting the last per-mode-literal row (in either cluster) would
- * otherwise leave the previous apply's value stale. A naive per-cluster
- * clear inside `applyColorState` would let a per-mode-free secondary undo
- * what the primary just required (or vice versa), so the clear-when-neither-
- * needs-it decision is made here, once, after both clusters have applied.
+ * The color slices + aggregate `color-scheme` decision are delegated to
+ * `applyColorSlices`; this function adds the non-color (spacing / font / size /
+ * generic-tab) writes.
  */
 export declare function applyFullState(state: TweakState, cfg?: PanelConfig): void;
+/**
+ * Apply ONLY the non-color slices (spacing / typography / size / generic-tab
+ * overrides), leaving the color clusters and aggregate `color-scheme` decision
+ * untouched. Complement of `applyColorSlices`; together they compose
+ * `applyFullState`.
+ *
+ * Extracted (#509 audit) so the persisted-overrides reapply paths
+ * (`reapplyPersistedOverrides`, the panel first-open effect) can, when a v4
+ * envelope exists but the ACTIVE (scheme, mode) identity has no color slot,
+ * still apply the scheme-INDEPENDENT non-color tweaks while leaving the active
+ * scheme's own stylesheet colors to show through — instead of painting the
+ * synthesized config-default colors inline. This mirrors the scheme-change
+ * handler's missing-slot behavior (gated on `hasActiveColorSlot`).
+ */
+export declare function applyNonColorSlices(state: TweakState, cfg?: PanelConfig): void;
 /**
  * Strip the inline CSS variables written by the color cluster(s) only —
  * palette slots, base roles, and semantic vars. Spacing / typography / size
@@ -495,6 +589,11 @@ export declare function applyFullState(state: TweakState, cfg?: PanelConfig): vo
  * historical `(clusters, sink)` call shape (e.g. the scheme-change path before
  * #357, and existing tests) is unchanged. Omitting all three preserves the
  * single-panel default-instance behaviour.
+ *
+ * The color-scheme removal on the `document.documentElement` path is gated on
+ * this instance owning the inline value (#501) — see
+ * `clearOwnedColorSchemeFromDocument`. The owner is `cfg.storagePrefix` when a
+ * `cfg` is given, else the default instance's prefix.
  */
 export declare function clearAppliedColorStyles(clusters?: readonly ColorClusterDataConfig[], sink?: ApplySink, cfg?: PanelConfig): void;
 /**
@@ -560,17 +659,41 @@ export interface StorageLike {
  * labels), so this migration only applies to the typography slice.
  */
 export declare const ZDTP_LEGACY_TYPOGRAPHY_RENAME_MAP: Readonly<Record<string, string | null>>;
+/**
+ * True when the v4 envelope holds a color slot for the CURRENTLY active
+ * identity. The scheme-change handler uses this to decide whether to hydrate +
+ * apply persisted overrides for the new scheme (slot present) or reseed from
+ * config defaults WITHOUT applying (slot absent — the pre-#500 behavior that
+ * lets the new scheme's stylesheet show through).
+ */
+export declare function hasActiveColorSlot(cfg?: PanelConfig, cluster?: ColorClusterDataConfig, storage?: StorageLike): boolean;
+/**
+ * Load the active `TweakState`, preferring the v4 per-scheme envelope
+ * (#500/#509).
+ *
+ * Order:
+ *   1. v4 present → select the active identity's color/secondary slots.
+ *   2. else run the legacy v1/v2/v3 chain (unchanged) → migrate that state into
+ *      a v4 envelope filed under the identity active at load, WITHOUT deleting
+ *      the legacy key (v4 wins on every future load via step 1). This is why the
+ *      pre-existing v1/v2/v3 migration tests keep passing: the legacy chain still
+ *      writes/keeps the v3 key exactly as before; v4 is layered on top.
+ *   3. else null (caller cold-seeds).
+ *
+ * A present-but-malformed v4 blob falls through to steps 2/3, which overwrite it.
+ */
 export declare function loadPersistedState(storage?: StorageLike, colorDefaults?: ColorTweakState, cluster?: ColorClusterDataConfig, cfg?: PanelConfig): TweakState | null;
 /**
- * Persist the full `TweakState` to v3.
+ * Merge-save the full `TweakState` into the v4 per-scheme envelope (#500/#509).
  *
- * `cfg` scopes the storage key to a specific panel instance (multi-instance,
- * #357). Omitting it resolves the default instance via `getPanelConfig()`,
- * preserving the single-panel path.
+ * The active identity's color/secondary slots are overwritten; every inactive
+ * identity's slot is preserved (read → merge → write). Global non-color slices
+ * are replaced wholesale. `cfg` scopes the storage key to a specific panel
+ * instance (multi-instance, #357).
  */
 export declare function savePersistedState(state: TweakState, storage?: StorageLike, cfg?: PanelConfig): void;
 /**
- * Remove v3 (and lingering v2/v1) keys.
+ * Remove the v4 key (and lingering v3/v2/v1 keys).
  *
  * `cfg` scopes the cleared keys to a specific panel instance (multi-instance,
  * #357). Omitting it resolves the default instance via `getPanelConfig()`,

package/dist/tabs/notes-tab.d.ts

@@ -0,0 +1,25 @@
+import type { TabConfig } from '../tokens/tier-model';
+interface NotesTabProps {
+    tab: TabConfig;
+}
+/**
+ * Notes tab — host-configurable "token notes" landing view (#515).
+ *
+ * Renders `tab.notesExtras.title` as a section heading
+ * (`div[role="heading"][aria-level=3]`, NEVER an hN tag — see
+ * packages/zdtp/CLAUDE.md "Panel DOM hygiene") and `tab.notesExtras.html` as
+ * sanitized HTML via `dangerouslySetInnerHTML` — the package's first and only
+ * use of it. `sanitizeHtml` (utils/sanitize-html.ts) is the security
+ * boundary, an allowlist parser, not this component and not the CSS below.
+ *
+ * The rendered `.tokenpanel-notes-body` subtree is HOST-AUTHORED PROSE
+ * CONTENT, not panel chrome: the DOM-hygiene ban on h1-h6/p/ul/a/table/etc.
+ * applies to the panel's OWN JSX, and does not apply inside sanitized note
+ * content — that's exactly the markup a "notes" feature needs to render.
+ *
+ * `assertValidPanelConfig` requires `notesExtras` (non-empty title + html)
+ * on every tab with `id: 'notes'`, so this component can assume it's
+ * present without a runtime fallback UI.
+ */
+export default function NotesTab({ tab }: NotesTabProps): import("preact").JSX.Element | null;
+export {};

package/dist/testing.js

@@ -1,5 +1,5 @@
-import { _ as r, c as i, f as _, h as n, i as g, b as R, a as p } from "./panel-config-CXTCcYQs.js";
-import { a as l, b as y, l as O } from "./tweak-state-BeXkzoj8.js";
+import { _ as r, c as _, h as i, j as n, k as g, b as R, a as p } from "./panel-config-Bw7D-25C.js";
+import { a as y, b as O, l as P } from "./tweak-state-CD1y56zR.js";
 import { F as K, G as E, a as S, S as u } from "./manifest-DCReQE0k.js";
 async function s(a, e) {
   await a.fill(e), await a.dispatchEvent("input");
@@ -10,12 +10,12 @@ export {
   S as GROUP_TITLES,
   u as SIZE_GROUP_ORDER,
   r as __resetPanelConfigForTests,
-  i as configurePanel,
-  l as getStorageKeyV1,
-  y as getStorageKeyV2,
-  O as loadPersistedState,
+  _ as configurePanel,
+  y as getStorageKeyV1,
+  O as getStorageKeyV2,
+  P as loadPersistedState,
   s as setPanelInputValue,
-  _ as storageKey_open,
+  i as storageKey_open,
   n as storageKey_position,
   g as storageKey_stateV1,
   R as storageKey_stateV2,

package/dist/tokens/manifest.d.ts

@@ -60,6 +60,14 @@ export interface TokenDef {
     step: number;
     /** Unit suffix (e.g. `rem`, `px`). Read-only rows may use an empty string. */
     unit: string;
+    /**
+     * Optional list of unit suffixes this row may cycle through by clicking
+     * the unit label (#519). 2+ entries opts in; omitted/single-entry keeps
+     * today's static, non-interactive unit suffix. Mirrors `TierValueKind`'s
+     * `length.units` — the default-slider mapping in a host's
+     * `toTierItem()`-style helper should pass it straight through.
+     */
+    units?: readonly string[];
     /** Read-only tokens are displayed but not editable (e.g. `clamp()` expressions). */
     readonly?: true;
     /** Which control renders this token. Defaults to `"slider"` when absent. */

package/dist/tokens/tier-model.d.ts

@@ -4,6 +4,16 @@ export type TierValueKind = {
     kind: 'length';
     step: number;
     unit: string;
+    /**
+     * Optional list of unit suffixes this row may cycle through by
+     * clicking the unit label (#519). 2+ entries opts the row into an
+     * interactive, click/Enter/Space-cycling unit suffix (wrapping through
+     * the list); omitted or a single entry keeps today's static,
+     * non-interactive unit span, pixel-identical. This kind is reused for
+     * ms durations and unitless values too — only declare `units` when
+     * cycling between those suffixes is valid CSS for the token.
+     */
+    units?: readonly string[];
 } | {
     kind: 'number';
     step: number;
@@ -132,10 +142,36 @@ export interface ColorClusterExtras {
     defaultShikiTheme: string;
     colorSchemes: Record<string, ColorScheme>;
     panelSettings: ClusterPanelSettings;
+    /**
+     * Config-time override map for a semantic tier's derived defaults (#499).
+     * Keyed by semantic item id; when a key is present here,
+     * `resolveColorClusterFromTab` uses its `SemanticValue` verbatim instead of
+     * running `deriveSemanticValue` on the item's plain-string `default` — this
+     * is the only way a host can ship a `{ literal: { light, dark } }` (or
+     * `{ ref }`) config-time default, since `TierItem.default` itself stays a
+     * plain string (Option B from #499, chosen over widening `TierItem.default`
+     * to `SemanticValue` — that field is consumed generically as a plain string
+     * by every tab kind, not just Color).
+     */
+    semanticDefaults?: Record<string, SemanticValue>;
+}
+/**
+ * Host-configurable "token notes" content — ONLY valid on the reserved
+ * `id: 'notes'` pseudo-tab (#515). That tab renders `title` as a section
+ * heading and `html` (sanitized by `utils/sanitize-html.ts`) as its body,
+ * instead of a tier-driven token editor. `assertValidPanelConfig` enforces
+ * the full contract: required + non-empty on `id: 'notes'`, forbidden on
+ * every other tab id, and `id: 'notes'` tabs must ship `tiers: []` and no
+ * `colorExtras`.
+ */
+export interface NotesExtras {
+    title: string;
+    html: string;
 }
 export interface TabConfig {
     id: string;
     label: string;
     tiers: readonly TierConfig[];
     colorExtras?: ColorClusterExtras;
+    notesExtras?: NotesExtras;
 }