@takazudo/zdtp 0.4.9 → 0.4.11

package/README.md

@@ -510,6 +510,7 @@ default instance only.
 | `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.    |
 | `colorPresets`       | `Record<string, ColorScheme>` (optional) | Optional named scheme presets surfaced in the Color tab "Scheme..." dropdown. Defaults to `{}`. See §7.5.                                              |
 | `applySink`          | `ApplySink` (optional)         | Optional sink that routes this instance's CSS-var writes off `:root`. See §5.4. Not JSON-serializable — do not include in Astro inline config.                        |
+| `autoRememberOnOpen` | `boolean` (optional)           | Whether opening the panel (any of the auto-remember call sites — see §10.1) writes the `:autoload` flag with `'auto'` provenance. Defaults to `true`. Set `false` for a public site that wants a panel-open button visible to every visitor without arming owner-mode for whoever clicks it. `enableAutoload()`'s explicit `'1'` write is unaffected either way. See §10.1's Auto-remember footgun. |
 
 ### 5.4 `applySink` — optional write target
 
@@ -555,16 +556,27 @@ const handle = configurePanel({
 });
 ```
 
-### 5.3 Mount strategy & auto-mount
+### 5.5 Mount strategy & auto-mount
 
 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 (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.
+- The panel module is **dynamically imported on first need**: when the user calls a console helper, OR when first-paint detects any of these gate signals in `localStorage` — `${storagePrefix}:visible` set to `1` or its `${storagePrefix}-open` mirror set to `1`, persisted overrides (a content check across the `${storagePrefix}-state` family — `-state` (v1) through every `-state-vN` — rather than a presence check on a specific version key; see §9), the owner-autoload flag (`${storagePrefix}:autoload` set to `'1'` or `'auto'`), 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 these 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.
 
+### 5.6 First-open geometry
+
+The first time an instance opens with no persisted position, the panel picks its position and size together as one coherent rectangle, not as two independently-computed values:
+
+- **Size first, position from that size.** The default size follows the historical `min(1200, 0.8·vw) × min(800, 0.8·vh)` rule, clamped to a minimum floor and the viewport. The default position then centers _that same clamped rectangle_. Position and size can no longer disagree about the panel's width — they used to be computed separately, which could center a wider phantom panel than the one actually rendered and spawn it partly off-screen on a narrow viewport.
+- **Always contained in the viewport.** The centered position is run through a containment clamp before use, so the whole panel — not just a grabbable strip of it — sits inside `[0, innerWidth]` × `[0, innerHeight]`. This holds at every viewport width, including phone widths, and it holds for a *persisted* size too: an instance that has a saved size but no saved position (the user resized the panel without ever dragging it) is centered and contained against that saved size, not against the default one.
+- **Instance-aware: concurrent panels cascade apart.** Each additional concurrently-mounted instance offsets its own fresh-open position by 24px on both axes. The offset comes from mount order with lowest-free-slot reuse — the first free ordinal is claimed on mount and given back on unmount, so opening a third panel after closing the first reuses ordinal 0 rather than always growing. Two instances opened at once therefore don't spawn stacked exactly on top of each other.
+- **A persisted position always wins.** The cascade offset applies only to the fallback used when an instance has no saved position yet. A panel the user has dragged (and which got saved) reopens exactly where it was left, regardless of how many sibling instances happen to be mounted.
+- **Containment beats distinctness.** These two guarantees are not both promised unconditionally — on a viewport with no spare room, the 24px cascade shrinks toward whatever slack is left, down to a 0px offset, rather than pushing a panel outside the viewport. Two instances' first-open positions may then coincide. Each axis degrades independently: at a 320px viewport width the horizontal offset collapses to 0 once the minimum-width floor eats all the spare width, while the vertical offset may still cascade its full 24px if vertical slack remains.
+- **A different, stricter rule than the drag-recovery clamp.** Once a panel has been dragged, its position is governed by a separate, deliberately permissive clamp: it only guarantees a small grip of the panel's header stays on-screen so the user can drag it back, and otherwise allows the panel to hang off any edge. That drag clamp is unchanged and keeps applying after a drag; the full-containment guarantee above is specific to the first-open fallback position and does not carry over once the user has moved the panel.
+
 ---
 
 ## 6. Tab / tier model schema
@@ -951,9 +963,9 @@ Behaviour notes:
 | `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.                                           |
+| `position`  | `${storagePrefix}-position` | Drag position `{ top, left }` so the panel reappears where the user left it.                                           |
 | `visible`   | `${storagePrefix}:visible`  | Adapter-level visibility-intent flag, owned by the lazy-load gate.                                                      |
-| `autoload`  | `${storagePrefix}:autoload` | Owner-mode autoload flag. When `'1'`, the panel bundle fetches eagerly on every page load and mounts CLOSED so the Alt+click element-path inspector is armed without opening the panel UI. Set by `enableAutoload()` and cleared by `disableAutoload()`. See §10.1. |
+| `autoload`  | `${storagePrefix}:autoload` | Owner-mode autoload flag. Holds `'1'` (explicit — set by `enableAutoload()`) or `'auto'` (auto-remembered — set by opening the panel). Either value arms the panel bundle to fetch eagerly on every page load and mount CLOSED so the Alt+click element-path inspector is armed without opening the panel UI. Cleared by `disableAutoload()`. See §10.1. |
 
 For example, with `storagePrefix: 'myapp-design-token-panel'`:
 
@@ -1042,7 +1054,7 @@ zdtp.toggle(); // toggle open/closed
   - 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).
+- **Auto-remember applies too** — `zdtp.show()` arms the `:autoload` flag with `'auto'` provenance 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.
 
@@ -1078,11 +1090,15 @@ Both the Astro host-adapter (`window[consoleNamespace].*`) and the package-root
 
 #### The `${storagePrefix}:autoload` flag
 
-Stored in `localStorage` as `'1'` when armed, removed or `'0'` otherwise. The host-adapter's lazy-load gate reads this flag on every page load — when it is `'1'`, the panel bundle loads eagerly (the same as when the panel was previously visible or overrides are persisted). **General visitors** who have never called `enableAutoload()` have no flag and pay zero bundle cost.
+Stored in `localStorage` as `'1'` (explicit — set by `enableAutoload()`) or `'auto'` (auto-remembered — set by opening the panel; see "Auto-remember on open" below), removed or `'0'` otherwise. The host-adapter's lazy-load gate honours **either** value — when the flag is `'1'` or `'auto'`, the panel bundle loads eagerly (the same as when the panel was previously visible, via either the `:visible` flag or its `-open` mirror, or overrides are persisted, checked as a content check across the `${storagePrefix}-state` family rather than a presence check on a specific version key — see §9). **General visitors** who have never opened the panel or called `enableAutoload()` have no flag and pay zero bundle cost.
+
+**Downstream-host recipe.** A host that writes its own lazy-load probe (e.g. to decide whether to eagerly fetch something else alongside the panel) can read the flag directly and test `=== '1'` to match only the explicit-owner population, excluding visitors who merely opened the panel once.
+
+**Legacy caveat.** Browsers that auto-remembered *before* this provenance split shipped already hold `'1'` — the split value was never stored for them, so there is nothing to reclassify. An `=== '1'` probe therefore sheds the auto-remembered population only for opens made from this version onward; it does not retroactively shed the pre-existing legacy population still holding `'1'`.
 
 #### Auto-remember on open
 
-Opening the panel by any means — `showDesignPanel()`, `toggleDesignPanel()`, or clicking the panel's own header close button to re-open it — **automatically sets the `:autoload` flag**. This means once you open the panel you will be in owner-mode on subsequent page loads without calling `enableAutoload()` explicitly.
+Opening the panel by any means — `showDesignPanel()`, `toggleDesignPanel()`, or clicking the panel's own header close button to re-open it — **automatically sets the `:autoload` flag to `'auto'`** (auto-remembered provenance, distinct from the `'1'` that `enableAutoload()` writes). This means once you open the panel you will be in owner-mode on subsequent page loads without calling `enableAutoload()` explicitly. An existing explicit `'1'` is never downgraded — an owner who armed autoload deliberately keeps that provenance even after opening the panel again.
 
 #### Element-path coupling
 
@@ -1090,12 +1106,14 @@ Opening the panel by any means — `showDesignPanel()`, `toggleDesignPanel()`, o
 
 #### Auto-remember footgun
 
-Because **any open trigger sets `:autoload`**, a visible "open panel" button, keyboard shortcut, or similar affordance on your site becomes a de-facto owner-mode opt-in for anyone who clicks it. On an owner-only public site:
+Because **any open trigger sets `:autoload`** (to `'auto'`), a visible "open panel" button, keyboard shortcut, or similar affordance on your site becomes a de-facto owner-mode opt-in for anyone who clicks it. On an owner-only public site:
 
 - Gate or omit such triggers (hide them behind a login check, remove them from the production build, etc.).
 - Rely on the console `enableAutoload()` call as the owner's explicit opt-in.
 - See the [Load the panel only for you](/docs/recipes/owner-autoload) recipe for a safe worked example.
 
+**If your site wants a visible panel button for every visitor** (not just the owner) — hiding the trigger isn't an option — set `autoRememberOnOpen: false` on `PanelConfig` (§5.3). Opening the panel then never persists owner-mode for anyone; `enableAutoload()` remains available as the explicit, owner-only opt-in regardless of this setting.
+
 ---
 
 ## 11. Tailwind not required

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

@@ -14,10 +14,10 @@
  *     namespace is a configured field — different consumers can pick
  *     distinct values to prove the contract is host-agnostic.
  *  4. Gate the panel module's dynamic import on the same probes the legacy
- *     host script used: an existing `wasVisible()` flag or any persisted v2
- *     overrides. When neither is set, the panel module stays out of the
- *     initial bundle and only loads when the user calls a `window.<ns>.*`
- *     helper from the console.
+ *     host script used: an existing `wasVisible()` flag or any non-empty
+ *     persisted state envelope. When none is set, the panel module stays out
+ *     of the initial bundle and only loads when the user calls a
+ *     `window.<ns>.*` helper from the console.
  *
  * Idempotency
  * -----------

package/dist/astro/host-adapter.js

@@ -1,16 +1,16 @@
-import { c as h, g as u, a as g, b as y, d as P, e as b, f as _, i as A } from "../panel-config-BNLlUc_r.js";
-import { g as d, Z as k } from "../tweak-state-Dti6XMoQ.js";
-import { s as I, l as E, a as T, b as c, c as C, d as S } from "../autoload-state-CFmRjtD-.js";
-const r = "tokenpanel-config";
-function v() {
+import { c as y, g as m, a as w, b, i as P } from "../panel-config-7Xg59uKj.js";
+import { g, Z as k } from "../tweak-state-DRKV1uYj.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-CTDDBxI8.js";
+const u = "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 e = document.getElementById(r);
+  const e = document.getElementById(u);
   if (!e)
     throw new Error(
-      `[design-token-panel] Inline config script #${r} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
+      `[design-token-panel] Inline config script #${u} not found. Ensure <DesignTokenPanelHost config={...} /> is rendered on this page before the host script runs.`
     );
   const o = e.textContent ?? "";
   let n;
@@ -18,38 +18,56 @@ function v() {
     n = JSON.parse(o);
   } catch (a) {
     throw new Error(
-      `[design-token-panel] Failed to parse inline config from #${r}: ${a.message}`
+      `[design-token-panel] Failed to parse inline config from #${u}: ${a.message}`
     );
   }
-  return _(n), n;
+  return b(n), n;
 }
-function D(e) {
+function T(e) {
   return e.__zudoDesignTokenPanelAdapter || (e.__zudoDesignTokenPanelAdapter = {}), e.__zudoDesignTokenPanelAdapter;
 }
-function V(e, o) {
-  const n = D(e);
+function v(e, o) {
+  const n = T(e);
   let a = n[o];
   return a || (a = { bound: !1, modulePromise: null }, n[o] = a), a;
 }
-function K(e) {
+function p(e) {
   try {
     return window.localStorage.getItem(e) === "1";
   } catch {
     return !1;
   }
 }
-function M(e, o, n) {
+function C(e) {
+  return e.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function O(e) {
+  if (e === null || e === "") return !1;
+  let o;
+  try {
+    o = JSON.parse(e);
+  } catch {
+    return !0;
+  }
+  return o === null ? !1 : Array.isArray(o) ? o.length > 0 : typeof o == "object" ? Object.keys(o).length > 0 : !0;
+}
+function x(e) {
   try {
-    const a = window.localStorage;
-    return a.getItem(n) !== null || a.getItem(o) !== null || a.getItem(e) !== null;
+    const o = new RegExp(`^${C(e.storagePrefix)}-state(-v\\d+)?$`), n = window.localStorage;
+    for (let a = 0; a < n.length; a++) {
+      const t = n.key(a);
+      if (t !== null && o.test(t) && O(n.getItem(t)))
+        return !0;
+    }
+    return !1;
   } catch {
     return !1;
   }
 }
-async function i(e) {
+async function s(e) {
   return e.modulePromise === null && (e.modulePromise = import("@takazudo/zdtp").then((o) => {
     try {
-      const n = u(), a = o.__panelConfigForTest();
+      const n = m(), a = o.__panelConfigForTest();
       n !== a && 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."
       );
@@ -61,55 +79,68 @@ async function i(e) {
     return o;
   })), e.modulePromise;
 }
-function O(e, o, n, a, t) {
-  const l = e[o] ?? {};
-  l.showDesignPanel = async () => {
-    c(t, !0), await i(n), a.open();
-  }, l.hideDesignPanel = async () => {
-    await i(n), a.close();
-  }, l.toggleDesignPanel = async () => {
-    await i(n), a.toggle();
-    let s = !1;
+function R(e, o, n, a, t) {
+  const i = e[o] ?? {};
+  i.showDesignPanel = async () => {
+    const r = d();
+    await s(n), c(r) && (f(t), a.open());
+  }, i.hideDesignPanel = async () => {
+    const r = d();
+    await s(n), c(r) && a.close();
+  }, i.toggleDesignPanel = async () => {
+    const r = d();
+    if (await s(n), !c(r)) return;
+    a.toggle();
+    let l = !1;
     try {
-      s = window.localStorage.getItem(d(t)) === "1";
+      l = window.localStorage.getItem(g(t)) === "1";
     } catch {
     }
-    s && c(t, !0);
-  }, l.enableAutoload = async () => {
-    (await i(n)).enableAutoload(t);
-  }, l.disableAutoload = async () => {
+    l && f(t);
+  }, i.enableAutoload = async () => {
+    const r = d(), l = await s(n);
+    c(r) && l.enableAutoload(t);
+  }, i.disableAutoload = async () => {
+    const r = d();
     if (n.modulePromise !== null) {
-      (await i(n)).disableAutoload(t);
+      const l = await s(n);
+      if (!c(r)) return;
+      l.disableAutoload(t);
       return;
     }
-    C(t), S(!1, t);
+    _(t), I(!1, t);
     try {
-      window.localStorage.setItem(g(t), "0");
+      window.localStorage.setItem(w(t), "0");
     } catch {
     }
     try {
-      window.localStorage.removeItem(d(t));
+      window.localStorage.removeItem(g(t));
     } catch {
     }
-  }, e[o] = l;
+  }, e[o] = i;
 }
-function x(e, o) {
-  A({
+function N(e, o) {
+  P({
     show: async () => {
-      await i(e), o.open();
+      const n = d();
+      await s(e), c(n) && o.open();
     },
     hide: async () => {
-      await i(e), o.close();
+      const n = d();
+      await s(e), c(n) && o.close();
     },
     toggle: async () => {
-      await i(e), o.toggle();
+      const n = d();
+      await s(e), c(n) && o.toggle();
     }
   });
 }
 (function() {
-  const o = v(), n = o.legacyIdRenameMap ? o : { ...o, legacyIdRenameMap: { ...k } }, a = h(n), t = u(), l = window, s = V(l, t.storagePrefix);
-  if (O(l, t.consoleNamespace, s, a, t), x(s, a), s.bound) return;
-  s.bound = !0;
-  const p = g(t), f = y(t), m = P(t), w = b(t);
-  (K(p) || M(f, m, w) || I(t) || E(t) || t.domTweaker !== void 0 && T(t)) && i(s);
+  const o = S(), n = o.legacyIdRenameMap ? o : { ...o, legacyIdRenameMap: { ...k } }, a = y(n), t = m(), i = window, r = v(i, t.storagePrefix);
+  if (R(i, t.consoleNamespace, r, a, t), N(r, a), r.bound) return;
+  r.bound = !0;
+  const l = w(t);
+  (p(l) || p(g(t)) || x(t) || A(t) || D(t) || t.domTweaker !== void 0 && E(t)) && s(r).catch((h) => {
+    console.error("[design-token-panel] Eager panel-module load failed.", h);
+  });
 })();

package/dist/astro/index.js

@@ -1,4 +1,4 @@
-import { s as t } from "../panel-config-BNLlUc_r.js";
+import { s as t } from "../panel-config-7Xg59uKj.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-CTDDBxI8.js

@@ -0,0 +1,88 @@
+import { g as n, j as o } from "./panel-config-7Xg59uKj.js";
+function c() {
+  return typeof document < "u" && document !== null && typeof document.getElementById == "function";
+}
+function f() {
+  return typeof document > "u" || document === null ? null : document;
+}
+function i(e) {
+  return e !== null && c() && document === e;
+}
+function r(e = n()) {
+  return `${e.storagePrefix}-elpath-enabled`;
+}
+function s(e = n()) {
+  try {
+    return localStorage.getItem(r(e)) === "1";
+  } catch {
+    return !1;
+  }
+}
+function m(e, t = n()) {
+  try {
+    localStorage.setItem(r(t), e ? "1" : "0");
+  } catch {
+  }
+}
+function u(e = n()) {
+  return `${e.storagePrefix}-domtweaker-enabled`;
+}
+function g(e = n()) {
+  try {
+    return localStorage.getItem(u(e)) === "1";
+  } catch {
+    return !1;
+  }
+}
+function w(e, t = n()) {
+  try {
+    localStorage.setItem(u(t), e ? "1" : "0");
+  } catch {
+  }
+}
+const a = "1", l = "auto";
+function y(e) {
+  if (typeof window > "u") return !1;
+  try {
+    const t = window.localStorage.getItem(o(e));
+    return t === a || t === l;
+  } catch {
+    return !1;
+  }
+}
+function E(e, t) {
+  if (!(typeof window > "u"))
+    try {
+      window.localStorage.setItem(o(e), t ? a : "0");
+    } catch {
+    }
+}
+function b(e) {
+  if (!(typeof window > "u") && e.autoRememberOnOpen !== !1)
+    try {
+      const t = o(e);
+      if (window.localStorage.getItem(t) === a) return;
+      window.localStorage.setItem(t, l);
+    } catch {
+    }
+}
+function h(e) {
+  if (!(typeof window > "u"))
+    try {
+      window.localStorage.removeItem(o(e));
+    } catch {
+    }
+}
+export {
+  g as a,
+  m as b,
+  h as c,
+  f as d,
+  c as e,
+  w as f,
+  E as g,
+  i,
+  s as l,
+  b as r,
+  y as s
+};

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

@@ -205,6 +205,21 @@ export interface PanelConfig {
      * callers that depend on it.
      */
     legacyIdRenameMap?: Record<string, string | null>;
+    /**
+     * Whether opening the panel (via any of the five auto-remember call sites
+     * documented in `state/autoload-state.ts`) writes `${storagePrefix}:autoload`
+     * with `'auto'` provenance.
+     *
+     * Defaults to `true` (unchanged historical behaviour). README §10.1 names
+     * the auto-remember footgun this field addresses: because any visible
+     * "open panel" trigger arms owner-mode autoload for whoever clicks it, a
+     * PUBLIC DOCS SITE that wants a panel button visible to every visitor
+     * (not just its owner) cannot use the documented mitigation of hiding the
+     * trigger. Set `false` on such a host so opening the panel never persists
+     * owner-mode; `enableAutoload()` remains available as the explicit
+     * owner-only opt-in regardless of this setting.
+     */
+    autoRememberOnOpen?: boolean;
 }
 /**
  * Handle returned by `configurePanel`. Identifies one configured panel