@takazudo/zdtp 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.

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 }`.                                                           |
@@ -316,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
@@ -336,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
 
@@ -389,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
@@ -1130,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
@@ -1143,13 +1156,18 @@ if (
   sink (or default `:root`) even when the panel stays hidden, otherwise
   hard-nav produces a FOUT.
 
-  `EAGER_LOAD_GATE_STATE_FAMILY.matchesKey(storagePrefix, key)` only recognizes
-  the exact `${storagePrefix}-state` / `${storagePrefix}-state-vN` key shape. It
-  does not read storage or perform the content check. The consumer must apply
-  the accompanying `valueRules`: raw empty strings, JSON `null`, and empty
+  `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.
+  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
@@ -1179,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 |
@@ -1650,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

@@ -588,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.                        |
@@ -646,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.
@@ -657,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.
@@ -904,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:
 
@@ -1063,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 }`. |
@@ -1089,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
@@ -1410,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-BSu6TUht.js";
-import { g, Z as k } from "../tweak-state-B7ok3Ob3.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-DmTY6tRy.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-BSu6TUht.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-DmTY6tRy.js → autoload-state-BI4-9A58.js}

@@ -1,4 +1,4 @@
-import { g as n, j as o } from "./panel-config-BSu6TUht.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

@@ -471,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. */

package/dist/constants.d.ts

@@ -43,17 +43,37 @@ export declare const EAGER_LOAD_GATE_KEY_SUFFIXES: {
     };
 };
 /**
- * The sixth eager-load signal: exact -state / -state-vN keys, for every numeric
- * version, with a content check. Missing keys and raw empty strings are blank;
+ * The single registry of state-key suffixes the current loader can read.
+ *
+ * EVERY storage-format version bump must update this registry in the same
+ * change that teaches the loader to read that version. The synchronous eager
+ * gate intentionally probes only these bounded, readable versions; speculative
+ * future versions would promise recovery that the loader cannot perform.
+ */
+export declare const READABLE_STATE_KEY_SUFFIXES: {
+    readonly v1: "-state";
+    readonly v2: "-state-v2";
+    readonly v3: "-state-v3";
+    readonly v4: "-state-v4";
+};
+/**
+ * The sixth eager-load signal: exact readable state keys, with a content
+ * check. Missing keys and raw empty strings are blank;
  * JSON null and empty objects/arrays do not activate. Non-empty collections and
  * all other parsed primitives (even false, 0, or JSON "") activate. Malformed
  * JSON fails open so the panel can migrate or reject the stored payload.
  *
- * matchesKey compares the prefix literally before matching the suffix, so regex
- * metacharacters in a prefix are safe and sibling-instance keys are excluded.
+ * matchesKey compares complete strings constructed from the literal prefix, so
+ * regex metacharacters are safe and sibling-instance keys are excluded.
  * These are storage signal descriptions, not a storage reader or panel bootstrap.
  */
 export declare const EAGER_LOAD_GATE_STATE_FAMILY: {
+    readonly keySuffixes: {
+        readonly v1: "-state";
+        readonly v2: "-state-v2";
+        readonly v3: "-state-v3";
+        readonly v4: "-state-v4";
+    };
     readonly matchesKey: (storagePrefix: string, key: string) => boolean;
     readonly valueRules: {
         readonly blank: false;

package/dist/constants.js

@@ -1,16 +1,24 @@
-const n = "zudo-design-token-panel", l = "toggle-design-token-panel";
-function o(e) {
-  return e.storagePrefix === void 0 || e.storagePrefix === n ? l : e.toggleEvent ?? `toggle-${e.storagePrefix}`;
+const o = "zudo-design-token-panel", l = "toggle-design-token-panel";
+function r(e) {
+  return e.storagePrefix === void 0 || e.storagePrefix === o ? l : e.toggleEvent ?? `toggle-${e.storagePrefix}`;
 }
-const a = {
+const s = {
   ":visible": { acceptedValues: ["1"], requiredConfig: null },
   "-open": { acceptedValues: ["1"], requiredConfig: null },
   ":autoload": { acceptedValues: ["1", "auto"], requiredConfig: null },
   "-elpath-enabled": { acceptedValues: ["1"], requiredConfig: null },
   "-domtweaker-enabled": { acceptedValues: ["1"], requiredConfig: "domTweaker" }
-}, r = {
-  matchesKey(e, t) {
-    return t.startsWith(e) && /^-state(-v\d+)?$/.test(t.slice(e.length));
+}, t = {
+  v1: "-state",
+  v2: "-state-v2",
+  v3: "-state-v3",
+  v4: "-state-v4"
+}, u = {
+  keySuffixes: t,
+  matchesKey(e, a) {
+    return Object.values(t).some(
+      (n) => a === e + n
+    );
   },
   valueRules: {
     blank: !1,
@@ -22,9 +30,10 @@ const a = {
   }
 };
 export {
-  n as DEFAULT_STORAGE_PREFIX,
+  o as DEFAULT_STORAGE_PREFIX,
   l as DEFAULT_TOGGLE_EVENT,
-  a as EAGER_LOAD_GATE_KEY_SUFFIXES,
-  r as EAGER_LOAD_GATE_STATE_FAMILY,
-  o as resolveToggleEventName
+  s as EAGER_LOAD_GATE_KEY_SUFFIXES,
+  u as EAGER_LOAD_GATE_STATE_FAMILY,
+  t as READABLE_STATE_KEY_SUFFIXES,
+  r as resolveToggleEventName
 };

package/dist/controls/actions-menu-popover.d.ts

@@ -1,7 +1,7 @@
 /**
  * ActionsMenuPopover — narrow-panel replacement for the header action links
  * (Export / Load from JSON… / Apply / Reset), collapsed behind the kebab
- * trigger below the panel's <480px container-query breakpoint (#518).
+ * trigger when the header yields through its CSS container query (#787).
  *
  * A PLAIN popover of ordinary action RoleButtons, NOT an ARIA menu:
  * role="menu"/menuitem demands arrow-key navigation and focus management,

package/dist/dom-tweaker/dom-tweaker-toggle-button.d.ts

@@ -6,4 +6,6 @@
  * import through DomTweakerOrchestrator.
  */
 import type { JSX } from 'preact';
-export declare function DomTweakerToggleButton(): JSX.Element | null;
+export declare function DomTweakerToggleButton({ compact }?: {
+    compact?: boolean;
+}): JSX.Element | null;

package/dist/element-inspect/element-inspect-toggle-button.d.ts

@@ -1,3 +1,5 @@
 import type { JSX } from 'preact';
 /** Header control for the element → tokens picker. */
-export declare function ElementInspectToggleButton(): JSX.Element | null;
+export declare function ElementInspectToggleButton({ compact }?: {
+    compact?: boolean;
+}): JSX.Element | null;

package/dist/element-path/element-path-toggle-button.d.ts

@@ -10,4 +10,6 @@
  * through its `ariaProps` bag.
  */
 import type { JSX } from 'preact';
-export declare function ElementPathToggleButton(): JSX.Element | null;
+export declare function ElementPathToggleButton({ compact }?: {
+    compact?: boolean;
+}): JSX.Element | null;