@takazudo/zdtp 0.4.12 → 0.4.14

package/CHANGELOG.md

@@ -1,6 +1,65 @@
 # Changelog
 
-## 0.4.12
+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.14] - 2026-08-29
+
+### Fixed
+
+- fix(zdtp): silence compatible global alias warning (2630d84)
+
+### Other Changes
+
+- test(zdtp): cover partial global alias shape (6314a7f)
+- Merge pull request [#647](https://github.com/Takazudo/zudo-design-token-panel/pull/647) from Takazudo/fix/646-compatible-zdtp-alias: fix(zdtp): silence warnings for compatible global aliases (44f6ca4)
+
+## [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
 
@@ -29,7 +88,7 @@
 - = start portable storage contract epic = [skip ci] (1605c3e)
 - = start sweep-260820 super-epic = [skip ci] (c29cc50)
 
-## 0.4.11
+## [0.4.11] - 2026-08-19
 
 ### Features
 
@@ -56,7 +115,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
 
@@ -69,7 +128,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
 
@@ -88,7 +147,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
 
@@ -100,7 +159,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
 
@@ -110,7 +169,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
 
@@ -134,7 +193,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
 
@@ -156,7 +215,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
 
@@ -202,7 +261,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
 
@@ -234,7 +293,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
 
@@ -265,13 +324,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
 
@@ -289,7 +348,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
 
@@ -308,7 +367,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
 
@@ -316,7 +375,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
 
@@ -324,7 +383,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
 
@@ -336,7 +395,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
 
@@ -351,13 +410,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
 
@@ -369,7 +428,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
@@ -389,13 +448,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
 
@@ -408,7 +467,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
 
@@ -418,7 +477,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
 
@@ -439,7 +498,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))
 
@@ -465,7 +524,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

@@ -401,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`). */
@@ -435,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
@@ -629,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 };
   };
@@ -1075,11 +1104,12 @@ window.zdtp.toggle = () => void | Promise<void>;  // toggle the panel
     always installs first ("first install wins" — see the next point). The
     package-root install site is therefore reached only by non-Astro hosts.
 - **Never clobbers a host-defined `window.zdtp`.** If `window.zdtp` already
-  exists and was not installed by this package, the install is skipped with
-  a `console.warn` — the host's own global is left untouched. (This also
-  covers the edge case of a host that picks `consoleNamespace: 'zdtp'`: the
-  namespace object installed at §6.4 is not this package's alias marker, so
-  the second install site treats it as host-owned and skips.)
+  exposes callable `show` / `hide` / `toggle` methods, the install is skipped
+  silently — this supports hosts that pre-claim the alias before lazily loading
+  the panel bundle. Other pre-existing values are also left untouched, but
+  produce a `console.warn`. (This includes the edge case of a host that picks
+  `consoleNamespace: 'zdtp'`: the namespace object installed at §6.4 does not
+  expose the fixed-name alias shape, so the second install site warns and skips.)
 - **Auto-remember carries over for free.** `zdtp.show()` routes through the
   same `showDesignTokenPanel()` / `handle.open()` core as every other open
   path, so it arms `${storagePrefix}:autoload = 'auto'` exactly like

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.
@@ -1053,7 +1053,7 @@ zdtp.toggle(); // toggle open/closed
 - **Available on both integration paths:**
   - Non-Astro hosts get it as soon as `@takazudo/zdtp`'s package-root module has loaded (it installs the alias at module init).
   - Astro hosts get it as soon as the host-adapter `<script>` has run — **before** the panel bundle itself has loaded. The first `zdtp.*` call lazy-imports the bundle, exactly like `window[consoleNamespace].*`.
-- **Never clobbers a host-defined `window.zdtp`.** If your page already has its own `window.zdtp` for something unrelated, the package leaves it alone and logs a `console.warn` instead of overwriting it — including the edge case of choosing `consoleNamespace: 'zdtp'` yourself.
+- **Never clobbers a host-defined `window.zdtp`.** If the existing value exposes callable `show`, `hide`, and `toggle` methods, the package treats it as an intentional host alias and stays silent — enabling hosts to pre-claim the alias before lazily loading the panel bundle. Other existing values are still left untouched and produce a `console.warn`, including the edge case of choosing `consoleNamespace: 'zdtp'` yourself.
 - **Auto-remember applies too** — `zdtp.show()` arms the `:autoload` flag with `'auto'` provenance exactly like `showDesignPanel()` (§10.1's Auto-remember footgun note applies here as well).
 
 See `PORTABLE-CONTRACT.md` §6.5 for the full install-site and no-clobber/no-double-install contract.

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-SgA84Uqe.js";
+import { g, Z as k } from "../tweak-state-DGLrzIwq.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-IlkEci88.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-SgA84Uqe.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-IlkEci88.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-SgA84Uqe.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/config/panel-config.d.ts

@@ -532,31 +532,6 @@ export interface ZdtpGlobalApi {
     hide: () => void | Promise<void>;
     toggle: () => void | Promise<void>;
 }
-/**
- * Install `window.zdtp = { show, hide, toggle }`, the fixed-name console
- * sugar for the common single-panel case (issue #523).
- *
- * Guard rules:
- *  - A pre-existing `window.zdtp` WITHOUT this package's marker is assumed to
- *    be host-defined — never overwritten. Logs a `console.warn` so the host
- *    can see why `zdtp.show()` did not appear.
- *  - A pre-existing `window.zdtp` WITH the marker means this package already
- *    installed the alias (from the other call site, or an earlier run of this
- *    same one). First install wins — the call is a silent no-op. In the Astro
- *    flow this manifests as "the adapter wins": its bootstrap script always
- *    runs (and installs the alias) before the panel module's lazy dynamic
- *    import can resolve and reach the package-root install site.
- *
- * `show` / `hide` / `toggle` are caller-supplied closures, so which instance
- * they target is up to the caller — the package-root install site (below,
- * `index.tsx`) wraps `showDesignTokenPanel()` etc., which re-resolve
- * `getPanelConfig()` (the CURRENT default instance) on every call; the Astro
- * host-adapter install site instead binds to the specific `PanelInstanceHandle`
- * captured at its own install time, which does NOT track a later change of
- * default (see PORTABLE-CONTRACT.md §6.5 for the full nuance). Either way,
- * for a multi-instance page use `configurePanel(cfg).open()` etc. on the
- * specific instance's own handle instead of relying on this alias.
- */
 export declare function installZdtpGlobalAlias(api: ZdtpGlobalApi): void;
 /**
  * Runtime validation at the host-adapter trust boundary. The Astro inline