@takazudo/zdtp 0.4.2 → 0.4.4

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 0.4.4
+
+### Features
+
+- **Ramp-native Tier-2 color editor.** The Color tab gained a semantic-value tier model — a `semantic: true` tier holds `SemanticValue` mappings (palette index, literal OKLCH, per-mode `light-dark()` literal, or a cross-tab ramp `{ ref }`) instead of raw palette entries, and can ship as a lone semantic tier with no palette tier at all ([#459](https://github.com/Takazudo/zudo-design-token-panel/issues/459), closes [#458](https://github.com/Takazudo/zudo-design-token-panel/issues/458)) ([8ed93e1](https://github.com/Takazudo/zudo-design-token-panel/pull/476))
+- Add semantic-tier marker + `SemanticValue` union (S1) ([#460](https://github.com/Takazudo/zudo-design-token-panel/pull/460)) (d7aa526)
+- serde `SCHEMA_V3` object leaves for `SemanticValue` variants (S5) ([#462](https://github.com/Takazudo/zudo-design-token-panel/pull/462)) (0185477)
+- Render literal semantic rows as editable OKLCH swatches (S3) ([#464](https://github.com/Takazudo/zudo-design-token-panel/pull/464)) (d8bceb3)
+- Emit literal semantic values verbatim in both emitters (S4) ([#465](https://github.com/Takazudo/zudo-design-token-panel/pull/465)) (5961ed7)
+- Cross-tab ref resolution + tabs-array cluster-bridge signature (S7a) ([#467](https://github.com/Takazudo/zudo-design-token-panel/pull/467)) (35ef368)
+- Emit cross-tab semantic refs as `var(--target)` in both emitters (S7b) ([#468](https://github.com/Takazudo/zudo-design-token-panel/pull/468)) (ea2aa8a)
+- Validate cross-tab ramp-source declarations (S8) ([#469](https://github.com/Takazudo/zudo-design-token-panel/pull/469)) (8558269)
+- Grouped ref-or-literal picker + wire color-tab semantic rows (S9) ([#470](https://github.com/Takazudo/zudo-design-token-panel/pull/470)) (3d5e5f7)
+- Per-mode literal `light-dark()` emission + `defaultMode` runtime (S11) ([#472](https://github.com/Takazudo/zudo-design-token-panel/pull/472)) (3a05623)
+- Per-mode light/dark literal editor UI (S12) ([#473](https://github.com/Takazudo/zudo-design-token-panel/pull/473)) (1828458)
+
+### Fixed
+
+- Seed Scheme preset load against the instance cluster, not the global default ([#491](https://github.com/Takazudo/zudo-design-token-panel/issues/491) audit) (a1b0dd8)
+- Thread `instanceConfig` into `ColorTab` for multi-instance ref resolution ([#491](https://github.com/Takazudo/zudo-design-token-panel/issues/491)) (66447ec)
+- Validate semantic marker shape + mixed-order palette-pick regression tests ([#487](https://github.com/Takazudo/zudo-design-token-panel/pull/487)) (0ebcc6e)
+- Scheme/preset load is a no-op for a palette-less color cluster ([#488](https://github.com/Takazudo/zudo-design-token-panel/pull/488)) (23d61ba)
+- Color-scheme lifecycle asymmetries in the applied-state ([#482](https://github.com/Takazudo/zudo-design-token-panel/pull/482)) (ef686fc)
+- serde robustness — order-independent ref diff, stale-ref warning, integer index leaves (c0b4356)
+- Restore legacy index-0 fallback + detect named-color literals ([#483](https://github.com/Takazudo/zudo-design-token-panel/pull/483)) (4f66b7d)
+- Show a disabled unresolved placeholder for a dangling `TierRefSelector` ref ([#484](https://github.com/Takazudo/zudo-design-token-panel/issues/484)) (a4c222b)
+- Thread owning color tab into `buildApplyOverrides` for secondary-cluster refs (D1) ([#481](https://github.com/Takazudo/zudo-design-token-panel/pull/481)) (60cbb7a)
+- Skip an unresolvable semantic `{ ref }` in the DOM emitter too (87131ee)
+- Drop phantom grayscale swatch for palette-less semantic tier ([#466](https://github.com/Takazudo/zudo-design-token-panel/pull/466) follow-up) (c955616)
+- Derive semantic maps for a palette-less semantic tier (S2b) ([#463](https://github.com/Takazudo/zudo-design-token-panel/pull/463)) (7d617d1)
+- Honor semantic-tier marker in palette detection + F4 (S2a) ([#461](https://github.com/Takazudo/zudo-design-token-panel/pull/461)) (ecb4482)
+
+### Other Changes
+
+- Eliminate intermittent vitest unhandled-error flake ([#494](https://github.com/Takazudo/zudo-design-token-panel/issues/494)) (ab60f91)
+- e2e confirm per-mode literal `light-dark()` + clear color-scheme on reset (S13) ([#474](https://github.com/Takazudo/zudo-design-token-panel/pull/474)) (a215c88)
+- e2e confirm cross-tab semantic ref cascade (S10) ([#471](https://github.com/Takazudo/zudo-design-token-panel/pull/471)) (235bb30)
+- e2e confirm lone literal semantic tier unblocks [#458](https://github.com/Takazudo/zudo-design-token-panel/issues/458) (S6) ([#466](https://github.com/Takazudo/zudo-design-token-panel/pull/466)) (8fb5136)
+- docs: translate token-manifest reference page to Japanese ([#490](https://github.com/Takazudo/zudo-design-token-panel/issues/490), [#478](https://github.com/Takazudo/zudo-design-token-panel/issues/478)) (7bcd835)
+- docs: translate color-cluster reference to Japanese ([#489](https://github.com/Takazudo/zudo-design-token-panel/issues/489), [#478](https://github.com/Takazudo/zudo-design-token-panel/issues/478)) (e033410)
+- docs: fix EN documentation drift from [#459](https://github.com/Takazudo/zudo-design-token-panel/issues/459) (referencesRamps, bridge signature, color-scheme caveat) (a7d8709)
+- docs: document ramp-native Tier-2 editor + example manifest + cascade test (S14) ([#475](https://github.com/Takazudo/zudo-design-token-panel/pull/475)) (136bcf6)
+- docs: fix broken `SemanticValue` heading anchor (drop em-dash from slug) (ef3cd91)
+- chore(deps): bump `@takazudo/zudo-doc` and `zudo-doc-history-server` to `^2.5.1` (d6c05dd)
+- chore(doc): sync generated `claude/index.mdx` with build output (d763238)
+
+## 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

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.
+
+**You do not need to import `@takazudo/zdtp/styles`** — the panel is visually self-contained out of the box.
 
-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>`):
+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
 
@@ -1033,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

@@ -30,9 +30,17 @@
  *   - Palette slots (resolved via `resolvePaletteCssVar(cluster, i)`) —
  *     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.
+ *   - Semantic tokens (`cluster.semanticCssNames` entries) — a legacy
+ *     index/`bg`/`fg` mapping is EMITTED as `var(--<paletteSlotName>)` so the
+ *     rewrite preserves the indirection that the hand-authored CSS relies on.
+ *     A single-mode `{ literal: string }` mapping (#465) is instead EMITTED
+ *     VERBATIM as the literal CSS value — there is no palette slot to
+ *     reference. A cross-tab/tier `{ ref }` mapping (#468) is resolved via
+ *     `resolveRefToCssVar` against the panel's full `tabs` array and EMITTED
+ *     as `var(--<resolved-target>)`. Per-mode `{ literal: { light, dark } }`
+ *     (#472) is EMITTED as `light-dark(<light>, <dark>)`, byte-identical to
+ *     the DOM emitter (the required `color-scheme: light dark` is NOT settable
+ *     via this pipeline — see the per-mode branch below for why).
  *   - Base roles (`cluster.baseRoles` entries) — NOT emitted. They do not
  *     belong to the apply pipeline's rewrite scope.
  *   - Spacing / typography / size — EMITTED when the corresponding
@@ -68,6 +76,13 @@ import type { TabConfig } from '../tokens/tier-model';
  *
  * `tabs` defaults to the active panel config's tab list. Injected by tests so
  * non-color token resolution works without a live panel config singleton.
+ *
+ * `currentTab` is the color TabConfig `state.color`'s semantic mappings live
+ * on — needed so a cross-tab/tier `{ ref }` mapping (#468) with an omitted
+ * `ref.tab` resolves against the RIGHT tab. Defaults to the `'color'` tab
+ * (primary-cluster behavior, unchanged). Secondary-cluster callers MUST pass
+ * the `'color-secondary'` tab explicitly — mirroring the DOM emitter's
+ * `applyFullState`/`applyColorState` `currentTab` threading
+ * (`state/tweak-state.ts`).
  */
-export declare function buildApplyOverrides(state: TweakState, colorDefaults: ColorTweakState | undefined, cluster?: ColorClusterConfig, tabs?: readonly TabConfig[]): Record<string, string>;
-//# sourceMappingURL=build-apply-overrides.d.ts.map
+export declare function buildApplyOverrides(state: TweakState, colorDefaults: ColorTweakState | undefined, cluster?: ColorClusterConfig, tabs?: readonly TabConfig[], currentTab?: TabConfig | undefined): Record<string, string>;

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,31 @@ 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
+/**
+ * A `SemanticValue`'s cross-tab ramp reference: names a target ramp item by
+ * `{ tab?, tier, item }`. An omitted `tab` means "the current tab" (intra-tab,
+ * back-compat). Mirrors the `{ ref }` variant of `SemanticValue` in
+ * `tokens/tier-model.ts`.
+ */
+export type CrossTabRef = {
+    tab?: string;
+    tier: string;
+    item: string;
+};
+/**
+ * Resolve a `{ tab?, tier, item }` reference to the target item's `cssVar`
+ * so a downstream emitter (#468) can write `var(--target-cssvar)`.
+ *
+ * Resolution:
+ *   - `tab` omitted (or equal to `currentTab.id`) → resolve within
+ *     `currentTab` (intra-tab; keeps a lone-tab caller working with the
+ *     default `tabs = [currentTab]`).
+ *   - `tab` set → look the target tab up by id in `tabs` (the panel config's
+ *     full tabs array), then find `tier` in it, then `item` in that tier.
+ *
+ * Throws `TierResolverError` with a precise message when the target tab, tier,
+ * or item does not exist. This is the single reachable cross-tab lookup path;
+ * #468 wraps the returned cssVar in `var(...)` and #469 validates source
+ * declarations up front.
+ */
+export declare function resolveRefToCssVar(ref: CrossTabRef, currentTab: TabConfig, tabs?: readonly TabConfig[]): string;

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,16 +1,16 @@
-import { c as h, g as u, a as g, b as w, d as y, e as P } from "../panel-config-DyVRQ2n1.js";
-import { g as d, Z as b } from "../tweak-state-DzZVbY25.js";
-import { s as _, l as A, a as c, c as k, b as I } from "../autoload-state-DsvvPDih.js";
-const i = "tokenpanel-config";
+import { c as h, g as u, a as g, b as w, d as y, e as P } from "../panel-config-CXTCcYQs.js";
+import { g as d, Z as b } from "../tweak-state-BeXkzoj8.js";
+import { s as _, l as A, a as c, c as k, b as I } from "../autoload-state-CmhI7q9j.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 n = document.getElementById(i);
+  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 o = n.textContent ?? "";
   let e;
@@ -18,7 +18,7 @@ function E() {
     e = JSON.parse(o);
   } catch (a) {
     throw new Error(
-      `[design-token-panel] Failed to parse inline config from #${i}: ${a.message}`
+      `[design-token-panel] Failed to parse inline config from #${l}: ${a.message}`
     );
   }
   return P(e), e;
@@ -46,7 +46,7 @@ function v(n, o) {
     return !1;
   }
 }
-async function l(n) {
+async function i(n) {
   return n.modulePromise === null && (n.modulePromise = import("@takazudo/zdtp").then((o) => {
     try {
       const e = u(), a = o.__panelConfigForTest();
@@ -64,22 +64,22 @@ async function l(n) {
 function D(n, o, e, a, t) {
   const s = n[o] ?? {};
   s.showDesignPanel = async () => {
-    c(t, !0), await l(e), a.open();
+    c(t, !0), await i(e), a.open();
   }, s.hideDesignPanel = async () => {
-    await l(e), a.close();
+    await i(e), a.close();
   }, s.toggleDesignPanel = async () => {
-    await l(e);
+    await i(e), a.toggle();
     let r = !1;
     try {
-      r = window.localStorage.getItem(d(t)) !== "1";
+      r = window.localStorage.getItem(d(t)) === "1";
     } catch {
     }
-    a.toggle(), r && c(t, !0);
+    r && c(t, !0);
   }, s.enableAutoload = async () => {
-    (await l(e)).enableAutoload(t);
+    (await i(e)).enableAutoload(t);
   }, s.disableAutoload = async () => {
     if (e.modulePromise !== null) {
-      (await l(e)).disableAutoload(t);
+      (await i(e)).disableAutoload(t);
       return;
     }
     k(t), I(!1, t);
@@ -98,5 +98,5 @@ function D(n, o, e, a, t) {
   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)) && l(r);
+  (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-DyVRQ2n1.js";
+import { s as t } from "../panel-config-CXTCcYQs.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-DsvvPDih.js → autoload-state-CmhI7q9j.js}

@@ -1,4 +1,4 @@
-import { g as a, j as o } from "./panel-config-DyVRQ2n1.js";
+import { g as a, j as o } from "./panel-config-CXTCcYQs.js";
 function n(e = a()) {
   return `${e.storagePrefix}-elpath-enabled`;
 }

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

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

@@ -1,3 +1,2 @@
 export { ColorPicker, type ColorPickerMode, type ColorPickerProps, LOCAL_STORAGE_KEY, getFixedPopoverStyle, usePopoverClose, } from './color-picker';
 export { default } from './color-picker';
-//# sourceMappingURL=index.d.ts.map

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

@@ -1,3 +1,2 @@
 export { PaletteChart, type PaletteChartProps, type Oklcha, type Channel, } from './palette-chart';
 export { default } from './palette-chart';
-//# sourceMappingURL=index.d.ts.map

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

@@ -72,4 +72,3 @@ declare function PaletteChartImpl({ colors, selectedIndex, visibleChannels, onCh
  */
 export declare const PaletteChart: typeof PaletteChartImpl;
 export default PaletteChart;
-//# sourceMappingURL=palette-chart.d.ts.map

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

@@ -21,6 +21,8 @@
  * `panelConfig.colorCluster`.
  */
 import type { ColorScheme } from './color-schemes';
+import type { SemanticValue } from '../tokens/tier-model';
+export type { SemanticValue } from '../tokens/tier-model';
 /**
  * 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).
@@ -76,8 +78,16 @@ export interface ColorClusterDataConfig {
      * `--brand-p{n}`, `--demo-palette-{n}`.
      */
     paletteCssVarTemplate: string;
-    /** Semantic token name → default palette index. */
-    semanticDefaults: Record<string, number>;
+    /**
+     * Semantic token name → default mapping. Historically always a palette
+     * index (`number`); widened to `SemanticValue` (#459) so a default can also
+     * be a literal color or a cross-tab ramp reference. `resolveColorClusterFromTab`
+     * now derives the `{ literal }` / best-effort `{ ref }` variants too (#463)
+     * for a `semantic: true` tier; actually resolving a `{ ref }` against the
+     * ramp tier it names (rendering + apply) is still downstream work
+     * (#467/#469).
+     */
+    semanticDefaults: Record<string, SemanticValue>;
     /** Semantic token name → CSS custom-property name. */
     semanticCssNames: Record<string, string>;
     /** Fallback indices used when a scheme doesn't declare a base role. */
@@ -104,23 +114,36 @@ import type { TabConfig } from '../tokens/tier-model';
 /**
  * Derive a `ColorClusterDataConfig` from a color `TabConfig`.
  *
- * - Palette items: the first tier whose items all have `kind: 'color'`.
- *   Each item's `cssVar` becomes a palette slot; `paletteCssVarTemplate` is
- *   synthesised as `"{item.cssVar}"` with `{n}` replaced by the slot index.
- *   Because item cssVars are explicit (e.g. `--zfb-palette-0`) rather
- *   than template-based, we derive the template from the first item by
- *   replacing the terminal digit sequence with `{n}`.
+ * - Palette items: the first tier whose items all have `kind: 'color'` and
+ *   are not `semantic: true`. Each item's `cssVar` becomes a palette slot;
+ *   `paletteCssVarTemplate` is synthesised as `"{item.cssVar}"` with `{n}`
+ *   replaced by the slot index. Because item cssVars are explicit (e.g.
+ *   `--zfb-palette-0`) rather than template-based, we derive the template
+ *   from the first item by replacing the terminal digit sequence with `{n}`.
  *
- * - Semantic items: the first tier with `referencesTier` set pointing at the
- *   palette tier. Each item's `id` → `cssVar` mapping becomes `semanticCssNames`;
- *   the item's `default` (a palette item id) is looked up to produce the index
- *   for `semanticDefaults`.
+ * - Semantic items: either the first tier with `referencesTier` set pointing
+ *   at the palette tier (legacy shape), or a tier explicitly marked
+ *   `semantic: true` (#461) — the latter may have no palette sibling at all.
+ *   Each item's `id` → `cssVar` mapping becomes `semanticCssNames`; the
+ *   item's `default` is resolved to a `SemanticValue` by
+ *   `deriveSemanticValue` (palette index / literal / ramp-ref — see there).
+ *
+ * - A tab with a semantic tier but NO palette tier still produces a usable
+ *   cluster: `paletteSize` is `0` (the palette-driven UI has nothing to
+ *   render) but `semanticDefaults`/`semanticCssNames` are populated from the
+ *   semantic tier so the Semantic Tokens section isn't left empty (#463).
  *
  * - Metadata comes from `tab.colorExtras` (required on a color tab).
  *
+ * `tabs` is the panel config's full tabs array, used to resolve a semantic
+ * tier's cross-tab `{ ref }` mappings against a ramp tier living in ANOTHER
+ * tab (typically the grouped Palette tab). It defaults to `[tab]` so an
+ * existing single-argument call still works — intra-tab refs resolve, and a
+ * cross-tab ramp declaration falls back to its best-effort shape (#467).
+ *
  * Returns `undefined` when the tab has no `colorExtras` (not a color tab).
  */
-export declare function resolveColorClusterFromTab(tab: TabConfig): ColorClusterDataConfig | undefined;
+export declare function resolveColorClusterFromTab(tab: TabConfig, tabs?: readonly TabConfig[]): ColorClusterDataConfig | undefined;
 /**
  * Find the primary color tab (id 'color') in the host's tabs array and
  * derive its `ColorClusterDataConfig`. Returns `undefined` when no color tab
@@ -132,4 +155,3 @@ export declare function resolvePrimaryColorCluster(tabs: readonly TabConfig[]):
  * `ColorClusterDataConfig`. Returns `null` when no secondary color tab exists.
  */
 export declare function resolveSecondaryColorClusterFromTabs(tabs: readonly TabConfig[]): ColorClusterDataConfig | null;
-//# sourceMappingURL=cluster-config.d.ts.map

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

@@ -102,4 +102,3 @@ export declare function resolveSemanticColors(scheme: ColorScheme): Record<strin
 export declare function schemeToCssPairs(scheme: ColorScheme): [string, string][];
 export declare function generateCssCustomProperties(): string;
 export declare function generateLightDarkCssProperties(): string;
-//# sourceMappingURL=color-scheme-utils.d.ts.map

package/dist/config/color-schemes.d.ts

@@ -85,4 +85,3 @@ export interface ColorScheme {
  * same indices.
  */
 export declare const colorSchemes: Record<string, ColorScheme>;
-//# sourceMappingURL=color-schemes.d.ts.map

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

@@ -337,6 +337,17 @@ export declare function registerPostConfigureHook(hook: () => void): void;
  * called `configurePanel`.
  */
 export declare function getPanelConfig(): PanelConfig;
+/**
+ * Return the configs of ALL registered panel instances, in registration order.
+ * Returns an empty array when no instance has been configured yet.
+ *
+ * Used by the Astro lifecycle handlers (unmountForSwap / reapplyFromStorage)
+ * to loop every mounted instance rather than only the default one. Without
+ * this, non-default panels have their DOM roots removed by Astro's body swap
+ * WITHOUT `render(null, root)` being called, so their useEffect cleanups never
+ * fire and window/document listeners accumulate per soft navigation.
+ */
+export declare function getAllPanelConfigs(): PanelConfig[];
 /**
  * Resolve the registered config for a SPECIFIC instance by its `storagePrefix`
  * (=== `instanceId`), or `null` when no such instance is registered.
@@ -483,4 +494,3 @@ export declare function resolveApplyRouting(cfg?: PanelConfig): ApplyRoutingMap;
  * registry level and merged into the first instance to be configured.
  */
 export declare function setPanelColorPresets(presets: Record<string, ColorScheme>): void;
-//# sourceMappingURL=panel-config.d.ts.map