@takazudo/zdtp 0.4.11 → 0.4.13

package/CHANGELOG.md

@@ -1,6 +1,83 @@
 # Changelog
 
-## 0.4.11
+All notable changes to `@takazudo/zdtp` are documented in this file.
+
+The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
+
+## [0.4.13] - 2026-08-29
+
+### Features
+
+- feat(zdtp): normalize static CSS colors (20567e7)
+
+### Fixed
+
+- fix(zdtp): expose readonly swatches as selectable (c3c8c28)
+- fix(zdtp): restrict referencesRamps to Color tabs (8894399)
+- fix(zdtp): enforce readonly Palette editing (5c2445c)
+- fix(zdtp): guard palette validity transitions (73a59fb)
+- fix(zdtp): preserve invalid palette slots as n-a (0e456e5)
+- fix(doc): align preview with latest zfb (9cd81bb)
+
+### Other Changes
+
+- Merge pull request [#636](https://github.com/Takazudo/zudo-design-token-panel/pull/636) from Takazudo/base/sweep-260829: fix(zdtp): correct Palette behavior and public contracts (db3ee47)
+- docs(zdtp): document referencesRamps tab restriction (555b562)
+- Merge pull request [#645](https://github.com/Takazudo/zudo-design-token-panel/pull/645) from Takazudo/base/sweep-260829-portable-contract-docs: fix(zdtp): align portable contracts and ramp validation (452fc32)
+- Merge topic/630-reference-color-mode-docs (7abfa37)
+- docs: clarify reference emission and color modes (f447a99)
+- Merge topic/632-references-ramps-color-tabs (7df5b55)
+- Merge topic/631-required-write-root-docs (ae76e2b)
+- Merge topic/629-shipped-semantic-contract (0ba0294)
+- docs(zdtp): sync shipped semantic tier contract (4bbc5d5)
+- docs: require write-root in apply guidance (10c76b1)
+- Merge pull request [#640](https://github.com/Takazudo/zudo-design-token-panel/pull/640) from Takazudo/base/sweep-260829-palette-correctness: fix(zdtp): correct Palette color and readonly behavior (36c0972)
+- Merge branch 'topic/626-palette-readonly' into base/sweep-260829-palette-correctness (53575d9)
+- Merge branch 'topic/625-palette-invalid-na' into base/sweep-260829-palette-correctness (73c2c6c)
+- Merge branch 'topic/624-static-css-color-normalization' into base/sweep-260829-palette-correctness (858c131)
+- Merge pull request [#635](https://github.com/Takazudo/zudo-design-token-panel/pull/635) from Takazudo/base/sweep-260829-zudo-dependency-refresh: chore(doc): refresh stable zudo dependencies (db555eb)
+- Merge branch 'topic/621-zudo-dependency-family' into base/sweep-260829-zudo-dependency-refresh (16ed6cd)
+- chore(doc): bump stable zudo dependency family (579671a)
+- Merge pull request [#615](https://github.com/Takazudo/zudo-design-token-panel/pull/615) from Takazudo/fix/populate-doc-changelog-20260823: docs: populate changelog release history (9ce99a1)
+- docs: clarify changelog source and locale history (7a0c194)
+- docs: populate changelog release history (559a9c5)
+- Merge pull request [#614](https://github.com/Takazudo/zudo-design-token-panel/pull/614) from Takazudo/agent-fix/zdtp-lint-warnings-20260823: chore: resolve zdtp lint warnings (9f16688)
+- chore: resolve zdtp lint warnings (ed175ca)
+- Merge pull request [#612](https://github.com/Takazudo/zudo-design-token-panel/pull/612) from Takazudo/agent-fix/actions-cache-node24-20260823: ci: update actions/cache to Node 24 (ab0ad0d)
+- ci: update actions/cache to Node 24 (234459b)
+- Merge pull request [#610](https://github.com/Takazudo/zudo-design-token-panel/pull/610) from Takazudo/chore/bump-zudo-deps-20260823: chore(doc): update zudo stack and preview wiring (d6d0d54)
+- chore(doc): bump zudo dependencies (6d50555)
+
+## [0.4.12] - 2026-08-20
+
+### Fixed
+
+- fix(doc): stabilize generated skill links (142420c)
+
+### Other Changes
+
+- Merge pull request [#599](https://github.com/Takazudo/zudo-design-token-panel/pull/599) from Takazudo/base/sweep-260820: Complete portable storage and documentation refresh (1d78e89)
+- Merge pull request [#609](https://github.com/Takazudo/zudo-design-token-panel/pull/609) from Takazudo/base/sweep-260820-zudo-doc-refresh: Refresh documentation site on zudo-doc 5.7 (157d736)
+- Merge topic/zudo-doc-integration into zudo-doc refresh epic (5c199a0)
+- Merge topic/zudo-doc-content into zudo-doc refresh epic (0b14ccf)
+- docs: fix reviewed cross-locale links (0bc0081)
+- docs: migrate bilingual zudo content (c572f05)
+- Merge topic/zudo-doc-branding into zudo-doc refresh epic (e2e2cca)
+- Brand zudo-doc hero and social metadata (b5c625f)
+- Merge topic/zudo-doc-foundation-gate into zudo-doc refresh epic (68784c3)
+- Harden deploy audit against missing workspaces (30c12c0)
+- Fix deploy audit panel workspace filter (b494335)
+- Merge topic/zudo-doc-scaffold into zudo-doc refresh epic (a0addac)
+- Avoid missing branded favicon asset (f73995e)
+- Rescaffold docs with zudo-doc 5.7 (6079124)
+- = start zudo-doc refresh epic = [skip ci] (e3479d5)
+- Merge pull request [#608](https://github.com/Takazudo/zudo-design-token-panel/pull/608) from Takazudo/base/sweep-260820-portable-storage-contract: Sync portable storage contract to state-v4 (b7997de)
+- Merge branch 'topic/portable-contract-v4' into base/sweep-260820-portable-storage-contract (e6a27b8)
+- docs(zdtp): document v4 portable storage contract (511f6fe)
+- = start portable storage contract epic = [skip ci] (1605c3e)
+- = start sweep-260820 super-epic = [skip ci] (c29cc50)
+
+## [0.4.11] - 2026-08-19
 
 ### Features
 
@@ -27,7 +104,7 @@
 - test: complete the lazy-load gate decision-matrix coverage ([#591](https://github.com/Takazudo/zudo-design-token-panel/pull/591)) (76cb4a3)
 - test: confirm multi-instance spawn geometry in a real browser ([#595](https://github.com/Takazudo/zudo-design-token-panel/pull/595)) (11988d6)
 
-## 0.4.10
+## [0.4.10] - 2026-08-10
 
 ### Fixed
 
@@ -40,7 +117,7 @@
 - docs: migrate the doc site to zudo-doc 4.x — S1–S6 series ([#556](https://github.com/Takazudo/zudo-design-token-panel/pull/556)–[#562](https://github.com/Takazudo/zudo-design-token-panel/pull/562)) (e2f36b5, 51c674c, ff38109, e36e718, e7838fb, c20cc83, f89a6bf)
 - docs(l-make-release): auto-proceed Step 3 gate for routine bumps (45a5aca)
 
-## 0.4.9
+## [0.4.9] - 2026-07-13
 
 ### Features
 
@@ -59,7 +136,7 @@
 - test: record color picker close control VRT (aa66eba)
 - chore: start panel UI tweaks 540 (57fb4c7)
 
-## 0.4.8
+## [0.4.8] - 2026-07-13
 
 ### Features
 
@@ -71,7 +148,7 @@
 - chore(dom-tweaker): remove consumed prototype resource ([#539](https://github.com/Takazudo/zudo-design-token-panel/pull/539)) (9a0ac51)
 - docs(l-make-release): add autonomy-after-the-gate principle (7f64206)
 
-## 0.4.7
+## [0.4.7] - 2026-07-12
 
 ### Fixed
 
@@ -81,7 +158,7 @@
 
 - chore(deps): resolve 19 pnpm audit security advisories ([#525](https://github.com/Takazudo/zudo-design-token-panel/pull/525)) (80c9a0e)
 
-## 0.4.6
+## [0.4.6] - 2026-07-12
 
 ### Features
 
@@ -105,7 +182,7 @@
 - test: VRT baselines re-recorded for zdtp title + square corners; broad coverage added for notes tab, help icons, unit cycling
 - chore: removed consumed `_temp-resource/` prototype scaffold (ccbd18a)
 
-## 0.4.5
+## [0.4.5] - 2026-07-07
 
 ### Features
 
@@ -127,7 +204,7 @@
 - docs: truth-up schemaId docs, tighten Import modal copy, export `SCHEMA_V1`/`SCHEMA_V2`/`SCHEMA_V3` ([#505](https://github.com/Takazudo/zudo-design-token-panel/issues/505)) (8088281)
 - docs: replace zmodular references with Takazudo Modular markdown links (afcfea2)
 
-## 0.4.4
+## [0.4.4] - 2026-07-06
 
 ### Features
 
@@ -173,7 +250,7 @@
 - chore(deps): bump `@takazudo/zudo-doc` and `zudo-doc-history-server` to `^2.5.1` (d6c05dd)
 - chore(doc): sync generated `claude/index.mdx` with build output (d763238)
 
-## 0.4.3
+## [0.4.3] - 2026-07-04
 
 ### Features
 
@@ -205,7 +282,7 @@
 - Browser test files now run serially — parallel files share one origin and raced each other's localStorage (fd37774)
 - Deps: bump @takazudo/* toolchain (zfb next.76, zudo-doc 2.5.0) (62b62f6)
 
-## 0.4.2
+## [0.4.2] - 2026-06-30
 
 ### Features
 
@@ -236,13 +313,13 @@
 - Bump the `@takazudo/*` toolchain (zfb next.72, zudo-doc 2.1.2). (d711839)
 - Doc-site migration to zudo-doc v2 — doc-site only, no package impact. ([#432](https://github.com/Takazudo/zudo-design-token-panel/pull/432))
 
-## 0.4.1
+## [0.4.1] - 2026-06-30
 
 ### Fixed
 
 - **Palette tab no longer renders unstyled for self-injection consumers.** The 0.4.0 palette-tab CSS (`palette-chart` / `palette-edit` / `palette-readout`) reached `dist/zdtp.css` but was missing from the stylesheet the panel self-injects at runtime, so consumers using `import('@takazudo/zdtp')` + `configurePanel(...)` without importing `@takazudo/zdtp/styles` saw collapsed swatch bars and a missing curve-editor canvas. The two palette stylesheets are now `@import`ed into the single `panel.css` aggregate (matching `color-picker.css`) so both CSS delivery paths stay in sync, guarded by a new static `Invariant G` test. ([#413](https://github.com/Takazudo/zudo-design-token-panel/issues/413))
 
-## 0.4.0
+## [0.4.0] - 2026-06-29
 
 ### Features
 
@@ -260,7 +337,7 @@
 - Integration + serde + browser-confirm test coverage for the palette tab. ([#396](https://github.com/Takazudo/zudo-design-token-panel/issues/396))
 - Add a grouped palette tab recipe + reference docs (EN + JA). ([#397](https://github.com/Takazudo/zudo-design-token-panel/issues/397))
 
-## 0.3.3
+## [0.3.3] - 2026-06-23
 
 ### Features
 
@@ -279,7 +356,7 @@
 
 - Add an end-to-end test asserting the oklch round-trip (panel `onChange` + apply path both emit `oklch(...)`) and wide-gamut P3 preservation. ([#379](https://github.com/Takazudo/zudo-design-token-panel/issues/379)) (0595f28)
 
-## 0.3.2
+## [0.3.2] - 2026-06-23
 
 ### Fixed
 
@@ -287,7 +364,7 @@
 
 - **Dedupe the reserved toggle event across listeners.** When a custom-prefix host opts into the reserved `toggle-design-token-panel` name via `config.toggleEvent`, both the eager default listener and the instance's own listener fired on one dispatch and resolved to the same instance — toggling it twice (open, then immediately close). The handler now dedupes per dispatch by resolved instance id carried on the shared Event object, so the panel opens exactly once. ([#371](https://github.com/Takazudo/zudo-design-token-panel/pull/371))
 
-## 0.3.1
+## [0.3.1] - 2026-06-23
 
 ### Fixed
 
@@ -295,7 +372,7 @@
 
 - **Skip the bin integration test suite when `dist/bin/server.js` is absent.** `server.integration.test.ts` spawns the built bin and previously threw in `beforeAll` when it was missing, failing the `node` vitest project on a fresh checkout (before a build). It now gates the suite with `describe.skipIf` on build presence (with a console warning) instead of hard-failing; CI builds before testing, so the suite still runs there. ([#360](https://github.com/Takazudo/zudo-design-token-panel/issues/360))
 
-## 0.3.0
+## [0.3.0] - 2026-06-22
 
 ### Features
 
@@ -307,7 +384,7 @@
 
 - **`PanelConfig.applySink`.** An optional `{ apply(pairs), clear(names) }` sink routes this instance's CSS-var writes and clears through a caller-supplied object instead of `document.documentElement`. Useful for shadow DOM, iframe, or test-spy contexts. `apply` = upsert; `clear` = remove. Reset sends the full token-name set for the instance to `sink.clear` so the sink target is completely cleaned. Sink errors are non-fatal (`console.warn`). The host owns the sink target's lifecycle. `applySink` carries function references and must not be passed through the Astro inline JSON config. ([#355](https://github.com/Takazudo/zudo-design-token-panel/issues/355))
 
-## 0.2.3
+## [0.2.3] - 2026-06-15
 
 ### Bug Fixes
 
@@ -322,13 +399,13 @@
 - docs: document the global (not scheme-scoped) tweak model in README §9 — on a host `color-scheme-changed` event the panel drops its inline overrides and re-seeds the live state from the new scheme, leaving `localStorage` untouched until the next edit. (238b4db, [#343](https://github.com/Takazudo/zudo-design-token-panel/issues/343))
 - ci: drop the stale npm `next` dist-tag on stable releases when it lags `latest`, so `@takazudo/zdtp@next` can no longer silently resolve to an older prerelease. (215ec59, [#345](https://github.com/Takazudo/zudo-design-token-panel/issues/345))
 
-## 0.2.2
+## [0.2.2] - 2026-06-15
 
 ### Other Changes
 
 - Post-review internal cleanups for the Element Path Copy feature (no behavior change): single source of truth for the highlight / element-path portal-mount ids (`HIGHLIGHT_PORTAL_MOUNT_ID` / `ELPATH_PORTAL_MOUNT_ID`, folded into `PANEL_EXCLUSION_SELECTOR`); `ElementPathToast` now owns its own fixed top-center positioning and z-index; `buildSummary` escapes the id consistently with the selector line; the always-on `mousemove` listener is passive + non-capture; and the hover-label summary is memoized. (0fdcbd6)
 
-## 0.2.1
+## [0.2.1] - 2026-06-14
 
 ### Features
 
@@ -340,7 +417,7 @@
 - Bump GitHub Actions off the deprecated Node 20 runtime: `checkout` / `setup-node` / pnpm-setup and the artifact actions to their Node-24-matched versions. (08d5b48, b46fd66, [#339](https://github.com/Takazudo/zudo-design-token-panel/pull/339), [#341](https://github.com/Takazudo/zudo-design-token-panel/pull/341))
 - Add a web-env bootstrap for Claude Code on the web. (23f00c3)
 
-## 0.2.0
+## [0.2.0] - 2026-06-09
 
 First clean stable release on the `latest` dist-tag, promoting the
 `0.2.0-next.1` / `0.2.0-next.2` prerelease line. A tagless
@@ -360,13 +437,13 @@ First clean stable release on the `latest` dist-tag, promoting the
 - Drop slider-describing prose and min/max examples from `README.md`, `PORTABLE-CONTRACT.md`, and the doc-site reference pages (`token-manifest.mdx`, `architecture.mdx`, `configure-panel.mdx`). (e210a2d, 9262585)
 - Resolve all `pnpm audit` advisories (1 critical, 3 high, 7 moderate, 1 low) in dev/doc-only tooling — none ship in the published package. (f3574e0)
 
-## 0.2.0-next.2
+## [0.2.0-next.2] - 2026-05-27
 
 ### Features
 
 - **Token-name tooltip parity across all tabs (Size / Font / Spacing / Easing / GenericTab).** The Color tab already showed a rich custom tooltip with the full token name on hover; every other tab fell back to the native HTML `title` attribute. A new shared `TokenLabel` component renders the same `.tokenpanel-tooltip` primitive at every token-name display site. `TooltipProvider` was lifted from `color-tab.tsx` to `panel.tsx` so all tabs share a single provider. (559c59f, 426e9c6, 84f5981, [#330](https://github.com/Takazudo/zudo-design-token-panel/issues/330), [#337](https://github.com/Takazudo/zudo-design-token-panel/pull/337))
 
-## 0.2.0-next.1
+## [0.2.0-next.1] - 2026-05-27
 
 ### Breaking Changes
 
@@ -379,7 +456,7 @@ First clean stable release on the `latest` dist-tag, promoting the
 - Update `packages/zdtp/README.md` and `packages/zdtp/PORTABLE-CONTRACT.md` to drop slider-describing prose and the min/max examples. (e210a2d)
 - Update doc-site reference pages (`token-manifest.mdx`, `architecture.mdx`, `configure-panel.mdx`) to drop the min/max examples and slider-UI prose. (9262585)
 
-## 0.1.0-next.3
+## [0.1.0-next.3] - 2026-05-27
 
 ### Features
 
@@ -389,7 +466,7 @@ First clean stable release on the `latest` dist-tag, promoting the
 
 - **Number inputs no longer overwrite the user's draft mid-keystroke.** `SliderRow` and the generic-tab item editor used to parse-and-clamp on every keystroke, immediately commit the clamped value, and round-trip it back into the input — so typing `2` then `2` (expecting `22`) snapped the input to `6` when the token's `max` was `6`. Out-of-range or empty drafts are now flagged with a `--invalid` red border and held without committing; on blur, an invalid draft reverts to the last known-good value. The slider thumb continues to scrub live. (21d3afa) ([#313](https://github.com/Takazudo/zudo-design-token-panel/issues/313))
 
-## 0.1.0-next.2
+## [0.1.0-next.2] - 2026-05-25
 
 ### Fixed
 
@@ -410,7 +487,7 @@ First clean stable release on the `latest` dist-tag, promoting the
   base tokens get the same visibility toggle as palette and semantic tokens. The
   eye is omitted only when the cluster declares no `cssVar` for that role.
 
-## 0.1.0-next.1
+## [0.1.0-next.1] - 2026-05-25
 
 ### Fixed — Astro consumers: `@takazudo/zdtp/astro` value import broke real npm installs ([#308](https://github.com/Takazudo/zudo-design-token-panel/issues/308))
 
@@ -436,7 +513,7 @@ First clean stable release on the `latest` dist-tag, promoting the
   side-effect import is unchanged. Docs (README, PORTABLE-CONTRACT, doc-site
   recipes) updated to the direct-subexport form.
 
-## 0.1.0-next.0
+## [0.1.0-next.0] - 2026-05-24
 
 ### Renamed — npm package is now `@takazudo/zdtp`
 

package/PORTABLE-CONTRACT.md

@@ -264,9 +264,10 @@ derives the keys at runtime from this single base.
 
 | Logical key | Derivation                  | Owner                | Purpose                                                                                                                                                      |
 | ----------- | --------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `state-v3`  | `${storagePrefix}-state-v3` | tweak-state          | Current unified envelope: tabs map + color + spacing + typography + size + panelPosition. Added `tabs` map for generic host-coined tabs.                     |
-| `state-v2`  | `${storagePrefix}-state-v2` | tweak-state (legacy) | Pre-v3 unified envelope (color + spacing + typography + size + panelPosition). Migrated into `state-v3` on first load, then deleted.                        |
-| `state-v1`  | `${storagePrefix}-state`    | tweak-state (legacy) | Pre-v2 flat-state format (Color-only). Migrated into `state-v3` on first load, then deleted.                                                                |
+| `state-v4`  | `${storagePrefix}-state-v4` | tweak-state          | Current unified envelope. `color` (and optional `secondary`) is keyed by active scheme/mode identity; global `tabs`, `spacing`, `typography`, and `size` slices remain unkeyed. |
+| `state-v3`  | `${storagePrefix}-state-v3` | tweak-state (legacy) | Retained downgrade-compatible envelope with a flat, single-slot `color` (plus global `tabs`, `spacing`, `typography`, and `size`). The selected v3 state is copied into v4; this key is not deleted by the v4 migration. |
+| `state-v2`  | `${storagePrefix}-state-v2` | tweak-state (legacy) | Pre-v3 unified envelope (color + spacing + typography + size). When selected, it is written to `state-v3` and the v2 key is deleted, then the result is copied into v4. |
+| `state-v1`  | `${storagePrefix}-state`    | tweak-state (legacy) | Pre-v2 flat-state format (Color-only). When selected, it is written to `state-v3` and the v1 key is deleted, then the result is copied into v4. |
 | `open`      | `${storagePrefix}-open`     | panel                | Mirror of the panel's `open` boolean state (so the next mount opens directly into the user's last state without a post-render toggle dispatch).              |
 | `position`  | `${storagePrefix}-position` | panel                | Drag position (`{ top, left }`) so the panel reappears where the user left it.                                                                              |
 | `visible`   | `${storagePrefix}:visible`  | adapter              | Adapter-level visibility-intent flag, owned by the lazy-load gate (§6).                                                                                      |
@@ -283,6 +284,7 @@ The derivation MUST emit the colon literally; do not "fix" it during refactors.
 the derivation produces:
 
 ```
+myapp-design-token-panel-state-v4
 myapp-design-token-panel-state-v3
 myapp-design-token-panel-state-v2
 myapp-design-token-panel-state
@@ -294,8 +296,39 @@ myapp-design-token-panel-domtweaker-enabled
 ```
 
 Unit tests in the package verify these derivations with literal-equality
-checks, and the v1 → v3 / v2 → v3 migration paths at first-load are part of
-the test matrix.
+checks. The v4 precedence and legacy v1/v2/v3 migration paths at first load
+are part of the test matrix; the version-agnostic `${storagePrefix}-state`
+family probe in §6.2 continues to cover this key and future versions.
+
+### Current `state-v4` envelope
+
+The current persisted envelope is stored under one `${storagePrefix}-state-v4`
+key. Its color slices are keyed by the active scheme/mode identity, while the
+non-color slices are global and unkeyed:
+
+```jsonc
+{
+  "color": {
+    "Default Light": { "palette": [], "semanticMappings": {} /* ... */ },
+    "Default Dark": { "palette": [], "semanticMappings": {} /* ... */ }
+  },
+  "secondary": {
+    "Default Light": { "palette": [], "semanticMappings": {} /* ... */ }
+  },
+  "tabs": { "my-custom-tab": { "tier-id": { "item-id": "value" } } },
+  "spacing": { "item-id": "value" },
+  "typography": { "item-id": "value" },
+  "size": { "item-id": "value" }
+}
+```
+
+`secondary` is optional and, when present, uses the same identity keys as the
+primary `color` map. On load, the active identity's color and secondary slots
+are selected. If that identity has no color slot yet, color is seeded from the
+active scheme's defaults; the global `tabs`, `spacing`, `typography`, and `size`
+slices still load. A save replaces only the active identity's color/secondary
+slots and preserves every other identity slot by merge, so editing one scheme
+cannot overwrite another scheme's tweaks.
 
 ### 2.1 Default first-open geometry
 
@@ -368,6 +401,15 @@ export interface PillSpec {
   customDefault: string;
 }
 
+/** Mapping value for a semantic color token (legacy and ramp-native forms). */
+export type SemanticValue =
+  | number
+  | 'bg'
+  | 'fg'
+  | { literal: string }
+  | { literal: { light: string; dark: string } }
+  | { ref: { tab?: string; tier: string; item: string } };
+
 /** A single editable or reference token within a tier. */
 export interface TierItem {
   /** Stable id used as the key in persisted state (e.g. `hsp-2xs`). */
@@ -402,8 +444,26 @@ export interface TierConfig {
    * pipeline emits `var(--target-cssvar)` for ref-tier items at apply time.
    */
   referencesTier?: string;
+  /**
+   * Marks a Color-tab tier as semantic data whose items hold `SemanticValue`
+   * mappings rather than raw palette entries. It is never treated as the
+   * palette tier, so a Color tab may contain a lone semantic tier.
+   */
+  semantic?: true;
+  /**
+   * Valid only when this semantic tier belongs to a tab whose id is exactly
+   * `color` or `color-secondary`; other owning tab ids are rejected at
+   * configure time. Declares one or more permitted same- or cross-tab ramp
+   * sources for per-row semantic `{ ref }` mappings. Each entry names a tier
+   * and optional tab (`tab` omitted means this tab); unlike `referencesTier`,
+   * this is a multi-source allow-list for individual semantic mappings.
+   */
+  referencesRamps?: readonly { tab?: string; tier: string }[];
 }
 
+For the full `SemanticValue` mapping and emission behavior, see the maintained
+[Color-cluster reference](https://zudo-design-token-panel.takazudomodular.com/docs/reference/color-cluster/).
+
 /**
  * Color-cluster extras — the non-tier fields required for the color tab.
  * Palette and semantic data move into the tier model as TierItems; ColorClusterExtras
@@ -596,7 +656,9 @@ export interface ColorClusterExtras {
     /**
      * Optional light/dark pairing. When set to an object, the panel honours
      * `document.documentElement[data-theme]` and switches schemes accordingly
-     * on init. Set to `false` to disable the light/dark UI.
+     * on init. Set to `false` to disable scheme-to-`data-theme` binding; this
+     * does not disable per-mode literal editing or emitted `light-dark(...)`
+     * values.
      */
     colorMode: false | { defaultMode: 'light' | 'dark'; lightScheme: string; darkScheme: string };
   };
@@ -899,7 +961,7 @@ panel bundle is NOT fetched and the page is completely free of panel JS.
 | Signal | Key derivation | Owner |
 |--------|---------------|-------|
 | `wasVisible` | `${storagePrefix}:visible`, OR its `${storagePrefix}-open` mirror | adapter |
-| `hasPersistedOverrides` | Content check across the `${storagePrefix}-state` family (`-state`, `-state-v2`, `-state-v3`, ... — every version, not a fixed list) | tweak-state |
+| `hasPersistedOverrides` | Content check across the `${storagePrefix}-state` family (`-state`, `-state-v2`, `-state-v3`, `-state-v4`, ... — every version, not a fixed list) | tweak-state |
 | `shouldAutoload` | `${storagePrefix}:autoload`, matching `'1'` or `'auto'` | autoload-state |
 | `loadElementPathEnabled` | `${storagePrefix}-elpath-enabled` | element-path-state |
 | `loadDomTweakerEnabled` | `${storagePrefix}-domtweaker-enabled` | dom-tweaker-state |
@@ -1174,29 +1236,35 @@ For any host's chosen `storagePrefix`, the derivation produces deterministic,
 literal-equal storage keys (see §2). Unit tests pin the derived keys to
 literal strings.
 
-### 8.3 v1 / v2 → v3 in-place migration
+### 8.3 v4 precedence and v1 / v2 / v3 migration
 
-On first load, `loadPersistedState` migrates forward through the chain:
+`loadPersistedState` first looks for a valid `state-v4` envelope. If that key
+is absent or invalid, it falls through to the retained legacy chain. The
+precedence and deletion rules are explicit:
 
-| Source key              | Target key               | Action after migration |
-| ----------------------- | ------------------------ | ---------------------- |
-| `${storagePrefix}-state` (v1)    | `${storagePrefix}-state-v3` | v1 key deleted |
-| `${storagePrefix}-state-v2` (v2) | `${storagePrefix}-state-v3` | v2 key deleted |
+| Storage condition | Selection / migration action | Key-retention result |
+| ----------------- | ---------------------------- | --------------------- |
+| Valid `${storagePrefix}-state-v4` (v4) | Select the active identity's `color` and optional `secondary` slots; load global `tabs`, `spacing`, `typography`, and `size`. | v4 wins; no legacy key is touched. |
+| v4 key absent or invalid | Fall through and inspect the legacy keys in order. | No deletion is caused by the v4 probe. |
+| Valid `${storagePrefix}-state-v3` (v3) | Use v3; do not inspect, rewrite, or delete lower legacy keys. | Copy the resulting state into v4 under the active identity; retain v3 for downgrade compatibility. |
+| Valid `${storagePrefix}-state-v2` (v2), with no valid v3 | Parse v2 and write the resulting flat state to v3. | Delete v2, then copy the resulting v3 state into v4; retain v3 for downgrade compatibility. |
+| Valid `${storagePrefix}-state` (v1), with no valid v3 or v2 | Lift the flat Color-only state into the unified state and write it to v3. | Delete v1, then copy the resulting v3 state into v4; retain v3 for downgrade compatibility. |
 
-A user who last opened the panel before v3 landed gets their old color/spacing
-tweaks lifted into the new envelope on first load.
+Thus a v3 key wins over v2 and v1, and a v4 migration never removes v3. The
+selected or newly written v3 state is always filed into the v4 envelope under
+the identity active at that moment. Subsequent loads read v4 first; a
+downgrade can still read the retained v3 envelope. Malformed legacy values are
+skipped in the same order so the next lower legacy key can be considered.
 
-The v3 envelope adds a `tabs` map alongside the existing per-category slices:
+The retained v3 envelope has a flat, single-slot `color` and global slices:
 
 ```ts
 // Simplified v3 localStorage envelope shape
 {
-  // legacy category slices — preserved for round-trip compatibility
   color:      { ... },
   spacing:    { ... },
   typography: { ... },
   size:       { ... },
-  // v3 extension — generic tab overrides keyed by tab id
   tabs: {
     "my-custom-tab": { "item-id-1": "some-value", ... },
     ...
@@ -1204,6 +1272,9 @@ The v3 envelope adds a `tabs` map alongside the existing per-category slices:
 }
 ```
 
+The current v4 envelope and its active-identity seeding and merge-write rules
+are specified in §2 above.
+
 ### 8.4 Typography-id rename map
 
 The optional `PanelConfig.legacyIdRenameMap` (`Record<string, string | null>`)
@@ -1304,6 +1375,6 @@ Cross-reference table — what each section pins down.
 | Modal class prefix and `data-design-token-panel-modal` selector contract                    | §7.3          |
 | Self-contained panel chrome palette (no host theme reads)                                  | §7.4          |
 | Host-adapter side-effect import (paired-unit obligation)                                    | §7.5          |
-| v1/v2 → v3 storage migration and typography-id rename map                                   | §8.3, §8.4    |
+| v4 envelope precedence, v1/v2/v3 storage migration, and typography-id rename map             | §2, §8.3, §8.4 |
 | JSON export/import schema v2 (serde v2)                                                     | §9            |
 | Out-of-scope / deferred concerns                                                            | §10           |

package/README.md

@@ -112,8 +112,8 @@ pnpm exec zdtp-server --help
 | Flag | Required | Purpose | Default |
 |---|---|---|---|
 | `--routing <path>` | yes | Path to the routing JSON file (cluster id → repo-relative CSS file path). Absolute, or relative to `--root`. See §3.2. | — |
-| `--write-root <dir>` | no | Sandbox directory: the bin refuses to write outside this tree. Absolute, or relative to `--root`. | `--root` |
-| `--root <dir>` | no | Repo-root reference used to resolve `--routing` and `--write-root`. | `process.cwd()` |
+| `--write-root <dir>` | yes | Required write boundary: the only directory tree the bin is allowed to write into. Absolute, or relative to `--root`. | — |
+| `--root <dir>` | no | CWD/resolution base used to resolve `--routing` and `--write-root`. | `process.cwd()` |
 | `--port <number>` | no | TCP port to bind. `0` asks the OS for an ephemeral port (the bin logs the assigned port on startup). | `24681` |
 | `--host <addr>` | no | Bind address. Use `0.0.0.0` to expose on the LAN (off by default). | `127.0.0.1` |
 | `--allow-origin <origin>` | repeatable | Origin allowed to POST to `/apply` (scheme + host + port, no trailing slash). At least one is required for any browser to apply. | none (all origins denied) |
@@ -170,7 +170,7 @@ For the full token-overrides payload schema and the `PanelConfig` shape, see §5
 The bin is **dev-only** and is built with three independent guards:
 
 - **Loopback default.** Binds to `127.0.0.1` so only requests from the same machine are accepted. Override with `--host` if you actually want LAN access.
-- **Write sandbox (`--write-root`).** Every routing entry is resolved against `--root` and verified to sit strictly inside `--write-root` before any file I/O happens. An entry whose resolved path escapes the sandbox — via `..` segments or an absolute path that points elsewhere — fails the apply with a 400 and a descriptive error message. `--write-root` defaults to `--root`, so routing entries are sandboxed to your repo root unless you narrow it further.
+- **Write sandbox (`--write-root`).** `--write-root` is required and defines the narrow directory tree the bin is allowed to write into. Every routing entry is resolved against `--root` and verified to sit strictly inside `--write-root` before any file I/O happens. An entry whose resolved path escapes the sandbox — via `..` segments or an absolute path that points elsewhere — fails the apply with a 400 and a descriptive error message. `--root` is the CWD/resolution base for relative `--routing` and `--write-root` paths and defaults to `process.cwd()`.
 - **CORS allow-list.** By default, **all origins are denied**. To let a browser POST to `/apply` you must list its origin explicitly with `--allow-origin <url>` (repeatable). Without a matching `--allow-origin`, the OPTIONS preflight returns 403 and POST returns 403 — no `Access-Control-Allow-Origin` header is emitted. Origin matching is **verbatim** on the full scheme + host + port string: `http://localhost:5173` and `http://127.0.0.1:5173` are different origins.
 
 **Atomic writes.** The bin serialises per-file writes through a small mutex and uses a write-temp-file-then-rename strategy, so a failure mid-write never leaves a half-rewritten CSS file on disk. If any file in a multi-file apply fails to write, every file that was already persisted is restored from the in-memory snapshot taken before the apply started.

package/dist/astro/host-adapter.js

@@ -1,6 +1,6 @@
-import { c as y, g as m, a as w, b, i as P } from "../panel-config-7Xg59uKj.js";
-import { g, Z as k } from "../tweak-state-DRKV1uYj.js";
-import { s as A, l as D, a as E, i as c, r as f, c as _, b as I, d } from "../autoload-state-CTDDBxI8.js";
+import { c as y, g as m, a as w, b, i as P } from "../panel-config-COHesW2B.js";
+import { g, Z as k } from "../tweak-state-BKNxtHzb.js";
+import { s as A, l as D, a as E, i as c, r as f, c as _, b as I, d } from "../autoload-state-CfL2VUe1.js";
 const u = "tokenpanel-config";
 function S() {
   if (typeof document > "u")

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { s as t } from "../panel-config-7Xg59uKj.js";
+import { s as t } from "../panel-config-COHesW2B.js";
 import { c as d } from "../color-schemes-CgzOBqGO.js";
 import { F as r, G as m, a as g, S as z } from "../manifest-DCReQE0k.js";
 const e = {

package/dist/{autoload-state-CTDDBxI8.js → autoload-state-CfL2VUe1.js}

@@ -1,4 +1,4 @@
-import { g as n, j as o } from "./panel-config-7Xg59uKj.js";
+import { g as n, j as o } from "./panel-config-COHesW2B.js";
 function c() {
   return typeof document < "u" && document !== null && typeof document.getElementById == "function";
 }

package/dist/components/palette-chart/palette-chart.d.ts

@@ -35,8 +35,19 @@ import { type Oklcha } from '../../utils/color-oklch';
 export type { Oklcha } from '../../utils/color-oklch';
 export type { Channel } from '../../utils/palette-curve';
 export interface PaletteChartProps {
-    /** Palette colors in OKLCH space. Band `i` = oklchaToHex(colors[i]). */
-    colors: Oklcha[];
+    /**
+     * Dense palette slots in OKLCH space. A null slot preserves its index/band,
+     * but has no numeric curve node and is not editable.
+     */
+    colors: Array<Oklcha | null>;
+    /**
+     * Dense per-index write permission, separate from color validity. A valid
+     * readonly color remains painted in the bands/curves, but receives no node
+     * hit target and is excluded from whole-curve editing.
+     */
+    editable: boolean[];
+    /** Dense stable item identities used to invalidate stale index-based gestures. */
+    identities: string[];
     /** Index of the currently selected color/step (highlighted band + node column). */
     selectedIndex: number;
     /** Which curves are drawn. Owned by the parent; chart only consumes. */
@@ -64,7 +75,7 @@ export interface PaletteChartProps {
      */
     onChangeEnd?: () => void;
 }
-declare function PaletteChartImpl({ colors, selectedIndex, visibleChannels, onChange, onSelectIndex, onChangeStart, onChangeEnd, }: PaletteChartProps): JSX.Element;
+declare function PaletteChartImpl({ colors, editable, identities, selectedIndex, visibleChannels, onChange, onSelectIndex, onChangeStart, onChangeEnd, }: PaletteChartProps): JSX.Element;
 /**
  * Memoized so parent re-renders that don't change props don't re-walk every
  * band/curve/node. The drag state lives in refs, so a controlled-value update

package/dist/{index-C8GR1TU-.js → index-BAY1JOUl.js}

@@ -1,7 +1,7 @@
 import { jsx as y, jsxs as K, Fragment as kt } from "preact/jsx-runtime";
 import { useEffect as P, useState as Y, useRef as O, useMemo as J, useCallback as X } from "preact/hooks";
-import { b as ft, p as wt, u as ht, a as Ne, A as bt, Z as gt } from "./index-BeYH-tJD.js";
-import { g as vt, m as j } from "./panel-config-7Xg59uKj.js";
+import { b as ft, p as wt, u as ht, a as Ne, A as bt, Z as gt } from "./index-U7Ol7tgA.js";
+import { g as vt, m as j } from "./panel-config-COHesW2B.js";
 const xt = (e, o) => {
   const t = new Array(e.length + o.length);
   for (let r = 0; r < e.length; r++)