@takazudo/zdtp 0.4.2 → 0.4.4

package/dist/panel.d.ts

@@ -16,4 +16,3 @@ interface DesignTokenTweakPanelProps {
 }
 export default function DesignTokenTweakPanel({ instanceConfig: instanceConfigProp, }?: DesignTokenTweakPanelProps): import("preact").JSX.Element;
 export type { TweakState } from './state/tweak-state';
-//# sourceMappingURL=panel.d.ts.map

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

@@ -45,4 +45,3 @@ export interface PerFileResult {
  * ```
  */
 export declare function createApplyHandler(options: ApplyHandlerOptions): (req: Request) => Promise<Response>;
-//# sourceMappingURL=create-apply-handler.d.ts.map

package/dist/server/index.d.ts

@@ -21,4 +21,3 @@ export type { ApplyHandlerOptions, PerFileResult } from './create-apply-handler'
 export { serializeFileWrite } from './serialize-write';
 export { CSS_VAR_NAME_RE, isPathSafe, isValidCssVarName, validateAndSanitizeTokens, } from './path-safety';
 export { loadRoutingFromFile, type ApplyRoutingMap } from './load-routing';
-//# sourceMappingURL=index.d.ts.map

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-XyKgftpe.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-DtNTKoLW.js";
 export {
   s as CSS_VAR_NAME_RE,
   i as createApplyHandler,

package/dist/server/load-routing.d.ts

@@ -36,4 +36,3 @@ export type ApplyRoutingMap = Record<string, string>;
  * ```
  */
 export declare function loadRoutingFromFile(absPath: string): ApplyRoutingMap;
-//# sourceMappingURL=load-routing.d.ts.map

package/dist/server/path-safety.d.ts

@@ -33,4 +33,3 @@ export declare function validateAndSanitizeTokens(tokens: Record<string, unknown
     sanitized?: Record<string, string>;
     error?: string;
 };
-//# sourceMappingURL=path-safety.d.ts.map

package/dist/server/serialize-write.d.ts

@@ -4,4 +4,3 @@
  * one settles (success or error). Calls for different paths run in parallel.
  */
 export declare function serializeFileWrite<T>(absPath: string, fn: () => Promise<T>): Promise<T>;
-//# sourceMappingURL=serialize-write.d.ts.map

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

@@ -89,4 +89,3 @@ export declare function setAutoload(cfg: PanelConfig, on: boolean): void;
  * SSR-safe and quota-tolerant.
  */
 export declare function clearAutoload(cfg: PanelConfig): void;
-//# sourceMappingURL=autoload-state.d.ts.map

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';
@@ -33,7 +40,6 @@ export declare function usePersist(setState: SetState<TweakState>, cfg?: PanelCo
     persistTypography: (updater: (prev: TokenOverrides) => TokenOverrides) => void;
     persistFont: (updater: (prev: TokenOverrides) => TokenOverrides) => void;
     persistSize: (updater: (prev: TokenOverrides) => TokenOverrides) => void;
-    persistPanelPosition: (updater: (prev: TweakState["panelPosition"]) => TweakState["panelPosition"]) => void;
     persistSecondary: (updater: (prev: ColorTweakState | undefined) => ColorTweakState | undefined) => void;
 };
 export type Persist = ReturnType<typeof usePersist>['persist'];
@@ -44,7 +50,5 @@ export type PersistTypography = ReturnType<typeof usePersist>['persistTypography
 /** Upstream alias for `PersistTypography`. See `persistFont` above. */
 export type PersistFont = PersistTypography;
 export type PersistSize = ReturnType<typeof usePersist>['persistSize'];
-export type PersistPanelPosition = ReturnType<typeof usePersist>['persistPanelPosition'];
 export type PersistSecondary = ReturnType<typeof usePersist>['persistSecondary'];
 export {};
-//# sourceMappingURL=persist.d.ts.map

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';
@@ -182,9 +185,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
@@ -195,9 +236,13 @@ export type TokenOverrides = Record<string, string>;
  * Unified persist envelope. Each tab owns its own sub-state so they can
  * evolve independently.
  *
- * `panelPosition` is persisted alongside the envelope so the user's drag
- * location survives reloads. `secondary` carries a second (optional) color
- * cluster — absent until a host opts in.
+ * Panel position and size are stored in SEPARATE localStorage keys
+ * (`-position` / `-size`) and are NOT part of this envelope. The panel reads
+ * them via `loadPosition` / `loadSize` on mount; drags / resizes write them
+ * directly via `savePosition` / `saveSize`.
+ *
+ * `secondary` carries a second (optional) color cluster — absent until a host
+ * opts in.
  *
  * `tabs` is the v3 extension: a tab-keyed map of `TabOverrides` for host-coined
  * generic tabs that use the tier model. The existing `color`/`spacing`/
@@ -209,7 +254,6 @@ export interface TweakState {
     spacing: TokenOverrides;
     typography: TokenOverrides;
     size: TokenOverrides;
-    panelPosition?: PanelPosition;
     secondary?: ColorTweakState;
     /** Generic tab overrides keyed by tab id. Added in v3 envelope. */
     tabs?: Record<string, TabOverrides>;
@@ -235,6 +279,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
@@ -304,14 +352,94 @@ export declare function getActiveSchemeName(cluster?: ColorClusterDataConfig, cf
  * no schemes should not call this directly — they use
  * `initSecondaryDefaults(cluster)` instead because there is no scheme to
  * seed from.
+ *
+ * @param cfg - The panel instance config. When provided and the config has
+ *   `applySink`, the host's `data-theme` attribute is ignored and the scheme
+ *   seed comes from `cluster.panelSettings.colorScheme` instead (sink-instance
+ *   guard). Omitting it silently falls through to reading `data-theme`, which
+ *   is the correct behavior for non-sink instances but wrong for sinks.
+ */
+export declare function initColorFromScheme(cluster?: ColorClusterDataConfig, cfg?: PanelConfig): ColorTweakState;
+/**
+ * Palette entry sanitiser. Raw `oklch(...)` values are preserved verbatim so
+ * wide-gamut chroma survives (and they never touch the canvas → no '#000000'
+ * under jsdom / engines whose 2D canvas can't parse oklch). Every NON-oklch entry
+ * goes through cssColorToHex() — the exact pre-OKLCH behaviour — which
+ * canonicalises valid hex/rgb and, crucially, turns an unparseable string into a
+ * safe '#000000' rather than leaking it into a CSS custom property. Without this,
+ * a bundled scheme's stray non-color entry (e.g. `Default Dark`'s slot-9 `"18"`,
+ * referenced by `background: 9`) would reach the apply path verbatim.
+ *
+ * Exported so the serde import path (design-token-serde.ts) can apply the same
+ * sanitiser to imported palette values — commit 8d54e07 hardened seeding; this
+ * export closes the equivalent gap in the JSON-import path.
  */
-export declare function initColorFromScheme(cluster?: ColorClusterDataConfig): ColorTweakState;
+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.
+ */
+export declare function applyColorState(state: ColorTweakState, cluster?: ColorClusterDataConfig, sink?: ApplySink, currentTab?: TabConfig, tabs?: readonly TabConfig[]): void;
 /**
  * Apply a `TokenOverrides` map for a given manifest — writes inline
  * `--css-var: value` on `:root` for every overridden token, and removes the
@@ -333,6 +461,15 @@ 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).
+ *
+ * `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.
  */
 export declare function applyFullState(state: TweakState, cfg?: PanelConfig): void;
 /**
@@ -440,4 +577,3 @@ export declare function savePersistedState(state: TweakState, storage?: StorageL
  * preserving the single-panel path.
  */
 export declare function clearPersistedState(storage?: StorageLike, cfg?: PanelConfig): void;
-//# sourceMappingURL=tweak-state.d.ts.map

package/dist/styles/z-index-tokens.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Semantic z-index scale for the design-token panel.
+ *
+ * Single source of truth shared with panel-tokens.css:
+ *   - CSS reads `var(--tokentweak-z-*)` (declared in panel-tokens.css)
+ *   - TSX reads the numeric exports here for inline `zIndex` styles
+ *
+ * Values in the INT32 high band so the panel sits above common host chrome
+ * (sticky headers, drawers typically use z-index 100–10000). Ceiling bounded
+ * by INT32_MAX = 2147483647; inspector-box and toast claim the two highest
+ * practical values so element-path affordances are never obscured.
+ *
+ * Tier order: overlay < shell < settingsPopover < colorPicker < tooltip
+ *             < inspectorBox < toast
+ */
+export declare const Z: {
+    /** Highlight rings — rendered just below the panel shell. */
+    readonly overlay: 2147482990;
+    /** Panel shell (position:fixed root-level). */
+    readonly shell: 2147482991;
+    /** Highlight-settings popover — body-sibling of the shell, competes at root. */
+    readonly settingsPopover: 2147482992;
+    /**
+     * Color-picker card (position:fixed) — DOM child of .tokenpanel-shell,
+     * which is a stacking context. This value is shell-local; against host
+     * content the picker paints at the shell's root-level z-index.
+     */
+    readonly colorPicker: 2147482993;
+    /** DOM tooltip portaled to document.body. */
+    readonly tooltip: 2147482994;
+    /** Element-path inspector box (body-mounted). */
+    readonly inspectorBox: 2147483000;
+    /** Element-path toast (body-mounted). */
+    readonly toast: 2147483001;
+};

package/dist/tabs/_generic-item-editor.d.ts

@@ -21,4 +21,3 @@ export interface GenericItemEditorProps {
 declare function GenericItemEditorInner({ item, value, onChange }: GenericItemEditorProps): import("preact").JSX.Element | null;
 declare const _default: typeof GenericItemEditorInner;
 export default _default;
-//# sourceMappingURL=_generic-item-editor.d.ts.map

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,7 +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 {};
-//# sourceMappingURL=color-tab.d.ts.map

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

@@ -19,4 +19,3 @@ interface FontTabProps {
  */
 export default function FontTab({ tab, state, persistFont }: FontTabProps): import("preact").JSX.Element;
 export {};
-//# sourceMappingURL=font-tab.d.ts.map

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/
@@ -40,4 +42,3 @@ export interface GenericTabProps {
  * components until Wave 5 migrates them to consume TabConfig.tiers.
  */
 export default function GenericTab({ tab, overrides, onChange }: GenericTabProps): import("preact").JSX.Element;
-//# sourceMappingURL=generic-tab.d.ts.map

package/dist/tabs/palette/palette-check-view.d.ts

@@ -19,4 +19,3 @@ export interface PaletteCheckViewProps {
     onChange: (tierId: string, itemId: string, next: string) => void;
 }
 export default function PaletteCheckView({ tab, overrides }: PaletteCheckViewProps): import("preact").JSX.Element;
-//# sourceMappingURL=palette-check-view.d.ts.map

package/dist/tabs/palette/palette-edit-view.d.ts

@@ -53,4 +53,3 @@ export interface PaletteEditViewProps {
     onCommitBatch?: (tierId: string, patch: Record<string, string>) => void;
 }
 export default function PaletteEditView({ tab, overrides, onChange, onCommitBatch }: PaletteEditViewProps): import("preact").JSX.Element;
-//# sourceMappingURL=palette-edit-view.d.ts.map

package/dist/tabs/palette/palette-readout.d.ts

@@ -20,4 +20,3 @@ export interface PaletteReadoutProps {
     outOfGamut: boolean;
 }
 export default function PaletteReadout({ oklcha, cssVar, outOfGamut }: PaletteReadoutProps): import("preact").JSX.Element;
-//# sourceMappingURL=palette-readout.d.ts.map

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

@@ -34,4 +34,3 @@ export interface PaletteTabProps {
     onCommitBatch?: (tierId: string, patch: Record<string, string>) => void;
 }
 export default function PaletteTab({ tab, overrides, onChange, onCommitBatch }: PaletteTabProps): import("preact").JSX.Element;
-//# sourceMappingURL=palette-tab.d.ts.map

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

@@ -17,4 +17,3 @@ interface SizeTabProps {
  */
 export default function SizeTab({ tab, state, persistSize }: SizeTabProps): import("preact").JSX.Element;
 export {};
-//# sourceMappingURL=size-tab.d.ts.map

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

@@ -20,4 +20,3 @@ interface SpacingTabProps {
  */
 export default function SpacingTab({ tab, state, persistSpacing }: SpacingTabProps): import("preact").JSX.Element;
 export {};
-//# sourceMappingURL=spacing-tab.d.ts.map

package/dist/testing.d.ts

@@ -78,4 +78,3 @@ export interface PlaywrightLocatorLike {
  *   include the unit suffix — the panel appends the configured unit itself.
  */
 export declare function setPanelInputValue(locator: PlaywrightLocatorLike, value: string): Promise<void>;
-//# sourceMappingURL=testing.d.ts.map

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-DyVRQ2n1.js";
-import { a as l, b as y, l as O } from "./tweak-state-DzZVbY25.js";
+import { _ as r, c as i, f as _, h as n, i as g, b as R, a as p } from "./panel-config-CXTCcYQs.js";
+import { a as l, b as y, l as O } from "./tweak-state-BeXkzoj8.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");

package/dist/tokens/manifest.d.ts

@@ -141,4 +141,3 @@ export declare const SIZE_GROUP_ORDER: readonly TokenGroup[];
 export declare function parseNumericValue(value: string): number | null;
 /** Format a numeric slider value back into the stored string form. */
 export declare function formatValue(n: number, unit: string): string;
-//# sourceMappingURL=manifest.d.ts.map

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;
@@ -89,4 +139,3 @@ export interface TabConfig {
     tiers: readonly TierConfig[];
     colorExtras?: ColorClusterExtras;
 }
-//# sourceMappingURL=tier-model.d.ts.map