@takazudo/zdtp 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -4,6 +4,77 @@ 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.2] - 2026-09-08
+
+### Features
+
+- Header actions now carry a stable `data-zdtp-action` attribute on both affordances — the inline header link and the compact kebab popover — with the ids `export`, `import`, `apply`, and `reset`. The ids are stable across releases; the display labels are not. This gives consumer tests a selector that survives a label change, which is what broke in [#831](https://github.com/Takazudo/zudo-design-token-panel/issues/831). The hook removes the dependence on the label; it does **not** remove the responsive collapse, so a locator still needs to be visibility-qualified and panel-scoped — see the recipe [Reaching header actions](https://zdtp.zudolab.dev/docs/recipes/reaching-header-actions/) and `PORTABLE-CONTRACT.md` §7.6. (91916b4, [#840](https://github.com/Takazudo/zudo-design-token-panel/issues/840))
+
+### Fixed
+
+- The popover action items and the header region items are now keyed by their stable action id rather than by their display label. Two actions sharing a label previously produced duplicate keys, so reconciliation could reuse the wrong node and leave an item with a stale handler or `aria-disabled` state. (c3384ae)
+- The 0.5.1 changelog said the old header-action selector "worked through 0.4.14". It worked through **0.5.0** — `v0.4.15` and `v0.5.0` both shipped before the collapse landed. (c3384ae)
+
+### Other Changes
+
+- The documentation site moved to `https://zdtp.zudolab.dev/`, and the playground and minimal example to `https://zdtp-playground.zudolab.dev/` and `https://zdtp-minimal.zudolab.dev/`. The package `homepage` field follows. (0b9e596, ef41bf2, [#835](https://github.com/Takazudo/zudo-design-token-panel/issues/835))
+- The 0.5.1 release notes now flag the header-action collapse as consumer-affecting, with the exact `1135px` container-query threshold and the fact that it measures the shell's content-box inline size rather than the viewport. (6215888, [#841](https://github.com/Takazudo/zudo-design-token-panel/issues/841))
+- New bilingual recipe, [Reaching header actions](https://zdtp.zudolab.dev/docs/recipes/reaching-header-actions/), covering both a label-based pattern for existing releases and the id-based pattern from this one. (c701369, [#842](https://github.com/Takazudo/zudo-design-token-panel/issues/842))
+- Twenty dead `*.pages.dev` example-demo links on the Examples page were repointed to their live `zudolab.dev` hosts. (c83ffa3, [#836](https://github.com/Takazudo/zudo-design-token-panel/issues/836))
+
+## [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.
+
+### Breaking Changes
+
+- **Narrowed the accepted-key set of `EAGER_LOAD_GATE_STATE_FAMILY.matchesKey`, a public exported API.** 0.5.0 accepted `${storagePrefix}-state` optionally followed by `-v` and one or more digits. 0.5.1 accepts only exact matches against the new `READABLE_STATE_KEY_SUFFIXES` registry — `-state`, `-state-v2`, `-state-v3`, `-state-v4`. So `${storagePrefix}-state` and `${storagePrefix}-state-v2` still match, while `${storagePrefix}-state-v1`, `${storagePrefix}-state-v0`, `${storagePrefix}-state-v01`, and `${storagePrefix}-state-v123` matched in 0.5.0 and do not in 0.5.1. The narrowing is deliberate — the synchronous eager gate must probe only the key versions the loader can actually read — but it is consumer-observable, the TypeScript signature is unchanged so a type check will not surface it, and it should have ridden a minor release rather than this patch. **Migration**: hosts asserting on `-state-vN` keys should derive them from the new `READABLE_STATE_KEY_SUFFIXES` export instead of matching a numeric pattern, so their assertions self-update at the next storage-format bump. (bcc55fd, [#790](https://github.com/Takazudo/zudo-design-token-panel/issues/790), [#793](https://github.com/Takazudo/zudo-design-token-panel/issues/793), [#814](https://github.com/Takazudo/zudo-design-token-panel/issues/814))
+
+- **Header action links now collapse behind the kebab menu at a panel content width of 1135px and below, making previously-clickable controls unreachable by their old selectors.** _(Retroactive correction added 2026-09-08. This behaviour shipped in 0.5.1 but was recorded only under **Fixed**, as `fix(panel): yield header controls before floating panel overflow`; it belongs here.)_ The header action links — Export, Load from JSON…, Apply, Reset — are hidden and served instead from the kebab trigger `.tokenpanel-actions-menu-btn` (`aria-label="Panel actions"`), which opens `.tokenpanel-actions-popover`. The rule is `@container tokenpanel (max-width: 1135px)` against `.tokenpanel-shell` (`container: tokenpanel / inline-size`). Two properties of that threshold matter: it engages at **1135px and below** — exactly 1135px collapses, 1136px does not — and it measures the **shell's own content-box inline size, not the viewport**, so the panel's borders count against the measured width. 1135px is wide enough that an ordinary desktop panel is already past it; a shell at 1024px is not a narrow or mobile case. The surprise is not that a responsive collapse exists but that it engages at a width most people would call desktop. Collapsed links are `display: none` and therefore leave the accessibility tree, so a query that worked through 0.5.0 times out on 0.5.1:
+
+  ```js
+  await page.getByRole('button', { name: 'Reset', exact: true }).click();
+  ```
+
+  Like the `matchesKey` narrowing above, this is consumer-observable, the TypeScript signature is unchanged so a type check will not surface it, and it should have ridden a minor release rather than this patch. **Migration**: open the kebab menu before reaching for an action, or drive the panel at a content width above the threshold — the recipe [Reaching header actions](https://zdtp.zudolab.dev/docs/recipes/reaching-header-actions/) covers both, with the boundary arithmetic. A stable `data-zdtp-action` attribute for these controls landed in 0.5.2; it does not exist in 0.5.1. (06cbb0e, [#787](https://github.com/Takazudo/zudo-design-token-panel/issues/787), [#831](https://github.com/Takazudo/zudo-design-token-panel/issues/831))
+
+### 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)
+- 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
@@ -503,7 +515,7 @@ export interface TierConfig {
 }
 
 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 reference](https://zdtp.zudolab.dev/docs/reference/color-cluster/).
 
 /**
  * Color-cluster extras — the non-tier fields required for the color tab.
@@ -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 |
@@ -1497,6 +1515,47 @@ pipeline:
 </script>
 ```
 
+### 7.6 `data-zdtp-action` — stable header-action DOM hook
+
+The four header actions carry a stable per-action attribute so a consumer test
+can select one without matching its display label:
+
+```html
+<div role="button" class="tokenpanel-action-link" data-zdtp-action="export">Export</div>
+```
+
+| Action label      | `data-zdtp-action` |
+| ----------------- | ------------------ |
+| `Export`          | `export`           |
+| `Load from JSON…` | `import`           |
+| `Apply`           | `apply`            |
+| `Reset`           | `reset`            |
+
+**The ids are stable; the labels are not.** Labels are display strings and may
+change at any minor version (note the ellipsis in `Load from JSON…`, which is
+`…` U+2026, not three periods). Select on the attribute, never on the text.
+
+Both affordances emit it with identical values: the header row and the compact
+kebab popover that takes over visually below the header's container-query
+threshold.
+
+**The hook does not remove the visibility branch.** `ShellHeader` *always*
+renders the header action row; the container query only hides it with
+`display: none`. So while the compact popover is open, `[data-zdtp-action="reset"]`
+matches **two** elements — the hidden header control and the popover item. A
+bare attribute selector is therefore not unambiguous at narrow widths; qualify
+it by visibility (Playwright's `:visible` / `.filter({ visible: true })`, or a
+non-zero bounding box) to land on exactly one.
+
+Scope — this hook covers the header actions and their compact popover only,
+which means every layout sharing `ShellHeader`: floating, right-docked, and
+bottom-docked. Deliberately **not** covered:
+
+- The **command palette**, which renders its own Export / Import / Apply entries
+  and whose reset entries are per-tab (`Reset {tab.label}`), not the header's
+  reset-all.
+- **Mini mode**, which renders Apply and has no header.
+
 ---
 
 ## 8. Storage-key continuity & migration paths
@@ -1642,6 +1701,28 @@ Items this contract deliberately does NOT pin down:
 
 ---
 
+## 11. Versioning & compatibility
+
+The package is pre-1.0 (`0.x`). This section states what a consumer may rely
+on across a release bump.
+
+- **The versioning promise.** On 0.x, patch releases preserve documented
+  public contracts and accepted consumer inputs. Consumer-breaking contract
+  changes, including input narrowing, require a minor release. Patches remain
+  free to fix bugs, and a bug fix can change observable behavior; the promise
+  only bounds what a patch may take *away* from a consumer.
+- **How breaking changes are signalled.** A consumer-breaking contract change
+  gets its own heading in the release notes, with a migration pointer naming
+  the new adoption path.
+- **What consumers should do.** A host mirroring the eager-load gate should
+  derive its checks from the exported registries
+  (`READABLE_STATE_KEY_SUFFIXES`, `EAGER_LOAD_GATE_KEY_SUFFIXES`) documented
+  in §6.2, rather than matching a pattern of its own — that way the host's
+  assertions self-update on the next storage-format bump instead of silently
+  drifting from the package's actual behavior.
+
+---
+
 ## Appendix A — section index
 
 Cross-reference table — what each section pins down.
@@ -1650,7 +1731,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 |
@@ -1670,7 +1751,9 @@ Cross-reference table — what each section pins down.
 | Modal class prefix and `data-design-token-panel-modal` selector contract                    | §7.3          |
 | Self-contained panel chrome palette (no host theme reads)                                  | §7.4          |
 | Host-adapter side-effect import (paired-unit obligation)                                    | §7.5          |
+| `data-zdtp-action` stable header-action hook (ids stable, labels not; two matches while the compact popover is open) | §7.6 |
 | v4 envelope precedence, v1/v2/v3 storage migration, and typography-id rename map             | §2, §8.3, §8.4 |
 | JSON export/import schemas v1/v2/v3 (serde)                                                  | §9            |
 | Out-of-scope / deferred concerns                                                            | §10           |
+| Versioning promise, breaking-change signalling, and consumer guidance for mirroring the eager-load gate registries | §11 |
 | Feature walkthrough and shortcut table                                                     | [Panel UX tour](/docs/recipes/panel-ux-tour) |

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;