@takazudo/zdtp 0.4.15 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to `@takazudo/zdtp` are documented in this file.
 
 The format is based on Keep a Changelog, and release notes are generated from the changelog MDX pages.
 
+## [0.5.0] - 2026-09-06
+
+`@takazudo/zdtp/constants` now exposes `DEFAULT_STORAGE_PREFIX`, `DEFAULT_TOGGLE_EVENT`, `resolveToggleEventName`, `EAGER_LOAD_GATE_KEY_SUFFIXES`, and `EAGER_LOAD_GATE_STATE_FAMILY` without importing the panel. Lazy hosts can share toggle-event rules and eager-load metadata; state-family matching still requires the documented content checks. The storage-key documentation is also corrected: position, size, density, and all three highlight keys already existed in published 0.4.14.
+
+### Features
+
+- feat(zdtp): publish isolated constants entry (11ff48b)
+- feat: describe eager-load gate signals with behavioral drift guard (0a2b610)
+
+### Fixed
+
+- fix: keep dock controls visible and reconcile menu with rendered CSS (dae7dcc)
+- fix(zdtp): preserve readable labels in changed token rows (97ede7f)
+
+### Other Changes
+
+- Merge pull request [#769](https://github.com/Takazudo/zudo-design-token-panel/pull/769) from Takazudo/base/sweep-260906 (c4c6230)
+- Merge pull request [#778](https://github.com/Takazudo/zudo-design-token-panel/pull/778) from Takazudo/base/sweep-260906-gate-constants (cc29811)
+- Merge branch 'topic/765-constants-docs' into base/sweep-260906-gate-constants (a82dc82)
+- docs: document constants subpath and storage key continuity (17426e0)
+- Merge branch 'topic/764-constants-package' into base/sweep-260906-gate-constants (572d11c)
+- Merge branch 'topic/763-gate-signals' into base/sweep-260906-gate-constants (c09f456)
+- Merge branch 'topic/762-constants-leaf' into base/sweep-260906-gate-constants (f038f71)
+- refactor(zdtp): extract panel constants leaf (369e495)
+- Merge pull request [#773](https://github.com/Takazudo/zudo-design-token-panel/pull/773) from Takazudo/base/sweep-260906-dock-escape (08678c2)
+- Merge branch 'topic/759-dock-fix' into base/sweep-260906-dock-escape (a44f2a4)
+- Merge branch 'topic/758-dock-decision' into base/sweep-260906-dock-escape (3d1ee55)
+- docs: define visible dock controls and CSS-driven menu contract (0da81f3)
+- Merge pull request [#768](https://github.com/Takazudo/zudo-design-token-panel/pull/768) from Takazudo/base/sweep-260906-changed-row-label (323b9b0)
+- Merge branch 'topic/754-changed-row-label' into base/sweep-260906-changed-row-label (69846f2)
+
 ## [0.4.15] - 2026-09-05
 
 ### Features

package/PORTABLE-CONTRACT.md

@@ -293,6 +293,13 @@ derives the keys at runtime from this single base.
 | `highlight-outline-width` | `${storagePrefix}-highlight-outline-width` | highlight-state | Global highlight outline width in local storage, clamped to 1–20.                              |
 | `highlight-active` | `${storagePrefix}-highlight-active` | highlight-state | Active CSS-variable-to-slot map in session storage.                                                                                                        |
 
+This is the current storage-key inventory, not a release-history table. The
+published 0.4.14 bundle already wrote `${storagePrefix}-position`,
+`${storagePrefix}-size`, `${storagePrefix}-density`, and all three
+`${storagePrefix}-highlight-*` keys. Their appearance in the 0.4.15 contract
+documentation records existing storage continuity; it does not make those keys
+new in 0.4.15.
+
 **Constraint — colon, not dash, for `visible` and `autoload`.** Both adapter-
 level flags use a `:` separator; every other derived key uses `-`. The colon
 form is a historical artifact for `visible`, preserved for storage-key
@@ -1094,8 +1101,17 @@ This is the reason the JSON-serializable constraint in §4.2 is non-negotiable.
 
 ### 6.2 Lazy-load gate
 
-The host adapter fires one eager `loadPanelModule()` call when any of the
-following signals is present in `localStorage` at page load:
+The machine-readable metadata for these signals is exported from the
+side-effect-free `@takazudo/zdtp/constants` subpath. Use
+`EAGER_LOAD_GATE_KEY_SUFFIXES` for the five fixed suffix descriptors
+(`:visible`, `-open`, `:autoload`, `-elpath-enabled`, and
+`-domtweaker-enabled`), and `EAGER_LOAD_GATE_STATE_FAMILY` for the versioned
+`-state` family. These exports are the source of truth for consumers that
+mirror the gate. Each fixed descriptor supplies `acceptedValues` and
+`requiredConfig`; presence alone is insufficient, and a named required config
+property must be defined. The prose below explains the runtime meaning. The host adapter fires one eager
+`loadPanelModule()` call when any of these signals activates in `localStorage`
+at page load:
 
 ```ts
 if (
@@ -1126,6 +1142,14 @@ if (
   hand or by another tool.) Overrides MUST be re-applied to the configured
   sink (or default `:root`) even when the panel stays hidden, otherwise
   hard-nav produces a FOUT.
+
+  `EAGER_LOAD_GATE_STATE_FAMILY.matchesKey(storagePrefix, key)` only recognizes
+  the exact `${storagePrefix}-state` / `${storagePrefix}-state-vN` key shape. It
+  does not read storage or perform the content check. The consumer must apply
+  the accompanying `valueRules`: raw empty strings, JSON `null`, and empty
+  objects/arrays do not activate; non-empty collections, every other parsed
+  primitive (including `false`, `0`, and JSON `""`), and malformed JSON do
+  activate.
 - `shouldAutoload()` — reads `${storagePrefix}:autoload` (colon-form, §2).
   Returns `true` when the flag is `'1'` (explicit, written by `enableAutoload()`)
   OR `'auto'` (auto-remembered, written by opening the panel — see "Auto-remember

package/README.md

@@ -414,6 +414,57 @@ Copy an example's structure when porting the panel into a new host.
 
 If you are building a **Rust SSG** or other non-Node host, the bin still runs as a sidecar Node.js subprocess (started by your host's build orchestration). The same routing JSON and host-adapter setup applies — the only difference is your host ships its own config format (not TypeScript) and you invoke the bin via your build system's subprocess spawner rather than npm scripts.
 
+#### Pre-import activation from a custom host
+
+The side-effect-free `@takazudo/zdtp/constants` subpath exposes
+`DEFAULT_STORAGE_PREFIX`, `DEFAULT_TOGGLE_EVENT`, and
+`resolveToggleEventName` without importing the panel. It also exports the
+machine-readable eager-load metadata (`EAGER_LOAD_GATE_KEY_SUFFIXES` and
+`EAGER_LOAD_GATE_STATE_FAMILY`); the exact gate contract lives in
+[`PORTABLE-CONTRACT.md`](./PORTABLE-CONTRACT.md) §6.2.
+
+A custom host can use those constants to register its toggle listener in the
+initial bundle and fetch the panel only when activated. Keep the stylesheet
+setup from §4.2 (or import `@takazudo/zdtp/styles` in your host stylesheet
+pipeline):
+
+```ts
+import type { PanelConfig } from '@takazudo/zdtp';
+import { resolveToggleEventName } from '@takazudo/zdtp/constants';
+
+// Call once with your complete config (for example myPanelConfig in §4.1.1).
+export function installLazyPanel(config: PanelConfig): void {
+  const toggleEvent = resolveToggleEventName(config);
+  let loading: Promise<void> | undefined;
+
+  function loadOnToggle(): void {
+    if (loading) return;
+    loading = import('@takazudo/zdtp')
+      .then(({ configurePanel }) => {
+        configurePanel(config);
+        window.removeEventListener(toggleEvent, loadOnToggle);
+        window.dispatchEvent(new CustomEvent(toggleEvent));
+      })
+      .catch((error: unknown) => {
+        loading = undefined;
+        console.error('Failed to load @takazudo/zdtp', error);
+      });
+  }
+
+  window.addEventListener(toggleEvent, loadOnToggle);
+}
+```
+
+The default `DEFAULT_STORAGE_PREFIX` is
+`'zudo-design-token-panel'`, and its `DEFAULT_TOGGLE_EVENT` is
+`'toggle-design-token-panel'`. `resolveToggleEventName` preserves that
+historical event even when a default-prefix config supplies `toggleEvent`; a
+non-default prefix uses its supplied `toggleEvent`, or derives
+`toggle-${storagePrefix}` when the override is omitted. The same config
+resolves the listener event and configures the loaded panel. This activation-only
+example does not implement the saved-state eager-load gate; see §6.2 of the
+contract when building a complete host adapter.
+
 ### 4.3 Recipe — Rust SSG (zfb)
 
 Worked example for the case where the host is a Rust dev server (e.g. [zfb / zudo-front-builder](https://github.com/Takazudo/zudo-front-builder)) rather than a Node-based runner. The bin itself is unchanged — it remains a Node.js subprocess invoked as `node path/to/dist/bin/server.js ...`. The Rust host's only job is to spawn that Node process, forward shutdown signals to it, and configure `--allow-origin` so the browser POST from the panel UI is accepted.

package/dist/astro/host-adapter.js

@@ -1,6 +1,6 @@
-import { c as y, g as m, a as w, b, i as P } from "../panel-config-CRf-ONSV.js";
-import { g, Z as k } from "../tweak-state-BGp_7Tfh.js";
-import { s as A, l as D, a as E, i as c, r as f, c as _, b as I, d } from "../autoload-state-7BQYXI7Y.js";
+import { c as y, g as m, a as w, b, i as P } from "../panel-config-BSu6TUht.js";
+import { g, Z as k } from "../tweak-state-B7ok3Ob3.js";
+import { s as A, l as D, a as E, i as c, r as f, c as _, b as I, d } from "../autoload-state-DmTY6tRy.js";
 const u = "tokenpanel-config";
 function S() {
   if (typeof document > "u")

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { s as t } from "../panel-config-CRf-ONSV.js";
+import { s as t } from "../panel-config-BSu6TUht.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-DvuKi7I4.js";
 const e = {

package/dist/{autoload-state-7BQYXI7Y.js → autoload-state-DmTY6tRy.js}

@@ -1,4 +1,4 @@
-import { g as n, j as o } from "./panel-config-CRf-ONSV.js";
+import { g as n, j as o } from "./panel-config-BSu6TUht.js";
 function c() {
   return typeof document < "u" && document !== null && typeof document.getElementById == "function";
 }

package/dist/config/panel-config.d.ts

@@ -47,6 +47,7 @@
  */
 import type { ColorScheme } from './color-schemes';
 import type { TabConfig } from '../tokens/tier-model';
+export { DEFAULT_STORAGE_PREFIX, DEFAULT_TOGGLE_EVENT } from '../constants';
 /**
  * Apply-routing map.
  *
@@ -510,13 +511,6 @@ export declare function storageKey_visible(cfg: PanelConfig): string;
 export declare function storageKey_autoload(cfg: PanelConfig): string;
 /** DOM id of the root element the Preact panel tree mounts into. */
 export declare function panelRootId(cfg: PanelConfig): string;
-/**
- * Historical public toggle-event name. Hosts have shipped `window.dispatchEvent(
- * new CustomEvent('toggle-design-token-panel'))` since the single-panel era, so
- * the default instance MUST keep emitting/listening on this name regardless of
- * its derived `toggle-${storagePrefix}` form.
- */
-export declare const DEFAULT_TOGGLE_EVENT = "toggle-design-token-panel";
 /**
  * Window-event name that toggles this instance's panel.
  *

package/dist/constants.d.ts

@@ -0,0 +1,66 @@
+/** Default storage-key prefix used by the single-panel configuration. */
+export declare const DEFAULT_STORAGE_PREFIX = "zudo-design-token-panel";
+/** Historical public window-event name for the default panel instance. */
+export declare const DEFAULT_TOGGLE_EVENT = "toggle-design-token-panel";
+/**
+ * Resolve the window-event name that toggles a panel instance.
+ *
+ * The default prefix keeps the historical event name, even when a host
+ * supplies a `toggleEvent`. Other prefixes honor an explicit event name and
+ * otherwise derive one from the prefix.
+ */
+export declare function resolveToggleEventName(cfg: {
+    storagePrefix?: string;
+    toggleEvent?: string;
+}): string;
+/**
+ * The five fixed eager-load signals, keyed by suffix relative to storagePrefix.
+ * Only acceptedValues activate a flag; presence alone is insufficient.
+ * requiredConfig means that property must be !== undefined in the panel config.
+ * This excludes preference keys and is NOT the whole gate: also inspect
+ * EAGER_LOAD_GATE_STATE_FAMILY, whose keys require a content check.
+ */
+export declare const EAGER_LOAD_GATE_KEY_SUFFIXES: {
+    readonly ':visible': {
+        readonly acceptedValues: readonly ["1"];
+        readonly requiredConfig: null;
+    };
+    readonly '-open': {
+        readonly acceptedValues: readonly ["1"];
+        readonly requiredConfig: null;
+    };
+    readonly ':autoload': {
+        readonly acceptedValues: readonly ["1", "auto"];
+        readonly requiredConfig: null;
+    };
+    readonly '-elpath-enabled': {
+        readonly acceptedValues: readonly ["1"];
+        readonly requiredConfig: null;
+    };
+    readonly '-domtweaker-enabled': {
+        readonly acceptedValues: readonly ["1"];
+        readonly requiredConfig: "domTweaker";
+    };
+};
+/**
+ * The sixth eager-load signal: exact -state / -state-vN keys, for every numeric
+ * version, with a content check. Missing keys and raw empty strings are blank;
+ * JSON null and empty objects/arrays do not activate. Non-empty collections and
+ * all other parsed primitives (even false, 0, or JSON "") activate. Malformed
+ * JSON fails open so the panel can migrate or reject the stored payload.
+ *
+ * matchesKey compares the prefix literally before matching the suffix, so regex
+ * metacharacters in a prefix are safe and sibling-instance keys are excluded.
+ * These are storage signal descriptions, not a storage reader or panel bootstrap.
+ */
+export declare const EAGER_LOAD_GATE_STATE_FAMILY: {
+    readonly matchesKey: (storagePrefix: string, key: string) => boolean;
+    readonly valueRules: {
+        readonly blank: false;
+        readonly jsonNull: false;
+        readonly object: "non-empty";
+        readonly array: "non-empty";
+        readonly primitive: true;
+        readonly malformedJson: true;
+    };
+};

package/dist/constants.js

@@ -0,0 +1,30 @@
+const n = "zudo-design-token-panel", l = "toggle-design-token-panel";
+function o(e) {
+  return e.storagePrefix === void 0 || e.storagePrefix === n ? l : e.toggleEvent ?? `toggle-${e.storagePrefix}`;
+}
+const a = {
+  ":visible": { acceptedValues: ["1"], requiredConfig: null },
+  "-open": { acceptedValues: ["1"], requiredConfig: null },
+  ":autoload": { acceptedValues: ["1", "auto"], requiredConfig: null },
+  "-elpath-enabled": { acceptedValues: ["1"], requiredConfig: null },
+  "-domtweaker-enabled": { acceptedValues: ["1"], requiredConfig: "domTweaker" }
+}, r = {
+  matchesKey(e, t) {
+    return t.startsWith(e) && /^-state(-v\d+)?$/.test(t.slice(e.length));
+  },
+  valueRules: {
+    blank: !1,
+    jsonNull: !1,
+    object: "non-empty",
+    array: "non-empty",
+    primitive: !0,
+    malformedJson: !0
+  }
+};
+export {
+  n as DEFAULT_STORAGE_PREFIX,
+  l as DEFAULT_TOGGLE_EVENT,
+  a as EAGER_LOAD_GATE_KEY_SUFFIXES,
+  r as EAGER_LOAD_GATE_STATE_FAMILY,
+  o as resolveToggleEventName
+};

package/dist/{index-C2DIYD0d.js → index-By6zFdp4.js}

@@ -1,7 +1,7 @@
 import { jsx as y, jsxs as K, Fragment as kt } from "preact/jsx-runtime";
 import { useEffect as P, useState as Y, useRef as O, useMemo as J, useCallback as X } from "preact/hooks";
-import { b as ft, p as wt, u as ht, a as Ne, A as bt, Z as gt } from "./index-BOOmFtJh.js";
-import { g as vt, m as j } from "./panel-config-CRf-ONSV.js";
+import { b as ft, p as wt, u as ht, a as Ne, A as bt, Z as gt } from "./index-CHzTi0y5.js";
+import { g as vt, m as j } from "./panel-config-BSu6TUht.js";
 const xt = (e, o) => {
   const t = new Array(e.length + o.length);
   for (let r = 0; r < e.length; r++)