0.5.1

Release notes for 0.5.1.

Released: 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, #793, #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:

  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 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, #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 from Takazudo/base/sweep-260906-2 (2631545)

• Merge pull request #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 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 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 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)