@takazudo/zdtp 0.1.0-next.0

package/dist/panel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"panel.d.ts","sourceRoot":"","sources":["../src/panel.tsx"],"names":[],"mappings":"AAwGA,MAAM,CAAC,OAAO,UAAU,qBAAqB,iCAkqB5C;AAED,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/route-tokens-to-files-1DvmWBdj.js

@@ -0,0 +1,41 @@
+const p = Object.freeze({});
+function h(o, r) {
+  if (!o.startsWith("--")) return null;
+  const s = Object.keys(r).sort((t, n) => n.length - t.length);
+  for (const t of s) {
+    const n = `--${t}-`;
+    if (o.startsWith(n) && o.length > n.length)
+      return t;
+  }
+  return null;
+}
+function a(o, r = p) {
+  const s = Object.keys(r), t = {};
+  for (const e of s) t[e] = {};
+  const n = [], i = [];
+  for (const [e, f] of Object.entries(o)) {
+    const u = h(e, r);
+    if (u === null) {
+      n.push(e), e.startsWith("--") ? s.length === 0 ? i.push(
+        `${e}: no applyRouting configured on PanelConfig (host has not enabled disk-rewrite)`
+      ) : i.push(
+        `${e}: no route configured for prefix family (known prefixes: ${s.map((l) => `"${l}"`).join(", ")})`
+      ) : i.push(`${e}: not a CSS custom property (must start with "--")`);
+      continue;
+    }
+    t[u][e] = f;
+  }
+  const c = [];
+  for (const e of s) {
+    const f = t[e];
+    Object.keys(f).length !== 0 && c.push({
+      prefix: e,
+      relativePath: r[e],
+      tokens: f
+    });
+  }
+  return { groups: c, rejected: n, rejectedReasons: i };
+}
+export {
+  a as r
+};

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

@@ -0,0 +1,48 @@
+import type { ApplyRoutingMap } from '../config/panel-config';
+export interface ApplyHandlerOptions {
+    /**
+     * Absolute path to the repository root. Used as the CWD reference when
+     * resolving `routing` paths and normalising `file` values in the response.
+     */
+    rootDir: string;
+    /**
+     * Absolute path to the directory that is allowed to contain CSS token files.
+     * Paths resolved from `routing` must sit strictly inside this directory
+     * (enforced by `isPathSafe`).
+     */
+    writeRoot: string;
+    /**
+     * Prefix → repo-relative CSS file path map. Matches the shape of
+     * `PanelConfig.applyRouting` (e.g. `{ zd: 'tokens/tokens.css' }`).
+     */
+    routing: ApplyRoutingMap;
+}
+export interface PerFileResult {
+    file: string;
+    changed: string[];
+    unchanged: string[];
+    unknown: string[];
+}
+/**
+ * Create a framework-agnostic Fetch API handler for the design-token apply
+ * endpoint.
+ *
+ * The returned function accepts a standard `Request` and returns a
+ * `Promise<Response>`. No Astro, Express, http, or Vite dependencies.
+ *
+ * @example
+ * ```ts
+ * import { createApplyHandler } from '@takazudo/zdtp/server';
+ *
+ * const handler = createApplyHandler({
+ *   rootDir: process.cwd(),
+ *   writeRoot: resolve(process.cwd(), 'tokens'),
+ *   routing: { zd: 'tokens/tokens.css' },
+ * });
+ *
+ * // Vite / Astro / any Fetch-compatible router:
+ * export const POST = ({ request }: { request: Request }) => handler(request);
+ * ```
+ */
+export declare function createApplyHandler(options: ApplyHandlerOptions): (req: Request) => Promise<Response>;
+//# sourceMappingURL=create-apply-handler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create-apply-handler.d.ts","sourceRoot":"","sources":["../../src/server/create-apply-handler.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAI9D,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,EAAE,eAAe,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAoFD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,mBAAmB,GAC3B,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAuIrC"}

package/dist/server/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @takazudo/zdtp/server
+ *
+ * Node-only server-side apply pipeline. Zero framework dependencies —
+ * the handler factory uses standard Fetch API types (Node 18+).
+ *
+ * @example
+ * ```ts
+ * import { createApplyHandler } from '@takazudo/zdtp/server';
+ * import { resolve } from 'node:path';
+ *
+ * const handler = createApplyHandler({
+ *   rootDir: process.cwd(),
+ *   writeRoot: resolve(process.cwd(), 'tokens'),
+ *   routing: { zd: 'tokens/tokens.css' },
+ * });
+ * ```
+ */
+export { createApplyHandler } from './create-apply-handler';
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,YAAY,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EACL,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,10 @@
+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";
+export {
+  s as CSS_VAR_NAME_RE,
+  i as createApplyHandler,
+  l as isPathSafe,
+  r as isValidCssVarName,
+  t as loadRoutingFromFile,
+  o as serializeFileWrite,
+  d as validateAndSanitizeTokens
+};

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

@@ -0,0 +1,39 @@
+/**
+ * CSS-var prefix family → host-relative CSS file path.
+ *
+ * Shape: `{ "<prefix>": "<host-relative-css-path>", ... }`.
+ * Both the panel UI (`PanelConfig.applyRouting`) and the bin (`--routing` flag)
+ * share this type so the two readers stay in sync.
+ *
+ * Same logical shape as `ApplyRoutingMap` in `config/panel-config.ts`
+ * (which is `Record<string, string>`). Exported from the server entry so
+ * bin code and consumer tooling can import it from `./server` without
+ * pulling in the full panel client bundle.
+ */
+export type ApplyRoutingMap = Record<string, string>;
+/**
+ * Read a routing JSON file from disk, validate its shape, and return the map.
+ *
+ * Throws a descriptive `Error` for any of:
+ *   - file does not exist / is unreadable
+ *   - invalid JSON syntax
+ *   - root value is not a plain object (null, array, primitive, etc.)
+ *   - any value in the map is not a non-empty string
+ *   - the map itself is empty (at least one prefix entry is required)
+ *
+ * Intended for Node.js / Vite plugin / bin contexts only — not for
+ * browser-side code (uses `node:fs`).
+ *
+ * @param absPath - Absolute path to the JSON file.
+ * @returns The validated routing map.
+ *
+ * @example
+ * ```ts
+ * import { loadRoutingFromFile } from '@takazudo/zdtp/server';
+ *
+ * const routing = loadRoutingFromFile('/abs/path/to/my.routing.json');
+ * // → { zd: 'tokens/tokens.css', ... }
+ * ```
+ */
+export declare function loadRoutingFromFile(absPath: string): ApplyRoutingMap;
+//# sourceMappingURL=load-routing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"load-routing.d.ts","sourceRoot":"","sources":["../../src/server/load-routing.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAiDpE"}

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

@@ -0,0 +1,36 @@
+export declare const CSS_VAR_NAME_RE: RegExp;
+export declare function isValidCssVarName(v: unknown): v is string;
+/**
+ * A resolved path is safe iff it sits strictly inside the write-root
+ * directory AND ends with `.css`. Cross-platform: uses `path.relative` to
+ * normalize separators and detect both escape attempts and (on Windows)
+ * different-drive resolutions. The naive `startsWith(${writeRoot}/)` check
+ * silently fails on Windows where the platform separator is a backslash.
+ *
+ * Reject conditions:
+ *   - resolvedPath does not end with `.css`
+ *   - resolvedPath equals writeRoot (relative is empty / `.`)
+ *   - relative is absolute (different drive or unrelated root on Windows)
+ *   - relative starts with `..` followed by a separator (escape) or is `..`
+ *     itself. Note that filenames such as `..hidden.css` directly under
+ *     writeRoot remain valid because `..hidden.css` is not `..` and does not
+ *     start with a separator.
+ */
+export declare function isPathSafe(writeRoot: string, resolvedPath: string): boolean;
+/**
+ * Validate the incoming `tokens` map and return a sanitized copy.
+ *
+ * - Keys must match `CSS_VAR_NAME_RE` (`--[a-zA-Z0-9_-]+`).
+ * - Values must be strings. Each value runs through `sanitizeCssValue`.
+ *   If sanitization changed the value, we still accept the sanitized form —
+ *   rejecting here would surface as a confusing 400 for callers whose color
+ *   picker briefly emits a trailing newline.
+ *
+ * Returns `{ sanitized }` on success, or `{ error }` describing the first
+ * offending key.
+ */
+export declare function validateAndSanitizeTokens(tokens: Record<string, unknown>): {
+    sanitized?: Record<string, string>;
+    error?: string;
+};
+//# sourceMappingURL=path-safety.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"path-safety.d.ts","sourceRoot":"","sources":["../../src/server/path-safety.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,eAAe,QAAuB,CAAC;AAEpD,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,MAAM,CAEzD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAO3E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAYA"}

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

@@ -0,0 +1,7 @@
+/**
+ * Serialize file writes per absolute path. Concurrent calls for the same path
+ * are chained so the next read-modify-write only starts after the previous
+ * 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/server/serialize-write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-write.d.ts","sourceRoot":"","sources":["../../src/server/serialize-write.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAa7F"}

package/dist/state/persist.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `usePersist` hook — orchestrates setState + DOM apply + localStorage write
+ * for the design-token panel. Each callback is a persist pipeline:
+ *
+ *   updater  →  setState(updater)  →  applyFullState(next)  →  savePersistedState(next)
+ *
+ * The slice-specific helpers (`persistColor`, `persistSpacing`, etc.) wrap a
+ * slice updater into a full-state updater so callers don't have to thread the
+ * whole envelope themselves.
+ *
+ * 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`.
+ */
+import { type ColorTweakState, type TabOverrides, type TokenOverrides, type TweakState } from './tweak-state';
+type SetState<T> = (updater: (prev: T | null) => T | null) => void;
+export declare function usePersist(setState: SetState<TweakState>): {
+    persist: (updater: (prev: TweakState) => TweakState) => void;
+    persistTab: (tabId: string, updater: (prev: TabOverrides) => TabOverrides) => void;
+    persistColor: (updater: (prev: ColorTweakState) => ColorTweakState) => void;
+    persistSpacing: (updater: (prev: TokenOverrides) => TokenOverrides) => void;
+    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'];
+export type PersistTab = ReturnType<typeof usePersist>['persistTab'];
+export type PersistColor = ReturnType<typeof usePersist>['persistColor'];
+export type PersistSpacing = ReturnType<typeof usePersist>['persistSpacing'];
+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/persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persist.d.ts","sourceRoot":"","sources":["../../src/state/persist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,eAAe,CAAC;AAEvB,KAAK,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;AAEnE,wBAAgB,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC;uBAE3C,CAAC,IAAI,EAAE,UAAU,KAAK,UAAU;wBAqBlC,MAAM,WAAW,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY;4BAiBnD,CAAC,IAAI,EAAE,eAAe,KAAK,eAAe;8BAO1C,CAAC,IAAI,EAAE,cAAc,KAAK,cAAc;iCAOxC,CAAC,IAAI,EAAE,cAAc,KAAK,cAAc;2BAAxC,CAAC,IAAI,EAAE,cAAc,KAAK,cAAc;2BAOxC,CAAC,IAAI,EAAE,cAAc,KAAK,cAAc;oCAOxC,CAAC,IAAI,EAAE,UAAU,CAAC,eAAe,CAAC,KAAK,UAAU,CAAC,eAAe,CAAC;gCAYlE,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,KAAK,eAAe,GAAG,SAAS;EA6B/E;AAED,MAAM,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC;AAC/D,MAAM,MAAM,UAAU,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,YAAY,CAAC,CAAC;AACrE,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,cAAc,CAAC,CAAC;AACzE,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,gBAAgB,CAAC,CAAC;AAC7E,MAAM,MAAM,iBAAiB,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,mBAAmB,CAAC,CAAC;AACnF,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAC;AAC5C,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,aAAa,CAAC,CAAC;AACvE,MAAM,MAAM,oBAAoB,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,sBAAsB,CAAC,CAAC;AACzF,MAAM,MAAM,gBAAgB,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,kBAAkB,CAAC,CAAC"}

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

@@ -0,0 +1,344 @@
+/**
+ * Tweak-state model for the design-token panel.
+ *
+ * This module owns:
+ *  - The `ColorTweakState` shape (palette + base roles + semantic mappings + shikiTheme).
+ *  - The unified `TweakState` envelope persisted under the v2 storage key.
+ *  - Pure helpers for initialising state from a scheme, applying state to the
+ *    DOM, and clearing applied inline styles.
+ *
+ * **Parameterisation — clusters come from `panelConfig`**
+ *
+ * The primary color cluster is read from the color TabConfig's colorExtras at
+ * call time, so a host that calls `configurePanel({ ..., colorCluster })`
+ * sees its own data flow through the apply / clear / load helpers without
+ * further plumbing. The package itself ships zero baked-in cluster data —
+ * a stub default lives only on `DEFAULT_PANEL_CONFIG` so the package imports
+ * cleanly when no host has yet called `configurePanel`.
+ *
+ * The cluster shape is `ColorClusterDataConfig` (re-exported here as
+ * `ColorClusterConfig` for backwards-compatibility). It is fully
+ * JSON-serializable: the palette CSS-var name is materialised at use sites
+ * by `resolvePaletteCssVar(cluster, i)`. Schemes and panel scheme settings
+ * (`panelSettings.colorScheme` + `colorMode`) live on the cluster too, so a
+ * host can swap the entire color story without editing
+ * `color-scheme-utils.ts` or `color-schemes.ts`.
+ *
+ * The secondary cluster is an opt-in field on `PanelConfig`. When the host
+ * does not configure one, the secondary slice is hidden / skipped end to end.
+ *
+ * **shikiTheme kept, applyShikiTheme stubbed**
+ *
+ * The `shikiTheme` field stays on the state + persist envelope so JSON
+ * round-tripping with external exports is seamless; the UI hides it and
+ * `applyShikiTheme` is a no-op. Removing the field would churn the serde
+ * format for no real benefit.
+ */
+import type { ColorRef, ColorScheme } from '../config/color-schemes';
+import type { TokenDef } from '../tokens/manifest';
+import { type ColorClusterDataConfig } from '../config/cluster-config';
+import { type TabOverrides } from '../apply/tier-resolver';
+export type { BaseRoleKey, ColorClusterDataConfig } from '../config/cluster-config';
+export { resolvePaletteCssVar } from '../config/cluster-config';
+export type ColorClusterConfig = ColorClusterDataConfig;
+export type { TabOverrides } from '../apply/tier-resolver';
+/**
+ * - `getStorageKeyV1()` is the original flat-state format (Color-only).
+ * - `getStorageKeyV2()` is the new namespaced format (`{ color: ..., ... }`)
+ *   that lets other tabs (Spacing, Typography, Size) add their own sub-states
+ *   without colliding with Color.
+ *
+ * On first load at v2 we migrate v1 → v2, write the new key, and delete v1.
+ *
+ * **Lazy derivation**
+ *
+ * Each helper reads `getPanelConfig()` on every call so a `configurePanel`
+ * call that lands *after* this module is imported still influences the keys
+ * the panel hits. Capturing the values at module load would freeze them
+ * before the host has a chance to configure.
+ */
+export declare function getStorageKeyV1(): string;
+export declare function getStorageKeyV2(): string;
+export declare function getStorageKeyV3(): string;
+export declare function getOpenKey(): string;
+export declare function getPositionKey(): string;
+export declare function getSizeKey(): string;
+export declare function getDensityKey(): string;
+export interface PanelPosition {
+    top: number;
+    left: number;
+}
+/**
+ * SSR-safe static fallback. Kept exported so hosts that read the constant
+ * during SSR (where `window` is undefined) still get a deterministic value.
+ * Runtime callers should prefer `defaultPosition()`, which returns a
+ * viewport-centered position when `window` is available.
+ */
+export declare const DEFAULT_POSITION: PanelPosition;
+/**
+ * Compute a viewport-centered default panel position for first-open behaviour.
+ *
+ * The panel CSS-sizes itself up to 1200×800 but caps at 80% of the viewport,
+ * so we mirror the same min/0.8x rule here. The resulting `top` / `left`
+ * place the panel at the geometric center of the viewport.
+ *
+ * Falls back to the static `DEFAULT_POSITION` when `window` is undefined
+ * (e.g. SSR / node test setup without jsdom). Real browsers + jsdom-backed
+ * tests get the centered position.
+ */
+export declare function defaultPosition(): PanelPosition;
+export declare function loadPosition(): PanelPosition;
+export declare function savePosition(pos: PanelPosition): void;
+/** Keep at least VISIBLE_MIN px of the panel on-screen so the user can grab it back. */
+export declare const VISIBLE_MIN = 60;
+export interface PanelSize {
+    width: number;
+    height: number;
+}
+/** Minimum panel size — small enough to feel snappy, large enough to keep the header + tabbar usable. */
+export declare const MIN_PANEL_WIDTH = 320;
+export declare const MIN_PANEL_HEIGHT = 240;
+/** Hard upper caps so the panel never grows past sensible bounds even before viewport clamping. */
+export declare const MAX_PANEL_WIDTH = 1600;
+export declare const MAX_PANEL_HEIGHT = 1200;
+/**
+ * SSR-safe static fallback. Matches the historical CSS expression
+ * `min(1200, 0.8 * vw)` × `min(800, 0.8 * vh)` evaluated for a 1024×768
+ * viewport so the package stays usable when imported during SSR (no
+ * window). Runtime callers should prefer `defaultSize()`.
+ */
+export declare const DEFAULT_SIZE: PanelSize;
+/**
+ * Compute the first-open panel size in px. Mirrors the historical CSS
+ * `min(1200, 0.8 * vw)` × `min(800, 0.8 * vh)` rule so existing users
+ * experience the same default size after this PR ships.
+ */
+export declare function defaultSize(): PanelSize;
+/**
+ * Clamp a `{ width, height }` against the configured min caps and the current
+ * viewport. The viewport upper bound prevents a panel saved on a 4K monitor
+ * from rendering off-screen when reopened on a 1080p laptop.
+ */
+export declare function clampSize(width: number, height: number): PanelSize;
+export declare function loadSize(): PanelSize;
+export declare function saveSize(size: PanelSize): void;
+/**
+ * User-chosen tab-grid density. Three discrete stops exposed as integers so a
+ * native `<input type="range">` slider can read/write directly:
+ *
+ *   0 = dense  — small min-card width, more columns fit on a wide panel
+ *   1 = cozy   — the auto-fit minmax default
+ *   2 = wide   — forces one column so long var names are fully readable
+ *
+ * Mapped to a CSS `min` length by `densityToGridMin()`; the resolved length is
+ * exposed on the panel shell via the `--tokenpanel-grid-min` custom property
+ * and consumed by `.tokenpanel-tab-grid` / `.tokenpanel-tab-advanced-grid`.
+ */
+export type PanelDensity = 0 | 1 | 2;
+export declare const DEFAULT_DENSITY: PanelDensity;
+export declare function densityToGridMin(density: PanelDensity): string;
+export declare function loadDensity(): PanelDensity;
+export declare function saveDensity(density: PanelDensity): void;
+export declare function clampPosition(top: number, left: number, panelWidth: number, _panelHeight: number): PanelPosition;
+/**
+ * Upstream re-highlights every `<pre>` on the page when the Shiki theme
+ * changes. This package does not use Shiki — we keep the function for
+ * API shape + persisted-state round-tripping, but the body is a no-op.
+ */
+export declare function applyShikiTheme(_themeName: string): Promise<void>;
+/** Theme list kept identical to upstream so imported state keeps its shikiTheme. */
+export declare const SHIKI_THEMES: string[];
+/**
+ * ColorTweakState — palette + base roles + semantic mappings. Shape is
+ * identical to upstream so persisted JSON can round-trip across projects.
+ *
+ * The state is palette-size agnostic (just `string[]`); the cluster config
+ * below supplies the expected length for validation + defaults.
+ */
+export interface ColorTweakState {
+    palette: string[];
+    background: number;
+    foreground: number;
+    cursor: number;
+    selectionBg: number;
+    selectionFg: number;
+    semanticMappings: Record<string, number | 'bg' | 'fg'>;
+    shikiTheme: 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
+ * the map — absent keys mean "use the stylesheet default".
+ */
+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.
+ *
+ * `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`/
+ * `typography`/`size` slices are retained for internal back-compat until Wave 5
+ * migrates those dedicated tab components to consume `TabConfig.tiers` directly.
+ */
+export interface TweakState {
+    color: ColorTweakState;
+    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>;
+}
+/** Produce an empty overrides map — `TweakState` default for new tabs. */
+export declare function emptyOverrides(): TokenOverrides;
+/**
+ * Resolve the active primary color cluster from the panel config's tabs.
+ * Returns the stub cluster when no color tab is configured.
+ */
+export declare function getActivePrimaryCluster(cfg?: import("..").PanelConfig): ColorClusterDataConfig;
+/**
+ * Produce a fresh `ColorTweakState` for a secondary color cluster.
+ * Generalises the no-scheme seed path: the palette length, semantic
+ * defaults, and shikiTheme all derive from the supplied cluster, so any
+ * host-supplied secondary cluster (any paletteSize, any semantic
+ * vocabulary) gets a deterministic neutral grayscale seed when the cluster
+ * does not ship its own scheme registry.
+ *
+ * Palette seed strategy:
+ *  - Synthesise a deterministic neutral grayscale palette of
+ *    `cluster.paletteSize` slots. Index 0 → black, last → white, middle
+ *    slots interpolate. Functional but visually flat; hosts wanting a
+ *    designed seed should ship a scheme registry on the cluster and call
+ *    `initColorFromScheme(cluster)` instead.
+ *
+ * The base-role indices are kept on the state shape for envelope-round-trip
+ * compatibility but are inert — `applyColorState` only writes a base role
+ * when the cluster declares the corresponding `baseRoles` entry.
+ */
+export declare function initSecondaryDefaults(cluster: ColorClusterDataConfig): ColorTweakState;
+/**
+ * Convenience helper used by `panel.tsx` and tests: seed a fresh secondary
+ * `ColorTweakState` from the active panel config's secondary cluster.
+ * Returns `undefined` when the host opted out of the secondary cluster
+ * (`secondaryColorCluster: null` or omitted).
+ */
+export declare function initSecondaryFromConfig(): ColorTweakState | undefined;
+export declare function cssColorToHex(color: string): string;
+export declare function setCssVar(name: string, value: string): void;
+/**
+ * Resolve a `ColorRef` to a palette index. If it's already a number, use it.
+ * If it's a string, find an exact palette match or the nearest color by RGB
+ * distance. `fallback` is returned only when `ref` is undefined.
+ */
+export declare function colorRefToIndex(ref: ColorRef | undefined, palette: string[], fallback: number): number;
+/**
+ * Resolve the active scheme name for the given cluster, considering
+ * light/dark mode. Reads `panelSettings` from the cluster so a
+ * host-supplied cluster can declare its own scheme + light/dark pairing
+ * without editing the panel package.
+ */
+export declare function getActiveSchemeName(cluster?: ColorClusterDataConfig): string;
+/**
+ * Initialise a `ColorTweakState` from the active color scheme for the given
+ * cluster. Defaults to the host's primary cluster (derived from the color
+ * TabConfig).
+ *
+ * Reads the scheme registry from `cluster.colorSchemes`. Clusters that ship
+ * no schemes should not call this directly — they use
+ * `initSecondaryDefaults(cluster)` instead because there is no scheme to
+ * seed from.
+ */
+export declare function initColorFromScheme(cluster?: ColorClusterDataConfig): ColorTweakState;
+export declare function initColorFromSchemeData(scheme: ColorScheme, cluster?: ColorClusterDataConfig): ColorTweakState;
+/** Resolve a semantic mapping to an actual color (bounds-checked). */
+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): void;
+/**
+ * Apply a `TokenOverrides` map for a given manifest — writes inline
+ * `--css-var: value` on `:root` for every overridden token, and removes the
+ * inline property for tokens absent from the map (so the stylesheet default
+ * comes back).
+ *
+ * Read-only tokens are skipped in both directions: they are informational rows
+ * in the UI and are never written to storage.
+ */
+export declare function applyTokenOverrides(tokens: readonly TokenDef[], overrides: TokenOverrides): void;
+/**
+ * Apply the full unified `TweakState` — primary color cluster + token
+ * overrides + optional secondary cluster.
+ *
+ * Tab configs AND the primary color cluster are read from `panelConfig`
+ * at call time so a host that calls `configurePanel` before mount sees its
+ * own data driving the apply pass.
+ */
+export declare function applyFullState(state: TweakState): void;
+/**
+ * Strip all tweak-applied inline CSS variables so the stylesheet-provided
+ * values from the active scheme take effect again.
+ *
+ * Accepts an optional list of clusters so callers can scope the wipe to a
+ * subset; the default wipes both the primary and secondary clusters so a
+ * panel-level reset leaves no stale inline overrides on `:root` regardless
+ * of which cluster was last edited.
+ */
+export declare function clearAppliedStyles(clusters?: readonly ColorClusterDataConfig[]): void;
+/**
+ * Test-friendly migration entry point. Reads from a provided storage (defaults
+ * to `localStorage`) and returns the loaded+migrated `TweakState`, or `null`
+ * when no usable state exists.
+ *
+ * Rules:
+ *  1. If v2 key exists and parses → use it (v2 wins).
+ *  2. Else if v1 key exists → parse with safe defaults, lift into `state.color`,
+ *     write v2, delete v1.
+ *  3. Else → return null (caller initialises from the active scheme).
+ *
+ * Malformed JSON is caught with `console.warn` and returns null (caller falls
+ * back to fresh defaults).
+ */
+export interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Legacy zdtp-internal typography rename map — opt-in via
+ * `PanelConfig.legacyIdRenameMap`.
+ *
+ * An earlier zdtp-internal port step renamed the font-size manifest ids from
+ * panel-internal labels (`text-caption`, `text-small`, `text-body`,
+ * `text-subheading`, `text-heading`, `text-display`) to main-site Tailwind
+ * tiers (`text-xs`, `text-sm`, `text-base`, `text-lg`, `text-3xl`,
+ * `text-5xl`), and dropped `text-micro` entirely (no main-site equivalent
+ * exists). This map preserves persisted user tweaks across that one-time
+ * rename — including the drop of `text-micro` (`null` value) — for callers
+ * that opt in.
+ *
+ * Critically, this map is NOT applied by default any more (see issue #51):
+ * hosts whose canonical manifest ids share names with these "old" labels —
+ * e.g. `zudo-doc`, where `text-caption` IS the stable id — were having
+ * their valid overrides remapped to non-existent ids and silently dropped.
+ * The default `loadPersistedState` path now applies an empty rename map.
+ *
+ * The `text-micro: null` entry exists because dropping is the only way to
+ * keep an obsolete legacy id from persisting indefinitely as dead
+ * localStorage data: `applyTokenOverrides` silently ignores unknown ids,
+ * but every save round-trips the dead key back to disk.
+ *
+ * Spacing + size manifest ids were NOT renamed (hsp-/vsp- ids kept their
+ * labels), so this migration only applies to the typography slice.
+ */
+export declare const ZDTP_LEGACY_TYPOGRAPHY_RENAME_MAP: Readonly<Record<string, string | null>>;
+export declare function loadPersistedState(storage?: StorageLike, colorDefaults?: ColorTweakState, cluster?: ColorClusterDataConfig): TweakState | null;
+/** Persist the full `TweakState` to v3. */
+export declare function savePersistedState(state: TweakState, storage?: StorageLike): void;
+/** Remove v3 (and lingering v2/v1) keys. */
+export declare function clearPersistedState(storage?: StorageLike): void;
+//# sourceMappingURL=tweak-state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tweak-state.d.ts","sourceRoot":"","sources":["../../src/state/tweak-state.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,23 @@
+/**
+ * GenericItemEditor — dispatches to the right control for a TierItem based on
+ * `item.type.kind`. Used by SpacingTab, FontTab, and SizeTab to render
+ * non-reference items with the appropriate editor.
+ *
+ * For pill items (item.pill is set), a pill toggle is rendered above the
+ * number input row — matching the PillSliderRow behaviour from the legacy
+ * size tab, but without a range slider (sliders need meaningful min/max which
+ * token manifests may not always define well).
+ *
+ * This is an internal helper; not exported from the package index.
+ */
+import type { TierItem } from '../tokens/tier-model';
+export interface GenericItemEditorProps {
+    item: TierItem;
+    value: string;
+    /** Called with (itemId, newValue). */
+    onChange: (itemId: string, next: string) => void;
+}
+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