@takazudo/zdtp 0.4.15 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,79 @@ 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.5.1] - 2026-09-06
+
+The panel now fits its token grids, card controls, and header controls at the minimum panel width instead of overflowing. Multiple panels keep stable spawn positions: spawn ordinals are persisted and survive Astro client-side navigation. Eager loading is bounded to state keys the panel can actually read, and the specimen stylesheet gained the boundaries the docs-adoption check required.
+
+### Fixed
+
+- fix: fit token grids and card controls at minimum panel width (8db4235)
+- fix(panel): yield header controls before floating panel overflow (06cbb0e)
+- fix: validate doc adoption boundaries (a11fd6a)
+
+### Other Changes
+
+- Merge pull request [#801](https://github.com/Takazudo/zudo-design-token-panel/pull/801) from Takazudo/base/sweep-260906-2 (2631545)
+- Merge pull request [#813](https://github.com/Takazudo/zudo-design-token-panel/pull/813) from Takazudo/base/sweep-260906-2-doc-zdtp-050 (406fb79)
+- Merge branch 'topic/795-doc-adoption-confirm' into base/sweep-260906-2-doc-zdtp-050 (1f5abd9)
+- Merge branch 'topic/795-doc-pin-manifest' into base/sweep-260906-2-doc-zdtp-050 (2fe626b)
+- Adopt zdtp 0.5.0 in docs (8026c66)
+- Merge pull request [#810](https://github.com/Takazudo/zudo-design-token-panel/pull/810) from Takazudo/base/sweep-260906-2-storage-bootstrap (e8edd31)
+- Merge branch 'topic/790-storage-bootstrap-confirm' into base/sweep-260906-2-storage-bootstrap (aca17d0)
+- Confirm storage bootstrap regressions (1fdb75e)
+- Merge branch 'topic/790-readable-gate-probe' into base/sweep-260906-2-storage-bootstrap (be49753)
+- Bound eager loading to readable state keys (bcc55fd)
+- Merge branch 'topic/790-astro-ordinal-lifecycle' into base/sweep-260906-2-storage-bootstrap (48a76ab)
+- Keep spawn positions stable across Astro navigation (2a6672b)
+- Merge branch 'topic/790-persisted-spawn-ordinal' into base/sweep-260906-2-storage-bootstrap (03deeaa)
+- Persist panel spawn ordinals (3f1caa3)
+- Merge pull request [#805](https://github.com/Takazudo/zudo-design-token-panel/pull/805) from Takazudo/base/sweep-260906-2-panel-width-layout (b62b94d)
+- test: follow compact panel actions in walking skeleton (de19350)
+- Merge branch 'topic/783-containment-confirm' into base/sweep-260906-2-panel-width-layout (1cdbb29)
+- test: update width-layout VRT baselines (f54695a)
+- test: reconcile compact label containment assertion (777ac84)
+- Merge branch 'topic/783-grid-implementation' into base/sweep-260906-2-panel-width-layout (5283cfc)
+- test: isolate and verify persisted highlight toggle state (373239c)
+- test: reconcile card fit fixtures with manifest and query contracts (6345370)
+- Merge branch 'topic/783-header-implementation' into base/sweep-260906-2-panel-width-layout (eacf1ef)
+- test(panel): correct header portal and edge-hit assertions (8fafedd)
+- Merge pull request [#800](https://github.com/Takazudo/zudo-design-token-panel/pull/800) from Takazudo/base/sweep-260906-2-docs-consistency (82073a5)
+- Merge branch 'topic/780-docs-version-skew-note' into base/sweep-260906-2-docs-consistency (d838cc2)
+- Merge branch 'topic/780-readme-section-renumber' into base/sweep-260906-2-docs-consistency (22dd16d)
+- docs: explain release skew in getting-started notes (b62ffb9)
+- docs: renumber README color presets section (fb19bed)
+
+## [0.5.0] - 2026-09-06
+
+`@takazudo/zdtp/constants` now exposes `DEFAULT_STORAGE_PREFIX`, `DEFAULT_TOGGLE_EVENT`, `resolveToggleEventName`, `EAGER_LOAD_GATE_KEY_SUFFIXES`, and `EAGER_LOAD_GATE_STATE_FAMILY` without importing the panel. Lazy hosts can share toggle-event rules and eager-load metadata; state-family matching still requires the documented content checks. The storage-key documentation is also corrected: position, size, density, and all three highlight keys already existed in published 0.4.14.
+
+### Features
+
+- feat(zdtp): publish isolated constants entry (11ff48b)
+- feat: describe eager-load gate signals with behavioral drift guard (0a2b610)
+
+### Fixed
+
+- fix: keep dock controls visible and reconcile menu with rendered CSS (dae7dcc)
+- fix(zdtp): preserve readable labels in changed token rows (97ede7f)
+
+### Other Changes
+
+- Merge pull request [#769](https://github.com/Takazudo/zudo-design-token-panel/pull/769) from Takazudo/base/sweep-260906 (c4c6230)
+- Merge pull request [#778](https://github.com/Takazudo/zudo-design-token-panel/pull/778) from Takazudo/base/sweep-260906-gate-constants (cc29811)
+- Merge branch 'topic/765-constants-docs' into base/sweep-260906-gate-constants (a82dc82)
+- docs: document constants subpath and storage key continuity (17426e0)
+- Merge branch 'topic/764-constants-package' into base/sweep-260906-gate-constants (572d11c)
+- Merge branch 'topic/763-gate-signals' into base/sweep-260906-gate-constants (c09f456)
+- Merge branch 'topic/762-constants-leaf' into base/sweep-260906-gate-constants (f038f71)
+- refactor(zdtp): extract panel constants leaf (369e495)
+- Merge pull request [#773](https://github.com/Takazudo/zudo-design-token-panel/pull/773) from Takazudo/base/sweep-260906-dock-escape (08678c2)
+- Merge branch 'topic/759-dock-fix' into base/sweep-260906-dock-escape (a44f2a4)
+- Merge branch 'topic/758-dock-decision' into base/sweep-260906-dock-escape (3d1ee55)
+- docs: define visible dock controls and CSS-driven menu contract (0da81f3)
+- Merge pull request [#768](https://github.com/Takazudo/zudo-design-token-panel/pull/768) from Takazudo/base/sweep-260906-changed-row-label (323b9b0)
+- Merge branch 'topic/754-changed-row-label' into base/sweep-260906-changed-row-label (69846f2)
+
 ## [0.4.15] - 2026-09-05
 
 ### Features

package/PORTABLE-CONTRACT.md

@@ -276,6 +276,7 @@ derives the keys at runtime from this single base.
 | `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.                                                                              |
+| `spawn-ordinal` | `${storagePrefix}-spawn-ordinal` | mount registry | Instance cascade identity: a JSON integer from 0 through 31, retained by Reset and restored across Astro body swaps. Invalid values fall back to lowest-free allocation. |
 | `size`      | `${storagePrefix}-size`     | panel                | Floating shell dimensions (`{ width, height }`) in pixels.                                                                                                  |
 | `dock`      | `${storagePrefix}-dock`     | panel                | Presentation mode: `'float'`, `'right'`, `'bottom'`, or `'mini'`.                                                                                          |
 | `dock-size` | `${storagePrefix}-dock-size` | panel               | Right/bottom dock dimensions (`{ right, bottom }`), defaulting to `{ right: 440, bottom: 340 }`.                                                           |
@@ -293,6 +294,13 @@ derives the keys at runtime from this single base.
 | `highlight-outline-width` | `${storagePrefix}-highlight-outline-width` | highlight-state | Global highlight outline width in local storage, clamped to 1–20.                              |
 | `highlight-active` | `${storagePrefix}-highlight-active` | highlight-state | Active CSS-variable-to-slot map in session storage.                                                                                                        |
 
+This is the current storage-key inventory, not a release-history table. The
+published 0.4.14 bundle already wrote `${storagePrefix}-position`,
+`${storagePrefix}-size`, `${storagePrefix}-density`, and all three
+`${storagePrefix}-highlight-*` keys. Their appearance in the 0.4.15 contract
+documentation records existing storage continuity; it does not make those keys
+new in 0.4.15.
+
 **Constraint — colon, not dash, for `visible` and `autoload`.** Both adapter-
 level flags use a `:` separator; every other derived key uses `-`. The colon
 form is a historical artifact for `visible`, preserved for storage-key
@@ -309,6 +317,7 @@ myapp-design-token-panel-state-v2
 myapp-design-token-panel-state
 myapp-design-token-panel-open
 myapp-design-token-panel-position
+myapp-design-token-panel-spawn-ordinal
 myapp-design-token-panel-size
 myapp-design-token-panel-dock
 myapp-design-token-panel-dock-size
@@ -329,8 +338,9 @@ myapp-design-token-panel-highlight-active  # sessionStorage
 
 Unit tests in the package verify these derivations with literal-equality
 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.
+are part of the test matrix. The bounded probe in §6.2 covers exactly the
+state versions the loader can read; every future format bump must update the
+shared readable-suffix registry in the same change.
 
 ### Current `state-v4` envelope
 
@@ -382,11 +392,20 @@ computed at open time as one coherent rectangle:
   against the persisted size, not against the default one.
 - **The fallback is instance-aware.** Each additional panel instance
   concurrently mounted on the page offsets its own fallback position by 24px
-  on both axes, keyed to mount order with lowest-free-slot reuse (a released
-  slot — e.g. from `destroy()` — is reused by the next instance that mounts,
-  rather than the ordinal growing forever). This exists only to keep
-  simultaneously-opened instances from landing exactly on top of one
-  another; it has no effect once a `position` value is persisted.
+  on both axes. Its `storagePrefix` persists the allocated ordinal, so an Astro
+  body swap restores the same cascade position even when remount order differs
+  from original open order. An absent, malformed, negative, fractional, or
+  out-of-range stored value uses mount order with lowest-free-slot reuse and
+  records the result. The stored format is a JSON integer from 0 through 31;
+  31 is the cap because 32 identities span at most 744px at the 24px step,
+  already the useful cascade range on ordinary desktop viewports. A released
+  live slot — e.g. from `destroy()` or a shell that does not re-materialise
+  after navigation — can be reused immediately; a retained stored identity
+  reserves nothing by itself and Reset does not delete it. If two prefixes
+  contain the same ordinal, the already-live holder keeps it and the later
+  claimant takes and persists the lowest free slot. This exists only to keep
+  simultaneously-opened instances from landing exactly on top of one another;
+  it has no effect once a `position` value is persisted.
 - **A persisted `position` value always wins over the cascade.** The 24px
   offset applies only to the computed fallback, never to a stored value —
   once `position` is written, that instance reopens at the exact stored
@@ -1094,8 +1113,17 @@ This is the reason the JSON-serializable constraint in §4.2 is non-negotiable.
 
 ### 6.2 Lazy-load gate
 
-The host adapter fires one eager `loadPanelModule()` call when any of the
-following signals is present in `localStorage` at page load:
+The machine-readable metadata for these signals is exported from the
+side-effect-free `@takazudo/zdtp/constants` subpath. Use
+`EAGER_LOAD_GATE_KEY_SUFFIXES` for the five fixed suffix descriptors
+(`:visible`, `-open`, `:autoload`, `-elpath-enabled`, and
+`-domtweaker-enabled`), and `EAGER_LOAD_GATE_STATE_FAMILY` for the versioned
+`-state` family. These exports are the source of truth for consumers that
+mirror the gate. Each fixed descriptor supplies `acceptedValues` and
+`requiredConfig`; presence alone is insufficient, and a named required config
+property must be defined. The prose below explains the runtime meaning. The host adapter fires one eager
+`loadPanelModule()` call when any of these signals activates in `localStorage`
+at page load:
 
 ```ts
 if (
@@ -1114,9 +1142,10 @@ if (
   is applied a second time to the `${storagePrefix}-open` mirror (dash-form,
   §2) that `panel.tsx` writes alongside it. Either key holding `'1'` means the
   panel was open before the last navigation.
-- `hasPersistedOverrides()` — scans every `localStorage` key matching the
-  `${storagePrefix}-state` family (dash-form, §2: `-state` (v1) through every
-  `-state-vN`) and returns `true` when at least one holds a non-empty envelope
+- `hasPersistedOverrides()` — performs bounded `getItem` probes for the
+  `${storagePrefix}-state` keys the loader can read (dash-form, §2: `-state`
+  (v1), `-state-v2`, `-state-v3`, and `-state-v4`) and returns `true` when at
+  least one holds a non-empty envelope
   (malformed JSON also counts as `true` — fail open, so the panel loads and
   can migrate or reject the payload rather than stranding the user with data
   it can never see). This is a **content check**, not a presence check on a
@@ -1126,6 +1155,19 @@ if (
   hand or by another tool.) Overrides MUST be re-applied to the configured
   sink (or default `:root`) even when the panel stays hidden, otherwise
   hard-nav produces a FOUT.
+
+  `READABLE_STATE_KEY_SUFFIXES` is the dependency-free registry of those four
+  readable suffixes. Every storage-format bump MUST update it in the same
+  change as the loader. `EAGER_LOAD_GATE_STATE_FAMILY.matchesKey(storagePrefix,
+  key)` recognizes only exact keys constructed from that registry; unreadable
+  future versions and `${storagePrefix}-spawn-ordinal` do not activate. It does
+  not read storage or perform the content check. The consumer must apply the
+  accompanying `valueRules`: raw empty strings, JSON `null`, and empty
+  objects/arrays do not activate; non-empty collections, every other parsed
+  primitive (including `false`, `0`, and JSON `""`), and malformed JSON do
+  activate. The top-level emptiness check is defensive-only: zdtp-written v4
+  envelopes always contain their top-level buckets, and Reset removes state
+  keys rather than writing empty envelopes.
 - `shouldAutoload()` — reads `${storagePrefix}:autoload` (colon-form, §2).
   Returns `true` when the flag is `'1'` (explicit, written by `enableAutoload()`)
   OR `'auto'` (auto-remembered, written by opening the panel — see "Auto-remember
@@ -1155,7 +1197,7 @@ that decision.
 | 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`, `-state-v4`, ... — every version, not a fixed list) | tweak-state |
+| `hasPersistedOverrides` | Bounded content checks for the readable suffix registry (`-state`, `-state-v2`, `-state-v3`, `-state-v4`) | 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 |
@@ -1626,7 +1668,7 @@ Cross-reference table — what each section pins down.
 | ------------------------------------------------------------------------------------------- | ------------- |
 | `configurePanel({...})` signature, multi-instance, `PanelInstanceHandle`, per-instance toggle events | §1     |
 | Storage-key derivation                                                                      | §2, §8        |
-| Default first-open geometry (coherent size+position, viewport containment, cascade, persisted-position precedence) | §2.1 |
+| Default first-open geometry (coherent size+position, viewport containment, persisted cascade identity, persisted-position precedence) | §2.1 |
 | `PanelDockConfig`, dock modes, body-margin reflow, edge claims, and dock storage | §1, §2, §7 |
 | `TabConfig` / `TierConfig` / `TierItem` / `TierValueKind` interfaces and apply behaviour   | §3            |
 | `TierConfig.preview` / `previewBase` matrix and host-page specimen lifecycle | §3.2 |

package/README.md

@@ -414,6 +414,57 @@ Copy an example's structure when porting the panel into a new host.
 
 If you are building a **Rust SSG** or other non-Node host, the bin still runs as a sidecar Node.js subprocess (started by your host's build orchestration). The same routing JSON and host-adapter setup applies — the only difference is your host ships its own config format (not TypeScript) and you invoke the bin via your build system's subprocess spawner rather than npm scripts.
 
+#### Pre-import activation from a custom host
+
+The side-effect-free `@takazudo/zdtp/constants` subpath exposes
+`DEFAULT_STORAGE_PREFIX`, `DEFAULT_TOGGLE_EVENT`, and
+`resolveToggleEventName` without importing the panel. It also exports the
+machine-readable eager-load metadata (`EAGER_LOAD_GATE_KEY_SUFFIXES` and
+`EAGER_LOAD_GATE_STATE_FAMILY`); the exact gate contract lives in
+[`PORTABLE-CONTRACT.md`](./PORTABLE-CONTRACT.md) §6.2.
+
+A custom host can use those constants to register its toggle listener in the
+initial bundle and fetch the panel only when activated. Keep the stylesheet
+setup from §4.2 (or import `@takazudo/zdtp/styles` in your host stylesheet
+pipeline):
+
+```ts
+import type { PanelConfig } from '@takazudo/zdtp';
+import { resolveToggleEventName } from '@takazudo/zdtp/constants';
+
+// Call once with your complete config (for example myPanelConfig in §4.1.1).
+export function installLazyPanel(config: PanelConfig): void {
+  const toggleEvent = resolveToggleEventName(config);
+  let loading: Promise<void> | undefined;
+
+  function loadOnToggle(): void {
+    if (loading) return;
+    loading = import('@takazudo/zdtp')
+      .then(({ configurePanel }) => {
+        configurePanel(config);
+        window.removeEventListener(toggleEvent, loadOnToggle);
+        window.dispatchEvent(new CustomEvent(toggleEvent));
+      })
+      .catch((error: unknown) => {
+        loading = undefined;
+        console.error('Failed to load @takazudo/zdtp', error);
+      });
+  }
+
+  window.addEventListener(toggleEvent, loadOnToggle);
+}
+```
+
+The default `DEFAULT_STORAGE_PREFIX` is
+`'zudo-design-token-panel'`, and its `DEFAULT_TOGGLE_EVENT` is
+`'toggle-design-token-panel'`. `resolveToggleEventName` preserves that
+historical event even when a default-prefix config supplies `toggleEvent`; a
+non-default prefix uses its supplied `toggleEvent`, or derives
+`toggle-${storagePrefix}` when the override is omitted. The same config
+resolves the listener event and configures the loaded panel. This activation-only
+example does not implement the saved-state eager-load gate; see §6.2 of the
+contract when building a complete host adapter.
+
 ### 4.3 Recipe — Rust SSG (zfb)
 
 Worked example for the case where the host is a Rust dev server (e.g. [zfb / zudo-front-builder](https://github.com/Takazudo/zudo-front-builder)) rather than a Node-based runner. The bin itself is unchanged — it remains a Node.js subprocess invoked as `node path/to/dist/bin/server.js ...`. The Rust host's only job is to spawn that Node process, forward shutdown signals to it, and configure `--allow-origin` so the browser POST from the panel UI is accepted.
@@ -537,7 +588,7 @@ default instance only.
 | `exportFilenameBase` | `string`                       | Default download filename base — exports save as `${exportFilenameBase}.json`.                                                                                         |
 | `toggleEvent`        | `string` (optional)            | Window-event name that toggles THIS instance. Defaults to `toggle-${storagePrefix}` for non-default instances; the default instance keeps `toggle-design-token-panel`. |
 | `tabs`               | `readonly TabConfig[]`         | **Required.** Tab strip data — each entry is a tab with one or more `TierConfig` objects. The color tab (id `'color'`) additionally requires `colorExtras`. See §6.    |
-| `colorPresets`       | `Record<string, ColorScheme>` (optional) | Optional named scheme presets surfaced in the Color tab "Scheme..." dropdown. Defaults to `{}`. See §7.5.                                              |
+| `colorPresets`       | `Record<string, ColorScheme>` (optional) | Optional named scheme presets surfaced in the Color tab "Scheme..." dropdown. Defaults to `{}`. See §7.4.                                              |
 | `applyEndpoint`      | `string` (optional)            | Browser POST target for apply previews and confirmed writes. See §3 and [Apply pipeline reference](/docs/reference/apply-pipeline).                                          |
 | `applyRouting`       | `Record<string, string>` (optional) | CSS-var prefix-family to repo-relative CSS-file routing map used by the apply endpoint.                                                                                   |
 | `applySink`          | `ApplySink` (optional)         | Optional sink that routes this instance's CSS-var writes off `:root`. See §5.4. Not JSON-serializable — do not include in Astro inline config.                        |
@@ -595,7 +646,7 @@ const handle = configurePanel({
 The Astro entry point (`<DesignTokenPanelHost>`) handles mounting for you. Internally:
 
 - The console API (`showDesignPanel` etc.) is **always installed eagerly**, even when the panel module has not loaded — calling them is what triggers the lazy import for cold-start users.
-- The panel module is **dynamically imported on first need**: when the user calls a console helper, OR when first-paint detects any of these gate signals in `localStorage` — `${storagePrefix}:visible` set to `1` or its `${storagePrefix}-open` mirror set to `1`, persisted overrides (a content check across the `${storagePrefix}-state` family — `-state` (v1) through every `-state-vN` — rather than a presence check on a specific version key; see §9), the owner-autoload flag (`${storagePrefix}:autoload` set to `'1'` or `'auto'`), or the element-path inspector enabled. `${storagePrefix}-domtweaker-enabled` is also a gate signal when `domTweaker` is configured.
+- The panel module is **dynamically imported on first need**: when the user calls a console helper, OR when first-paint detects any of these gate signals in `localStorage` — `${storagePrefix}:visible` set to `1` or its `${storagePrefix}-open` mirror set to `1`, persisted overrides (bounded content checks for the state formats the loader can read: `-state` (v1), `-state-v2`, `-state-v3`, and `-state-v4`; see §9), the owner-autoload flag (`${storagePrefix}:autoload` set to `'1'` or `'auto'`), or the element-path inspector enabled. `${storagePrefix}-domtweaker-enabled` is also a gate signal when `domTweaker` is configured.
 - This gating keeps the panel bundle out of the initial JS payload for first-time visitors while still re-applying overrides on hard reload for users who have tweaked things. **General visitors** (none of these signals set) pay no panel-bundle cost; the small host adapter/config bootstrap still runs.
 
 For a Vite-only / non-Astro host, mount it yourself by importing the adapter module after `configurePanel(...)`. See §8.5.
@@ -606,7 +657,7 @@ The first time an instance opens with no persisted position, the panel picks its
 
 - **Size first, position from that size.** The default size follows the historical `min(1200, 0.8·vw) × min(800, 0.8·vh)` rule, clamped to a minimum floor and the viewport. The default position then centers _that same clamped rectangle_. Position and size can no longer disagree about the panel's width — they used to be computed separately, which could center a wider phantom panel than the one actually rendered and spawn it partly off-screen on a narrow viewport.
 - **Always contained in the viewport.** The centered position is run through a containment clamp before use, so the whole panel — not just a grabbable strip of it — sits inside `[0, innerWidth]` × `[0, innerHeight]`. This holds at every viewport width, including phone widths, and it holds for a *persisted* size too: an instance that has a saved size but no saved position (the user resized the panel without ever dragging it) is centered and contained against that saved size, not against the default one.
-- **Instance-aware: concurrent panels cascade apart.** Each additional concurrently-mounted instance offsets its own fresh-open position by 24px on both axes. The offset comes from mount order with lowest-free-slot reuse — the first free ordinal is claimed on mount and given back on unmount, so opening a third panel after closing the first reuses ordinal 0 rather than always growing. Two instances opened at once therefore don't spawn stacked exactly on top of each other.
+- **Instance-aware: concurrent panels cascade apart.** Each additional concurrently-mounted instance offsets its own fresh-open position by 24px on both axes. Each `storagePrefix` persists its allocated ordinal, so an Astro body swap restores the same cascade position even when remount order differs from original open order. With no valid stored ordinal, allocation uses mount order with lowest-free-slot reuse and then records the result. Unmounting always releases the live claim: a departed instance's retained identity does not reserve a slot, and a later panel may reuse it. If two prefixes contain the same ordinal, the already-live holder keeps it and the later claimant takes and persists the lowest free slot. Two instances opened at once therefore don't spawn stacked exactly on top of each other.
 - **A persisted position always wins.** The cascade offset applies only to the fallback used when an instance has no saved position yet. A panel the user has dragged (and which got saved) reopens exactly where it was left, regardless of how many sibling instances happen to be mounted.
 - **Containment beats distinctness.** These two guarantees are not both promised unconditionally — on a viewport with no spare room, the 24px cascade shrinks toward whatever slack is left, down to a 0px offset, rather than pushing a panel outside the viewport. Two instances' first-open positions may then coincide. Each axis degrades independently: at a 320px viewport width the horizontal offset collapses to 0 once the minimum-width floor eats all the spare width, while the vertical offset may still cascade its full 24px if vertical slack remains.
 - **A different, stricter rule than the drag-recovery clamp.** Once a panel has been dragged, its position is governed by a separate, deliberately permissive clamp: it only guarantees a small grip of the panel's header stays on-screen so the user can drag it back, and otherwise allows the panel to hang off any edge. That drag clamp is unchanged and keeps applying after a drag; the full-containment guarantee above is specific to the first-open fallback position and does not carry over once the user has moved the panel.
@@ -853,7 +904,7 @@ literal mapping, or `light-dark(light, dark)` for a per-mode literal.
 Roles absent from `colorExtras.baseRoles` are not written, so a minimalist
 cluster (just `background` + `foreground`) is fine.
 
-### 7.5 Host-supplied scheme presets — `colorPresets`
+### 7.4 Host-supplied scheme presets — `colorPresets`
 
 The Color tab's "Scheme..." dropdown surfaces named `ColorScheme` entries. Two sources feed it:
 
@@ -1012,6 +1063,7 @@ Behaviour notes:
 | `state-v1`  | `${storagePrefix}-state`    | Legacy pre-v2 flat-state format (Color-only). Migrated into `state-v3` (and from there into `state-v4`) on first load, then deleted. |
 | `open`      | `${storagePrefix}-open`     | Mirror of the panel's `open` boolean, read synchronously at mount so user intent survives reloads. |
 | `position`  | `${storagePrefix}-position` | Drag position `{ top, left }` so the panel reappears where the user left it. |
+| `spawn-ordinal` | `${storagePrefix}-spawn-ordinal` | Instance cascade identity: a JSON integer from 0 through 31, retained by Reset and restored across Astro body swaps. Invalid values fall back to lowest-free allocation. |
 | `size`      | `${storagePrefix}-size`     | Floating shell dimensions `{ width, height }` in pixels. |
 | `dock`      | `${storagePrefix}-dock`     | Presentation mode: `'float'`, `'right'`, `'bottom'`, or `'mini'`. |
 | `dock-size` | `${storagePrefix}-dock-size` | Right/bottom dock dimensions `{ right, bottom }`, defaulting to `{ right: 440, bottom: 340 }`. |
@@ -1038,6 +1090,7 @@ myapp-design-token-panel-state-v2
 myapp-design-token-panel-state
 myapp-design-token-panel-open
 myapp-design-token-panel-position
+myapp-design-token-panel-spawn-ordinal
 myapp-design-token-panel-size
 myapp-design-token-panel-dock
 myapp-design-token-panel-dock-size
@@ -1359,7 +1412,7 @@ For the regression-guard tests that pin this contract, see `package-exports.test
 
 **Symptom:** on first paint after a hard reload, the page renders with the consumer's default token values for a beat before snapping to the user's saved overrides.
 
-**Resolution:** the host adapter eagerly re-applies persisted overrides during the lazy-load gate (it content-checks the exact `${storagePrefix}-state` / `${storagePrefix}-state-vN` family and the visibility, autoload, and enabled-feature signals synchronously from `localStorage`). If you still see a flash, your `<DesignTokenPanelHost>` is being rendered too late in the document (e.g. inside a deferred island) — move it to the layout's `<body>` and verify the inline `<script type="application/json" id="tokenpanel-config">` is in the initial HTML.
+**Resolution:** the host adapter eagerly re-applies persisted overrides during the lazy-load gate (it performs bounded content checks for the readable `${storagePrefix}-state`, `-state-v2`, `-state-v3`, and `-state-v4` keys, plus the visibility, autoload, and enabled-feature signals synchronously from `localStorage`). If you still see a flash, your `<DesignTokenPanelHost>` is being rendered too late in the document (e.g. inside a deferred island) — move it to the layout's `<body>` and verify the inline `<script type="application/json" id="tokenpanel-config">` is in the initial HTML.
 
 ### 13.2 Auto-mount race on first reload
 

package/dist/astro/host-adapter.js

@@ -1,8 +1,9 @@
-import { c as y, g as m, a as w, b, i as P } from "../panel-config-CRf-ONSV.js";
-import { g, Z as k } from "../tweak-state-BGp_7Tfh.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-7BQYXI7Y.js";
+import { c as y, g as m, a as w, b, i as P } from "../panel-config-CqbuB0nh.js";
+import { g, Z as A } from "../tweak-state-c53KtLHq.js";
+import { s as D, l as E, a as _, i as c, r as f, c as k, b as S, d } from "../autoload-state-BI4-9A58.js";
+import { READABLE_STATE_KEY_SUFFIXES as T } from "../constants.js";
 const u = "tokenpanel-config";
-function S() {
+function I() {
   if (typeof document > "u")
     throw new Error(
       "[design-token-panel] host-adapter loaded without a document; expected to run in a browser context."
@@ -12,24 +13,24 @@ function S() {
     throw new Error(
       `[design-token-panel] Inline config script #${u} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
     );
-  const o = e.textContent ?? "";
-  let n;
+  const n = e.textContent ?? "";
+  let o;
   try {
-    n = JSON.parse(o);
+    o = JSON.parse(n);
   } catch (a) {
     throw new Error(
       `[design-token-panel] Failed to parse inline config from #${u}: ${a.message}`
     );
   }
-  return b(n), n;
+  return b(o), o;
 }
-function T(e) {
+function v(e) {
   return e.__zudoDesignTokenPanelAdapter || (e.__zudoDesignTokenPanelAdapter = {}), e.__zudoDesignTokenPanelAdapter;
 }
-function v(e, o) {
-  const n = T(e);
-  let a = n[o];
-  return a || (a = { bound: !1, modulePromise: null }, n[o] = a), a;
+function C(e, n) {
+  const o = v(e);
+  let a = o[n];
+  return a || (a = { bound: !1, modulePromise: null }, o[n] = a), a;
 }
 function p(e) {
   try {
@@ -38,58 +39,53 @@ function p(e) {
     return !1;
   }
 }
-function C(e) {
-  return e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
 function O(e) {
   if (e === null || e === "") return !1;
-  let o;
+  let n;
   try {
-    o = JSON.parse(e);
+    n = JSON.parse(e);
   } catch {
     return !0;
   }
-  return o === null ? !1 : Array.isArray(o) ? o.length > 0 : typeof o == "object" ? Object.keys(o).length > 0 : !0;
+  return n === null ? !1 : Array.isArray(n) ? n.length > 0 : typeof n == "object" ? Object.keys(n).length > 0 : !0;
 }
 function x(e) {
   try {
-    const o = new RegExp(`^${C(e.storagePrefix)}-state(-v\\d+)?$`), n = window.localStorage;
-    for (let a = 0; a < n.length; a++) {
-      const t = n.key(a);
-      if (t !== null && o.test(t) && O(n.getItem(t)))
+    const n = window.localStorage;
+    for (const o of Object.values(T))
+      if (O(n.getItem(e.storagePrefix + o)))
         return !0;
-    }
     return !1;
   } catch {
     return !1;
   }
 }
 async function s(e) {
-  return e.modulePromise === null && (e.modulePromise = import("@takazudo/zdtp").then((o) => {
+  return e.modulePromise === null && (e.modulePromise = import("@takazudo/zdtp").then((n) => {
     try {
-      const n = m(), a = o.__panelConfigForTest();
-      n !== a && console.warn(
+      const o = m(), a = n.__panelConfigForTest();
+      o !== a && console.warn(
         "[design-token-panel] Singleton-sharing check failed: the host adapter and the panel module observed different PanelConfig singletons. This indicates the package's `config/panel-config` module is no longer code-split into a single shared chunk. The panel may behave correctly today, but storage keys / namespaces / branding could diverge between the two surfaces in future bundles."
       );
-    } catch (n) {
+    } catch (o) {
       console.warn(
-        "[design-token-panel] Singleton-sharing check could not run (likely an older dist without the __panelConfigForTest accessor): " + n.message
+        "[design-token-panel] Singleton-sharing check could not run (likely an older dist without the __panelConfigForTest accessor): " + o.message
       );
     }
-    return o;
+    return n;
   })), e.modulePromise;
 }
-function R(e, o, n, a, t) {
-  const i = e[o] ?? {};
+function N(e, n, o, a, t) {
+  const i = e[n] ?? {};
   i.showDesignPanel = async () => {
     const r = d();
-    await s(n), c(r) && (f(t), a.open());
+    await s(o), c(r) && (f(t), a.open());
   }, i.hideDesignPanel = async () => {
     const r = d();
-    await s(n), c(r) && a.close();
+    await s(o), c(r) && a.close();
   }, i.toggleDesignPanel = async () => {
     const r = d();
-    if (await s(n), !c(r)) return;
+    if (await s(o), !c(r)) return;
     a.toggle();
     let l = !1;
     try {
@@ -98,17 +94,17 @@ function R(e, o, n, a, t) {
     }
     l && f(t);
   }, i.enableAutoload = async () => {
-    const r = d(), l = await s(n);
+    const r = d(), l = await s(o);
     c(r) && l.enableAutoload(t);
   }, i.disableAutoload = async () => {
     const r = d();
-    if (n.modulePromise !== null) {
-      const l = await s(n);
+    if (o.modulePromise !== null) {
+      const l = await s(o);
       if (!c(r)) return;
       l.disableAutoload(t);
       return;
     }
-    _(t), I(!1, t);
+    k(t), S(!1, t);
     try {
       window.localStorage.setItem(w(t), "0");
     } catch {
@@ -117,30 +113,30 @@ function R(e, o, n, a, t) {
       window.localStorage.removeItem(g(t));
     } catch {
     }
-  }, e[o] = i;
+  }, e[n] = i;
 }
-function N(e, o) {
+function F(e, n) {
   P({
     show: async () => {
-      const n = d();
-      await s(e), c(n) && o.open();
+      const o = d();
+      await s(e), c(o) && n.open();
     },
     hide: async () => {
-      const n = d();
-      await s(e), c(n) && o.close();
+      const o = d();
+      await s(e), c(o) && n.close();
     },
     toggle: async () => {
-      const n = d();
-      await s(e), c(n) && o.toggle();
+      const o = d();
+      await s(e), c(o) && n.toggle();
     }
   });
 }
 (function() {
-  const o = S(), n = o.legacyIdRenameMap ? o : { ...o, legacyIdRenameMap: { ...k } }, a = y(n), t = m(), i = window, r = v(i, t.storagePrefix);
-  if (R(i, t.consoleNamespace, r, a, t), N(r, a), r.bound) return;
+  const n = I(), o = n.legacyIdRenameMap ? n : { ...n, legacyIdRenameMap: { ...A } }, a = y(o), t = m(), i = window, r = C(i, t.storagePrefix);
+  if (N(i, t.consoleNamespace, r, a, t), F(r, a), r.bound) return;
   r.bound = !0;
   const l = w(t);
-  (p(l) || p(g(t)) || x(t) || A(t) || D(t) || t.domTweaker !== void 0 && E(t)) && s(r).catch((h) => {
+  (p(l) || p(g(t)) || x(t) || D(t) || E(t) || t.domTweaker !== void 0 && _(t)) && s(r).catch((h) => {
     console.error("[design-token-panel] Eager panel-module load failed.", h);
   });
 })();

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { s as t } from "../panel-config-CRf-ONSV.js";
+import { s as t } from "../panel-config-CqbuB0nh.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-DvuKi7I4.js";
 const e = {

package/dist/{autoload-state-7BQYXI7Y.js → autoload-state-BI4-9A58.js}

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

package/dist/config/panel-config.d.ts

@@ -47,6 +47,7 @@
  */
 import type { ColorScheme } from './color-schemes';
 import type { TabConfig } from '../tokens/tier-model';
+export { DEFAULT_STORAGE_PREFIX, DEFAULT_TOGGLE_EVENT } from '../constants';
 /**
  * Apply-routing map.
  *
@@ -470,6 +471,13 @@ export declare function storageKey_stateV3(cfg: PanelConfig): string;
 export declare function storageKey_stateV4(cfg: PanelConfig): string;
 /** Legacy v1 key (Color-only flat state). Migrated into v2 on first load, then deleted. */
 export declare function storageKey_stateV1(cfg: PanelConfig): string;
+/**
+ * Persisted identity used to keep a fresh panel's cascade position stable
+ * across an Astro body swap. This is deliberately separate from the unified
+ * tweak-state envelopes: it identifies an instance; it is not user-authored
+ * token state and does not participate in state-schema migration.
+ */
+export declare function storageKey_spawnOrdinal(cfg: PanelConfig): string;
 /** Mirror of the panel's `open` boolean (synchronous mount-time read). */
 export declare function storageKey_open(cfg: PanelConfig): string;
 /** Drag position `{ top, left }` so the panel reappears where the user left it. */
@@ -510,13 +518,6 @@ export declare function storageKey_visible(cfg: PanelConfig): string;
 export declare function storageKey_autoload(cfg: PanelConfig): string;
 /** DOM id of the root element the Preact panel tree mounts into. */
 export declare function panelRootId(cfg: PanelConfig): string;
-/**
- * Historical public toggle-event name. Hosts have shipped `window.dispatchEvent(
- * new CustomEvent('toggle-design-token-panel'))` since the single-panel era, so
- * the default instance MUST keep emitting/listening on this name regardless of
- * its derived `toggle-${storagePrefix}` form.
- */
-export declare const DEFAULT_TOGGLE_EVENT = "toggle-design-token-panel";
 /**
  * Window-event name that toggles this instance's panel.
  *