@takazudo/zdtp 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.4.5
+
+### Features
+
+- Per-scheme/per-mode keyed color persistence — envelope v4 ([#509](https://github.com/Takazudo/zudo-design-token-panel/issues/509)) (653c4ab)
+- Distinguish declared-outside-scanned-block from genuinely-absent unknowns ([#508](https://github.com/Takazudo/zudo-design-token-panel/issues/508)) (441fa93)
+- Scan top-level `@theme` blocks in `applyTokenOverrides` ([#507](https://github.com/Takazudo/zudo-design-token-panel/issues/507)) (d6c6692)
+- Add `colorExtras.semanticDefaults` config-time override map ([#499](https://github.com/Takazudo/zudo-design-token-panel/issues/499)) (543136e)
+
+### Fixed
+
+- Harden v4 persistence load edge cases ([#509](https://github.com/Takazudo/zudo-design-token-panel/issues/509) audit, epic [#502](https://github.com/Takazudo/zudo-design-token-panel/issues/502) review) (2b07460)
+- Scope color-scheme clearing to panel-written values (closes [#506](https://github.com/Takazudo/zudo-design-token-panel/issues/506)) (f434c8c)
+- Validate persisted semantic index mappings against live cluster paletteSize ([#503](https://github.com/Takazudo/zudo-design-token-panel/issues/503)) (915ffbf)
+
+### Other Changes
+
+- docs: sync README + doc-site with `@theme` apply, v4 persistence, schemaId ([#511](https://github.com/Takazudo/zudo-design-token-panel/issues/511)) (3c3fd57)
+- test: cross-cutting interaction coverage for [#510](https://github.com/Takazudo/zudo-design-token-panel/issues/510) confirm pass (9a5d7fe)
+- docs: truth-up schemaId docs, tighten Import modal copy, export `SCHEMA_V1`/`SCHEMA_V2`/`SCHEMA_V3` ([#505](https://github.com/Takazudo/zudo-design-token-panel/issues/505)) (8088281)
+- docs: replace zmodular references with Takazudo Modular markdown links (afcfea2)
+
 ## 0.4.4
 
 ### Features

package/README.md

@@ -161,6 +161,8 @@ export const panelConfig: PanelConfig = {
 
 For the full token-overrides payload schema and the `PanelConfig` shape, see §5 and §6.
 
+**Which CSS blocks the rewriter scans.** Each routed file's rewrite only reaches two locations: the FIRST top-level `:root { ... }` block and the FIRST top-level `@theme { ... }` block (bare `@theme`, or with one modifier such as `@theme inline` — the shape Tailwind v4 prescribes when theme values reference other variables). Later blocks of either kind, and anything nested under `@media` / `@layer` / `@supports`, are not scanned. A cssVar declared in BOTH blocks is rewritten only in `:root` (`:root`-first-match-wins). A file with neither block returns a 409 — see §11 for the Tailwind `@theme` worked example, and [Apply pipeline reference](/docs/reference/apply-pipeline) for the full response-field contract, including the `unknownOutsideBlockCssVars` diagnostic for a cssVar that's declared somewhere in the file but outside both scanned blocks.
+
 ### 3.3 Security model
 
 The bin is **dev-only** and is built with three independent guards:
@@ -273,7 +275,7 @@ export const myPanelConfig: PanelConfig = {
   storagePrefix: 'myapp-design-token-panel',
   consoleNamespace: 'myapp',
   modalClassPrefix: 'myapp-design-token-panel-modal',
-  schemaId: 'myapp-design-tokens/v1',
+  schemaId: 'myapp-design-tokens/v1', // display-only label — see §5.3; import/export always use the canonical SCHEMA_V1/V2/V3
   exportFilenameBase: 'myapp-design-tokens',
   tabs: [spacingTab /*, fontTab, sizeTab, colorTab, ... */],
 };
@@ -477,7 +479,7 @@ export interface PanelInstanceHandle {
 | `storagePrefix`      | `string`                       | Base for every derived `localStorage` key. Also the instance id. See §9.                                                                                               |
 | `consoleNamespace`   | `string`                       | Global object the package installs `showDesignPanel` / `hideDesignPanel` / `toggleDesignPanel` on (e.g. `consoleNamespace: 'myapp'` → `window.myapp.showDesignPanel`). |
 | `modalClassPrefix`   | `string`                       | BEM root class for every modal the panel owns (export, import, apply). Emits `${prefix}__overlay`, `${prefix}__panel`, etc.                                            |
-| `schemaId`           | `string`                       | `$schema` value emitted into export JSON and required on import.                                                                                                       |
+| `schemaId`           | `string`                       | **Display-only** label surfaced in the Import modal's copy. `serialize()` always emits the canonical `SCHEMA_V2`/`SCHEMA_V3` and `deserialize()` always validates against the canonical `SCHEMA_V1`/`V2`/`V3` — neither reads this field. See §14's migration recipe. |
 | `exportFilenameBase` | `string`                       | Default download filename base — exports save as `${exportFilenameBase}.json`.                                                                                         |
 | `toggleEvent`        | `string` (optional)            | Window-event name that toggles THIS instance. Defaults to `toggle-${storagePrefix}` for non-default instances; the default instance keeps `toggle-design-token-panel`. |
 | `tabs`               | `readonly TabConfig[]`         | **Required.** Tab strip data — each entry is a tab with one or more `TierConfig` objects. The color tab (id `'color'`) additionally requires `colorExtras`. See §6.    |
@@ -533,7 +535,7 @@ const handle = configurePanel({
 The Astro entry point (`<DesignTokenPanelHost>`) handles mounting for you. Internally:
 
 - The console API (`showDesignPanel` etc.) is **always installed eagerly**, even when the panel module has not loaded — calling them is what triggers the lazy import for cold-start users.
-- The panel module is **dynamically imported on first need**: when the user calls a console helper, OR when first-paint detects any of four gate signals in `localStorage` — `${storagePrefix}:visible` set to `1`, persisted overrides (`${storagePrefix}-state-v3`), the owner-autoload flag (`${storagePrefix}:autoload` set to `1`), or the element-path inspector enabled.
+- The panel module is **dynamically imported on first need**: when the user calls a console helper, OR when first-paint detects any of four gate signals in `localStorage` — `${storagePrefix}:visible` set to `1`, persisted overrides (checked as `${storagePrefix}-state-v4`, falling back to `-state-v3` / `-state-v2` for pre-migration sessions — see §9), the owner-autoload flag (`${storagePrefix}:autoload` set to `1`), or the element-path inspector enabled.
 - This gating keeps the panel out of the initial JS bundle for first-time visitors while still re-applying overrides on hard reload for users who have tweaked things. **General visitors** (none of the four signals set) pay zero bundle cost.
 
 For a Vite-only / non-Astro host, mount it yourself by importing the adapter module after `configurePanel(...)`. See §11.5.
@@ -693,6 +695,13 @@ export interface ColorClusterExtras {
     colorScheme: string;
     colorMode: false | { defaultMode: 'light' | 'dark'; lightScheme: string; darkScheme: string };
   };
+  /**
+   * Optional config-time override map for a semantic tier's derived defaults,
+   * keyed by semantic item id. This is the ONLY way to ship a `{ literal }` /
+   * `{ literal: { light, dark } }` / `{ ref }` default — `TierItem.default`
+   * itself stays a plain string, consumed generically by every tab kind.
+   */
+  semanticDefaults?: Record<string, SemanticValue>;
 }
 
 export interface ColorScheme {
@@ -712,6 +721,30 @@ export interface ColorScheme {
 > re-exported from the package root:
 > `import type { ColorClusterConfig } from '@takazudo/zdtp'`.
 
+**`colorExtras.semanticDefaults`.** Without this field, a semantic tier's default `SemanticValue` is DERIVED from each `TierItem.default` string (palette-index lookup, or a literal fallback). `semanticDefaults` lets a host override that derivation for specific semantic item ids and ship a default the plain-string `default` field can't express — most usefully a per-mode literal that resolves via CSS `light-dark()`:
+
+```ts
+const colorTab: TabConfig = {
+  id: 'color',
+  label: 'Color',
+  tiers: [paletteTier, semanticTier],
+  colorExtras: {
+    id: 'myapp',
+    baseRoles: { background: '--myapp-bg', foreground: '--myapp-fg' },
+    baseDefaults: {},
+    defaultShikiTheme: 'dracula',
+    colorSchemes: { /* ... */ },
+    panelSettings: { colorScheme: 'Default', colorMode: false },
+    semanticDefaults: {
+      // Keyed by the semantic TierItem's `id`, not its cssVar.
+      danger: { literal: { light: '#b91c1c', dark: '#f87171' } },
+    },
+  },
+};
+```
+
+A key present in `semanticDefaults` wins verbatim over the derived value; keys not listed fall back to the normal derivation from `TierItem.default`.
+
 ### 7.2 JSON-serializable constraint (important)
 
 **Every field on the color `TabConfig` (including `colorExtras` and every
@@ -888,9 +921,10 @@ Behaviour notes:
 
 | Logical key | Derivation                  | Purpose                                                                                                                 |
 | ----------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
-| `state-v3`  | `${storagePrefix}-state-v3` | Current unified envelope (color + spacing + typography + size + panelPosition + generic `tabs` map). Added in abstract-token-tiers epic. |
-| `state-v2`  | `${storagePrefix}-state-v2` | Legacy pre-v3 format. Migrated into `state-v3` on first load, then deleted.                                             |
-| `state-v1`  | `${storagePrefix}-state`    | Legacy pre-v2 flat-state format (Color-only). Migrated into `state-v3` on first load, then deleted.                    |
+| `state-v4`  | `${storagePrefix}-state-v4` | Current unified envelope. Same top-level slices as v3, EXCEPT `color` (and optional `secondary`) is an identity-keyed map — one `ColorTweakState` slot per active-scheme identity — instead of a single flat object. See "Per-scheme color persistence" below. |
+| `state-v3`  | `${storagePrefix}-state-v3` | Legacy pre-v4 format (flat, single-slot `color`). Migrated into `state-v4` on first load; the v3 key itself is left in place (not deleted) so a downgrade can still read it. |
+| `state-v2`  | `${storagePrefix}-state-v2` | Legacy pre-v3 format. Migrated into `state-v3` (and from there into `state-v4`) on first load, then deleted.            |
+| `state-v1`  | `${storagePrefix}-state`    | Legacy pre-v2 flat-state format (Color-only). Migrated into `state-v3` (and from there into `state-v4`) on first load, then deleted. |
 | `open`      | `${storagePrefix}-open`     | Mirror of the panel's `open` boolean (synchronous mount-time read — preserves user intent across reloads, fixes #1549). |
 | `position`  | `${storagePrefix}-position` | Drag position `{ top, right }` so the panel reappears where the user left it.                                           |
 | `visible`   | `${storagePrefix}:visible`  | Adapter-level visibility-intent flag, owned by the lazy-load gate.                                                      |
@@ -899,6 +933,7 @@ Behaviour notes:
 For example, with `storagePrefix: 'myapp-design-token-panel'`:
 
 ```
+myapp-design-token-panel-state-v4
 myapp-design-token-panel-state-v3
 myapp-design-token-panel-state-v2
 myapp-design-token-panel-state
@@ -912,18 +947,40 @@ myapp-design-token-panel:autoload
 
 The `visible` and `autoload` keys use a literal `:` separator, not `-`. Every other derived key uses `-`. The colon form is intentional for these adapter-level flags — see [`PORTABLE-CONTRACT.md`](./PORTABLE-CONTRACT.md) §2 for the historical reason. Don't try to "normalize" them; the unit tests assert this specific shape.
 
-### Scheme changes and the global tweak model
+### Per-scheme color persistence (v4 envelope)
 
-Tweak state is **global**, not scheme-scoped: the keys above are derived only from `storagePrefix` and carry no color-scheme name. A single envelope holds every slice — the `color` slice stores **absolute** colors (palette + role/semantic indices resolved against that palette), while the `spacing` / `typography` / `size` slices store token overrides that are independent of the active scheme.
+Color/secondary tweaks are persisted **per (scheme, mode) identity**, inside the single `state-v4` storage key — there is no per-scheme key fan-out. The identity is exactly the active scheme name the panel already resolves for seeding (`getActiveSchemeName`): a cluster without `colorMode` resolves one constant identity (one slot, effectively the old global behavior); a cluster with light/dark `colorMode` resolves a distinct identity per side, so a light tweak and a dark tweak occupy independent slots in the same envelope:
 
-Because the stored palette is absolute, it cannot simply be re-applied on top of a different scheme. So when the host dispatches a `color-scheme-changed` event (e.g. a light/dark toggle), the panel **re-seeds its live color state from the newly active scheme**: it removes only the inline `:root` color-cluster overrides it had applied (`clearAppliedColorStyles`) and re-initializes only the live `color` (and optional `secondary`) slices from that scheme. Palette tweaks are therefore intentionally **not** carried across a scheme switch — the panel adopts the new scheme's palette rather than layering the previous absolute colors on top of it. This is the panel's deliberate global model; it does **not** persist a separate color slice per scheme.
+```jsonc
+{
+  "color": {
+    "Default Light": { "palette": [...], "semanticMappings": {...}, /* ... */ },
+    "Default Dark":  { "palette": [...], "semanticMappings": {...}, /* ... */ }
+  },
+  "secondary": { "Default Light": { /* ... */ } }, // optional, same identity keying
+  "spacing": { /* ... */ },
+  "typography": { /* ... */ },
+  "size": { /* ... */ }
+}
+```
+
+The `spacing` / `typography` / `size` (and generic `tabs`) slices stay **global and unkeyed**, exactly as in v1–v3 — a scheme/mode toggle never touches them.
 
-The `spacing` / `typography` / `size` slices are scheme-INDEPENDENT, so they are deliberately left untouched by the re-seed: their live values and their applied inline `:root` vars survive a scheme toggle (the scheme-change handler narrows the clear to the color cluster(s) for exactly this reason — see #347). A full panel reset (Reset / Apply) still wipes every slice via `clearAppliedStyles`.
+When the host dispatches a `color-scheme-changed` event (e.g. a light/dark toggle), the panel re-seeds its live color state for the newly active identity:
+
+- If that identity already has a persisted slot, the slot's stored `color` (and `secondary`) state is loaded and re-applied — a per-scheme tweak now **survives** a round-trip through another scheme and back.
+- If the identity has no slot yet (never tweaked under this scheme before), the panel cold-seeds from that scheme's defaults instead — the pre-existing "adopt the new scheme's palette" behavior for a scheme you haven't touched.
+
+Editing color under scheme A only ever overwrites scheme A's slot (`writeMergedV4` merge-saves: it reads the existing envelope, replaces just the active identity's slot, and preserves every other identity's slot untouched) — it never mutates scheme B's stored state. A full panel reset (Reset / Apply) still wipes every slice via `clearAppliedStyles`.
+
+**Migration.** On first load with no `state-v4` key, the legacy v1/v2/v3 chain runs unchanged (v3 wins over v2 over v1, exactly as before) and the resulting single flat `TweakState` is filed into `state-v4` under whichever identity is active at that moment — every subsequent load reads `state-v4` first. The legacy v3/v2/v1 keys are left in place by the v4 migration step (only the v1→v2→v3 chain deletes as it goes), so a host that needs to downgrade can still read them.
+
+**Host-owned `color-scheme` is never touched.** A host that manages its own `<html style="color-scheme">` (e.g. a site-level light/dark toggle) has that inline style tracked separately from the panel's own writes; the panel's mount/clear paths only ever remove a `color-scheme` value that the panel itself applied, never a host-owned one (#501).
 
 Two consequences worth knowing as a host integrator:
 
-- The event handler does not rewrite the `localStorage` envelope — it only re-seeds the live (in-memory) state and clears the inline overrides. The persisted envelope remains until the next in-panel edit re-persists the (re-seeded) state, or a full reload re-applies it via `loadPersistedState`.
-- Do **not** manually delete the tweak keys on a scheme toggle. The panel already re-seeds on the event, and a manual envelope delete would also discard the scheme-independent `spacing` / `typography` / `size` overrides.
+- The event handler does not rewrite `localStorage` directly beyond what's described above — it reads/re-seeds the live (in-memory) state and clears the inline overrides for the previous identity. The next in-panel edit (or a full reload via `loadPersistedState`) is what persists the current identity's state.
+- Do **not** manually delete the tweak keys on a scheme toggle. The panel already handles per-identity persistence on the event, and a manual envelope delete would also discard the scheme-independent `spacing` / `typography` / `size` overrides.
 
 ---
 
@@ -1032,6 +1089,39 @@ Because the fallback ladder is host-CSS-var-driven, a brand-new consumer can mou
 
 The CSS variables the panel **writes to** (the `cssVar` field on each `TokenDef`, the cluster's `paletteCssVarTemplate`, base-role names, and semantic CSS names) are entirely consumer-controlled. The package never reads those consumer CSS variables; it only writes through `setProperty` on `:root`.
 
+### 11.2 Apply-to-disk for a Tailwind v4 `@theme` block
+
+The section above is about the panel's OWN chrome — it never needed Tailwind. This section is about the opposite direction: a Tailwind v4 **consumer** whose design tokens live inside `@theme { ... }` (so Tailwind can generate utility classes from them) rather than `:root`.
+
+The apply-to-disk rewriter (§3.2) scans the first top-level `:root` block AND the first top-level `@theme` block, so a Tailwind v4 token file like this applies out of the box (issue #496's repro):
+
+```css
+:root {
+  --palette-cool-700: oklch(0.21 0.03 264);
+}
+
+@theme {
+  --spacing-md: 0.75rem;
+  --color-ink: light-dark(var(--palette-cool-700), var(--palette-cool-50));
+}
+```
+
+POSTing overrides for `--palette-cool-700` (in `:root`), `--spacing-md`, or `--color-ink` (both in `@theme`) all land in `changed` — no indirection required. A file that is 100% `@theme` (no `:root` block at all) also applies cleanly; only a file with **neither** block 409s.
+
+**Legacy workaround (no longer required).** Before the rewriter learned to scan `@theme`, the only way to make a Tailwind-`@theme` token editable was to declare the editable value in `:root` and have `@theme` alias it via `var(...)`:
+
+```css
+:root {
+  --spacing-md-editable: 0.75rem; /* apply pipeline writes here */
+}
+
+@theme {
+  --spacing-md: var(--spacing-md-editable); /* Tailwind reads the alias */
+}
+```
+
+This indirection is no longer necessary — declare the token directly inside `@theme` as shown above. The alias pattern still works (it's just two ordinary top-level blocks), so existing consumers are not required to migrate.
+
 ---
 
 ## 12. Bundler notes
@@ -1112,6 +1202,17 @@ This recipe walks through wiring the panel into a project that does not currentl
 
    Pick identifiers for `storagePrefix`, `consoleNamespace`, `modalClassPrefix`, `schemaId`, `exportFilenameBase`, and your palette CSS-var family (`paletteCssVarTemplate`). Pull these into a host-side config file (e.g. `src/lib/panel-config.ts`). If you are migrating from an internal snapshot fork and want to preserve users' saved state across the migration, keep the legacy values verbatim; otherwise pick fresh, neutral identifiers (e.g. `myapp-design-token-panel`).
 
+   `schemaId` is display-only (see §5.3) — it never gates import/export, so picking any string here is safe. If you want the Import modal's copy to name the ACTUAL schema your export/import round-trips through, import `SCHEMA_V1` / `SCHEMA_V2` / `SCHEMA_V3` from the package root and set `schemaId` to one of them instead of an arbitrary string:
+
+   ```ts
+   import { SCHEMA_V3 } from '@takazudo/zdtp';
+
+   export const myPanelConfig: PanelConfig = {
+     // ...
+     schemaId: SCHEMA_V3, // truthful label — matches what serialize()/deserialize() actually validate against
+   };
+   ```
+
 3. **Author your token manifest in the host project.**
 
    The package itself ships zero baked-in manifest data. Define `SPACING_TOKENS`, `FONT_TOKENS`, `SIZE_TOKENS`, `COLOR_TOKENS` (or whatever names you prefer) in your project and wire them up as `tokens.spacing`, `tokens.typography`, `tokens.size`, `tokens.color`. The host is the source of truth.

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

@@ -2,79 +2,186 @@
  * 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
+ * CSS custom properties inside the FIRST top-level `:root { ... }` block AND
+ * the FIRST top-level `@theme { ... }` block (Tailwind v4 design-token scope)
+ * 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.
+ * - Two top-level blocks are scanned: the FIRST top-level `:root { ... }` block
+ *   and the FIRST top-level `@theme { ... }` block (first-of-each-kind only).
+ *   Later blocks of either kind, and tokens inside `@media`, `@layer`,
+ *   `@supports`, or nested blocks, are IGNORED.
+ * - `:root`-first-match-wins: for each override var, `:root` is tried first and
+ *   `@theme` is the fallback. A var declared in BOTH blocks is rewritten only
+ *   in `:root`.
+ * - `@theme` accepts an optional modifier — `@theme`, `@theme inline`,
+ *   `@theme static`, `@theme reference`, or a combination — because Tailwind v4
+ *   prescribes `@theme inline` precisely when theme values reference other
+ *   variables (the mainstream case). `:root` matching stays strict: grouped
+ *   selectors such as `:root, html { ... }` are NOT treated as a `:root` block.
  * - 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.
+ *   as `unchanged` on the second call and produces byte-identical output. The
+ *   two non-overlapping regions are spliced back in DESCENDING start order so
+ *   the earlier region's offsets stay valid through the later region's splice.
+ * - `unknownOutsideBlock` (#508): a whole-file scan (ignoring the "first
+ *   block of each kind" and "no nesting" restrictions above) reclassifies any
+ *   `unknown` key that IS declared somewhere in the file, so callers can tell
+ *   "declared, but outside a scanned block" apart from "genuinely absent".
  *
  * 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.
+ * - Only the FIRST top-level block of each kind is scanned; a second top-level
+ *   `:root` or `@theme` block is ignored.
+ * - Nested `:root` / `@theme` 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`
+ * - If the same cssVar is declared multiple times inside a single scanned
  *   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). */
+     *  changed, including the "no scannable 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. */
+    /** cssVar names present in a scanned block 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). */
+    /** cssVar names in `overrides` that were not found in EITHER the first
+     *  top-level `:root` block or the first top-level `@theme` block (the name
+     *  is absent, or neither block exists). */
     unknown: string[];
+    /**
+     * Subset of `unknown` (#508): cssVar names that ARE declared somewhere in
+     * `source` — found by a whole-file scan, not restricted to the two scanned
+     * blocks — but outside both of them, so nothing was rewritten. Typical
+     * causes: the declaration sits in a nested block (`@media`/`@layer`/
+     * `@supports`), a grouped selector (`:root, html { ... }`), or a SECOND
+     * top-level `:root`/`@theme` block (the scanner only reads the first of
+     * each kind). Lets callers distinguish "declared, but Apply doesn't rewrite
+     * this location" from "genuinely absent / typo'd name" — the remaining
+     * `unknown` entries not in this list.
+     */
+    unknownOutsideBlock: 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.
+ * Thrown by {@link applyTokenOverridesOrThrow} when the source has neither a
+ * top-level `:root { ... }` block nor a top-level `@theme { ... }` block. Lets
+ * the dev-API handler surface a diagnostic message without having to probe the
+ * result shape.
  */
-export declare class NoRootBlockError extends Error {
+export declare class NoTokenBlockError extends Error {
     constructor(message?: string);
 }
 /**
- * Rewrite `overrides` into the first top-level `:root { ... }` block of
- * `source` and return an {@link ApplyResult} describing the outcome.
+ * @deprecated Retained as an alias for {@link NoTokenBlockError} so existing
+ * `instanceof` / import sites keep working. The scan now covers `@theme`
+ * blocks too, so "NoRootBlock" is no longer literally accurate.
+ */
+export declare const NoRootBlockError: typeof NoTokenBlockError;
+export interface BlockBounds {
+    /** Index of the first character INSIDE the block (just after the opening
+     *  `{`). */
+    contentStart: number;
+    /** Index of the matching `}` (exclusive end of block content). */
+    contentEnd: number;
+}
+/**
+ * Bounds of the first top-level `:root { ... }` block, or `null`. Grouped
+ * selectors (`:root, html { ... }`) are intentionally NOT matched.
+ */
+export declare function findFirstTopLevelRootBlock(source: string): BlockBounds | null;
+/**
+ * Bounds of the first top-level `@theme { ... }` block, or `null`. Tolerates an
+ * optional modifier (`@theme inline`, `@theme static`, ...) between `@theme`
+ * and the opening `{`.
+ */
+export declare function findFirstTopLevelThemeBlock(source: string): BlockBounds | null;
+export type SingleReplaceStatus = 'changed' | 'unchanged' | 'unknown';
+export interface SingleReplaceResult {
+    content: string;
+    status: SingleReplaceStatus;
+}
+/**
+ * Replace every CSS block comment (`/​* ... *​/`) with same-length whitespace
+ * so the per-declaration regex below cannot match a fake declaration that
+ * lives INSIDE a comment. Same-length is critical: the masked string is used
+ * only as a search space, but the resulting `match.index` is then sliced
+ * straight back into the original (un-masked) `content`, so masked and
+ * original must agree byte-for-byte on offsets.
+ *
+ * Pre-fix behaviour: a `:root` containing
+ *
+ *   /* --zd-foo: red; *​/
+ *   --zd-foo: blue;
  *
- * 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.
+ * would have its commented-out value rewritten by the regex (it matches the
+ * FIRST occurrence), leaving the live declaration untouched and silently
+ * corrupting the user-authored comment.
+ */
+export declare function maskComments(input: string): string;
+/**
+ * Replace the value of a single custom property inside `content`. The name
+ * may be supplied with or without the leading `--`. Returns the updated
+ * content along with a status flag used to populate `changed` / `unchanged`
+ * / `unknown` in the top-level {@link ApplyResult}.
+ *
+ * The match is run against a comment-masked copy of `content` so a
+ * commented-out declaration cannot shadow a live one (B4 fix). Edits are
+ * still spliced back into the original `content` so trailing inline comments
+ * survive byte-for-byte.
+ */
+export declare function replaceOne(content: string, cssVarName: string, newValue: string): SingleReplaceResult;
+/**
+ * Rewrite `overrides` into the first top-level `:root { ... }` block AND the
+ * first top-level `@theme { ... }` block of `source`, returning an
+ * {@link ApplyResult} describing the outcome.
+ *
+ * Per override var, `:root` is tried first and `@theme` is the fallback, so a
+ * var present in both blocks is rewritten only in `:root` (`:root`-first-match-
+ * wins). The two non-overlapping block regions are spliced back into `source`
+ * in DESCENDING start order so the earlier region's offsets stay valid.
+ *
+ * If `source` has neither block, the function returns `source` unchanged with
+ * every key routed to `unknown` — the companion {@link applyTokenOverridesOrThrow}
+ * raises {@link NoTokenBlockError} in that case so callers that need a hard
+ * failure can distinguish it from a file 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.
+ * raises {@link NoTokenBlockError} when the source has neither a top-level
+ * `:root { ... }` block nor a top-level `@theme { ... }` block, instead of
+ * returning every override under `unknown`. Use this from server-side handlers
+ * where "no writable token 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.
+ * source contains at least one scannable top-level token block — a `:root`
+ * block OR a `@theme` block. Consistent with the {@link applyTokenOverridesOrThrow}
+ * throw condition (which fires only when this returns `false`).
+ */
+export declare function hasApplicableTokenBlock(source: string): boolean;
+/**
+ * @deprecated Renamed to {@link hasApplicableTokenBlock} now that the scan
+ * covers `@theme` blocks too. Retained as an alias so existing call sites keep
+ * working; it returns `true` for a `@theme`-only file (no `:root`).
  */
-export declare function hasTopLevelRootBlock(source: string): boolean;
+export declare const hasTopLevelRootBlock: typeof hasApplicableTokenBlock;

package/dist/astro/host-adapter.js

@@ -1,56 +1,56 @@
-import { c as h, g as u, a as g, b as w, d as y, e as P } from "../panel-config-CXTCcYQs.js";
-import { g as d, Z as b } from "../tweak-state-BeXkzoj8.js";
-import { s as _, l as A, a as c, c as k, b as I } from "../autoload-state-CmhI7q9j.js";
-const l = "tokenpanel-config";
-function E() {
+import { c as w, g as u, a as g, b as y, d as P, e as b, f as _ } from "../panel-config-CipeKMTz.js";
+import { g as d, Z as A } from "../tweak-state-xt-tSQ_t.js";
+import { s as k, l as I, a as c, c as E, b as C } from "../autoload-state-DF7TsTgY.js";
+const i = "tokenpanel-config";
+function S() {
   if (typeof document > "u")
     throw new Error(
       "[design-token-panel] host-adapter loaded without a document; expected to run in a browser context."
     );
-  const n = document.getElementById(l);
+  const n = document.getElementById(i);
   if (!n)
     throw new Error(
-      `[design-token-panel] Inline config script #${l} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
+      `[design-token-panel] Inline config script #${i} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
     );
-  const o = n.textContent ?? "";
+  const a = n.textContent ?? "";
   let e;
   try {
-    e = JSON.parse(o);
-  } catch (a) {
+    e = JSON.parse(a);
+  } catch (o) {
     throw new Error(
-      `[design-token-panel] Failed to parse inline config from #${l}: ${a.message}`
+      `[design-token-panel] Failed to parse inline config from #${i}: ${o.message}`
     );
   }
-  return P(e), e;
+  return _(e), e;
 }
-function C(n) {
+function T(n) {
   return n.__zudoDesignTokenPanelAdapter || (n.__zudoDesignTokenPanelAdapter = {}), n.__zudoDesignTokenPanelAdapter;
 }
-function S(n, o) {
-  const e = C(n);
-  let a = e[o];
-  return a || (a = { bound: !1, modulePromise: null }, e[o] = a), a;
+function V(n, a) {
+  const e = T(n);
+  let o = e[a];
+  return o || (o = { bound: !1, modulePromise: null }, e[a] = o), o;
 }
-function T(n) {
+function v(n) {
   try {
     return window.localStorage.getItem(n) === "1";
   } catch {
     return !1;
   }
 }
-function v(n, o) {
+function D(n, a, e) {
   try {
-    const e = window.localStorage;
-    return e.getItem(o) !== null || e.getItem(n) !== null;
+    const o = window.localStorage;
+    return o.getItem(e) !== null || o.getItem(a) !== null || o.getItem(n) !== null;
   } catch {
     return !1;
   }
 }
-async function i(n) {
-  return n.modulePromise === null && (n.modulePromise = import("@takazudo/zdtp").then((o) => {
+async function l(n) {
+  return n.modulePromise === null && (n.modulePromise = import("@takazudo/zdtp").then((a) => {
     try {
-      const e = u(), a = o.__panelConfigForTest();
-      e !== a && console.warn(
+      const e = u(), o = a.__panelConfigForTest();
+      e !== o && 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 (e) {
@@ -58,17 +58,17 @@ async function i(n) {
         "[design-token-panel] Singleton-sharing check could not run (likely an older dist without the __panelConfigForTest accessor): " + e.message
       );
     }
-    return o;
+    return a;
   })), n.modulePromise;
 }
-function D(n, o, e, a, t) {
-  const s = n[o] ?? {};
+function K(n, a, e, o, t) {
+  const s = n[a] ?? {};
   s.showDesignPanel = async () => {
-    c(t, !0), await i(e), a.open();
+    c(t, !0), await l(e), o.open();
   }, s.hideDesignPanel = async () => {
-    await i(e), a.close();
+    await l(e), o.close();
   }, s.toggleDesignPanel = async () => {
-    await i(e), a.toggle();
+    await l(e), o.toggle();
     let r = !1;
     try {
       r = window.localStorage.getItem(d(t)) === "1";
@@ -76,13 +76,13 @@ function D(n, o, e, a, t) {
     }
     r && c(t, !0);
   }, s.enableAutoload = async () => {
-    (await i(e)).enableAutoload(t);
+    (await l(e)).enableAutoload(t);
   }, s.disableAutoload = async () => {
     if (e.modulePromise !== null) {
-      (await i(e)).disableAutoload(t);
+      (await l(e)).disableAutoload(t);
       return;
     }
-    k(t), I(!1, t);
+    E(t), C(!1, t);
     try {
       window.localStorage.setItem(g(t), "0");
     } catch {
@@ -91,12 +91,12 @@ function D(n, o, e, a, t) {
       window.localStorage.removeItem(d(t));
     } catch {
     }
-  }, n[o] = s;
+  }, n[a] = s;
 }
 (function() {
-  const o = E(), e = o.legacyIdRenameMap ? o : { ...o, legacyIdRenameMap: { ...b } }, a = h(e), t = u(), s = window, r = S(s, t.storagePrefix);
-  if (D(s, t.consoleNamespace, r, a, t), r.bound) return;
+  const a = S(), e = a.legacyIdRenameMap ? a : { ...a, legacyIdRenameMap: { ...A } }, o = w(e), t = u(), s = window, r = V(s, t.storagePrefix);
+  if (K(s, t.consoleNamespace, r, o, t), r.bound) return;
   r.bound = !0;
-  const f = g(t), p = w(t), m = y(t);
-  (T(f) || v(p, m) || _(t) || A(t)) && i(r);
+  const f = g(t), m = y(t), p = P(t), h = b(t);
+  (v(f) || D(m, p, h) || k(t) || I(t)) && l(r);
 })();

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { s as t } from "../panel-config-CXTCcYQs.js";
+import { s as t } from "../panel-config-CipeKMTz.js";
 import { c as d } from "../color-schemes-CgzOBqGO.js";
 import { F as r, G as m, a as g, S as z } from "../manifest-DCReQE0k.js";
 const e = {

package/dist/{autoload-state-CmhI7q9j.js → autoload-state-DF7TsTgY.js}

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