@takazudo/zdtp 0.1.0-next.0

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

@@ -0,0 +1,81 @@
+/**
+ * Pure, IO-free CSS custom-property value replacement.
+ *
+ * `applyTokenOverrides(source, overrides)` rewrites the values of one or more
+ * CSS custom properties inside the FIRST top-level `:root { ... }` block of a
+ * CSS file, preserving surrounding whitespace and trailing inline comments.
+ * The module is the regex foundation that the dev-API endpoint
+ * wraps; it performs no IO, no DOM access, and is safe to import in any
+ * environment.
+ *
+ * Behavior summary
+ * ----------------
+ * - Only the FIRST top-level `:root { ... }` block is modified. Tokens inside
+ *   `@media`, `@layer`, `@supports`, or nested `:root` blocks are IGNORED.
+ * - Per-cssVar regex: `(--name:)\s*([\s\S]+?);` with the name regex-escaped.
+ *   The non-greedy value capture stops at the first `;`, which preserves any
+ *   trailing `/​* ... *​/` inline comment on the same logical line.
+ * - A whitespace-trimmed comparison between the old value and the override
+ *   decides whether the cssVar lands in `changed` or `unchanged`.
+ * - Idempotent: applying the same overrides twice in a row reports every key
+ *   as `unchanged` on the second call and produces byte-identical output.
+ *
+ * Known limitations (if a richer transform is ever needed, swap this module
+ * for a real CSS parser such as postcss):
+ * - Only `:root` as a bare selector is recognized. Grouped selectors such as
+ *   `:root, html { ... }` are NOT treated as a `:root` block.
+ * - Nested `:root` under `@media` / `@layer` / `@supports` is intentionally
+ *   skipped; see the test matrix in the companion `__tests__` file.
+ * - Values containing a literal `;` inside a string or comment would confuse
+ *   the non-greedy regex. Not supported.
+ * - If the same cssVar is declared multiple times in the top-level `:root`
+ *   block, only the FIRST occurrence is rewritten.
+ */
+export interface ApplyResult {
+    /** The new CSS file contents (byte-identical to `source` when nothing
+     *  changed, including the "no :root block" case). */
+    updated: string;
+    /** cssVar names actually rewritten (trimmed new value differs from old). */
+    changed: string[];
+    /** cssVar names present in the file whose trimmed value already matched
+     *  the override. */
+    unchanged: string[];
+    /** cssVar names in `overrides` that were not found in the first top-level
+     *  `:root` block (either because the name is absent, or because no
+     *  top-level `:root` block exists). */
+    unknown: string[];
+}
+/**
+ * Thrown by {@link applyTokenOverridesOrThrow} when the source has no
+ * top-level `:root { ... }` block. Lets the dev-API handler surface a
+ * diagnostic message without having to probe the result shape.
+ */
+export declare class NoRootBlockError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Rewrite `overrides` into the first top-level `:root { ... }` block of
+ * `source` and return an {@link ApplyResult} describing the outcome.
+ *
+ * If `source` has no top-level `:root` block, the function returns
+ * `source` unchanged with every key routed to `unknown` — the companion
+ * {@link applyTokenOverridesOrThrow} raises {@link NoRootBlockError} in
+ * that case so callers that need a hard failure can distinguish it from a
+ * block where merely none of the overrides matched.
+ */
+export declare function applyTokenOverrides(source: string, overrides: Record<string, string>): ApplyResult;
+/**
+ * Throwing variant. Same shape as {@link applyTokenOverrides} except it
+ * raises {@link NoRootBlockError} when no top-level `:root { ... }` block
+ * exists, instead of returning every override under `unknown`. Use this from
+ * server-side handlers where "no :root block" is a fatal configuration
+ * problem rather than an expected state.
+ */
+export declare function applyTokenOverridesOrThrow(source: string, overrides: Record<string, string>): ApplyResult;
+/**
+ * Low-level predicate exposed primarily for callers that want to report a
+ * precise diagnostic without running a full rewrite. Returns `true` iff the
+ * 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/apply-token-overrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-token-overrides.d.ts","sourceRoot":"","sources":["../../src/apply/apply-token-overrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,MAAM,WAAW,WAAW;IAC1B;yDACqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;wBACoB;IACpB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB;;2CAEuC;IACvC,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,SAAwD;CAK5E;AAyOD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,WAAW,CA4Bb;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,WAAW,CAMb;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAE5D"}

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

@@ -0,0 +1,71 @@
+/**
+ * Build the flat `{ cssVarName: cssValue }` diff consumed by the host's
+ * Apply endpoint (e.g. a dev-API route that POSTs the diff to the panel
+ * server).
+ *
+ * Consumes the `TweakState` shape directly:
+ *
+ * Color tokens:
+ *   - `state.color.palette: string[]` — palette hex values
+ *   - `state.color.semanticMappings: Record<string, number | 'bg' | 'fg'>` —
+ *     semantic-token → palette-index map
+ *   - `state.color.background` / `foreground` — palette indices used when a
+ *     semantic mapping is `"bg"` / `"fg"` respectively
+ *
+ * Non-color tokens (spacing / typography / size including radius):
+ *   - `state.spacing: TokenOverrides` — keyed by token id (e.g. `hsp-md`)
+ *   - `state.typography: TokenOverrides` — keyed by token id (e.g. `text-base`)
+ *   - `state.size: TokenOverrides` — keyed by token id (e.g. `radius-lg`)
+ *
+ * The routing layer (`route-tokens-to-files.ts`) then splits the map into
+ * per-file groups. The host (or the deferred bin) applies each group to
+ * its target `.css` file.
+ *
+ * Scope
+ * -----
+ * Only cssVars that the cluster's or tabs' CSS files actually declare are emitted.
+ * Specifically:
+ *
+ *   - Palette slots (resolved via `resolvePaletteCssVar(cluster, i)`) —
+ *     EMITTED as hex values.
+ *   - Semantic tokens (`cluster.semanticCssNames` entries) — EMITTED as
+ *     `var(--<paletteSlotName>)` so the rewrite preserves the indirection
+ *     that the hand-authored CSS relies on.
+ *   - 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
+ *     `TokenOverrides` map is non-empty. Values are resolved through the
+ *     tier resolver so reference tiers emit `var(--targetCssVar)` rather
+ *     than the raw item id string. Readonly items are skipped.
+ *
+ * Diff-only output
+ * ----------------
+ * For color tokens, a cssVar is emitted ONLY when the current state differs
+ * from the provided baseline. Callers without a baseline (tests,
+ * degraded-init paths) can pass `colorDefaults: undefined`; in that case the
+ * whole color block is treated as changed.
+ *
+ * For non-color tokens, `TokenOverrides` is already a sparse diff (only
+ * overridden tokens appear in the map) — no baseline comparison is needed.
+ *
+ * Pure / no IO — safe to import anywhere (browser, Node, tests).
+ */
+import type { ColorTweakState, TweakState, ColorClusterConfig } from '../state/tweak-state';
+import type { TabConfig } from '../tokens/tier-model';
+/**
+ * Produce the flat cssVar → value map for the dev-API handler.
+ *
+ * `colorDefaults` should be the scheme baseline the UI diffs against (the
+ * same baseline the panel passes to the Export / Import modals). Pass
+ * `undefined` to force the whole color block into the output.
+ *
+ * `cluster` defaults to the primary color cluster derived from the active
+ * panel config's color TabConfig so primary-cluster callers do not have to
+ * thread the active cluster through every layer. Secondary-cluster callers
+ * MUST pass an explicit cluster argument.
+ *
+ * `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.
+ */
+export declare function buildApplyOverrides(state: TweakState, colorDefaults: ColorTweakState | undefined, cluster?: ColorClusterConfig, tabs?: readonly TabConfig[]): Record<string, string>;
+//# sourceMappingURL=build-apply-overrides.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build-apply-overrides.d.ts","sourceRoot":"","sources":["../../src/apply/build-apply-overrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE5F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAItD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,aAAa,EAAE,eAAe,GAAG,SAAS,EAC1C,OAAO,GAAE,kBAA8C,EACvD,IAAI,GAAE,SAAS,SAAS,EAA0B,GACjD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA2DxB"}

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

@@ -0,0 +1,65 @@
+/**
+ * Token-to-file routing — pure grouping module.
+ *
+ * Given a map of cssVar overrides (e.g. from the tweak state's serialized
+ * form), split the entries by target source file so the dev-API handler can
+ * call the rewriter once per file. The prefix → file map is supplied by the
+ * caller (typically read from `panelConfig.applyRouting`) — the package
+ * ships zero baked-in routing defaults; hosts MUST configure their own.
+ *
+ * Anything that does NOT look like a `--<prefix>-...` cssVar, OR whose prefix
+ * has no entry in the supplied routing map, lands in `rejected`. The caller
+ * surfaces those (e.g. as a non-empty `rejected[]` field on the apply
+ * response) so silent drops become visible.
+ *
+ * No IO, no DOM, no Node-specific imports — safe to bundle for the browser.
+ */
+import type { ApplyRoutingMap } from '../config/panel-config';
+/**
+ * Prefix-family identifier. Plain string — the routing map is host-supplied.
+ */
+export type TokenPrefix = string;
+export interface RouteGroup {
+    /** Which prefix family these tokens belong to. */
+    prefix: string;
+    /** Repo-relative path of the source CSS file the rewriter should edit. */
+    relativePath: string;
+    /** Ordered map of cssVar → value. Insertion order follows the input. */
+    tokens: Record<string, string>;
+}
+export interface RouteResult {
+    /** At most one group per prefix. Empty when every entry was rejected. */
+    groups: RouteGroup[];
+    /** cssVar names whose prefix is not supported. */
+    rejected: string[];
+    /**
+     * Diagnostic messages explaining each rejection. Same length as `rejected`,
+     * indexed in lockstep. Hosts surface these in the UI so silent drops
+     * become visible.
+     */
+    rejectedReasons: string[];
+}
+/**
+ * Empty default routing — the package ships no baked-in prefix → file map.
+ * Hosts MUST supply `panelConfig.applyRouting` (or pass an explicit map to
+ * `routeTokensToFiles`) for the apply pipeline to do anything; without it,
+ * every entry lands in `rejected` with a clear diagnostic.
+ */
+export declare const TOKEN_SOURCE_FILES: Readonly<ApplyRoutingMap>;
+/**
+ * Split `overrides` into per-file groups plus a rejected list.
+ *
+ * - Groups are emitted in `Object.keys(routing)` order.
+ * - Tokens within a group preserve the input's insertion order.
+ * - A group is only emitted when it has at least one token.
+ * - `rejected` preserves the input's insertion order, with a parallel
+ *   `rejectedReasons` array describing why each entry failed.
+ *
+ * @param overrides - Flat cssVar → value map.
+ * @param routing - Prefix → repo-relative path map (typically from
+ *   `panelConfig.applyRouting`). When omitted or empty, every entry lands in
+ *   `rejected` so callers surface a clear "apply not configured" error
+ *   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/route-tokens-to-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-tokens-to-files.d.ts","sourceRoot":"","sources":["../../src/apply/route-tokens-to-files.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC;AAEjC,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;;OAIG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,eAAe,CAAqB,CAAC;AAyB/E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,OAAO,GAAE,eAAoC,GAC5C,WAAW,CAyCb"}

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

@@ -0,0 +1,75 @@
+/**
+ * Cross-tier reference resolver and CSS value emitter.
+ *
+ * Pure module — no DOM, no Preact, no IO. Safe to import in any environment.
+ *
+ * ## TabOverrides shape
+ *
+ * `TabOverrides` is a two-level nested map:
+ *
+ *   tierId → itemId → overrideValue (CSS string)
+ *
+ * Example:
+ *   {
+ *     raw:      { 'ease-in': 'cubic-bezier(0.42,0,1,1)' },
+ *     semantic: { 'tab-open': 'ease-in' },  // ref value — points at a raw item id
+ *   }
+ *
+ * For a literal tier (no referencesTier) the value is the CSS string to emit.
+ * For a reference tier (referencesTier is set) the value is the id of a target
+ * item in the named tier.
+ */
+import type { TabConfig } from '../tokens/tier-model';
+export type TabOverrides = Readonly<Record<string, Readonly<Record<string, string>>>>;
+export declare class TierResolverError extends Error {
+    constructor(message: string);
+}
+export type ResolvedLiteral = {
+    kind: 'literal';
+    value: string;
+};
+export type ResolvedRef = {
+    kind: 'ref';
+    targetCssVar: string;
+};
+export type ResolvedTierItem = ResolvedLiteral | ResolvedRef;
+/**
+ * Resolve the effective CSS value for a single tier item.
+ *
+ * For literal tiers (no `referencesTier`):
+ *   Returns { kind: 'literal', value } where value is the override string
+ *   or the item's `default`.
+ *
+ * For reference tiers (`referencesTier` is set):
+ *   The override value is interpreted as an item id in the referenced tier.
+ *   Returns { kind: 'ref', targetCssVar } pointing at the referenced item's
+ *   cssVar so callers can emit `var(--targetCssVar)`.
+ *
+ * Pill semantics:
+ *   When a literal-tier item has a `pill` spec and the override value equals
+ *   `pill.value`, the pill value is returned verbatim (the pill toggle is ON).
+ *   When the override is absent but the item has a pill, `pill.customDefault`
+ *   is used as the baseline (not the item's `default`). The item's `default`
+ *   is used only when neither an override nor a pill customDefault apply.
+ *
+ * Error cases (throw TierResolverError):
+ *   - tierId not found in tab.tiers
+ *   - referencesTier id not found in tab.tiers
+ *   - ref override points at a tier other than the one declared in referencesTier
+ *     (guarded by design: the resolver validates the target tier id)
+ *
+ * Fallback case (no error):
+ *   - ref override id not found in the target tier → falls back to the target
+ *     tier's item whose id matches itemId; if that also doesn't exist, falls
+ *     back to the first item's default.
+ */
+export declare function resolveTierItemValue(tab: TabConfig, tierId: string, itemId: string, overrides: TabOverrides): ResolvedTierItem;
+/**
+ * Convert a resolved tier item into the final CSS value string to write into
+ * a CSS custom property.
+ *
+ * - Literal → returns the value as-is (e.g. `1.25rem`).
+ * - Ref     → returns `var(--targetCssVar)` (e.g. `var(--zfb-easing-ease-in)`).
+ */
+export declare function emitTierItemCssValue(resolved: ResolvedTierItem): string;
+//# sourceMappingURL=tier-resolver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tier-resolver.d.ts","sourceRoot":"","sources":["../../src/apply/tier-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAwB,MAAM,sBAAsB,CAAC;AAE5E,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAMtF,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAK5B;AAMD,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AACjE,MAAM,MAAM,WAAW,GAAG;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAChE,MAAM,MAAM,gBAAgB,GAAG,eAAe,GAAG,WAAW,CAAC;AAkB7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,YAAY,GACtB,gBAAgB,CAwElB;AAMD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAGvE"}

package/dist/apply-modal.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Apply modal — previews the diff between the current `TweakState` and the
+ * scheme defaults, then POSTs the diff to the dev-only
+ * `/api/dev/design-tokens-apply` endpoint so the tweaks are written back
+ * into the host's design-system CSS files on disk.
+ *
+ * Wiring summary
+ * --------------
+ * - Diff building is delegated to `./apply/build-apply-overrides`, which
+ *   consumes the new `ColorTweakState` shape (palette + semanticMappings) and
+ *   emits the flat `{ cssVar: value }` map using `SEMANTIC_CSS_NAMES`.
+ * - Per-file grouping (for the preview and for the success view) uses
+ *   `./apply/route-tokens-to-files` — the exact same routing the dev-API
+ *   handler runs server-side, so the preview matches the server's view of
+ *   the world byte-for-byte.
+ * - Styling uses bundled BEM classes derived from
+ *   `panelConfig.modalClassPrefix` via `modalClass(...)`. The matching CSS
+ *   lives in `styles/panel.css` keyed on the default modal class prefix;
+ *   consumers that override the prefix opt out of bundled CSS and ship
+ *   their own. No Tailwind classes remain.
+ *
+ * Dialog lifecycle (unchanged)
+ * ----------------------------
+ * Uses the native `<dialog>` element. Every dismissal path (× / backdrop /
+ * Escape / programmatic close) routes through `dialog.close()`, which fires
+ * the native `close` event exactly once; `onClose` then fires exactly once
+ * per dismissal regardless of the path taken.
+ */
+import { type ColorTweakState, type TweakState } from './state/tweak-state';
+export interface ApplyModalProps {
+    state: TweakState;
+    open: boolean;
+    onClose: () => void;
+    /**
+     * Scheme baseline used to diff the current `state.color` against when
+     * computing the flat cssVar overrides. When absent, the entire color block
+     * is treated as changed — useful for tests, but real callers (the panel
+     * itself) always pass the active scheme's initial `ColorTweakState`.
+     */
+    colorDefaults?: ColorTweakState;
+    /**
+     * Fired exactly once after the user confirms a successful apply by clicking
+     * "Done". The parent is expected to clear the persisted state envelope,
+     * clear any inline-applied styles, and reset in-memory state to empty.
+     */
+    onApplied: () => void;
+}
+export declare function ApplyModal(props: ApplyModalProps): import("preact").JSX.Element;
+//# sourceMappingURL=apply-modal.d.ts.map

package/dist/apply-modal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-modal.d.ts","sourceRoot":"","sources":["../src/apply-modal.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAWH,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAK5E,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,UAAU,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,eAAe,CAAC;IAChC;;;;OAIG;IACH,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB;AAmJD,wBAAgB,UAAU,CAAC,KAAK,EAAE,eAAe,gCA0YhD"}

package/dist/astro/DesignTokenPanelHost.astro

@@ -0,0 +1,76 @@
+---
+/**
+ * Astro entry point for the design-token panel.
+ *
+ * Drop into a layout once. The component AND the host-adapter side-effect
+ * import are a paired unit — both lines are required, always together:
+ *
+ * ```astro
+ * ---
+ * import { DesignTokenPanelHost } from '@takazudo/zdtp/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';
+ * ---
+ * <DesignTokenPanelHost config={panelConfig} />
+ * <script>
+ *   // Required side-effect import for the host adapter. The package's
+ *   // distributed Astro surface ships built `dist/astro/*` files, and the
+ *   // package-side hoisted <script> from those built files does not reliably
+ *   // reach production page bundles. Owning the script import in the
+ *   // consumer wrapper sidesteps that pipeline issue. The package's
+ *   // `package.json` lists `dist/astro/host-adapter.js` in `sideEffects` so
+ *   // Rollup preserves the consumer-side import regardless of whether its
+ *   // result is used. The dynamic `void import(...)` form is the recommended
+ *   // canonical wiring because it loads the host-adapter chunk off the
+ *   // critical path.
+ *   void import('@takazudo/zdtp/astro/host-adapter');
+ * </script>
+ * ```
+ *
+ * The component renders ONE inline `<script type="application/json">` block
+ * carrying the serialised `PanelConfig`; the host adapter (loaded via the
+ * consumer-owned import above) reads it by id at module init.
+ *
+ * History — why the host-adapter import lives in the consumer wrapper:
+ * a previous shape emitted a sibling `<script>import './host-adapter';</script>`
+ * block. Vite/Rollup processed that block, recognised the import as
+ * resolving to a sibling JS file outside the consumer's source tree,
+ * emitted an empty chunk, and never linked it from any page entry. The
+ * result was a silent runtime ReferenceError on production builds. Moving
+ * the import into the consumer wrapper hands bundling responsibility to
+ * the consumer's own Astro toolchain, which produces a real chunk that
+ * lands in the page entry.
+ *
+ * Why inline JSON instead of `define:vars` or `set:html` of a JS literal?
+ * `<script type="application/json">` is not parsed as JavaScript by the HTML
+ * parser, so we can serialise arbitrary user-supplied data without an XSS
+ * surface or escaping gymnastics — provided we close-tag-escape strings
+ * (`</` → `<\/`) defensively.
+ */
+
+import type { PanelConfig } from '../config/panel-config';
+
+export interface Props {
+  config: PanelConfig;
+}
+
+const { config } = Astro.props;
+
+// Defensive escape: any literal `<` inside a string field could let the HTML
+// parser see `</script>` or `<!--` and either close the surrounding script
+// element or enter the script-data-escaped state. JSON.stringify does not
+// escape `<` — so we replace every `<` with the JSON unicode escape
+// `<`. The browser's HTML parser sees only the literal characters
+// `\`, `u`, `0`, `0`, `3`, `c` (no `<`), and JSON.parse on the consumer side
+// decodes `<` back to `<`. Targeted replacements like
+// `</script` → `<\/script` work for the close-tag case but `<!--` → `<\!--`
+// produces an invalid JSON escape (`\!` is not in the JSON spec) and
+// JSON.parse rejects it. The unicode-escape sweep is robust against both.
+// See https://html.spec.whatwg.org/multipage/scripting.html#restrictions-for-contents-of-script-elements
+const configJson = JSON.stringify(config).replace(/</g, '\\u003c');
+---
+
+<script type="application/json" id="tokenpanel-config" set:html={configJson} />

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

@@ -0,0 +1,47 @@
+/**
+ * Astro host adapter.
+ *
+ * Loaded by `DesignTokenPanelHost.astro` via a per-page `<script>` block.
+ * Responsibilities:
+ *
+ *  1. Read the JSON config inlined by the Astro component (a
+ *     `<script type="application/json" id="tokenpanel-config">` element).
+ *  2. Call `configurePanel(parsedConfig)` BEFORE the lazy-load probes run, so
+ *     every downstream `getPanelConfig()` reader (storage keys, console
+ *     namespace, modal class prefix, …) sees the host's intended values.
+ *  3. Install the console API on `window[config.consoleNamespace]`
+ *     (`showDesignPanel` / `hideDesignPanel` / `toggleDesignPanel`). The
+ *     namespace is a configured field — different consumers can pick
+ *     distinct values to prove the contract is host-agnostic.
+ *  4. Gate the panel module's dynamic import on the same probes the legacy
+ *     host script used: an existing `wasVisible()` flag or any persisted v2
+ *     overrides. When neither is set, the panel module stays out of the
+ *     initial bundle and only loads when the user calls a `window.<ns>.*`
+ *     helper from the console.
+ *
+ * Idempotency
+ * -----------
+ * The Astro `<script>` re-executes on view-transition (`astro:before-swap` /
+ * `astro:page-load`) — the consumer-side bundler emits one script per page
+ * and Astro's view-transition runtime re-runs it. We pin a window-scoped
+ * flag derived from the configured `storagePrefix` so subsequent runs short-
+ * circuit. (The panel module owns its own view-transition listener
+ * lifecycle internally; this flag is only about *adapter*-level state.)
+ *
+ * Singleton sharing
+ * -----------------
+ * `configurePanel` mutates a module-level singleton in
+ * `../config/panel-config.ts`. The dynamic import below resolves through the
+ * package's exports map back to the lib bundle's `dist/index.js`, which
+ * imports from the same `panel-config` chunk that this adapter imports —
+ * Vite's multi-entry build code-splits shared modules into a single chunk so
+ * both surfaces observe one and the same singleton. Without that property,
+ * the adapter's `configurePanel` call would not be visible to the panel.
+ *
+ * NOTE: This file is a sibling of `index.ts`; both compile under the
+ * `astro/*` entry tree of `vite.config.ts`. It is consumed only by the
+ * Astro toolchain on the consumer side (via the `<script>` import in
+ * `DesignTokenPanelHost.astro`), never by the lib bundle's `index.ts`.
+ */
+export {};
+//# sourceMappingURL=host-adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host-adapter.d.ts","sourceRoot":"","sources":["../../src/astro/host-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG"}

package/dist/astro/host-adapter.js

@@ -0,0 +1,81 @@
+import { c as u, g as l, a as f, b as p, d as h, e as m } from "../panel-config-DP2_P7dD.js";
+import { Z as w } from "../tweak-state-DSJa5csL.js";
+const r = "tokenpanel-config";
+function P() {
+  if (typeof document > "u")
+    throw new Error(
+      "[design-token-panel] host-adapter loaded without a document; expected to run in a browser context."
+    );
+  const e = document.getElementById(r);
+  if (!e)
+    throw new Error(
+      `[design-token-panel] Inline config script #${r} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
+    );
+  const o = e.textContent ?? "";
+  let n;
+  try {
+    n = JSON.parse(o);
+  } catch (t) {
+    throw new Error(
+      `[design-token-panel] Failed to parse inline config from #${r}: ${t.message}`
+    );
+  }
+  return m(n), n;
+}
+function y(e) {
+  return e.__zudoDesignTokenPanelAdapter || (e.__zudoDesignTokenPanelAdapter = {}), e.__zudoDesignTokenPanelAdapter;
+}
+function _(e, o) {
+  const n = y(e);
+  let t = n[o];
+  return t || (t = { bound: !1, modulePromise: null }, n[o] = t), t;
+}
+function k(e) {
+  try {
+    return window.localStorage.getItem(e) === "1";
+  } catch {
+    return !1;
+  }
+}
+function b(e, o) {
+  try {
+    const n = window.localStorage;
+    return n.getItem(o) !== null || n.getItem(e) !== null;
+  } catch {
+    return !1;
+  }
+}
+async function i(e) {
+  return e.modulePromise === null && (e.modulePromise = import("@takazudo/zdtp").then((o) => {
+    try {
+      const n = l(), t = o.__panelConfigForTest();
+      n !== t && console.warn(
+        "[design-token-panel] Singleton-sharing check failed: the host adapter and the panel module observed different PanelConfig singletons. This indicates the package's `config/panel-config` module is no longer code-split into a single shared chunk. The panel may behave correctly today, but storage keys / namespaces / branding could diverge between the two surfaces in future bundles."
+      );
+    } catch (n) {
+      console.warn(
+        "[design-token-panel] Singleton-sharing check could not run (likely an older dist without the __panelConfigForTest accessor): " + n.message
+      );
+    }
+    return o;
+  })), e.modulePromise;
+}
+function T(e, o, n) {
+  const t = e[o] ?? {};
+  t.showDesignPanel = async () => {
+    (await i(n)).showDesignTokenPanel();
+  }, t.hideDesignPanel = async () => {
+    (await i(n)).hideDesignTokenPanel();
+  }, t.toggleDesignPanel = async () => {
+    (await i(n)).toggleDesignPanel();
+  }, e[o] = t;
+}
+(function() {
+  const o = P(), n = o.legacyIdRenameMap ? o : { ...o, legacyIdRenameMap: { ...w } };
+  u(n);
+  const t = l(), a = window, s = _(a, t.storagePrefix);
+  if (T(a, t.consoleNamespace, s), s.bound) return;
+  s.bound = !0;
+  const c = f(t), d = p(t), g = h(t);
+  (k(c) || b(d, g)) && i(s);
+})();

package/dist/astro/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Astro sub-export entry.
+ *
+ * Consumers import the host component via:
+ *
+ * ```astro
+ * import { DesignTokenPanelHost } from '@takazudo/zdtp/astro';
+ * ```
+ *
+ * The named-export pattern is preserved verbatim through the lib build:
+ * `vite.config.ts` marks `*.astro` external (regex) so Vite leaves the
+ * `from './DesignTokenPanelHost.astro'` literal in `dist/astro/index.js`,
+ * and a postbuild copy step (`scripts/copy-astro-assets.mjs`) places the
+ * raw `.astro` file alongside it. The consumer's own Astro toolchain then
+ * resolves the relative path at build time.
+ *
+ * `PanelConfig` is re-exported here so callers don't need a deep
+ * `@takazudo/zdtp/dist/config/panel-config` import to
+ * type their config object.
+ */
+export { default as DesignTokenPanelHost } from './DesignTokenPanelHost.astro';
+export type { PanelConfig } from '../config/panel-config';
+export type { ColorScheme, ColorRef } from '../config/color-schemes';
+export type { ColorClusterConfig } from '../state/tweak-state';
+export { setPanelColorPresets } from '../config/panel-config';
+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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/astro/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,OAAO,IAAI,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAC/E,YAAY,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1D,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGrE,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAI/D,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAK9D,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAKvD,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAKvG,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACnG,YAAY,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}