@takazudo/zdtp 0.4.3 → 0.4.5

package/dist/server/create-apply-handler.d.ts

@@ -22,6 +22,12 @@ export interface PerFileResult {
     changed: string[];
     unchanged: string[];
     unknown: string[];
+    /**
+     * Subset of `unknown` (#508): declared somewhere in the file but outside
+     * the scanned `:root`/`@theme` blocks — see `ApplyResult.unknownOutsideBlock`
+     * in `apply-token-overrides.ts` for the full classification rules.
+     */
+    unknownOutsideBlock: string[];
 }
 /**
  * Create a framework-agnostic Fetch API handler for the design-token apply

package/dist/server/index.js

@@ -1,4 +1,4 @@
-import { C as s, c as i, i as l, a as r, l as t, s as o, v as d } from "../load-routing-DtNTKoLW.js";
+import { C as s, c as i, i as l, a as r, l as t, s as o, v as d } from "../load-routing-LJ72261l.js";
 export {
   s as CSS_VAR_NAME_RE,
   i as createApplyHandler,

package/dist/state/persist.d.ts

@@ -11,6 +11,13 @@
  * Framework-agnostic wrt. the setState function: pass any
  * `(updater) => void` that propagates `updater(prev)` to the caller's state.
  * In practice the panel passes Preact's `setState` from `useState`.
+ *
+ * `persistColor`'s updater is `(prev: ColorTweakState) => ColorTweakState`, so
+ * the widened `ColorTweakState.semanticMappings: Record<string, SemanticValue>`
+ * (#459) — including the `{ literal }` / `{ ref }` object variants added for
+ * #462 — already flows through this hook's generic pass-through unchanged; the
+ * actual validating hydrate/round-trip logic for those variants lives in
+ * `tweak-state.ts` (`hydrateSemanticMappings` / `savePersistedState`), not here.
  */
 import { type ColorTweakState, type TabOverrides, type TokenOverrides, type TweakState } from './tweak-state';
 import type { PanelConfig } from '../config/panel-config';

package/dist/state/tweak-state.d.ts

@@ -42,8 +42,11 @@
 import type { ColorRef, ColorScheme } from '../config/color-schemes';
 import type { TokenDef } from '../tokens/manifest';
 import { type ColorClusterDataConfig } from '../config/cluster-config';
+import type { SemanticValue } from '../tokens/tier-model';
+export type { SemanticValue } from '../tokens/tier-model';
 import { type ApplySink, type PanelConfig } from '../config/panel-config';
 export type { ApplySink } from '../config/panel-config';
+import type { TabConfig } from '../tokens/tier-model';
 import { type TabOverrides } from '../apply/tier-resolver';
 export type { BaseRoleKey, ColorClusterDataConfig } from '../config/cluster-config';
 export { resolvePaletteCssVar } from '../config/cluster-config';
@@ -77,6 +80,12 @@ export type { TabOverrides } from '../apply/tier-resolver';
 export declare function getStorageKeyV1(cfg?: PanelConfig): string;
 export declare function getStorageKeyV2(cfg?: PanelConfig): string;
 export declare function getStorageKeyV3(cfg?: PanelConfig): string;
+/**
+ * v4 unified envelope key — the per-scheme-keyed color format (#500/#509).
+ * See `storageKey_stateV4` for the shape rationale. Read first by
+ * `loadPersistedState`; v1/v2/v3 migrate into it on first load.
+ */
+export declare function getStorageKeyV4(cfg?: PanelConfig): string;
 export declare function getOpenKey(cfg?: PanelConfig): string;
 export declare function getPositionKey(cfg?: PanelConfig): string;
 export declare function getSizeKey(cfg?: PanelConfig): string;
@@ -182,9 +191,47 @@ export interface ColorTweakState {
     cursor: number;
     selectionBg: number;
     selectionFg: number;
-    semanticMappings: Record<string, number | 'bg' | 'fg'>;
+    /**
+     * Semantic token name → mapping. Widened from `Record<string, number | 'bg'
+     * | 'fg'>` to `Record<string, SemanticValue>` (#459 S1). This is additive
+     * for readers of the type (every legacy value is still a valid
+     * `SemanticValue`), but it BREAKS any exhaustive `switch`/equality check
+     * written against the old narrow union — callers that pattern-match on a
+     * mapping value must now also handle the new `{ literal }` / `{ ref }`
+     * object variants (see `isIndexMapping` / `isLiteralMapping` /
+     * `isPerModeLiteral` / `isRefMapping` below). `resolveMapping` (exported)
+     * still only resolves the legacy `number | 'bg' | 'fg'` shape — resolving
+     * the new variants is downstream work (#467/#469).
+     */
+    semanticMappings: Record<string, SemanticValue>;
     shikiTheme: string;
 }
+/** True when `v` is a legacy index-style mapping (palette index or bg/fg alias). */
+export declare function isIndexMapping(v: SemanticValue): v is number | 'bg' | 'fg';
+/** True when `v` is either literal-color variant (plain string or light/dark pair). */
+export declare function isLiteralMapping(v: SemanticValue): v is {
+    literal: string;
+} | {
+    literal: {
+        light: string;
+        dark: string;
+    };
+};
+/** True when `v` is specifically the light/dark literal-color variant. */
+export declare function isPerModeLiteral(v: SemanticValue): v is {
+    literal: {
+        light: string;
+        dark: string;
+    };
+};
+/** True when `v` is a cross-tab/tier ramp-item reference. */
+export declare function isRefMapping(v: SemanticValue): v is {
+    ref: {
+        tab?: string;
+        tier: string;
+        item: string;
+    };
+};
 /**
  * Per-token override map. Keys are `TokenDef.id` (e.g. `hsp-sm`); values are
  * raw CSS length strings (e.g. `0.75rem`). Only overridden tokens appear in
@@ -217,6 +264,32 @@ export interface TweakState {
     /** Generic tab overrides keyed by tab id. Added in v3 envelope. */
     tabs?: Record<string, TabOverrides>;
 }
+/**
+ * On-disk v4 persist envelope (#500/#509). Same top-level slices as the runtime
+ * `TweakState`, EXCEPT the `color` and `secondary` slices are identity-keyed
+ * sub-objects: one `ColorTweakState` slot per active-color IDENTITY (see
+ * `getActiveColorIdentity`). This is what lets a per-scheme color tweak survive
+ * a scheme toggle — editing under scheme A never touches scheme B's slot.
+ *
+ * The non-color slices (`spacing` / `typography` / `size` / `tabs`) stay global
+ * and unkeyed, exactly as in v1–v3: a light/dark toggle does not change them.
+ *
+ * `secondary` slots are keyed by the SAME primary identity — the secondary
+ * cluster has no scheme of its own but reseeds on the same `color-scheme-changed`
+ * event, so it follows the primary's identity.
+ *
+ * `loadPersistedState` selects the active identity's slots into a runtime
+ * `TweakState`; `savePersistedState` merge-saves the active slots while
+ * preserving every inactive identity's slot.
+ */
+export interface PersistedEnvelopeV4 {
+    color: Record<string, ColorTweakState>;
+    secondary?: Record<string, ColorTweakState>;
+    spacing: TokenOverrides;
+    typography: TokenOverrides;
+    size: TokenOverrides;
+    tabs?: Record<string, TabOverrides>;
+}
 /** Produce an empty overrides map — `TweakState` default for new tabs. */
 export declare function emptyOverrides(): TokenOverrides;
 /**
@@ -238,6 +311,10 @@ export declare function getActivePrimaryCluster(cfg?: PanelConfig): ColorCluster
  *    slots interpolate. Functional but visually flat; hosts wanting a
  *    designed seed should ship a scheme registry on the cluster and call
  *    `initColorFromScheme(cluster)` instead.
+ *  - A cluster with `paletteSize: 0` (a lone `semantic: true` tier with no
+ *    palette sibling, #458/#466) seeds an EMPTY palette — there is nothing
+ *    to ramp. Forcing a 1-slot grayscale floor here produced a phantom
+ *    `--zudo-stub-p0` swatch/token with no backing tier; see #466.
  *
  * The base-role indices are kept on the state shape for envelope-round-trip
  * compatibility but are inert — `applyColorState` only writes a base role
@@ -315,6 +392,24 @@ export declare function getActiveSchemeName(cluster?: ColorClusterDataConfig, cf
  *   is the correct behavior for non-sink instances but wrong for sinks.
  */
 export declare function initColorFromScheme(cluster?: ColorClusterDataConfig, cfg?: PanelConfig): ColorTweakState;
+/**
+ * Derive the active-color IDENTITY — the key under which the v4 envelope files
+ * this instance's `color` / `secondary` slots (#500/#509).
+ *
+ * The identity is EXACTLY the active scheme name `initColorFromScheme` resolves
+ * for the primary cluster via `getActiveSchemeName` (the active scheme, with the
+ * light/dark mode already folded into the resolved name where the cluster
+ * `panelSettings.colorMode` distinguishes modes). This is deliberate: the same
+ * inputs whose change triggers a reseed today produce the identity, so the
+ * invariant holds — *the same identity that causes a reseed selects its own
+ * persisted slot*. A colorMode-less cluster resolves a constant identity (one
+ * slot); a light/dark cluster resolves distinct identities per side.
+ *
+ * The secondary cluster has no scheme concept of its own but reseeds on the same
+ * `color-scheme-changed` event, so its slots are keyed by this SAME primary
+ * identity — callers pass the PRIMARY cluster here for both slices.
+ */
+export declare function getActiveColorIdentity(cluster?: ColorClusterDataConfig, cfg?: PanelConfig): string;
 /**
  * Palette entry sanitiser. Raw `oklch(...)` values are preserved verbatim so
  * wide-gamut chroma survives (and they never touch the canvas → no '#000000'
@@ -331,11 +426,79 @@ export declare function initColorFromScheme(cluster?: ColorClusterDataConfig, cf
  */
 export declare function normalizeSchemePaletteEntry(value: string): string;
 export declare function initColorFromSchemeData(scheme: ColorScheme, cluster?: ColorClusterDataConfig): ColorTweakState;
-/** Resolve a semantic mapping to an actual color (bounds-checked). */
+/**
+ * Resolve a semantic mapping to an actual color (bounds-checked).
+ *
+ * Only handles the legacy `number | 'bg' | 'fg'` index shape — the narrower
+ * type this function accepted before `ColorTweakState.semanticMappings` /
+ * `ColorClusterDataConfig.semanticDefaults` were widened to `SemanticValue`
+ * (#459 S1). Callers holding a `SemanticValue` must narrow with
+ * `isIndexMapping()` first; resolving the `{ literal }` / `{ ref }` variants
+ * is downstream work (#467/#469), not this function's job today.
+ */
 export declare function resolveMapping(mapping: number | 'bg' | 'fg', palette: string[], bgIndex: number, fgIndex: number): string;
 export declare function safeIndex(index: number, len: number): number;
-/** Apply a single `ColorTweakState` to the DOM using the given cluster config. */
-export declare function applyColorState(state: ColorTweakState, cluster?: ColorClusterDataConfig, sink?: ApplySink): void;
+/**
+ * The cluster's configured default light/dark mode, or `'light'` when the
+ * cluster declares no `colorMode` (`colorMode === false`).
+ *
+ * This is the single runtime reader of `ClusterPanelSettings.colorMode.defaultMode`
+ * (#472). The field validates but was previously never read at runtime; this
+ * helper (consumed by `resolveSemanticPreviewColor`) gives it a real effect —
+ * it selects which side of a per-mode `{ literal: { light, dark } }` pair is the
+ * fallback when `light-dark()` cannot resolve.
+ */
+export declare function getClusterDefaultMode(cluster: ColorClusterDataConfig): 'light' | 'dark';
+/**
+ * Resolve a per-mode literal to a single concrete CSS color for `mode`.
+ *
+ * Used wherever CSS `light-dark()` cannot be used — a preview swatch, an SSR
+ * seed, or any non-browser consumer that needs one flat value rather than a
+ * `light-dark(...)` function. The emitters (`applyColorState`,
+ * `buildApplyOverrides`) deliberately do NOT call this; they emit
+ * `light-dark()` and let the browser choose.
+ */
+export declare function resolvePerModeLiteral(value: {
+    literal: {
+        light: string;
+        dark: string;
+    };
+}, mode: 'light' | 'dark'): string;
+/**
+ * Resolve a semantic mapping to a single concrete CSS color suitable for a
+ * PREVIEW swatch — a flat value, never a `light-dark()` function. Mirrors the
+ * internal apply-path resolver, except a per-mode `{ literal: { light, dark } }`
+ * value collapses to `getClusterDefaultMode(cluster)`'s side (#472).
+ *
+ * This is the "preview/seed" consumer referenced by #472/#473: the per-mode
+ * editor UI (#473) renders its swatch from this so the user sees the cluster's
+ * default-mode color, while the applied CSS var still emits `light-dark()`.
+ */
+export declare function resolveSemanticPreviewColor(mapping: SemanticValue, state: ColorTweakState, cluster?: ColorClusterDataConfig, currentTab?: TabConfig, tabs?: readonly TabConfig[]): string;
+/**
+ * Apply a single `ColorTweakState` to the DOM using the given cluster config.
+ *
+ * `currentTab` / `tabs` are optional and exist so a cross-tab/tier `{ ref }`
+ * semantic mapping (#468) can resolve: `currentTab` should be the color
+ * TabConfig this cluster was derived from (id `'color'` or
+ * `'color-secondary'`), and `tabs` the panel's full tabs array so a ref
+ * pointing into another tab (e.g. the grouped Palette tab) resolves. Callers
+ * that never hold `{ ref }` mappings (or have no tab context, e.g. most
+ * existing tests) can omit both — `resolveSemanticCssValue` returns `null`
+ * for an unresolvable ref rather than throwing, and this function skips a
+ * `null` (leaving the token at its stylesheet default) rather than painting
+ * a fallback color.
+ *
+ * `ownerPrefix` (#501) is the instance `storagePrefix` this apply belongs to.
+ * When supplied AND this cluster emits a per-mode `light-dark()` literal (so
+ * `color-scheme: light dark` is written to the apply target — either
+ * `document.documentElement` or the sink's root), the instance is recorded as
+ * the owner of that inline `color-scheme` so the clear paths can later remove
+ * it without ever wiping a host-owned `<html style="color-scheme">`. Omitting
+ * it (direct callers with no instance context, e.g. some tests) skips the
+ * bookkeeping only — the actual CSS write is unchanged.
+ */
+export declare function applyColorState(state: ColorTweakState, cluster?: ColorClusterDataConfig, sink?: ApplySink, currentTab?: TabConfig, tabs?: readonly TabConfig[], ownerPrefix?: string): void;
 /**
  * Apply a `TokenOverrides` map for a given manifest — writes inline
  * `--css-var: value` on `:root` for every overridden token, and removes the
@@ -346,6 +509,31 @@ export declare function applyColorState(state: ColorTweakState, cluster?: ColorC
  * in the UI and are never written to storage.
  */
 export declare function applyTokenOverrides(tokens: readonly TokenDef[], overrides: TokenOverrides, sink?: ApplySink): void;
+/**
+ * Apply ONLY the color slices — primary color cluster + optional secondary
+ * cluster + the aggregate `color-scheme` decision — leaving spacing / font /
+ * size / generic-tab vars untouched.
+ *
+ * Extracted from `applyFullState` (#500/#509) so the scheme-change handler can
+ * re-paint the new identity's persisted color overrides after
+ * `clearAppliedColorStyles` WITHOUT re-writing (or clearing) the scheme-
+ * independent non-color vars that must survive a light/dark toggle (#347).
+ *
+ * `color-scheme` is managed as an AGGREGATE across the primary + secondary
+ * clusters, not per-cluster (#482 D3): `applyColorState` only ever SETS
+ * `color-scheme: light dark` when its OWN cluster needs it, it never clears
+ * it, so demoting the last per-mode-literal row (in either cluster) would
+ * otherwise leave the previous apply's value stale. A naive per-cluster
+ * clear inside `applyColorState` would let a per-mode-free secondary undo
+ * what the primary just required (or vice versa), so the clear-when-neither-
+ * needs-it decision is made here, once, after both clusters have applied.
+ *
+ * #501 — the `document.documentElement` clear is scoped to a color-scheme THIS
+ * instance actually wrote (`clearOwnedColorSchemeFromDocument`) so a host that
+ * owns `<html style="color-scheme">` is never clobbered; the sink path stays
+ * unconditional (sink targets are panel-owned) but drops the ownership claim.
+ */
+export declare function applyColorSlices(color: ColorTweakState, secondary: ColorTweakState | undefined, cfg?: PanelConfig): void;
 /**
  * Apply the full unified `TweakState` — primary color cluster + token
  * overrides + optional secondary cluster.
@@ -357,8 +545,27 @@ export declare function applyTokenOverrides(tokens: readonly TokenDef[], overrid
  * When `cfg` is supplied its `applySink` (if any) is used to route all
  * CSS-var writes for this instance. Omitting `cfg` uses the default active
  * config (single-panel path, unchanged behavior).
+ *
+ * The color slices + aggregate `color-scheme` decision are delegated to
+ * `applyColorSlices`; this function adds the non-color (spacing / font / size /
+ * generic-tab) writes.
  */
 export declare function applyFullState(state: TweakState, cfg?: PanelConfig): void;
+/**
+ * Apply ONLY the non-color slices (spacing / typography / size / generic-tab
+ * overrides), leaving the color clusters and aggregate `color-scheme` decision
+ * untouched. Complement of `applyColorSlices`; together they compose
+ * `applyFullState`.
+ *
+ * Extracted (#509 audit) so the persisted-overrides reapply paths
+ * (`reapplyPersistedOverrides`, the panel first-open effect) can, when a v4
+ * envelope exists but the ACTIVE (scheme, mode) identity has no color slot,
+ * still apply the scheme-INDEPENDENT non-color tweaks while leaving the active
+ * scheme's own stylesheet colors to show through — instead of painting the
+ * synthesized config-default colors inline. This mirrors the scheme-change
+ * handler's missing-slot behavior (gated on `hasActiveColorSlot`).
+ */
+export declare function applyNonColorSlices(state: TweakState, cfg?: PanelConfig): void;
 /**
  * Strip the inline CSS variables written by the color cluster(s) only —
  * palette slots, base roles, and semantic vars. Spacing / typography / size
@@ -382,6 +589,11 @@ export declare function applyFullState(state: TweakState, cfg?: PanelConfig): vo
  * historical `(clusters, sink)` call shape (e.g. the scheme-change path before
  * #357, and existing tests) is unchanged. Omitting all three preserves the
  * single-panel default-instance behaviour.
+ *
+ * The color-scheme removal on the `document.documentElement` path is gated on
+ * this instance owning the inline value (#501) — see
+ * `clearOwnedColorSchemeFromDocument`. The owner is `cfg.storagePrefix` when a
+ * `cfg` is given, else the default instance's prefix.
  */
 export declare function clearAppliedColorStyles(clusters?: readonly ColorClusterDataConfig[], sink?: ApplySink, cfg?: PanelConfig): void;
 /**
@@ -447,17 +659,41 @@ export interface StorageLike {
  * labels), so this migration only applies to the typography slice.
  */
 export declare const ZDTP_LEGACY_TYPOGRAPHY_RENAME_MAP: Readonly<Record<string, string | null>>;
+/**
+ * True when the v4 envelope holds a color slot for the CURRENTLY active
+ * identity. The scheme-change handler uses this to decide whether to hydrate +
+ * apply persisted overrides for the new scheme (slot present) or reseed from
+ * config defaults WITHOUT applying (slot absent — the pre-#500 behavior that
+ * lets the new scheme's stylesheet show through).
+ */
+export declare function hasActiveColorSlot(cfg?: PanelConfig, cluster?: ColorClusterDataConfig, storage?: StorageLike): boolean;
+/**
+ * Load the active `TweakState`, preferring the v4 per-scheme envelope
+ * (#500/#509).
+ *
+ * Order:
+ *   1. v4 present → select the active identity's color/secondary slots.
+ *   2. else run the legacy v1/v2/v3 chain (unchanged) → migrate that state into
+ *      a v4 envelope filed under the identity active at load, WITHOUT deleting
+ *      the legacy key (v4 wins on every future load via step 1). This is why the
+ *      pre-existing v1/v2/v3 migration tests keep passing: the legacy chain still
+ *      writes/keeps the v3 key exactly as before; v4 is layered on top.
+ *   3. else null (caller cold-seeds).
+ *
+ * A present-but-malformed v4 blob falls through to steps 2/3, which overwrite it.
+ */
 export declare function loadPersistedState(storage?: StorageLike, colorDefaults?: ColorTweakState, cluster?: ColorClusterDataConfig, cfg?: PanelConfig): TweakState | null;
 /**
- * Persist the full `TweakState` to v3.
+ * Merge-save the full `TweakState` into the v4 per-scheme envelope (#500/#509).
  *
- * `cfg` scopes the storage key to a specific panel instance (multi-instance,
- * #357). Omitting it resolves the default instance via `getPanelConfig()`,
- * preserving the single-panel path.
+ * The active identity's color/secondary slots are overwritten; every inactive
+ * identity's slot is preserved (read → merge → write). Global non-color slices
+ * are replaced wholesale. `cfg` scopes the storage key to a specific panel
+ * instance (multi-instance, #357).
  */
 export declare function savePersistedState(state: TweakState, storage?: StorageLike, cfg?: PanelConfig): void;
 /**
- * Remove v3 (and lingering v2/v1) keys.
+ * Remove the v4 key (and lingering v3/v2/v1 keys).
  *
  * `cfg` scopes the cleared keys to a specific panel instance (multi-instance,
  * #357). Omitting it resolves the default instance via `getPanelConfig()`,

package/dist/tabs/color-tab.d.ts

@@ -35,6 +35,7 @@
  * in the panel.
  */
 import { type ColorTweakState } from '../state/tweak-state';
+import { type PanelConfig } from '../config/panel-config';
 import type { TabConfig } from '../tokens/tier-model';
 import type { PersistColor, PersistSecondary } from '../state/persist';
 interface ColorTabProps {
@@ -52,6 +53,17 @@ interface ColorTabProps {
     secondaryTab: TabConfig | null;
     secondaryState: ColorTweakState | null;
     persistSecondary: PersistSecondary;
+    /**
+     * The mounted panel instance's config (multi-instance, #353/#357). When
+     * supplied, cross-tab cluster/ref resolution (cluster derivation, the
+     * grouped ref-or-literal picker's ramp groups, preview resolution, and the
+     * host preset list) reads THIS instance's `tabs` / `colorPresets` rather
+     * than the active default instance — matching the apply path, which
+     * already resolves against `cfg.tabs` via `usePersist` (`applyFullState`,
+     * `state/persist.ts`). Omitted (e.g. a direct test render) →
+     * `getPanelConfig()`, preserving the single-instance path.
+     */
+    instanceConfig?: PanelConfig;
 }
-export default function ColorTab({ tab, state, persistColor, secondaryTab, secondaryState, persistSecondary, }: ColorTabProps): import("preact").JSX.Element;
+export default function ColorTab({ tab, state, persistColor, secondaryTab, secondaryState, persistSecondary, instanceConfig, }: ColorTabProps): import("preact").JSX.Element;
 export {};

package/dist/tabs/generic-tab.d.ts

@@ -28,8 +28,10 @@ export interface GenericTabProps {
      * When an item has no override, its `TierItem.default` is used.
      */
     overrides: TabOverrides;
-    /** Called when the user commits a change to any item. */
-    onChange: (tierId: string, itemId: string, next: string) => void;
+    /** Called when the user commits a change to any item. `next: undefined`
+     *  (only reachable for ref-tier items) means "drop the stored override for
+     *  this item" rather than writing a literal value. */
+    onChange: (tierId: string, itemId: string, next: string | undefined) => void;
 }
 /**
  * Renders a non-reserved tab (any TabConfig whose id is not color/font/

package/dist/testing.js

@@ -1,5 +1,5 @@
-import { _ as r, c as i, f as _, h as n, i as g, b as R, a as p } from "./panel-config-3tBEHjvZ.js";
-import { a as l, b as y, l as O } from "./tweak-state-BEx1SHu7.js";
+import { _ as r, c as i, h as _, i as n, j as g, b as R, a as p } from "./panel-config-CipeKMTz.js";
+import { a as y, b as O, l as P } from "./tweak-state-xt-tSQ_t.js";
 import { F as K, G as E, a as S, S as u } from "./manifest-DCReQE0k.js";
 async function s(a, e) {
   await a.fill(e), await a.dispatchEvent("input");
@@ -11,9 +11,9 @@ export {
   u as SIZE_GROUP_ORDER,
   r as __resetPanelConfigForTests,
   i as configurePanel,
-  l as getStorageKeyV1,
-  y as getStorageKeyV2,
-  O as loadPersistedState,
+  y as getStorageKeyV1,
+  O as getStorageKeyV2,
+  P as loadPersistedState,
   s as setPanelInputValue,
   _ as storageKey_open,
   n as storageKey_position,

package/dist/tokens/tier-model.d.ts

@@ -56,6 +56,33 @@ export interface PillSpec {
     value: string;
     customDefault: string;
 }
+/**
+ * A semantic token's mapping value.
+ *
+ * Legacy shape stays valid: a palette index (`number`) or the `'bg'` / `'fg'`
+ * sentinel aliases. New variants (added for #459) let a semantic tier point at
+ * an arbitrary literal color (optionally split light/dark) or reference a ramp
+ * item living in another tab/tier — both resolved downstream by #467/#469.
+ *
+ * Defined here (not in `state/tweak-state.ts`) because `config/cluster-config.ts`
+ * needs it for `ColorClusterDataConfig.semanticDefaults`, and cluster-config.ts
+ * already imports types from this module — keeping the definition here avoids
+ * a new type-only import cycle. `state/tweak-state.ts` re-exports it.
+ */
+export type SemanticValue = number | 'bg' | 'fg' | {
+    literal: string;
+} | {
+    literal: {
+        light: string;
+        dark: string;
+    };
+} | {
+    ref: {
+        tab?: string;
+        tier: string;
+        item: string;
+    };
+};
 export interface TierItem {
     id: string;
     cssVar: string;
@@ -73,6 +100,29 @@ export interface TierConfig {
      *  an item in the tier whose id matches referencesTier. The apply pipeline
      *  emits var(--tier1-cssvar). */
     referencesTier?: string;
+    /**
+     * Marks this tier as a SEMANTIC tier (its items hold `SemanticValue`
+     * mappings, not raw palette entries) so the panel never mistakes it for
+     * the palette tier. Optional and additive — omitting it preserves today's
+     * behavior (palette-tier detection stays structural, via
+     * `resolveColorClusterFromTab`'s `kind: 'color'` check).
+     */
+    semantic?: true;
+    /**
+     * Cross-tab ramp-source declaration for a semantic tier: the ramp tier(s)
+     * this tier's `{ ref }` mappings are allowed to point into. Each entry names
+     * a tier id and an optional tab id (omitted `tab` means "this tab").
+     * `assertValidPanelConfig` validates every declared source up front (the
+     * tab/tier must exist and share this tier's kind); `resolveColorClusterFromTab`
+     * (`config/cluster-config.ts`) uses the allow-list to derive each row's
+     * `SemanticValue`; the grouped `TierRefSelector` picker
+     * (`controls/tier-ref-selector.tsx`) renders one `<optgroup>` per declared
+     * source.
+     */
+    referencesRamps?: readonly {
+        tab?: string;
+        tier: string;
+    }[];
 }
 export interface ColorClusterExtras {
     id: string;
@@ -82,6 +132,18 @@ export interface ColorClusterExtras {
     defaultShikiTheme: string;
     colorSchemes: Record<string, ColorScheme>;
     panelSettings: ClusterPanelSettings;
+    /**
+     * Config-time override map for a semantic tier's derived defaults (#499).
+     * Keyed by semantic item id; when a key is present here,
+     * `resolveColorClusterFromTab` uses its `SemanticValue` verbatim instead of
+     * running `deriveSemanticValue` on the item's plain-string `default` — this
+     * is the only way a host can ship a `{ literal: { light, dark } }` (or
+     * `{ ref }`) config-time default, since `TierItem.default` itself stays a
+     * plain string (Option B from #499, chosen over widening `TierItem.default`
+     * to `SemanticValue` — that field is consumed generically as a plain string
+     * by every tab kind, not just Color).
+     */
+    semanticDefaults?: Record<string, SemanticValue>;
 }
 export interface TabConfig {
     id: string;