@takazudo/zdtp 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -4,10 +4,65 @@ 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.6.0] - 2026-09-08
+
+### Breaking Changes
+
+- fix: validate reserved palette tab configuration (73e70f9). The reserved `palette` tab now rejects `colorExtras`, empty or non-color tiers, and inconsistent CSS-variable families. This also affects Astro host configuration validation. **Migration**: remove `colorExtras` from the `palette` tab; give each tier non-empty color items using either consecutive numbered CSS variables with one prefix or unique named variables with one prefix. Move mixed-kind generic tiers to a differently named tab and update any `referencesRamps` tab references.
+
+### Features
+
+- feat(minimal): teach grouped palette and semantic colors (5dcbe12)
+- feat(playground): use grouped OKLCH palette and semantic colors (42c7c86)
+
+### Fixed
+
+- fix: preserve host color-scheme on per-mode apply (90c30c6)
+- fix: render specimen fonts from instance values (7d18952)
+- fix: normalize emitted declaration module specifiers (8f858c0)
+- fix: expose panel config validator through public entrypoints (5335713)
+
+### Other Changes
+
+- docs: explain grouped palettes and per-mode semantic colors (3d1d114)
+- Restructure playground colors into grouped semantic ramps (2076abe)
+- test: verify specimen instance isolation in Chromium (6ff7ed6)
+- test: guard packed declarations across TypeScript resolution modes (f1e5e21)
+
+## [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)
@@ -25,7 +80,6 @@ The panel now fits its token grids, card controls, and header controls at the mi
 - 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)

package/PORTABLE-CONTRACT.md

@@ -191,6 +191,24 @@ export function setPanelColorPresets(presets: Record<string, ColorScheme>): void
 export function assertValidPanelConfig(value: unknown): asserts value is PanelConfig;
 ```
 
+`assertValidPanelConfig` and its `PanelConfig` type are public exports from both
+`@takazudo/zdtp` and `@takazudo/zdtp/testing`; no deep import is needed.
+Run the assertion against your host config in a CI test, for example:
+
+```ts
+import { assertValidPanelConfig } from '@takazudo/zdtp/testing';
+import { panelConfig } from './panel-config';
+
+// An invalid manifest throws and fails the test/CI run.
+assertValidPanelConfig(panelConfig);
+```
+
+The assertion accepts `unknown` and narrows it to `PanelConfig` on success.
+Validation is explicit: `configurePanel` does not call this assertion. A host
+that wants configure-time validation can import both functions from
+`@takazudo/zdtp` and call `assertValidPanelConfig(config)` before
+`configurePanel(config)`.
+
 Required behaviours:
 
 - **Multi-instance.** Calling `configurePanel` with a **distinct**
@@ -515,7 +533,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.
@@ -1515,6 +1533,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
@@ -1660,6 +1719,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.
@@ -1688,7 +1769,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/dist/apply/build-apply-overrides.d.ts

@@ -60,8 +60,8 @@
  *
  * Pure / no IO — safe to import anywhere (browser, Node, tests).
  */
-import type { ColorTweakState, TweakState, ColorClusterConfig } from '../state/tweak-state';
-import type { TabConfig } from '../tokens/tier-model';
+import type { ColorTweakState, TweakState, ColorClusterConfig } from "../state/tweak-state.js";
+import type { TabConfig } from "../tokens/tier-model.js";
 /**
  * Produce the flat cssVar → value map for the dev-API handler.
  *

package/dist/apply/last-applied.d.ts

@@ -1,4 +1,4 @@
-import type { PanelConfig } from '../config/panel-config';
+import type { PanelConfig } from "../config/panel-config.js";
 export type FlatOverrides = Record<string, string>;
 export declare function loadLastApplied(cfg: PanelConfig): FlatOverrides;
 export declare function saveLastApplied(overrides: FlatOverrides, cfg: PanelConfig): void;

package/dist/apply/reconcile-applied.d.ts

@@ -1,5 +1,5 @@
-import type { PanelConfig } from '../config/panel-config';
-import type { ColorTweakState, TweakState } from '../state/tweak-state';
+import type { PanelConfig } from "../config/panel-config.js";
+import type { ColorTweakState, TweakState } from "../state/tweak-state.js";
 /**
  * Remove only overrides the server confirms it wrote. CSS variables are
  * resolved through the manifest token index so color, secondary-color,

package/dist/apply/route-tokens-to-files.d.ts

@@ -14,7 +14,7 @@
  *
  * No IO, no DOM, no Node-specific imports — safe to bundle for the browser.
  */
-import type { ApplyRoutingMap } from '../config/panel-config';
+import type { ApplyRoutingMap } from "../config/panel-config.js";
 /**
  * Prefix-family identifier. Plain string — the routing map is host-supplied.
  */

package/dist/apply/tier-resolver.d.ts

@@ -19,7 +19,7 @@
  * For a reference tier (referencesTier is set) the value is the id of a target
  * item in the named tier.
  */
-import type { TabConfig } from '../tokens/tier-model';
+import type { TabConfig } from "../tokens/tier-model.js";
 export type TabOverrides = Readonly<Record<string, Readonly<Record<string, string>>>>;
 export declare class TierResolverError extends Error {
     constructor(message: string);

package/dist/apply-modal.d.ts

@@ -1,5 +1,5 @@
-import { type PanelConfig } from './config/panel-config';
-import { type ColorTweakState, type TweakState } from './state/tweak-state';
+import { type PanelConfig } from "./config/panel-config.js";
+import { type ColorTweakState, type TweakState } from "./state/tweak-state.js";
 export interface ApplyModalProps {
     state: TweakState;
     open: boolean;

package/dist/astro/host-adapter.js

@@ -1,6 +1,6 @@
-import { c as y, g as m, a as w, b, i as P } from "../panel-config-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 { c as y, g as m, a as w, b, i as P } from "../panel-config-Crn5QJGy.js";
+import { g, Z as A } from "../tweak-state-Dzr5kDhX.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-CGnis85c.js";
 import { READABLE_STATE_KEY_SUFFIXES as T } from "../constants.js";
 const u = "tokenpanel-config";
 function I() {

package/dist/astro/index.d.ts

@@ -22,11 +22,11 @@
  * callers don't need a deep `@takazudo/zdtp/dist/config/panel-config`
  * import to type their config object.
  */
-export type { PanelConfig } from '../config/panel-config';
-export type { ColorScheme, ColorRef } from '../config/color-schemes';
-export type { ColorClusterConfig } from '../state/tweak-state';
-export { setPanelColorPresets } from '../config/panel-config';
-export { colorSchemes } from '../config/color-schemes';
-export { panelSettings, SEMANTIC_CSS_NAMES, SEMANTIC_DEFAULTS_ZD } from '../config/color-scheme-utils';
-export { GROUP_ORDER, FONT_GROUP_ORDER, SIZE_GROUP_ORDER, GROUP_TITLES } from '../tokens/manifest';
-export type { TokenDef, TokenManifest } from '../tokens/manifest';
+export type { PanelConfig } from "../config/panel-config.js";
+export type { ColorScheme, ColorRef } from "../config/color-schemes.js";
+export type { ColorClusterConfig } from "../state/tweak-state.js";
+export { setPanelColorPresets } from "../config/panel-config.js";
+export { colorSchemes } from "../config/color-schemes.js";
+export { panelSettings, SEMANTIC_CSS_NAMES, SEMANTIC_DEFAULTS_ZD } from "../config/color-scheme-utils.js";
+export { GROUP_ORDER, FONT_GROUP_ORDER, SIZE_GROUP_ORDER, GROUP_TITLES } from "../tokens/manifest.js";
+export type { TokenDef, TokenManifest } from "../tokens/manifest.js";

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { s as t } from "../panel-config-CqbuB0nh.js";
+import { s as t } from "../panel-config-Crn5QJGy.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-BI4-9A58.js → autoload-state-CGnis85c.js}

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

package/dist/bulk/bulk-actions.d.ts

@@ -1,7 +1,7 @@
 import type { ComponentChildren } from 'preact';
-import type { TierConfig } from '../tokens/tier-model';
-import { type NumericValue } from '../utils/numeric-transform';
-import type { FlatTabEntry, RowContribution, TokenAddress } from '../tabs/flat/types';
+import type { TierConfig } from "../tokens/tier-model.js";
+import { type NumericValue } from "../utils/numeric-transform.js";
+import type { FlatTabEntry, RowContribution, TokenAddress } from "../tabs/flat/types.js";
 export interface BulkOperations {
     multiply: string;
     add: string;

package/dist/bulk/index.d.ts

@@ -1,2 +1,2 @@
-export { BulkActionBar, DEFAULT_BULK_OPERATIONS, createBulkContribution, isBulkSelectable, isSelectable, numericEntryUnit, numericValueForEntry, transformBulkEntry, } from './bulk-actions';
-export type { BulkActionBarProps, BulkContributionOptions, BulkOperations, BulkPatchEntry, } from './bulk-actions';
+export { BulkActionBar, DEFAULT_BULK_OPERATIONS, createBulkContribution, isBulkSelectable, isSelectable, numericEntryUnit, numericValueForEntry, transformBulkEntry, } from "./bulk-actions.js";
+export type { BulkActionBarProps, BulkContributionOptions, BulkOperations, BulkPatchEntry, } from "./bulk-actions.js";

package/dist/chain/index.d.ts

@@ -1,2 +1,2 @@
-export { ChainButton, ChainPopover, TOKEN_CHAIN_CONTRIBUTION, TokenChainButton, TokenChainPopover, type TokenChainButtonProps, type TokenChainPopoverProps, } from './token-chain-popover';
-export { TokenChainProvider, useTokenChainContext, type TokenChainContextValue, type TokenChainProviderProps, } from './token-chain-context';
+export { ChainButton, ChainPopover, TOKEN_CHAIN_CONTRIBUTION, TokenChainButton, TokenChainPopover, type TokenChainButtonProps, type TokenChainPopoverProps, } from "./token-chain-popover.js";
+export { TokenChainProvider, useTokenChainContext, type TokenChainContextValue, type TokenChainProviderProps, } from "./token-chain-context.js";

package/dist/chain/token-chain-context.d.ts

@@ -1,7 +1,7 @@
 import type { ComponentChildren } from 'preact';
-import type { PanelConfig } from '../config/panel-config';
-import type { TweakState } from '../state/tweak-state';
-import { type TokenGraph } from '../utils/token-graph';
+import type { PanelConfig } from "../config/panel-config.js";
+import type { TweakState } from "../state/tweak-state.js";
+import { type TokenGraph } from "../utils/token-graph.js";
 export interface TokenChainContextValue {
     graph: TokenGraph;
 }

package/dist/chain/token-chain-popover.d.ts

@@ -1,6 +1,6 @@
 import type { JSX } from 'preact';
-import { type TokenAddress } from '../utils/token-index';
-import type { RowContribution } from '../tabs/flat/types';
+import { type TokenAddress } from "../utils/token-index.js";
+import type { RowContribution } from "../tabs/flat/types.js";
 export interface TokenChainPopoverProps {
     address: TokenAddress;
     anchorRef: React.RefObject<HTMLElement | null>;

package/dist/changed/contribution.d.ts

@@ -5,11 +5,11 @@
  * row's visual state, Changed-only filtering, ghost value, and revert affordance
  * all consult the same `isChanged` result for the row's stable token address.
  */
-import type { PanelConfig } from '../config/panel-config';
-import type { TweakState } from '../state/tweak-state';
-import { revertEntry, type ColorBaseline } from '../utils/token-diff';
-import type { TokenIndex, TokenAddress } from '../utils/token-index';
-import type { RowContribution } from '../tabs/flat/types';
+import type { PanelConfig } from "../config/panel-config.js";
+import type { TweakState } from "../state/tweak-state.js";
+import { revertEntry, type ColorBaseline } from "../utils/token-diff.js";
+import type { TokenIndex, TokenAddress } from "../utils/token-index.js";
+import type { RowContribution } from "../tabs/flat/types.js";
 export interface ChangedContributionOptions {
     index: TokenIndex;
     state: TweakState;

package/dist/changed/footer-content.d.ts

@@ -1,8 +1,8 @@
 import type { JSX } from 'preact';
-import type { PanelConfig } from '../config/panel-config';
-import type { ColorBaseline } from '../utils/token-diff';
-import type { TweakState } from '../state/tweak-state';
-import type { TokenIndex } from '../utils/token-index';
+import type { PanelConfig } from "../config/panel-config.js";
+import type { ColorBaseline } from "../utils/token-diff.js";
+import type { TweakState } from "../state/tweak-state.js";
+import type { TokenIndex } from "../utils/token-index.js";
 export declare const COPY_REVERT_MS = 2000;
 export interface ChangedFooterContentProps {
     index: TokenIndex;

package/dist/changed/index.d.ts

@@ -1,4 +1,4 @@
-export { changedContribution, changedStateContribution, createChangedContribution, revertEntry, } from './contribution';
-export { ChangedFooter, ChangedFooterContent, COPY_REVERT_MS } from './footer-content';
-export { ChangedOnlyToggle } from './tab-filter';
-export { ChangedTabBadge, TabChangedBadge } from './tab-badge';
+export { changedContribution, changedStateContribution, createChangedContribution, revertEntry, } from "./contribution.js";
+export { ChangedFooter, ChangedFooterContent, COPY_REVERT_MS } from "./footer-content.js";
+export { ChangedOnlyToggle } from "./tab-filter.js";
+export { ChangedTabBadge, TabChangedBadge } from "./tab-badge.js";

package/dist/components/color-picker/color-field.d.ts

@@ -7,7 +7,7 @@
  * DOM-hygiene compliant: div-button with onClick + onKeyDown (Enter/Space);
  * no banned semantic tags — hostile-host policy (CLAUDE.md).
  */
-import type { ColorPickerValueFormat } from './color-picker';
+import type { ColorPickerValueFormat } from "./color-picker.js";
 export interface ColorFieldProps {
     /** Current color value. Hex string in hex mode; `oklch(...)` string in oklch mode. */
     value: string;

package/dist/components/color-picker/index.d.ts

@@ -1,2 +1,2 @@
-export { ColorPicker, type ColorPickerMode, type ColorPickerProps, LOCAL_STORAGE_KEY, getFixedPopoverStyle, usePopoverClose, } from './color-picker';
-export { default } from './color-picker';
+export { ColorPicker, type ColorPickerMode, type ColorPickerProps, LOCAL_STORAGE_KEY, getFixedPopoverStyle, usePopoverClose, } from "./color-picker.js";
+export { default } from "./color-picker.js";

package/dist/components/palette-chart/index.d.ts

@@ -1,2 +1,2 @@
-export { PaletteChart, type PaletteChartProps, type Oklcha, type Channel, } from './palette-chart';
-export { default } from './palette-chart';
+export { PaletteChart, type PaletteChartProps, type Oklcha, type Channel, } from "./palette-chart.js";
+export { default } from "./palette-chart.js";

package/dist/components/palette-chart/palette-chart.d.ts

@@ -1,6 +1,6 @@
 import type { JSX } from 'preact';
-import { type Channel } from '../../utils/palette-curve';
-import { type Oklcha } from '../../utils/color-oklch';
+import { type Channel } from "../../utils/palette-curve.js";
+import { type Oklcha } from "../../utils/color-oklch.js";
 /**
  * PaletteChart — controlled, presentational OKLCH L/C/H curve editor.
  *
@@ -32,8 +32,8 @@ import { type Oklcha } from '../../utils/color-oklch';
  *   within the same SVG, so a pointer-down on a node hits the circle (DOM order
  *   within an SVG determines paint/hit precedence).
  */
-export type { Oklcha } from '../../utils/color-oklch';
-export type { Channel } from '../../utils/palette-curve';
+export type { Oklcha } from "../../utils/color-oklch.js";
+export type { Channel } from "../../utils/palette-curve.js";
 export interface PaletteChartProps {
     /**
      * Dense palette slots in OKLCH space. A null slot preserves its index/band,

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

@@ -20,9 +20,9 @@
  * everything the color tab needs to render is reachable from
  * `panelConfig.colorCluster`.
  */
-import type { ColorScheme } from './color-schemes';
-import type { SemanticValue } from '../tokens/tier-model';
-export type { SemanticValue } from '../tokens/tier-model';
+import type { ColorScheme } from "./color-schemes.js";
+import type { SemanticValue } from "../tokens/tier-model.js";
+export type { SemanticValue } from "../tokens/tier-model.js";
 /**
  * Base-role keys that a cluster may declare. Subset is allowed (a cluster may
  * ship zero base roles when its design system doesn't expose them as tokens).
@@ -110,7 +110,7 @@ export interface ColorClusterDataConfig {
 export declare function resolvePaletteCssVar(cluster: {
     paletteCssVarTemplate: string;
 }, index: number): string;
-import type { TabConfig } from '../tokens/tier-model';
+import type { TabConfig } from "../tokens/tier-model.js";
 /**
  * Derive a `ColorClusterDataConfig` from a color `TabConfig`.
  *

package/dist/config/color-scheme-utils.d.ts

@@ -14,7 +14,7 @@
  *   mappings in the bundled tokens, so the panel's defaults on first open
  *   match the example CSS exactly.
  */
-import { type ColorScheme, type ColorRef } from './color-schemes';
+import { type ColorScheme, type ColorRef } from "./color-schemes.js";
 /**
  * Minimal local replacement for the upstream `settings` object. The panel only
  * ever reads `colorScheme` and `colorMode`; the rest of the upstream settings

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

@@ -45,9 +45,9 @@
  * arbitrary host-irrelevant data. Hosts MUST call `configurePanel(...)` to
  * see useful behaviour.
  */
-import type { ColorScheme } from './color-schemes';
-import type { TabConfig } from '../tokens/tier-model';
-export { DEFAULT_STORAGE_PREFIX, DEFAULT_TOGGLE_EVENT } from '../constants';
+import type { ColorScheme } from "./color-schemes.js";
+import type { TabConfig } from "../tokens/tier-model.js";
+export { DEFAULT_STORAGE_PREFIX, DEFAULT_TOGGLE_EVENT } from "../constants.js";
 /**
  * Apply-routing map.
  *
@@ -430,8 +430,8 @@ export declare function clearColorSchemeOwnership(prefix: string): void;
  * never removes a `color-scheme` it did not write.
  */
 export declare function ownsColorScheme(prefix: string): boolean;
-export { resolvePrimaryColorCluster, resolveSecondaryColorClusterFromTabs, } from './cluster-config';
-import type { ColorClusterDataConfig } from './cluster-config';
+export { resolvePrimaryColorCluster, resolveSecondaryColorClusterFromTabs, } from "./cluster-config.js";
+import type { ColorClusterDataConfig } from "./cluster-config.js";
 /**
  * Resolve the active primary color cluster from the panel config's tabs array.
  *

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

@@ -11,6 +11,10 @@
  */
 import type { ComponentChildren, JSX } from 'preact';
 export interface ActionsMenuAction {
+    /** Stable action id, emitted as `data-zdtp-action` on the rendered item.
+     *  Required so the DOM hook can never silently go missing; labels are
+     *  display strings and must not be used as the key (PORTABLE-CONTRACT §7.6). */
+    id: string;
     label: string;
     onSelect: () => void;
     disabled?: boolean;

package/dist/controls/role-button.d.ts

@@ -16,5 +16,8 @@ export interface RoleButtonProps {
     title?: string;
     'aria-label'?: string;
     'data-testid'?: string;
+    /** Stable per-action DOM hook for consumer tests (see PORTABLE-CONTRACT §7.6).
+     *  Keyed on an action id, never on the display label. */
+    'data-zdtp-action'?: string;
 }
-export declare function RoleButton({ children, onClick, className, 'aria-disabled': ariaDisabled, ariaProps, tabIndex, elementRef, id, title, 'aria-label': ariaLabel, 'data-testid': testId, }: RoleButtonProps): JSX.Element;
+export declare function RoleButton({ children, onClick, className, 'aria-disabled': ariaDisabled, ariaProps, tabIndex, elementRef, id, title, 'aria-label': ariaLabel, 'data-testid': testId, 'data-zdtp-action': zdtpAction, }: RoleButtonProps): JSX.Element;

package/dist/controls/tier-ref-selector.d.ts

@@ -1,4 +1,4 @@
-import type { TabConfig } from '../tokens/tier-model';
+import type { TabConfig } from "../tokens/tier-model.js";
 /**
  * Names one item in a (possibly cross-tab) tier. `tab` omitted means "the tab
  * `TierRefSelector` itself renders in" — the intra-tab case used by the

package/dist/dom-tweaker/dom-tweaker-diff-action-link.d.ts

@@ -1,5 +1,5 @@
 import type { JSX } from 'preact';
-import type { PanelConfig } from '../config/panel-config';
+import type { PanelConfig } from "../config/panel-config.js";
 export interface DomTweakerDiffActionLinkProps {
     instanceConfig: PanelConfig;
     onSelected?: () => void;

package/dist/dom-tweaker/dom-tweaker-orchestrator.d.ts

@@ -10,7 +10,7 @@
  *      explicit scalar config values into that boundary.
  */
 import type { ComponentChildren, JSX } from 'preact';
-import type { PanelConfig } from '../config/panel-config';
+import type { PanelConfig } from "../config/panel-config.js";
 export declare function DomTweakerOrchestrator({ children, instanceConfig, }: {
     children: ComponentChildren;
     instanceConfig: PanelConfig;

package/dist/dom-tweaker/dom-tweaker-state.d.ts

@@ -6,7 +6,7 @@
  * time (never at module init), so a late `configurePanel({ storagePrefix })`
  * is respected by no-arg callers.
  */
-import { type PanelConfig } from '../config/panel-config';
+import { type PanelConfig } from "../config/panel-config.js";
 export declare function storageKey_domTweakerEnabled(cfg?: PanelConfig): string;
 /**
  * Load the persisted enabled flag from localStorage. Defaults to `false` on

package/dist/dom-tweaker/lazy/class-editor-popup.d.ts

@@ -1,5 +1,5 @@
 import type { JSX } from 'preact';
-import { type TrackedElementRect } from './pinned-selection-overlay';
+import { type TrackedElementRect } from "./pinned-selection-overlay.js";
 export interface ClassEditorPopupProps {
     target: Element | null;
     selectorSummary: string;

package/dist/dom-tweaker/lazy/diff-export-modal.d.ts

@@ -1,5 +1,5 @@
 import type { JSX } from 'preact';
-import { type PanelConfig } from '../../config/panel-config';
+import { type PanelConfig } from "../../config/panel-config.js";
 export interface DiffExportModalProps {
     diffText: string;
     onClose: () => void;

package/dist/dom-tweaker/lazy/index.d.ts

@@ -8,8 +8,8 @@
  * lazy boundary does not read global panel config.
  */
 import type { JSX } from 'preact';
-import type { DomTweakerRuntimeStatus } from '../dom-tweaker-context';
-export { buildStaticSuggestions, buildSuggestions, buildThemeSuggestions, filterSuggestions, STATIC_SUGGESTIONS, } from './suggestions';
+import type { DomTweakerRuntimeStatus } from "../dom-tweaker-context.js";
+export { buildStaticSuggestions, buildSuggestions, buildThemeSuggestions, filterSuggestions, STATIC_SUGGESTIONS, } from "./suggestions.js";
 export interface DomTweakerLazyBoundaryProps {
     enabled: boolean;
     storagePrefix: string;

package/dist/element-inspect/element-inspect-context.d.ts

@@ -1,4 +1,4 @@
-import type { FindTokensForElementResult } from './find-tokens-for-element';
+import type { FindTokensForElementResult } from "./find-tokens-for-element.js";
 /** The synthetic tab id used by the transient element-inspect view. */
 export declare const ELEMENT_INSPECT_TAB_ID = "inspect";
 export interface ElementInspectContextValue {

package/dist/element-inspect/element-inspect-orchestrator.d.ts

@@ -1,7 +1,7 @@
 import type { ComponentChildren } from 'preact';
-import type { PanelConfig } from '../config/panel-config';
-import type { TweakState } from '../state/tweak-state';
-import type { CommitTweakStateOptions, TweakStateUpdater } from '../state/transaction';
+import type { PanelConfig } from "../config/panel-config.js";
+import type { TweakState } from "../state/tweak-state.js";
+import type { CommitTweakStateOptions, TweakStateUpdater } from "../state/transaction.js";
 type CommitTweakState = (reason: string, next: TweakStateUpdater, options?: CommitTweakStateOptions) => void;
 export interface ElementInspectOrchestratorProps {
     children: ComponentChildren;