@takazudo/zdtp 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## 0.4.6
+
+### Features
+
+- Notes tab — host-configurable token notes as the panel's top page ([#515](https://github.com/Takazudo/zudo-design-token-panel/issues/515)) (4169a05)
+- Palette tab: groups collapsed by default with boxed toggle headers ([#517](https://github.com/Takazudo/zudo-design-token-panel/issues/517)) (2ff5a1e)
+- Container-query responsive header & tabs at narrow panel widths, plus "zdtp" panel title + square corners ([#518](https://github.com/Takazudo/zudo-design-token-panel/issues/518)) (25dff1a)
+- Click-to-cycle unit suffix on value inputs ([#519](https://github.com/Takazudo/zudo-design-token-panel/issues/519)) (b05581d)
+- "?" help tooltips for Literal and Per-mode rows in the Color tab ([#520](https://github.com/Takazudo/zudo-design-token-panel/issues/520)) (c85fd69)
+- `zdtp.show()` — fixed-name global open API ([#523](https://github.com/Takazudo/zudo-design-token-panel/issues/523)) (9b3c636)
+
+### Fixed
+
+- Tooltip repositions correctly after panel resize (ResizeObserver initial-delivery fix) ([#516](https://github.com/Takazudo/zudo-design-token-panel/issues/516)) (d10fe16)
+- Closed a C0-control URL-scheme bypass in the notes-tab HTML sanitizer ([#515](https://github.com/Takazudo/zudo-design-token-panel/issues/515)) (19f7147)
+- Corrected kebab-close dead zone + title truncation in the responsive header ([#518](https://github.com/Takazudo/zudo-design-token-panel/issues/518)) (bfc4b81)
+- `window.zdtp` guards against a null instance and clarifies multi-instance behavior ([#523](https://github.com/Takazudo/zudo-design-token-panel/issues/523)) (bcc71aa)
+
+### Other Changes
+
+- docs: notes-tab demo in doc-site manifest; help-icon resize-pin trade-off + sanitizer intent documented (82cf7d8, fe1b477)
+- test: VRT baselines re-recorded for zdtp title + square corners; broad coverage added for notes tab, help icons, unit cycling
+- chore: removed consumed `_temp-resource/` prototype scaffold (ccbd18a)
+
+## 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

@@ -53,6 +53,8 @@ The package builds against Preact (declared as a `peerDependency`) and ships its
 
 > Visual: a screenshot or short capture would go here. Skipped in the v1 README — a placeholder is worse than nothing. See the external example repos linked in §15 for live demos.
 
+**Browser floor:** the panel's own header/tabbar chrome adapts to the panel's *width* (not the viewport) via CSS container queries, which are Baseline 2023 (Safari 16+). The panel is a developer tool used on evergreen browsers, so older browsers simply keep the wide-layout chrome with no JS fallback.
+
 ---
 
 ## 2. Install
@@ -161,6 +163,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 +277,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, ... */],
 };
@@ -324,6 +328,22 @@ That is the entire integration. `<DesignTokenPanelHost>` emits a JSON `<script>`
 window.myapp.toggleDesignPanel();
 ```
 
+Or use the fixed-name `zdtp` global — no need to remember your own
+`consoleNamespace`:
+
+```js
+// In the browser devtools console — works regardless of consoleNamespace
+zdtp.show();
+zdtp.hide();
+zdtp.toggle();
+```
+
+`zdtp.show()` / `hide()` / `toggle()` are console sugar for the exact same
+open/close verbs `window.myapp.*` exposes (see §10 for the full contract) —
+`window.myapp.*` keeps working unchanged. On an Astro page, `zdtp.*` is
+available as soon as the host-adapter script has run, even before the panel
+bundle itself has loaded.
+
 Or wire a hidden keyboard shortcut / dev-only button to call the same helper.
 
 ### 4.1.4 Stylesheet (self-injected — no consumer import required)
@@ -470,6 +490,13 @@ export interface PanelInstanceHandle {
 }
 ```
 
+`open()` / `close()` / `toggle()` are the same primitives both
+`window.myapp.*` (§10) and the fixed-name `window.zdtp.*` global (§10) wrap
+for the **default** (most-recently-configured) instance. On a page with more
+than one instance, call `handle.open()` / `.close()` / `.toggle()` directly
+on the specific instance's handle — `window.zdtp.*` always targets the
+default instance only.
+
 ### 5.3 Field summary
 
 | Field                | Type                           | Purpose                                                                                                                                                                |
@@ -477,7 +504,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 +560,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 +720,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 +746,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 +946,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 +958,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 +972,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)
+
+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:
+
+```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.
 
-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.
+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:
 
-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.
+- 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.
 
-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`.
+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.
 
 ---
 
@@ -943,6 +1025,27 @@ window.myapp.disableAutoload(); // disarm owner-mode; unmounts the panel
 
 All helpers are **async** — the first call lazy-imports the panel module. Subsequent calls share the memoised module promise and resolve synchronously after the first import completes.
 
+### Fixed-name global: `window.zdtp`
+
+`consoleNamespace` is a **required** field on `PanelConfig` — every consumer picks its own value, so `window[consoleNamespace].*` needs the host's chosen namespace before you can open the panel from the console. `window.zdtp` is an additive, fixed-name alias that needs none:
+
+```ts
+zdtp.show();   // open the panel (lazy-loads the bundle on first call, same as showDesignPanel())
+zdtp.hide();   // close the panel
+zdtp.toggle(); // toggle open/closed
+```
+
+- **`show` / `hide` / `toggle` only.** There is no `zdtp.enableAutoload()` — owner-autoload (§10.1) stays on `window[consoleNamespace].*` and the package-root `enableAutoload()` / `disableAutoload()` exports.
+- **`window[consoleNamespace].*` is unchanged** — `window.zdtp` is sugar layered on top of it, not a replacement. Both stay available side by side.
+- **Targets the default instance**, exactly like the package-root `showDesignTokenPanel()` / `hideDesignTokenPanel()` / `toggleDesignPanel()` exports and `window[consoleNamespace].*` itself. On an Astro host specifically, the alias binds to whichever instance's adapter script installs it first, rather than re-resolving "the current default" on every call — see `PORTABLE-CONTRACT.md` §6.5 for the exact per-install-site rule. For a page with more than one panel instance, use `configurePanel(cfg)`'s returned handle (§5.2) instead — it is unambiguous regardless of install order.
+- **Available on both integration paths:**
+  - Non-Astro hosts get it as soon as `@takazudo/zdtp`'s package-root module has loaded (it installs the alias at module init).
+  - Astro hosts get it as soon as the host-adapter `<script>` has run — **before** the panel bundle itself has loaded. The first `zdtp.*` call lazy-imports the bundle, exactly like `window[consoleNamespace].*`.
+- **Never clobbers a host-defined `window.zdtp`.** If your page already has its own `window.zdtp` for something unrelated, the package leaves it alone and logs a `console.warn` instead of overwriting it — including the edge case of choosing `consoleNamespace: 'zdtp'` yourself.
+- **Auto-remember applies too** — `zdtp.show()` arms the `:autoload` flag exactly like `showDesignPanel()` (§10.1's Auto-remember footgun note applies here as well).
+
+See `PORTABLE-CONTRACT.md` §6.5 for the full install-site and no-clobber/no-double-install contract.
+
 ### Backward-compatible: the on-demand flow is unchanged
 
 The pre-existing on-demand usage — calling `window.<consoleNamespace>.showDesignPanel()` / `hideDesignPanel()` / `toggleDesignPanel()` to lazy-import and initialize the panel — is **unchanged and fully supported**. Owner-autoload (§10.1) is an opt-in layered on top, not a replacement. If you never call `enableAutoload()`, the panel behaves exactly as it always did: nothing loads for any visitor until the first console call.
@@ -1032,6 +1135,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 +1248,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;