@takazudo/zdtp 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 0.4.3
+
+### Features
+
+- **Dismiss-layer arbitration for layered surfaces.** A shared dismiss-layer stack routes Escape to only the topmost open layer (nested popover → popover → panel), and all three modals gained gesture-aware backdrop dismissal (press+release must both land outside), fixing one-Escape-closes-everything, trigger-click reopen races, and text-selection drags closing modals ([#446](https://github.com/Takazudo/zudo-design-token-panel/issues/446)) (9119c7e, 8257b19)
+- **CSS isolation architecture.** Panel z-indexes are now a semantic token scale shared by CSS and TSX (shell renders above common host chrome), a `box-sizing` reset is scoped to the panel subtree, panel geometry moved from rem to px so host root font-size cannot warp the panel, and `color-scheme` is declared on panel surfaces ([#448](https://github.com/Takazudo/zudo-design-token-panel/issues/448)) (62f8e4c)
+- **Visual-regression test tier.** 8 Playwright baselines (palette chart, color-picker swatch + popover, panel chrome — light + dark) with a documented `test:vrt:update` flow, wired into CI ([#454](https://github.com/Takazudo/zudo-design-token-panel/issues/454)) (5241e02)
+- **Real lint + doc-link gates.** oxlint wired for the panel and linkinator + html-validate for the doc site — the CI Lint step is no longer a no-op ([#443](https://github.com/Takazudo/zudo-design-token-panel/issues/443)) (4812160)
+
+### Fixed
+
+- `configurePanel` re-runs no longer throw when combined with `setPanelColorPresets` (Astro view-transitions + lazy color presets recipe); sink instances seed from `panelSettings.colorScheme` instead of the host `data-theme`; palette cssVar templates and `colorExtras` are validated at configure time ([#440](https://github.com/Takazudo/zudo-design-token-panel/issues/440)) (afe8a36, 87df039, 4d5e611)
+- `applyTokenOverrides` no longer rewrites the wrong declaration when one custom-property name is a suffix of another — `zdtp-server` could corrupt CSS files on disk ([#441](https://github.com/Takazudo/zudo-design-token-panel/issues/441)) (3be6865)
+- Highlight subsystem: match cache is evicted on stylesheet changes (stale detached elements no longer stay highlighted), percentage values are classified as lengths, and a highlight probe runs one full-DOM walk instead of three ([#442](https://github.com/Takazudo/zudo-design-token-panel/issues/442)) (fc07e41)
+- PaletteSelector listbox is fully keyboard-operable; ApplyModal's `onApplied` cleanup contract now holds on every dismissal route ([#446](https://github.com/Takazudo/zudo-design-token-panel/issues/446)) (8257b19)
+- State persistence: changing a palette's size no longer discards spacing/typography/size/tab overrides; restored positions are viewport-clamped and finite; fresh-mount toggle intent; window-resize handling debounced; imported palette values pass the seed-time sanitizer; dead `panelPosition` path removed ([#447](https://github.com/Takazudo/zudo-design-token-panel/issues/447)) (8f67382)
+- Astro soft navigation unmounts/remounts **all** registered panel instances (was: default only — other instances leaked listeners per navigation and vanished until re-toggled), and persisted overrides are reapplied for every instance, including hidden ones ([#449](https://github.com/Takazudo/zudo-design-token-panel/issues/449), [#457](https://github.com/Takazudo/zudo-design-token-panel/issues/457)) (908d6df, 8ce3d8b)
+- CSS accessibility: `:focus-visible` styles for every native form control (host `outline: none` resets can no longer hide focus), raw color literals replaced by `--tokentweak-*` tokens, 24×24 minimum hit areas, `prefers-reduced-motion` support ([#450](https://github.com/Takazudo/zudo-design-token-panel/issues/450)) (fa36675)
+- The panel's SVG defensive reset now survives a hostile `svg { fill: red !important }` host rule ([#452](https://github.com/Takazudo/zudo-design-token-panel/issues/452)) (6ac7129)
+- Packaging: exports map gained `default` conditions and a `./package.json` export, broken declaration maps are no longer shipped, and a post-build check fails the build if any exports entry does not resolve against `dist/` ([#444](https://github.com/Takazudo/zudo-design-token-panel/issues/444)) (13862a4)
+- `release.yml` `dry_run` builds the package again, as its description advertises (8ce3d8b)
+
+### Other Changes
+
+- Docs now describe the real stylesheet mechanism — the panel self-injects its CSS via an inline import; no consumer CSS import is required — and stale pre-rename `packages/zudo-design-token-panel/` paths are purged ([#445](https://github.com/Takazudo/zudo-design-token-panel/issues/445)) (54756a2)
+- CI overhaul: PR branch filters cover live `base/**` branches, tests gate main pushes and `v*` release tags, Playwright browsers are cached, duplicate builds removed, concurrency cancellation + job timeouts everywhere ([#443](https://github.com/Takazudo/zudo-design-token-panel/issues/443)) (dbf5704)
+- New automated hostile-host isolation gate (Level 5): the panel's computed styles and viewport-fixed positioning are asserted inside a hostile host page, including a transform-ancestor scenario ([#452](https://github.com/Takazudo/zudo-design-token-panel/issues/452)) (6ac7129)
+- 17 browser-mode gesture tests for panel drag-to-move / resize incl. viewport clamping and persistence ([#453](https://github.com/Takazudo/zudo-design-token-panel/issues/453)) (a4b25af)
+- Test-suite hygiene: the DOM-policy static gate covers every panel TSX file and the full blocked-tag list, the palette drag browser test asserts for real, shared effect-flush helper, and a `test:unit` script runs the non-browser projects without Chromium ([#451](https://github.com/Takazudo/zudo-design-token-panel/issues/451)) (ebe0018, 8a7ee63, 4682139, 9b6c989)
+- Browser test files now run serially — parallel files share one origin and raced each other's localStorage (fd37774)
+- Deps: bump @takazudo/* toolchain (zfb next.76, zudo-doc 2.5.0) (62b62f6)
+
+## 0.4.2
+
+### Features
+
+- **OKLCH color tab — the reserved `color` tab now honors `format: 'oklch'`.** A cluster-based color tab whose palette tier items declare `type: { kind: 'color', format: 'oklch' }` now edits its palette swatches through the lossless OKLCH `ColorField` (the `valueFormat: 'oklch'` picker added in 0.3.3) while keeping the full color-cluster feature set — base roles, semantic→palette mappings, the "Scheme…" preset dropdown, and the secondary cluster. The palette `format` is read from `tab.tiers` (the flattened cluster drops per-item format), and both the primary and secondary cluster palettes honor it. Absent / `'hex'` format keeps the existing native hex behavior, so existing consumers and the highlight popover are unchanged. ([#436](https://github.com/Takazudo/zudo-design-token-panel/issues/436), epic [#434](https://github.com/Takazudo/zudo-design-token-panel/issues/434), supersedes [#433](https://github.com/Takazudo/zudo-design-token-panel/issues/433)) (ab761b6)
+
+- **Owner-only autoload.** A new `${storagePrefix}:autoload` `localStorage` flag lets the site owner load the panel in their own browser without touching general visitors. When the flag is set, the panel bundle loads eagerly on every page visit and mounts CLOSED — the **Alt+click element-path inspector** is armed immediately even while the panel UI stays hidden. General visitors (no flag) receive zero panel JS.
+
+  New package-root exports: `enableAutoload()`, `disableAutoload()`, `shouldAutoload()`. The Astro host-adapter also installs `window[consoleNamespace].enableAutoload()` and `window[consoleNamespace].disableAutoload()` on the console API surface.
+
+  The existing on-demand flow (`showDesignPanel()` / `hideDesignPanel()` / `toggleDesignPanel()`) is unchanged. Owner-autoload is an opt-in layer on top of it, not a replacement.
+
+  **Auto-remember:** any action that opens the panel also writes `${storagePrefix}:autoload = '1'`. Once an owner opens the panel, subsequent page loads reload it automatically without another explicit `enableAutoload()` call.
+
+  **Lazy-load gate updated from 2 to 4 signals:** the host-adapter gate now fires on `wasVisible() || hasPersistedOverrides() || shouldAutoload() || loadElementPathEnabled()`. The last two signals are new; the previous two-signal behavior is a strict subset of the new gate, so existing consumers see no change.
+
+  ([#419](https://github.com/Takazudo/zudo-design-token-panel/issues/419), [#420](https://github.com/Takazudo/zudo-design-token-panel/issues/420), [#421](https://github.com/Takazudo/zudo-design-token-panel/issues/421), [#422](https://github.com/Takazudo/zudo-design-token-panel/issues/422), [#423](https://github.com/Takazudo/zudo-design-token-panel/issues/423))
+
+### Fixed
+
+- **Runtime preserves OKLCH through seed / apply / persist.** `initColorFromSchemeData` no longer eagerly normalizes the whole palette to sRGB hex via a canvas `fillStyle` round-trip — raw `oklch(...)` palette values now survive seeding (wide-gamut chroma intact; no collapse to `#000000` under jsdom / engines whose 2D canvas can't parse `oklch`), and `colorRefToIndex` is format-tolerant + alpha-aware. Non-`oklch` entries are still sanitized through `cssColorToHex`, so an invalid bundled-scheme string (e.g. `Default Dark`'s slot-9 `"18"`, referenced by `background: 9`) cannot leak into a CSS custom property. ([#435](https://github.com/Takazudo/zudo-design-token-panel/issues/435)) (162bf8e, 8d54e07)
+
+- **Owner-autoload review fixes** — `disableAutoload()` now unmounts the panel, and element-path storage keys are per-instance. ([#424](https://github.com/Takazudo/zudo-design-token-panel/issues/424)) (ecfd745)
+
+### Other Changes
+
+- **Panel is draggable, movable & resizable on narrow windows**; `defaultSize()` is clamped to the `MIN_PANEL` floor on phone-width viewports; and Element-Path-Copy keeps working while the panel is closed. ([#415](https://github.com/Takazudo/zudo-design-token-panel/pull/415)) (2dc40a1, 8fb99b5, f163625)
+- Wave-2 OKLCH cluster end-to-end test plus runtime / color-tab coverage. ([#437](https://github.com/Takazudo/zudo-design-token-panel/issues/437)) (8da36c6, 47e4d83, fad4ded)
+- Bump the `@takazudo/*` toolchain (zfb next.72, zudo-doc 2.1.2). (d711839)
+- Doc-site migration to zudo-doc v2 — doc-site only, no package impact. ([#432](https://github.com/Takazudo/zudo-design-token-panel/pull/432))
+
 ## 0.4.1
 
 ### Fixed

package/README.md

@@ -292,7 +292,8 @@ The `<DesignTokenPanelHost>` component AND a paired `<script>` block that loads
 import { ClientRouter } from 'astro:transitions';
 import DesignTokenPanelHost from '@takazudo/zdtp/astro/DesignTokenPanelHost.astro';
 import { myPanelConfig } from '../lib/my-panel-config';
-import '@takazudo/zdtp/styles';
+// No CSS import needed — the panel self-injects its stylesheet on first mount.
+// import '@takazudo/zdtp/styles'; // optional: pull CSS into your own pipeline
 ---
 
 <!doctype html>
@@ -325,18 +326,20 @@ window.myapp.toggleDesignPanel();
 
 Or wire a hidden keyboard shortcut / dev-only button to call the same helper.
 
-### 4.1.4 Bundled CSS
+### 4.1.4 Stylesheet (self-injected — no consumer import required)
+
+The panel injects its own stylesheet at runtime. When the panel first mounts, `ensurePanelStyles()` (called from `ensureMounted()` in `src/index.tsx`) appends a `<style>` element to `document.head` carrying the bundled CSS. The CSS is embedded in the JS bundle as a string via a `?inline` import, so it survives Vite library mode's build step and reaches the browser without any consumer-side stylesheet import.
 
-The package builds in Vite library mode, which extracts every CSS side-effect import from the source into a single emitted stylesheet at `dist/design-token-panel.css` and **strips the `import './styles/panel.css'` line from the emitted JS**. That means the consumer's bundler has no static reference to follow and the CSS will not arrive on its own — you MUST import the bundled stylesheet exactly once from somewhere on the consumer's static module graph (typically next to where you mount `<DesignTokenPanelHost>`):
+**You do not need to import `@takazudo/zdtp/styles`** — the panel is visually self-contained out of the box.
+
+The `./styles` (alias `./styles.css`) sub-export still resolves to `./dist/zdtp.css` and remains available if you prefer to pull the CSS into your own stylesheet pipeline (e.g. for SSR hydration, PostCSS processing, or bundler-level deduplication). This import is now optional:
 
 ```ts
-// Astro frontmatter, Vite entry, anywhere on the static import chain
+// Optional — pull CSS into your own pipeline if needed
 import '@takazudo/zdtp/styles';
 ```
 
-The `./styles` (alias `./styles.css`) sub-export resolves to `./dist/design-token-panel.css` — the single combined chrome + tokens file Vite emits at build time. `package.json` still declares `sideEffects: ["**/*.css"]` so production bundlers don't tree-shake the import away.
-
-If you skip this line, the panel's JS will still run, `window.<ns>.showDesignPanel()` will mount `#…-design-token-panel-root`, and the shell DOM will render — but with no chrome rules applied (transparent background, default page font), so it appears invisible. See §13 for further notes on bundler behaviour.
+If the panel looks unstyled after mounting, the most likely cause is that the panel module itself failed to load (network error, bundler misconfiguration, missing `preact` peer). The stylesheet is self-injected by the same JS that mounts the panel — if the JS ran, the CSS is present. See §12 for further notes on bundler behaviour.
 
 ### 4.1.5 Why the host-adapter import lives in your wrapper
 
@@ -530,8 +533,8 @@ 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**: either when the user calls a console helper, OR when first-paint detects either a `${storagePrefix}:visible` flag set to `1` or any `${storagePrefix}-state-v2` payload in `localStorage`.
-- This gating keeps the panel out of the initial JS bundle for first-time visitors while still re-applying overrides on hard reload for users who have tweaked things.
+- The panel module is **dynamically imported on first need**: when the user calls a console helper, OR when first-paint detects any of four gate signals in `localStorage` — `${storagePrefix}:visible` set to `1`, persisted overrides (`${storagePrefix}-state-v3`), the owner-autoload flag (`${storagePrefix}:autoload` set to `1`), or the element-path inspector enabled.
+- This gating keeps the panel out of the initial JS bundle for first-time visitors while still re-applying overrides on hard reload for users who have tweaked things. **General visitors** (none of the four signals set) pay zero bundle cost.
 
 For a Vite-only / non-Astro host, mount it yourself by importing the adapter module after `configurePanel(...)`. See §11.5.
 
@@ -891,6 +894,7 @@ Behaviour notes:
 | `open`      | `${storagePrefix}-open`     | Mirror of the panel's `open` boolean (synchronous mount-time read — preserves user intent across reloads, fixes #1549). |
 | `position`  | `${storagePrefix}-position` | Drag position `{ top, right }` so the panel reappears where the user left it.                                           |
 | `visible`   | `${storagePrefix}:visible`  | Adapter-level visibility-intent flag, owned by the lazy-load gate.                                                      |
+| `autoload`  | `${storagePrefix}:autoload` | Owner-mode autoload flag. When `'1'`, the panel bundle fetches eagerly on every page load and mounts CLOSED so the Alt+click element-path inspector is armed without opening the panel UI. Set by `enableAutoload()` and cleared by `disableAutoload()`. See §10.1. |
 
 For example, with `storagePrefix: 'myapp-design-token-panel'`:
 
@@ -901,11 +905,12 @@ myapp-design-token-panel-state
 myapp-design-token-panel-open
 myapp-design-token-panel-position
 myapp-design-token-panel:visible
+myapp-design-token-panel:autoload
 ```
 
-### Note: colon vs dash on the `visible` key
+### Note: colon vs dash — `visible` and `autoload`
 
-The `visible` key uses a literal `:` separator, not `-`. Every other derived key uses `-`. This is intentional — see [`PORTABLE-CONTRACT.md`](./PORTABLE-CONTRACT.md) §2 for the historical reason. Don't try to "normalize" it; the unit tests assert this specific shape.
+The `visible` and `autoload` keys use a literal `:` separator, not `-`. Every other derived key uses `-`. The colon form is intentional for these adapter-level flags — see [`PORTABLE-CONTRACT.md`](./PORTABLE-CONTRACT.md) §2 for the historical reason. Don't try to "normalize" them; the unit tests assert this specific shape.
 
 ### Scheme changes and the global tweak model
 
@@ -924,19 +929,27 @@ Two consequences worth knowing as a host integrator:
 
 ## 10. Console API contract
 
-Once `configurePanel` has run, the package installs three async helpers on the global `window[consoleNamespace]` object:
+Once `configurePanel` has run, the package installs async helpers on the global `window[consoleNamespace]` object:
 
 ```ts
-window.myapp.showDesignPanel(); // open the panel
-window.myapp.hideDesignPanel(); // close the panel
-window.myapp.toggleDesignPanel(); // toggle
+window.myapp.showDesignPanel();   // open the panel (lazy-loads the bundle on first call)
+window.myapp.hideDesignPanel();   // close the panel
+window.myapp.toggleDesignPanel(); // toggle open/closed
+
+// Owner-autoload (see §10.1)
+window.myapp.enableAutoload();  // arm owner-mode; panel loads CLOSED with Alt+click ready
+window.myapp.disableAutoload(); // disarm owner-mode; unmounts the panel
 ```
 
-All three are **async** — the first call lazy-imports the panel module. Subsequent calls share the memoised module promise and resolve synchronously after the first import completes.
+All helpers are **async** — the first call lazy-imports the panel module. Subsequent calls share the memoised module promise and resolve synchronously after the first import completes.
+
+### Backward-compatible: the on-demand flow is unchanged
+
+The pre-existing on-demand usage — calling `window.<consoleNamespace>.showDesignPanel()` / `hideDesignPanel()` / `toggleDesignPanel()` to lazy-import and initialize the panel — is **unchanged and fully supported**. Owner-autoload (§10.1) is an opt-in layered on top, not a replacement. If you never call `enableAutoload()`, the panel behaves exactly as it always did: nothing loads for any visitor until the first console call.
 
 ### Co-existing helpers on the same namespace
 
-The adapter **merges** its three helpers into any existing object at `window[namespace]` rather than overwriting the namespace wholesale. This means a host can share a namespace between multiple dev tools (e.g. `window.myapp.ogpDebug.show()` from a separate package, alongside `window.myapp.showDesignPanel()` from this one) without collisions.
+The adapter **merges** its helpers into any existing object at `window[namespace]` rather than overwriting the namespace wholesale. This means a host can share a namespace between multiple dev tools (e.g. `window.myapp.ogpDebug.show()` from a separate package, alongside `window.myapp.showDesignPanel()` from this one) without collisions.
 
 ### Default
 
@@ -944,6 +957,44 @@ There is no default `consoleNamespace` exposed to consumers — the field is req
 
 ---
 
+### 10.1 Owner-autoload — loading the panel only for you
+
+**Use case:** you are deploying a public site and want the design-token panel available to yourself (the site owner) without loading any panel JS for general visitors. Once armed, every page load fetches the bundle eagerly and mounts the panel CLOSED — the Alt+click element-path inspector is ready immediately, and you can open the panel UI at any time.
+
+#### API surface
+
+Both the Astro host-adapter (`window[consoleNamespace].*`) and the package-root exports expose the same interface:
+
+| Call | Effect |
+|------|--------|
+| `window.myapp.enableAutoload()` | Sets `${storagePrefix}:autoload` to `'1'`, arms the element-path inspector (`-elpath-enabled`), loads the panel bundle, mounts CLOSED. |
+| `window.myapp.disableAutoload()` | Clears `:autoload`, `:visible`, `-elpath-enabled`, and the open-state key; unmounts the panel. |
+| `enableAutoload()` (package-root export) | Same as the console form — for non-Astro hosts. |
+| `disableAutoload()` (package-root export) | Same as the console form — for non-Astro hosts. |
+| `shouldAutoload()` (package-root export) | Returns `true` iff the flag is currently set. |
+
+#### The `${storagePrefix}:autoload` flag
+
+Stored in `localStorage` as `'1'` when armed, removed or `'0'` otherwise. The host-adapter's lazy-load gate reads this flag on every page load — when it is `'1'`, the panel bundle loads eagerly (the same as when the panel was previously visible or overrides are persisted). **General visitors** who have never called `enableAutoload()` have no flag and pay zero bundle cost.
+
+#### Auto-remember on open
+
+Opening the panel by any means — `showDesignPanel()`, `toggleDesignPanel()`, or clicking the panel's own header close button to re-open it — **automatically sets the `:autoload` flag**. This means once you open the panel you will be in owner-mode on subsequent page loads without calling `enableAutoload()` explicitly.
+
+#### Element-path coupling
+
+`enableAutoload()` arms the Alt+click element-path inspector by writing `-elpath-enabled = '1'`. The inspector runs inside the Preact shell; mounting the shell CLOSED (rather than unmounted) keeps the inspector functional even while the panel UI is hidden. You can still turn the inspector off via the in-panel toggle — `disableAutoload()` clears it as part of full teardown.
+
+#### Auto-remember footgun
+
+Because **any open trigger sets `:autoload`**, a visible "open panel" button, keyboard shortcut, or similar affordance on your site becomes a de-facto owner-mode opt-in for anyone who clicks it. On an owner-only public site:
+
+- Gate or omit such triggers (hide them behind a login check, remove them from the production build, etc.).
+- Rely on the console `enableAutoload()` call as the owner's explicit opt-in.
+- See the [Load the panel only for you](/docs/recipes/owner-autoload) recipe for a safe worked example.
+
+---
+
 ## 11. Tailwind not required
 
 The panel ships its own bundled CSS scoped under a panel-private namespace:
@@ -985,23 +1036,25 @@ The CSS variables the panel **writes to** (the `cssVar` field on each `TokenDef`
 
 ## 12. Bundler notes
 
-The package builds in **Vite library mode**, which has a quirk that's important to understand: it extracts every `import './something.css'` from the source and emits a single combined stylesheet (`dist/design-token-panel.css`), but **removes the import statements from the emitted JS files**. The `dist/index.js` and `dist/astro/host-adapter.js` therefore have no static reference back to the CSS — `sideEffects: ["**/*.css"]` in `package.json` only protects existing imports from tree-shaking; it cannot resurrect an import the build step has already deleted.
-
-Net effect: the consumer MUST add a one-line side-effect import to their static module graph, as described in §3.4. The `./styles` sub-export is the canonical entry:
+The package builds in **Vite library mode**. Normally, Vite library mode extracts every `import './something.css'` from the source and emits a combined stylesheet (`dist/zdtp.css`), removing the import statements from the emitted JS files. This package works around that limitation via a `?inline` import:
 
 ```ts
-import '@takazudo/zdtp/styles';
+// src/index.tsx (shipped in dist/index.js)
+import panelCss from './styles/panel.css?inline'; // string — survives Vite library build
 ```
 
-`./styles.css` is provided as an alias for clarity in tooling that prefers explicit extensions:
+The `?inline` import is NOT stripped by Vite library mode — it emits the CSS as a JavaScript string constant inside `dist/index.js`. When `ensureMounted()` is called, `ensurePanelStyles()` uses that string to append a `<style>` element to `document.head`. **The panel is therefore visually self-contained: consumers do not need to import the stylesheet.**
+
+The `./styles` sub-export (`dist/zdtp.css`) is still emitted alongside the JS bundle (via a retained side-effect import in `src/index.tsx`). It remains available for consumers who prefer to pull the CSS into their own pipeline (SSR hydration, PostCSS, bundler deduplication):
 
 ```ts
+// Optional — only needed if you want the CSS in your own pipeline
+import '@takazudo/zdtp/styles';
+// Alias with explicit extension:
 import '@takazudo/zdtp/styles.css';
 ```
 
-If you forget the import, the JS layer still works — `window.<ns>.showDesignPanel()` mounts the shell DOM correctly — but every chrome rule is missing, so the panel appears invisible against the host page background. The fix is the import, not bundler reconfiguration.
-
-(Historical note: an earlier draft of this section claimed `sideEffects` alone was sufficient and consumers did not need to import CSS. That was incorrect — Vite library mode's CSS-extraction behaviour means `sideEffects` is necessary but not sufficient. The §3.4 + this section now reflect the actual contract.)
+If the panel appears unstyled, the JS module itself failed to load — the stylesheet is self-injected by the same code that mounts the panel. Adding a styles import will not fix a module-load failure.
 
 ### 12.1 Host-adapter side-effect import (paired-unit contract)
 

package/dist/apply/apply-token-overrides.d.ts

@@ -78,4 +78,3 @@ export declare function applyTokenOverridesOrThrow(source: string, overrides: Re
  * source contains at least one top-level `:root { ... }` block.
  */
 export declare function hasTopLevelRootBlock(source: string): boolean;
-//# sourceMappingURL=apply-token-overrides.d.ts.map

package/dist/apply/build-apply-overrides.d.ts

@@ -6,7 +6,8 @@
  * Consumes the `TweakState` shape directly:
  *
  * Color tokens:
- *   - `state.color.palette: string[]` — palette hex values
+ *   - `state.color.palette: string[]` — palette color values (hex, or
+ *     `oklch(...)` when the palette tier declares `type.format: 'oklch'`)
  *   - `state.color.semanticMappings: Record<string, number | 'bg' | 'fg'>` —
  *     semantic-token → palette-index map
  *   - `state.color.background` / `foreground` — palette indices used when a
@@ -27,7 +28,8 @@
  * Specifically:
  *
  *   - Palette slots (resolved via `resolvePaletteCssVar(cluster, i)`) —
- *     EMITTED as hex values.
+ *     EMITTED as the stored color value (hex, or `oklch(...)` for
+ *     oklch-format palettes).
  *   - Semantic tokens (`cluster.semanticCssNames` entries) — EMITTED as
  *     `var(--<paletteSlotName>)` so the rewrite preserves the indirection
  *     that the hand-authored CSS relies on.
@@ -68,4 +70,3 @@ import type { TabConfig } from '../tokens/tier-model';
  * non-color token resolution works without a live panel config singleton.
  */
 export declare function buildApplyOverrides(state: TweakState, colorDefaults: ColorTweakState | undefined, cluster?: ColorClusterConfig, tabs?: readonly TabConfig[]): Record<string, string>;
-//# sourceMappingURL=build-apply-overrides.d.ts.map

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

@@ -62,4 +62,3 @@ export declare const TOKEN_SOURCE_FILES: Readonly<ApplyRoutingMap>;
  *   instead of silently no-oping.
  */
 export declare function routeTokensToFiles(overrides: Record<string, string>, routing?: ApplyRoutingMap): RouteResult;
-//# sourceMappingURL=route-tokens-to-files.d.ts.map

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

@@ -72,4 +72,3 @@ export declare function resolveTierItemValue(tab: TabConfig, tierId: string, ite
  * - Ref     → returns `var(--targetCssVar)` (e.g. `var(--zfb-easing-ease-in)`).
  */
 export declare function emitTierItemCssValue(resolved: ResolvedTierItem): string;
-//# sourceMappingURL=tier-resolver.d.ts.map

package/dist/apply-modal.d.ts

@@ -56,4 +56,3 @@ export interface ApplyModalProps {
     instanceConfig?: PanelConfig;
 }
 export declare function ApplyModal(props: ApplyModalProps): import("preact").JSX.Element;
-//# sourceMappingURL=apply-modal.d.ts.map

package/dist/astro/DesignTokenPanelHost.astro

@@ -9,10 +9,8 @@
  * ---
  * import DesignTokenPanelHost from '@takazudo/zdtp/astro/DesignTokenPanelHost.astro';
  * import { panelConfig } from './my-design-token-config';
- * // Required side-effect import for the package's bundled chrome CSS —
- * // Vite library mode strips the source CSS import from the emitted JS,
- * // so consumers must re-pull the extracted stylesheet explicitly.
- * import '@takazudo/zdtp/styles';
+ * // No CSS import needed — the panel self-injects its stylesheet on first mount.
+ * // Optional: import '@takazudo/zdtp/styles'; // pull CSS into your own pipeline
  * ---
  * <DesignTokenPanelHost config={panelConfig} />
  * <script>

package/dist/astro/host-adapter.d.ts

@@ -44,4 +44,3 @@
  * `DesignTokenPanelHost.astro`), never by the lib bundle's `index.ts`.
  */
 export {};
-//# sourceMappingURL=host-adapter.d.ts.map

package/dist/astro/host-adapter.js

@@ -1,79 +1,102 @@
-import { c as f, g as c, a as p, b as h, d as m, e as w } from "../panel-config-066BPYJD.js";
-import { Z as P } from "../tweak-state-Do5gj6Nw.js";
-const i = "tokenpanel-config";
-function y() {
+import { c as h, g as u, a as g, b as w, d as y, e as P } from "../panel-config-3tBEHjvZ.js";
+import { g as d, Z as b } from "../tweak-state-BEx1SHu7.js";
+import { s as _, l as A, a as c, c as k, b as I } from "../autoload-state-B1MWY_Pp.js";
+const l = "tokenpanel-config";
+function E() {
   if (typeof document > "u")
     throw new Error(
       "[design-token-panel] host-adapter loaded without a document; expected to run in a browser context."
     );
-  const e = document.getElementById(i);
-  if (!e)
+  const n = document.getElementById(l);
+  if (!n)
     throw new Error(
-      `[design-token-panel] Inline config script #${i} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
+      `[design-token-panel] Inline config script #${l} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
     );
-  const t = e.textContent ?? "";
-  let n;
+  const o = n.textContent ?? "";
+  let e;
   try {
-    n = JSON.parse(t);
-  } catch (o) {
+    e = JSON.parse(o);
+  } catch (a) {
     throw new Error(
-      `[design-token-panel] Failed to parse inline config from #${i}: ${o.message}`
+      `[design-token-panel] Failed to parse inline config from #${l}: ${a.message}`
     );
   }
-  return w(n), n;
+  return P(e), e;
 }
-function _(e) {
-  return e.__zudoDesignTokenPanelAdapter || (e.__zudoDesignTokenPanelAdapter = {}), e.__zudoDesignTokenPanelAdapter;
+function C(n) {
+  return n.__zudoDesignTokenPanelAdapter || (n.__zudoDesignTokenPanelAdapter = {}), n.__zudoDesignTokenPanelAdapter;
 }
-function b(e, t) {
-  const n = _(e);
-  let o = n[t];
-  return o || (o = { bound: !1, modulePromise: null }, n[t] = o), o;
+function S(n, o) {
+  const e = C(n);
+  let a = e[o];
+  return a || (a = { bound: !1, modulePromise: null }, e[o] = a), a;
 }
-function k(e) {
+function T(n) {
   try {
-    return window.localStorage.getItem(e) === "1";
+    return window.localStorage.getItem(n) === "1";
   } catch {
     return !1;
   }
 }
-function C(e, t) {
+function v(n, o) {
   try {
-    const n = window.localStorage;
-    return n.getItem(t) !== null || n.getItem(e) !== null;
+    const e = window.localStorage;
+    return e.getItem(o) !== null || e.getItem(n) !== null;
   } catch {
     return !1;
   }
 }
-async function r(e) {
-  return e.modulePromise === null && (e.modulePromise = import("@takazudo/zdtp").then((t) => {
+async function i(n) {
+  return n.modulePromise === null && (n.modulePromise = import("@takazudo/zdtp").then((o) => {
     try {
-      const n = c(), o = t.__panelConfigForTest();
-      n !== o && console.warn(
+      const e = u(), a = o.__panelConfigForTest();
+      e !== 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 (e) {
       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): " + e.message
       );
     }
-    return t;
-  })), e.modulePromise;
+    return o;
+  })), n.modulePromise;
 }
-function I(e, t, n, o) {
-  const a = e[t] ?? {};
-  a.showDesignPanel = async () => {
-    await r(n), o.open();
-  }, a.hideDesignPanel = async () => {
-    await r(n), o.close();
-  }, a.toggleDesignPanel = async () => {
-    await r(n), o.toggle();
-  }, e[t] = a;
+function D(n, o, e, a, t) {
+  const s = n[o] ?? {};
+  s.showDesignPanel = async () => {
+    c(t, !0), await i(e), a.open();
+  }, s.hideDesignPanel = async () => {
+    await i(e), a.close();
+  }, s.toggleDesignPanel = async () => {
+    await i(e), a.toggle();
+    let r = !1;
+    try {
+      r = window.localStorage.getItem(d(t)) === "1";
+    } catch {
+    }
+    r && c(t, !0);
+  }, s.enableAutoload = async () => {
+    (await i(e)).enableAutoload(t);
+  }, s.disableAutoload = async () => {
+    if (e.modulePromise !== null) {
+      (await i(e)).disableAutoload(t);
+      return;
+    }
+    k(t), I(!1, t);
+    try {
+      window.localStorage.setItem(g(t), "0");
+    } catch {
+    }
+    try {
+      window.localStorage.removeItem(d(t));
+    } catch {
+    }
+  }, n[o] = s;
 }
 (function() {
-  const t = y(), n = t.legacyIdRenameMap ? t : { ...t, legacyIdRenameMap: { ...P } }, o = f(n), a = c(), l = window, s = b(l, a.storagePrefix);
-  if (I(l, a.consoleNamespace, s, o), s.bound) return;
-  s.bound = !0;
-  const d = p(a), g = h(a), u = m(a);
-  (k(d) || C(g, u)) && r(s);
+  const o = E(), e = o.legacyIdRenameMap ? o : { ...o, legacyIdRenameMap: { ...b } }, a = h(e), t = u(), s = window, r = S(s, t.storagePrefix);
+  if (D(s, t.consoleNamespace, r, a, t), r.bound) return;
+  r.bound = !0;
+  const f = g(t), p = w(t), m = y(t);
+  (T(f) || v(p, m) || _(t) || A(t)) && i(r);
 })();

package/dist/astro/index.d.ts

@@ -30,4 +30,3 @@ 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';
-//# sourceMappingURL=index.d.ts.map

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { s as t } from "../panel-config-066BPYJD.js";
+import { s as t } from "../panel-config-3tBEHjvZ.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-DCReQE0k.js";
 const e = {

package/dist/autoload-state-B1MWY_Pp.js

@@ -0,0 +1,46 @@
+import { g as a, j as o } from "./panel-config-3tBEHjvZ.js";
+function n(e = a()) {
+  return `${e.storagePrefix}-elpath-enabled`;
+}
+function l(e = a()) {
+  try {
+    return localStorage.getItem(n(e)) === "1";
+  } catch {
+    return !1;
+  }
+}
+function c(e, t = a()) {
+  try {
+    localStorage.setItem(n(t), e ? "1" : "0");
+  } catch {
+  }
+}
+function d(e) {
+  if (typeof window > "u") return !1;
+  try {
+    return window.localStorage.getItem(o(e)) === "1";
+  } catch {
+    return !1;
+  }
+}
+function u(e, t) {
+  if (!(typeof window > "u"))
+    try {
+      window.localStorage.setItem(o(e), t ? "1" : "0");
+    } catch {
+    }
+}
+function f(e) {
+  if (!(typeof window > "u"))
+    try {
+      window.localStorage.removeItem(o(e));
+    } catch {
+    }
+}
+export {
+  u as a,
+  c as b,
+  f as c,
+  l,
+  d as s
+};

package/dist/bin/cors.d.ts

@@ -21,4 +21,3 @@ export declare function isOriginAllowed(origin: string | null | undefined, allow
  * permitted.
  */
 export declare function buildCorsHeaders(origin: string): Record<string, string>;
-//# sourceMappingURL=cors.d.ts.map

package/dist/bin/parse-args.d.ts

@@ -35,4 +35,3 @@ export declare const HELP_TEXT = "Usage: zdtp-server [options]\n\nRun a small No
  * `ParsedArgs` record. Throws on malformed input — the bin handles the throw.
  */
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;
-//# sourceMappingURL=parse-args.d.ts.map

package/dist/bin/server.d.ts

@@ -20,4 +20,3 @@
  *   - shuts down gracefully on SIGINT/SIGTERM
  */
 export {};
-//# sourceMappingURL=server.d.ts.map

package/dist/bin/server.js

@@ -2,7 +2,7 @@
 import { realpathSync as H } from "node:fs";
 import { createServer as C } from "node:http";
 import { resolve as d } from "node:path";
-import { l as x, c as N } from "../load-routing-XyKgftpe.js";
+import { l as x, c as N } from "../load-routing-DtNTKoLW.js";
 function g(t, e) {
   return typeof t != "string" || t.length === 0 || e.length === 0 ? !1 : e.includes(t);
 }

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

@@ -35,4 +35,3 @@ export interface ColorFieldProps {
  */
 export declare function ColorField({ value, onChange, valueFormat, label, cssVar, readonly: isReadonly, }: ColorFieldProps): import("preact").JSX.Element;
 export default ColorField;
-//# sourceMappingURL=color-field.d.ts.map

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

@@ -7,7 +7,7 @@
  *
  * Issue #175 (Wave 2 of the OKLCH Picker epic, issue #174-base).
  *
- * Design rules (see packages/zudo-design-token-panel/CLAUDE.md):
+ * Design rules (see packages/zdtp/CLAUDE.md):
  *   - All interactive elements use <div role="button" tabIndex={0}> with
  *     explicit Enter/Space onKeyDown handlers. Native button and heading tags
  *     are not used (hostile-host policy).
@@ -75,8 +75,18 @@ export declare function getFixedPopoverStyle(anchor: HTMLElement | null, estW: n
  *
  * Deliberately does NOT close on scroll — a scroll event on the host page
  * should not dismiss an in-flight color edit.
+ *
+ * `anchorRef` (F11): the popover's trigger element lives OUTSIDE `containerRef`.
+ * A pointerdown on the trigger while the popover is open must NOT trigger the
+ * outside-close, otherwise it races the trigger's own click-to-toggle: the
+ * pointerdown closes, then the click reopens, so the trigger can never dismiss
+ * its own popover. Excluding the anchor lets the click toggle it shut.
+ *
+ * Escape is arbitrated by the shared dismiss-layer stack (F10): only the
+ * topmost open popover consumes a single Escape, so one keypress never also
+ * tears down the panel underneath.
  */
-export declare function usePopoverClose(containerRef: React.RefObject<HTMLElement | null>, onClose: () => void): void;
+export declare function usePopoverClose(containerRef: React.RefObject<HTMLElement | null>, onClose: () => void, anchorRef?: React.RefObject<HTMLElement | null>): void;
 /**
  * ColorPicker — popover body only.
  *
@@ -85,4 +95,3 @@ export declare function usePopoverClose(containerRef: React.RefObject<HTMLElemen
  */
 export declare function ColorPicker({ color, onChange, valueFormat, label, defaultMode, anchorRef, onClose, }: ColorPickerProps): JSX.Element;
 export default ColorPicker;
-//# sourceMappingURL=color-picker.d.ts.map

package/dist/components/color-picker/custom-slider.d.ts

@@ -22,4 +22,3 @@ export interface CustomSliderProps {
 }
 export declare function CustomSlider({ config, value, gradient, onChange, onDragStart, onDragEnd, }: CustomSliderProps): JSX.Element;
 export default CustomSlider;
-//# sourceMappingURL=custom-slider.d.ts.map