@wix/web5-core 1.61.0 → 1.63.0

package/dist/cjs/theme/tokenContract.js

@@ -0,0 +1,163 @@
+"use strict";
+
+exports.__esModule = true;
+exports.TOKEN_NAME_PATTERN = exports.THEME_TOKEN_CONTRACT = exports.BRAND_TOKENS = void 0;
+exports.bucketOf = bucketOf;
+exports.hostAliasFor = hostAliasFor;
+/**
+ * The theme-token contract (DL #193).
+ *
+ * One home for the answer to "who is allowed to set this token, and who wins
+ * when more than one of them does". Three things need that answer and must not
+ * each keep their own copy:
+ *
+ *   - **`applyThemeOverrides`** decides, per key, whether to write the real
+ *     token or its `--web5-host-*` alias.
+ *   - **the seed's `validate-templates`** fails a template that sets a brand
+ *     token.
+ *   - **the shop owner's panel** renders a control per `editable` entry.
+ *
+ * A leaf module beside `hostScope.ts`, and for the same reason: both are data
+ * that several packages must agree on, and both have to be readable from plain
+ * Node tooling. Requiring this package's ENTRY from Node fails — the CSS import
+ * in it is a syntax error to the CJS loader, which is what `scope-css.ts`
+ * documents — but a deep import of a leaf like this one works, so the seed's
+ * validator can read it without loading a component library.
+ *
+ * It was briefly its own package. That was justified by `embed-loader` needing
+ * the list without taking core's eleven dependencies — and the loader turned
+ * out not to need it at all, because `applyThemeOverrides` has owned runtime
+ * token injection here since DL #131.
+ *
+ * ## The two buckets
+ *
+ * The split is about who WINS, not about what may be imported. A platform
+ * adapter is free to read anything the store states; the bucket decides what
+ * happens when a template has an opinion about the same token.
+ *
+ * - `brand` — the store's identity: colour roles and font families. The
+ *   imported value is written as the real token, last, so it wins
+ *   unconditionally. A template is not permitted to set these.
+ * - `host`  — the store's shape: corner radius today. The imported value is
+ *   written as `--web5-host-<name>` and consumed by core as a `var()`
+ *   fallback, so a template stating the real token beats it and a template
+ *   that stays silent inherits the store's.
+ *
+ * A token absent from this map is treated as `host`. That is deliberate and
+ * safe: an alias nothing consumes renders nothing, so an adapter that learns
+ * to read a token core has never heard of cannot override a template by
+ * accident. The wiring line in core is the real gate for a host token, not the
+ * entry here.
+ *
+ * ## Why all but one are brand
+ *
+ * This is not a new taxonomy. Twenty of these are the set
+ * `web50-shopify-adapter` already emits, with a bucket attached; the
+ * twenty-first, `--heading`, has been in core's catalogue since DL #131 and is
+ * consumed by the seed, but no adapter fills it yet. Exactly one token changes
+ * hands relative to the behaviour before DL #193 — `--radius`, which used to
+ * win against the template that had chosen a different one. That single
+ * misfiling is the whole of the bug this contract exists to fix.
+ */
+
+/** How a value is spelled, which is what makes validation possible. */
+
+/** Which layer wins when both a store and a template state this token. */
+
+const brandColor = label => ({
+  bucket: 'brand',
+  type: 'color-hsl',
+  editable: false,
+  ...(label === undefined ? {} : {
+    label
+  })
+});
+
+/**
+ * Every token a platform adapter may meaningfully emit today.
+ *
+ * Growth is adapter-driven on purpose: a token joins when an adapter can
+ * actually read it, not on spec. `theme_overrides` is capped at 32 entries by
+ * its proto, so there are twelve slots left and no reason to spend them on
+ * speculation. `--spacing` is the tempting next one and should be resisted —
+ * it scales every `p-*`, `m-*` and `gap-*` in the bundle from one number.
+ */
+const THEME_TOKEN_CONTRACT = exports.THEME_TOKEN_CONTRACT = Object.freeze({
+  // ── brand · colour roles (18) ────────────────────────────────────────────
+  '--background': brandColor(),
+  '--foreground': brandColor(),
+  '--card': brandColor(),
+  '--card-foreground': brandColor(),
+  '--popover': brandColor(),
+  '--popover-foreground': brandColor(),
+  '--primary': brandColor(),
+  '--primary-foreground': brandColor(),
+  '--secondary': brandColor(),
+  '--secondary-foreground': brandColor(),
+  '--muted': brandColor(),
+  '--muted-foreground': brandColor(),
+  '--accent': brandColor(),
+  '--accent-foreground': brandColor(),
+  '--border': brandColor(),
+  '--input': brandColor(),
+  '--ring': brandColor(),
+  /**
+   * Brand-shaped and supported end to end, but no adapter fills it yet: the
+   * seed consumes it (`--color-heading-fg: hsl(var(--heading, var(--foreground)))`)
+   * and core has catalogued it since DL #131, while `web50-shopify-adapter`
+   * emits the other twenty. A store that states a distinct heading colour has
+   * somewhere for it to go the moment an adapter learns to read one.
+   */
+  '--heading': brandColor(),
+  // ── brand · type (2) ─────────────────────────────────────────────────────
+  '--font-sans': {
+    bucket: 'brand',
+    type: 'font-stack',
+    editable: false
+  },
+  '--font-display': {
+    bucket: 'brand',
+    type: 'font-stack',
+    editable: false
+  },
+  // ── host · shape (1) ─────────────────────────────────────────────────────
+  /**
+   * The one token whose bucket changed, and the reason this contract exists.
+   * Editable because it is the one value a store and a template are known to
+   * disagree about in a way a merchant can see and wants to settle.
+   */
+  '--radius': {
+    bucket: 'host',
+    type: 'length',
+    editable: true,
+    label: 'Corner rounding'
+  }
+});
+
+/**
+ * The tokens written directly, which is the only question the loader has to
+ * answer per key — everything else takes the alias path.
+ */
+const BRAND_TOKENS = exports.BRAND_TOKENS = Object.freeze(new Set(Object.entries(THEME_TOKEN_CONTRACT).filter(([, entry]) => entry.bucket === 'brand').map(([token]) => token)));
+
+/**
+ * A token name we are willing to compose into a CSS declaration.
+ *
+ * The keys reaching the loader came out of a backend map, which came out of an
+ * adapter reading a merchant's theme file. A key carrying `:` or `;` would
+ * write arbitrary declarations onto the mount, so the shape is checked where
+ * the declaration is built rather than trusted from the source.
+ */
+const TOKEN_NAME_PATTERN = exports.TOKEN_NAME_PATTERN = /^--[a-z0-9-]+$/;
+
+/** `--radius` → `--web5-host-radius`. Derived, never stored: one fewer thing to get wrong. */
+function hostAliasFor(token) {
+  return `--web5-host-${token.slice(2)}`;
+}
+
+/** Whether this token is written directly (brand) or as an alias (host, and anything unknown). */
+function bucketOf(token) {
+  var _THEME_TOKEN_CONTRACT;
+  return ((_THEME_TOKEN_CONTRACT = THEME_TOKEN_CONTRACT[token]) == null ? void 0 : _THEME_TOKEN_CONTRACT.bucket) ?? 'host';
+}
+//# sourceMappingURL=tokenContract.js.map

package/dist/cjs/theme/tokenContract.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["brandColor","label","bucket","type","editable","undefined","THEME_TOKEN_CONTRACT","exports","Object","freeze","BRAND_TOKENS","Set","entries","filter","entry","map","token","TOKEN_NAME_PATTERN","hostAliasFor","slice","bucketOf","_THEME_TOKEN_CONTRACT"],"sources":["../../../src/theme/tokenContract.ts"],"sourcesContent":["/**\n * The theme-token contract (DL #193).\n *\n * One home for the answer to \"who is allowed to set this token, and who wins\n * when more than one of them does\". Three things need that answer and must not\n * each keep their own copy:\n *\n *   - **`applyThemeOverrides`** decides, per key, whether to write the real\n *     token or its `--web5-host-*` alias.\n *   - **the seed's `validate-templates`** fails a template that sets a brand\n *     token.\n *   - **the shop owner's panel** renders a control per `editable` entry.\n *\n * A leaf module beside `hostScope.ts`, and for the same reason: both are data\n * that several packages must agree on, and both have to be readable from plain\n * Node tooling. Requiring this package's ENTRY from Node fails — the CSS import\n * in it is a syntax error to the CJS loader, which is what `scope-css.ts`\n * documents — but a deep import of a leaf like this one works, so the seed's\n * validator can read it without loading a component library.\n *\n * It was briefly its own package. That was justified by `embed-loader` needing\n * the list without taking core's eleven dependencies — and the loader turned\n * out not to need it at all, because `applyThemeOverrides` has owned runtime\n * token injection here since DL #131.\n *\n * ## The two buckets\n *\n * The split is about who WINS, not about what may be imported. A platform\n * adapter is free to read anything the store states; the bucket decides what\n * happens when a template has an opinion about the same token.\n *\n * - `brand` — the store's identity: colour roles and font families. The\n *   imported value is written as the real token, last, so it wins\n *   unconditionally. A template is not permitted to set these.\n * - `host`  — the store's shape: corner radius today. The imported value is\n *   written as `--web5-host-<name>` and consumed by core as a `var()`\n *   fallback, so a template stating the real token beats it and a template\n *   that stays silent inherits the store's.\n *\n * A token absent from this map is treated as `host`. That is deliberate and\n * safe: an alias nothing consumes renders nothing, so an adapter that learns\n * to read a token core has never heard of cannot override a template by\n * accident. The wiring line in core is the real gate for a host token, not the\n * entry here.\n *\n * ## Why all but one are brand\n *\n * This is not a new taxonomy. Twenty of these are the set\n * `web50-shopify-adapter` already emits, with a bucket attached; the\n * twenty-first, `--heading`, has been in core's catalogue since DL #131 and is\n * consumed by the seed, but no adapter fills it yet. Exactly one token changes\n * hands relative to the behaviour before DL #193 — `--radius`, which used to\n * win against the template that had chosen a different one. That single\n * misfiling is the whole of the bug this contract exists to fix.\n */\n\n/** How a value is spelled, which is what makes validation possible. */\nexport type TokenType =\n  /** An HSL triplet with no `hsl()` wrapper — `0 0% 9%`. The core bridge wraps it. */\n  | 'color-hsl'\n  /** A CSS font stack — `'Poppins', ui-sans-serif, sans-serif`. */\n  | 'font-stack'\n  /** A CSS length. MUST carry a unit: a bare `0` turns `calc(var(--radius) - 4px)`\n   *  into a type error and takes the derived radius scale out entirely. */\n  | 'length';\n\n/** Which layer wins when both a store and a template state this token. */\nexport type TokenBucket = 'brand' | 'host';\n\nexport interface TokenContractEntry {\n  bucket: TokenBucket;\n  type: TokenType;\n  /** May the shop owner set this from the panel? */\n  editable: boolean;\n  /** Shown in the owner's panel. Absent for entries that are not editable. */\n  label?: string;\n}\n\nconst brandColor = (label?: string): TokenContractEntry => ({\n  bucket: 'brand',\n  type: 'color-hsl',\n  editable: false,\n  ...(label === undefined ? {} : { label }),\n});\n\n/**\n * Every token a platform adapter may meaningfully emit today.\n *\n * Growth is adapter-driven on purpose: a token joins when an adapter can\n * actually read it, not on spec. `theme_overrides` is capped at 32 entries by\n * its proto, so there are twelve slots left and no reason to spend them on\n * speculation. `--spacing` is the tempting next one and should be resisted —\n * it scales every `p-*`, `m-*` and `gap-*` in the bundle from one number.\n */\nexport const THEME_TOKEN_CONTRACT: Readonly<Record<string, TokenContractEntry>> =\n  Object.freeze({\n    // ── brand · colour roles (18) ────────────────────────────────────────────\n    '--background': brandColor(),\n    '--foreground': brandColor(),\n    '--card': brandColor(),\n    '--card-foreground': brandColor(),\n    '--popover': brandColor(),\n    '--popover-foreground': brandColor(),\n    '--primary': brandColor(),\n    '--primary-foreground': brandColor(),\n    '--secondary': brandColor(),\n    '--secondary-foreground': brandColor(),\n    '--muted': brandColor(),\n    '--muted-foreground': brandColor(),\n    '--accent': brandColor(),\n    '--accent-foreground': brandColor(),\n    '--border': brandColor(),\n    '--input': brandColor(),\n    '--ring': brandColor(),\n\n    /**\n     * Brand-shaped and supported end to end, but no adapter fills it yet: the\n     * seed consumes it (`--color-heading-fg: hsl(var(--heading, var(--foreground)))`)\n     * and core has catalogued it since DL #131, while `web50-shopify-adapter`\n     * emits the other twenty. A store that states a distinct heading colour has\n     * somewhere for it to go the moment an adapter learns to read one.\n     */\n    '--heading': brandColor(),\n\n    // ── brand · type (2) ─────────────────────────────────────────────────────\n    '--font-sans': { bucket: 'brand', type: 'font-stack', editable: false },\n    '--font-display': { bucket: 'brand', type: 'font-stack', editable: false },\n\n    // ── host · shape (1) ─────────────────────────────────────────────────────\n    /**\n     * The one token whose bucket changed, and the reason this contract exists.\n     * Editable because it is the one value a store and a template are known to\n     * disagree about in a way a merchant can see and wants to settle.\n     */\n    '--radius': {\n      bucket: 'host',\n      type: 'length',\n      editable: true,\n      label: 'Corner rounding',\n    },\n  });\n\n/**\n * The tokens written directly, which is the only question the loader has to\n * answer per key — everything else takes the alias path.\n */\nexport const BRAND_TOKENS: ReadonlySet<string> = Object.freeze(\n  new Set(\n    Object.entries(THEME_TOKEN_CONTRACT)\n      .filter(([, entry]) => entry.bucket === 'brand')\n      .map(([token]) => token),\n  ),\n) as ReadonlySet<string>;\n\n/**\n * A token name we are willing to compose into a CSS declaration.\n *\n * The keys reaching the loader came out of a backend map, which came out of an\n * adapter reading a merchant's theme file. A key carrying `:` or `;` would\n * write arbitrary declarations onto the mount, so the shape is checked where\n * the declaration is built rather than trusted from the source.\n */\nexport const TOKEN_NAME_PATTERN = /^--[a-z0-9-]+$/;\n\n/** `--radius` → `--web5-host-radius`. Derived, never stored: one fewer thing to get wrong. */\nexport function hostAliasFor(token: string): string {\n  return `--web5-host-${token.slice(2)}`;\n}\n\n/** Whether this token is written directly (brand) or as an alias (host, and anything unknown). */\nexport function bucketOf(token: string): TokenBucket {\n  return THEME_TOKEN_CONTRACT[token]?.bucket ?? 'host';\n}\n"],"mappings":"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","ignoreList":[]}

package/dist/esm/client/applyThemeOverrides.js

@@ -11,11 +11,23 @@
  *   compiled bundle stylesheet uses — host-page styling is never touched, and
  *   equal specificity + later document order makes the override win. Callers
  *   must therefore apply AFTER the client bundle's CSS is in the document.
- * - **Open token set**: any sanely-shaped custom property is applied, so a
- *   template can grow new tokens without an FE or BE release. The mandatory
- *   `--` prefix means an override can only define custom properties — it can
- *   never set a real CSS property inside the scope. The server enforces the
- *   same shape (plus value sanitation) at write time.
+ * - **Bucketed, since DL #193**: a `brand` token (colour roles, font families)
+ *   is written as itself, so the store's identity beats the template's. Every
+ *   other key — `host` tokens and anything the contract has never heard of —
+ *   is written as its `--web5-host-*` alias, which core's stylesheets consume
+ *   as a `var()` fallback. A template stating the real token therefore wins on
+ *   shape, and an unknown key is inert rather than dangerous: a custom property
+ *   nothing references renders nothing, so an adapter that learns to read a new
+ *   token cannot silently override a template.
+ * - **The token set stays open, but the destination changed.** Before DL #193
+ *   an unrecognised key was applied verbatim, so a template could consume
+ *   `var(--foo)` and grow a token with no release. It now arrives as
+ *   `--web5-host-foo`, so the template consumes `var(--web5-host-foo, <default>)`
+ *   instead. One line different, and the provenance is explicit — the wiring
+ *   line is what activates a host token, not the contract entry.
+ * - The mandatory `--` prefix means an override can only define custom
+ *   properties — it can never set a real CSS property inside the scope. The
+ *   server enforces the same shape (plus value sanitation) at write time.
  * - **Values are inert**: entries are written with
  *   `CSSStyleDeclaration.setProperty`, never string-concatenated into CSS, so
  *   a hostile value cannot terminate the declaration or open a new rule.
@@ -23,6 +35,8 @@
  *   re-apply; empty/absent input removes it.
  */
 import { WEB5_SCOPE } from '../hostScope.js';
+import { traceThemeOverrides } from './themeDebug.js';
+import { THEME_TOKEN_CONTRACT, bucketOf, hostAliasFor } from '../theme/tokenContract.js';
 
 /** A themeOverrides key: always a CSS custom property. */
 
@@ -33,20 +47,24 @@ import { WEB5_SCOPE } from '../hostScope.js';
  */
 
 /**
- * The known token catalog — the CSS custom properties the seed's Tailwind
- * bridge consumes today. GUIDANCE, NOT A GATE: writers (the Shopify theme
- * extractor, admin tooling) should stick to these to produce visible effect,
- * but `applyThemeOverrides` deliberately applies any well-formed custom
- * property so the vocabulary can grow from the seed alone (matching the
- * open-set validation on the server).
+ * The known token catalog. GUIDANCE, NOT A GATE — `applyThemeOverrides` still
+ * applies any well-formed custom property, so the vocabulary can grow without a
+ * release here.
+ *
+ * Derived from `@wix/web5-token-contract` rather than restated, because two
+ * hand-maintained copies of one list is how they drift. The contract also
+ * carries what this Set cannot: which bucket each token is in, and therefore
+ * who wins when a store and a template disagree.
  */
-export const THEME_OVERRIDE_TOKENS = new Set(['--background', '--foreground', '--card', '--card-foreground', '--popover', '--popover-foreground', '--primary', '--primary-foreground', '--secondary', '--secondary-foreground', '--muted', '--muted-foreground', '--accent', '--accent-foreground', '--border', '--input', '--ring', '--radius', '--font-sans', '--font-display', '--heading']);
+export const THEME_OVERRIDE_TOKENS = new Set(Object.keys(THEME_TOKEN_CONTRACT));
 
 /** Mirrors the server's Consts.ThemeOverrideKeyPattern. */
 const KEY_PATTERN = /^--[a-z][a-z0-9-]{0,62}$/;
 const MARKER_ATTR = 'data-web5-theme-overrides';
 export function applyThemeOverrides(overrides) {
-  if (typeof document === 'undefined') return;
+  if (typeof document === 'undefined') {
+    return;
+  }
   const existing = document.head.querySelector(`style[${MARKER_ATTR}]`);
   const entries = Object.entries(overrides ?? {}).filter(_ref => {
     let [key] = _ref;
@@ -58,6 +76,10 @@ export function applyThemeOverrides(overrides) {
   });
   if (entries.length === 0) {
     existing == null || existing.remove();
+    // Nothing to apply is itself a traceable answer: it means every token on
+    // the page is the template's, which is otherwise indistinguishable from
+    // tracing having failed.
+    traceThemeOverrides([]);
     return;
   }
   const style = document.createElement('style');
@@ -70,9 +92,15 @@ export function applyThemeOverrides(overrides) {
   }
   sheet.insertRule(`${WEB5_SCOPE} {}`, 0);
   const rule = sheet.cssRules[0];
+  const applied = [];
   for (const [key, value] of entries) {
+    // Brand wins over the template, so it is written as the token the
+    // stylesheets actually read. Everything else lands in the host namespace,
+    // where core consumes it only as a fallback the template can beat.
+    const target = bucketOf(key) === 'brand' ? key : hostAliasFor(key);
     try {
-      rule.style.setProperty(key, value);
+      rule.style.setProperty(target, value);
+      applied.push([key, value]);
     } catch {
       // An engine that rejects the value leaves the token at its baked
       // default — degraded theming, never broken CSS.
@@ -81,5 +109,8 @@ export function applyThemeOverrides(overrides) {
   // Replace-on-reapply: the fresh element is appended (so it stays last in
   // document order) before the stale one is dropped.
   existing == null || existing.remove();
+  // AFTER the stale element is gone, so the resolved values traced below are
+  // the ones the page will actually render. Off unless explicitly enabled.
+  traceThemeOverrides(applied);
 }
 //# sourceMappingURL=applyThemeOverrides.js.map

package/dist/esm/client/applyThemeOverrides.js.map

@@ -1 +1 @@
-{"version":3,"names":["WEB5_SCOPE","THEME_OVERRIDE_TOKENS","Set","KEY_PATTERN","MARKER_ATTR","applyThemeOverrides","overrides","document","existing","head","querySelector","entries","Object","filter","_ref","key","wellFormed","test","console","warn","length","remove","style","createElement","setAttribute","appendChild","sheet","insertRule","rule","cssRules","value","setProperty"],"sources":["../../../src/client/applyThemeOverrides.ts"],"sourcesContent":["/**\n * Runtime theme token injection (DL #131).\n *\n * `Configuration.themeOverrides` carries per-store CSS custom-property\n * overrides (`--primary`, `--radius`, `--heading`, ...) computed from the\n * store's own theme (e.g. the Shopify `settings_data.json` extractor). This\n * applies them to the page so they win over the bundle's baked `theme.css`:\n *\n * - **Scoped, not `:root`**: the rule targets `WEB5_SCOPE`, the same\n *   `:is(#root, .w5-root, [data-web5-placement], .debug-view)` selector every\n *   compiled bundle stylesheet uses — host-page styling is never touched, and\n *   equal specificity + later document order makes the override win. Callers\n *   must therefore apply AFTER the client bundle's CSS is in the document.\n * - **Open token set**: any sanely-shaped custom property is applied, so a\n *   template can grow new tokens without an FE or BE release. The mandatory\n *   `--` prefix means an override can only define custom properties — it can\n *   never set a real CSS property inside the scope. The server enforces the\n *   same shape (plus value sanitation) at write time.\n * - **Values are inert**: entries are written with\n *   `CSSStyleDeclaration.setProperty`, never string-concatenated into CSS, so\n *   a hostile value cannot terminate the declaration or open a new rule.\n * - **Idempotent**: one marker element per document, replaced wholesale on\n *   re-apply; empty/absent input removes it.\n */\nimport { WEB5_SCOPE } from '../hostScope';\n\n/** A themeOverrides key: always a CSS custom property. */\nexport type ThemeOverrideKey = `--${string}`;\n\n/**\n * Writer-side shape for a theme override map. The catalog below documents\n * the tokens the seed consumes today; the type stays open so new tokens\n * flow end-to-end with no release anywhere but the seed.\n */\nexport type ThemeOverrides = Record<ThemeOverrideKey, string>;\n\n/**\n * The known token catalog — the CSS custom properties the seed's Tailwind\n * bridge consumes today. GUIDANCE, NOT A GATE: writers (the Shopify theme\n * extractor, admin tooling) should stick to these to produce visible effect,\n * but `applyThemeOverrides` deliberately applies any well-formed custom\n * property so the vocabulary can grow from the seed alone (matching the\n * open-set validation on the server).\n */\nexport const THEME_OVERRIDE_TOKENS: ReadonlySet<string> = new Set([\n  '--background', '--foreground',\n  '--card', '--card-foreground',\n  '--popover', '--popover-foreground',\n  '--primary', '--primary-foreground',\n  '--secondary', '--secondary-foreground',\n  '--muted', '--muted-foreground',\n  '--accent', '--accent-foreground',\n  '--border', '--input', '--ring',\n  '--radius',\n  '--font-sans', '--font-display',\n  '--heading',\n]);\n\n/** Mirrors the server's Consts.ThemeOverrideKeyPattern. */\nconst KEY_PATTERN = /^--[a-z][a-z0-9-]{0,62}$/;\n\nconst MARKER_ATTR = 'data-web5-theme-overrides';\n\nexport function applyThemeOverrides(\n  overrides?: Record<string, string> | null,\n): void {\n  if (typeof document === 'undefined') return;\n\n  const existing = document.head.querySelector(`style[${MARKER_ATTR}]`);\n  const entries = Object.entries(overrides ?? {}).filter(([key]) => {\n    const wellFormed = KEY_PATTERN.test(key);\n    if (!wellFormed) {\n      console.warn(`[web5-theme] Skipping malformed theme override key: ${key}`);\n    }\n    return wellFormed;\n  });\n\n  if (entries.length === 0) {\n    existing?.remove();\n    return;\n  }\n\n  const style = document.createElement('style');\n  style.setAttribute(MARKER_ATTR, '');\n  document.head.appendChild(style);\n  const sheet = style.sheet;\n  if (!sheet) {\n    style.remove();\n    return;\n  }\n  sheet.insertRule(`${WEB5_SCOPE} {}`, 0);\n  const rule = sheet.cssRules[0] as CSSStyleRule;\n  for (const [key, value] of entries) {\n    try {\n      rule.style.setProperty(key, value);\n    } catch {\n      // An engine that rejects the value leaves the token at its baked\n      // default — degraded theming, never broken CSS.\n    }\n  }\n  // Replace-on-reapply: the fresh element is appended (so it stays last in\n  // document order) before the stale one is dropped.\n  existing?.remove();\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,UAAU,QAAQ,cAAc;;AAEzC;;AAGA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,qBAA0C,GAAG,IAAIC,GAAG,CAAC,CAChE,cAAc,EAAE,cAAc,EAC9B,QAAQ,EAAE,mBAAmB,EAC7B,WAAW,EAAE,sBAAsB,EACnC,WAAW,EAAE,sBAAsB,EACnC,aAAa,EAAE,wBAAwB,EACvC,SAAS,EAAE,oBAAoB,EAC/B,UAAU,EAAE,qBAAqB,EACjC,UAAU,EAAE,SAAS,EAAE,QAAQ,EAC/B,UAAU,EACV,aAAa,EAAE,gBAAgB,EAC/B,WAAW,CACZ,CAAC;;AAEF;AACA,MAAMC,WAAW,GAAG,0BAA0B;AAE9C,MAAMC,WAAW,GAAG,2BAA2B;AAE/C,OAAO,SAASC,mBAAmBA,CACjCC,SAAyC,EACnC;EACN,IAAI,OAAOC,QAAQ,KAAK,WAAW,EAAE;EAErC,MAAMC,QAAQ,GAAGD,QAAQ,CAACE,IAAI,CAACC,aAAa,CAAC,SAASN,WAAW,GAAG,CAAC;EACrE,MAAMO,OAAO,GAAGC,MAAM,CAACD,OAAO,CAACL,SAAS,IAAI,CAAC,CAAC,CAAC,CAACO,MAAM,CAACC,IAAA,IAAW;IAAA,IAAV,CAACC,GAAG,CAAC,GAAAD,IAAA;IAC3D,MAAME,UAAU,GAAGb,WAAW,CAACc,IAAI,CAACF,GAAG,CAAC;IACxC,IAAI,CAACC,UAAU,EAAE;MACfE,OAAO,CAACC,IAAI,CAAC,uDAAuDJ,GAAG,EAAE,CAAC;IAC5E;IACA,OAAOC,UAAU;EACnB,CAAC,CAAC;EAEF,IAAIL,OAAO,CAACS,MAAM,KAAK,CAAC,EAAE;IACxBZ,QAAQ,YAARA,QAAQ,CAAEa,MAAM,CAAC,CAAC;IAClB;EACF;EAEA,MAAMC,KAAK,GAAGf,QAAQ,CAACgB,aAAa,CAAC,OAAO,CAAC;EAC7CD,KAAK,CAACE,YAAY,CAACpB,WAAW,EAAE,EAAE,CAAC;EACnCG,QAAQ,CAACE,IAAI,CAACgB,WAAW,CAACH,KAAK,CAAC;EAChC,MAAMI,KAAK,GAAGJ,KAAK,CAACI,KAAK;EACzB,IAAI,CAACA,KAAK,EAAE;IACVJ,KAAK,CAACD,MAAM,CAAC,CAAC;IACd;EACF;EACAK,KAAK,CAACC,UAAU,CAAC,GAAG3B,UAAU,KAAK,EAAE,CAAC,CAAC;EACvC,MAAM4B,IAAI,GAAGF,KAAK,CAACG,QAAQ,CAAC,CAAC,CAAiB;EAC9C,KAAK,MAAM,CAACd,GAAG,EAAEe,KAAK,CAAC,IAAInB,OAAO,EAAE;IAClC,IAAI;MACFiB,IAAI,CAACN,KAAK,CAACS,WAAW,CAAChB,GAAG,EAAEe,KAAK,CAAC;IACpC,CAAC,CAAC,MAAM;MACN;MACA;IAAA;EAEJ;EACA;EACA;EACAtB,QAAQ,YAARA,QAAQ,CAAEa,MAAM,CAAC,CAAC;AACpB","ignoreList":[]}
+{"version":3,"names":["WEB5_SCOPE","traceThemeOverrides","THEME_TOKEN_CONTRACT","bucketOf","hostAliasFor","THEME_OVERRIDE_TOKENS","Set","Object","keys","KEY_PATTERN","MARKER_ATTR","applyThemeOverrides","overrides","document","existing","head","querySelector","entries","filter","_ref","key","wellFormed","test","console","warn","length","remove","style","createElement","setAttribute","appendChild","sheet","insertRule","rule","cssRules","applied","value","target","setProperty","push"],"sources":["../../../src/client/applyThemeOverrides.ts"],"sourcesContent":["/**\n * Runtime theme token injection (DL #131).\n *\n * `Configuration.themeOverrides` carries per-store CSS custom-property\n * overrides (`--primary`, `--radius`, `--heading`, ...) computed from the\n * store's own theme (e.g. the Shopify `settings_data.json` extractor). This\n * applies them to the page so they win over the bundle's baked `theme.css`:\n *\n * - **Scoped, not `:root`**: the rule targets `WEB5_SCOPE`, the same\n *   `:is(#root, .w5-root, [data-web5-placement], .debug-view)` selector every\n *   compiled bundle stylesheet uses — host-page styling is never touched, and\n *   equal specificity + later document order makes the override win. Callers\n *   must therefore apply AFTER the client bundle's CSS is in the document.\n * - **Bucketed, since DL #193**: a `brand` token (colour roles, font families)\n *   is written as itself, so the store's identity beats the template's. Every\n *   other key — `host` tokens and anything the contract has never heard of —\n *   is written as its `--web5-host-*` alias, which core's stylesheets consume\n *   as a `var()` fallback. A template stating the real token therefore wins on\n *   shape, and an unknown key is inert rather than dangerous: a custom property\n *   nothing references renders nothing, so an adapter that learns to read a new\n *   token cannot silently override a template.\n * - **The token set stays open, but the destination changed.** Before DL #193\n *   an unrecognised key was applied verbatim, so a template could consume\n *   `var(--foo)` and grow a token with no release. It now arrives as\n *   `--web5-host-foo`, so the template consumes `var(--web5-host-foo, <default>)`\n *   instead. One line different, and the provenance is explicit — the wiring\n *   line is what activates a host token, not the contract entry.\n * - The mandatory `--` prefix means an override can only define custom\n *   properties — it can never set a real CSS property inside the scope. The\n *   server enforces the same shape (plus value sanitation) at write time.\n * - **Values are inert**: entries are written with\n *   `CSSStyleDeclaration.setProperty`, never string-concatenated into CSS, so\n *   a hostile value cannot terminate the declaration or open a new rule.\n * - **Idempotent**: one marker element per document, replaced wholesale on\n *   re-apply; empty/absent input removes it.\n */\nimport { WEB5_SCOPE } from '../hostScope';\nimport { traceThemeOverrides } from './themeDebug';\nimport {\n  THEME_TOKEN_CONTRACT,\n  bucketOf,\n  hostAliasFor,\n} from '../theme/tokenContract';\n\n/** A themeOverrides key: always a CSS custom property. */\nexport type ThemeOverrideKey = `--${string}`;\n\n/**\n * Writer-side shape for a theme override map. The catalog below documents\n * the tokens the seed consumes today; the type stays open so new tokens\n * flow end-to-end with no release anywhere but the seed.\n */\nexport type ThemeOverrides = Record<ThemeOverrideKey, string>;\n\n/**\n * The known token catalog. GUIDANCE, NOT A GATE — `applyThemeOverrides` still\n * applies any well-formed custom property, so the vocabulary can grow without a\n * release here.\n *\n * Derived from `@wix/web5-token-contract` rather than restated, because two\n * hand-maintained copies of one list is how they drift. The contract also\n * carries what this Set cannot: which bucket each token is in, and therefore\n * who wins when a store and a template disagree.\n */\nexport const THEME_OVERRIDE_TOKENS: ReadonlySet<string> = new Set(\n  Object.keys(THEME_TOKEN_CONTRACT),\n);\n\n/** Mirrors the server's Consts.ThemeOverrideKeyPattern. */\nconst KEY_PATTERN = /^--[a-z][a-z0-9-]{0,62}$/;\n\nconst MARKER_ATTR = 'data-web5-theme-overrides';\n\nexport function applyThemeOverrides(\n  overrides?: Record<string, string> | null,\n): void {\n  if (typeof document === 'undefined') {\n    return;\n  }\n\n  const existing = document.head.querySelector(`style[${MARKER_ATTR}]`);\n  const entries = Object.entries(overrides ?? {}).filter(([key]) => {\n    const wellFormed = KEY_PATTERN.test(key);\n    if (!wellFormed) {\n      console.warn(\n        `[web5-theme] Skipping malformed theme override key: ${key}`,\n      );\n    }\n    return wellFormed;\n  });\n\n  if (entries.length === 0) {\n    existing?.remove();\n    // Nothing to apply is itself a traceable answer: it means every token on\n    // the page is the template's, which is otherwise indistinguishable from\n    // tracing having failed.\n    traceThemeOverrides([]);\n    return;\n  }\n\n  const style = document.createElement('style');\n  style.setAttribute(MARKER_ATTR, '');\n  document.head.appendChild(style);\n  const sheet = style.sheet;\n  if (!sheet) {\n    style.remove();\n    return;\n  }\n  sheet.insertRule(`${WEB5_SCOPE} {}`, 0);\n  const rule = sheet.cssRules[0] as CSSStyleRule;\n  const applied: [string, string][] = [];\n  for (const [key, value] of entries) {\n    // Brand wins over the template, so it is written as the token the\n    // stylesheets actually read. Everything else lands in the host namespace,\n    // where core consumes it only as a fallback the template can beat.\n    const target = bucketOf(key) === 'brand' ? key : hostAliasFor(key);\n    try {\n      rule.style.setProperty(target, value);\n      applied.push([key, value]);\n    } catch {\n      // An engine that rejects the value leaves the token at its baked\n      // default — degraded theming, never broken CSS.\n    }\n  }\n  // Replace-on-reapply: the fresh element is appended (so it stays last in\n  // document order) before the stale one is dropped.\n  existing?.remove();\n  // AFTER the stale element is gone, so the resolved values traced below are\n  // the ones the page will actually render. Off unless explicitly enabled.\n  traceThemeOverrides(applied);\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,UAAU,QAAQ,cAAc;AACzC,SAASC,mBAAmB,QAAQ,cAAc;AAClD,SACEC,oBAAoB,EACpBC,QAAQ,EACRC,YAAY,QACP,wBAAwB;;AAE/B;;AAGA;AACA;AACA;AACA;AACA;;AAGA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,MAAMC,qBAA0C,GAAG,IAAIC,GAAG,CAC/DC,MAAM,CAACC,IAAI,CAACN,oBAAoB,CAClC,CAAC;;AAED;AACA,MAAMO,WAAW,GAAG,0BAA0B;AAE9C,MAAMC,WAAW,GAAG,2BAA2B;AAE/C,OAAO,SAASC,mBAAmBA,CACjCC,SAAyC,EACnC;EACN,IAAI,OAAOC,QAAQ,KAAK,WAAW,EAAE;IACnC;EACF;EAEA,MAAMC,QAAQ,GAAGD,QAAQ,CAACE,IAAI,CAACC,aAAa,CAAC,SAASN,WAAW,GAAG,CAAC;EACrE,MAAMO,OAAO,GAAGV,MAAM,CAACU,OAAO,CAACL,SAAS,IAAI,CAAC,CAAC,CAAC,CAACM,MAAM,CAACC,IAAA,IAAW;IAAA,IAAV,CAACC,GAAG,CAAC,GAAAD,IAAA;IAC3D,MAAME,UAAU,GAAGZ,WAAW,CAACa,IAAI,CAACF,GAAG,CAAC;IACxC,IAAI,CAACC,UAAU,EAAE;MACfE,OAAO,CAACC,IAAI,CACV,uDAAuDJ,GAAG,EAC5D,CAAC;IACH;IACA,OAAOC,UAAU;EACnB,CAAC,CAAC;EAEF,IAAIJ,OAAO,CAACQ,MAAM,KAAK,CAAC,EAAE;IACxBX,QAAQ,YAARA,QAAQ,CAAEY,MAAM,CAAC,CAAC;IAClB;IACA;IACA;IACAzB,mBAAmB,CAAC,EAAE,CAAC;IACvB;EACF;EAEA,MAAM0B,KAAK,GAAGd,QAAQ,CAACe,aAAa,CAAC,OAAO,CAAC;EAC7CD,KAAK,CAACE,YAAY,CAACnB,WAAW,EAAE,EAAE,CAAC;EACnCG,QAAQ,CAACE,IAAI,CAACe,WAAW,CAACH,KAAK,CAAC;EAChC,MAAMI,KAAK,GAAGJ,KAAK,CAACI,KAAK;EACzB,IAAI,CAACA,KAAK,EAAE;IACVJ,KAAK,CAACD,MAAM,CAAC,CAAC;IACd;EACF;EACAK,KAAK,CAACC,UAAU,CAAC,GAAGhC,UAAU,KAAK,EAAE,CAAC,CAAC;EACvC,MAAMiC,IAAI,GAAGF,KAAK,CAACG,QAAQ,CAAC,CAAC,CAAiB;EAC9C,MAAMC,OAA2B,GAAG,EAAE;EACtC,KAAK,MAAM,CAACf,GAAG,EAAEgB,KAAK,CAAC,IAAInB,OAAO,EAAE;IAClC;IACA;IACA;IACA,MAAMoB,MAAM,GAAGlC,QAAQ,CAACiB,GAAG,CAAC,KAAK,OAAO,GAAGA,GAAG,GAAGhB,YAAY,CAACgB,GAAG,CAAC;IAClE,IAAI;MACFa,IAAI,CAACN,KAAK,CAACW,WAAW,CAACD,MAAM,EAAED,KAAK,CAAC;MACrCD,OAAO,CAACI,IAAI,CAAC,CAACnB,GAAG,EAAEgB,KAAK,CAAC,CAAC;IAC5B,CAAC,CAAC,MAAM;MACN;MACA;IAAA;EAEJ;EACA;EACA;EACAtB,QAAQ,YAARA,QAAQ,CAAEY,MAAM,CAAC,CAAC;EAClB;EACA;EACAzB,mBAAmB,CAACkC,OAAO,CAAC;AAC9B","ignoreList":[]}

package/dist/esm/client/themeDebug.js

@@ -0,0 +1,131 @@
+/**
+ * Theme-override tracing (debug-only).
+ *
+ * Answers the one question the token pipeline cannot otherwise be asked:
+ * **which layer actually won?**
+ *
+ * Since DL #193 a `brand` token is written as itself and everything else as its
+ * `--web5-host-*` alias, which core's stylesheets consume as a `var()` fallback
+ * a template can beat. That makes the outcome a cascade decision, and a cascade
+ * decision is invisible — there is no callback, no return value, and nothing in
+ * the DOM to read. Worse, `applyThemeOverrides` writes through the CSSOM
+ * (`insertRule` + `setProperty`, never `textContent`) so that a hostile value
+ * can never terminate a declaration, which means DevTools renders the marker as
+ * `<style data-web5-theme-overrides="">` — an empty tag, with the rules real but
+ * nowhere in the DOM tree. Every part of that is deliberate and every part of it
+ * looks broken.
+ *
+ * So this reads the resolved value back off the mount **after** the rule is in,
+ * and reports what the browser actually decided:
+ *
+ *   [web5:theme] --radius   host   wrote --web5-host-radius=0rem  →  1.25rem  TEMPLATE
+ *   [web5:theme] --primary  brand  wrote --primary=0 0% 9%        →  0 0% 9%  STORE
+ *
+ * Off by default. Enable with `?web5DebugTheme=1` (one-shot, wins over storage)
+ * or `localStorage["web5_debug_theme"] = "1"` (sticky) — the same shape as
+ * `matchDebug`, so there is one convention to learn rather than two.
+ *
+ * It is gated rather than always-on because reading a computed value forces a
+ * style recalculation, and this runs during page setup. One read is taken for
+ * the whole batch, not one per token.
+ */
+import { WEB5_SCOPES } from '../hostScope.js';
+import { bucketOf, hostAliasFor } from '../theme/tokenContract.js';
+export const THEME_DEBUG_KEY = 'web5_debug_theme';
+
+/** Query param that forces theme tracing on, overriding localStorage. */
+export const THEME_DEBUG_QUERY_PARAM = 'web5DebugTheme';
+const LOG_PREFIX = '[web5:theme]';
+const isTruthy = value => value === '1' || value === 'true';
+let cached = null;
+
+/** Whether theme tracing is enabled. Memoized — resolved once per page load. */
+export const isThemeDebugEnabled = () => {
+  if (cached !== null) {
+    return cached;
+  }
+  cached = false;
+  try {
+    if (isTruthy(new URLSearchParams(window.location.search).get(THEME_DEBUG_QUERY_PARAM))) {
+      cached = true;
+      return cached;
+    }
+  } catch {
+    // window / URLSearchParams unavailable (SSR, non-DOM environments).
+  }
+  try {
+    cached = isTruthy(localStorage.getItem(THEME_DEBUG_KEY));
+  } catch {
+    // localStorage can throw in privacy mode / non-DOM environments.
+  }
+  return cached;
+};
+
+/** Test seam — the flag is memoized for the page, so tests must be able to clear it. */
+export const resetThemeDebugCache = () => {
+  cached = null;
+};
+/**
+ * Report what each override did, after the rule is live.
+ *
+ * `applied` is what `applyThemeOverrides` actually wrote — already filtered for
+ * key shape, so anything malformed has been dropped and warned about before
+ * reaching here.
+ */
+export function traceThemeOverrides(applied) {
+  if (!isThemeDebugEnabled()) {
+    return;
+  }
+  if (applied.length === 0) {
+    // Silence here would be indistinguishable from tracing being broken, and
+    // "no overrides reached the page" is itself the answer often enough — a
+    // store with nothing imported means every token is the template's.
+    // eslint-disable-next-line no-console
+    console.info(`${LOG_PREFIX} no overrides applied — nothing usable arrived for this store, so every token is whatever the template and core defaults say`);
+    return;
+  }
+  let mount = null;
+  try {
+    mount = document.querySelector(WEB5_SCOPES.join(','));
+  } catch {
+    // Malformed selector cannot happen with the constant, but querySelector is
+    // the one call here that can throw, and a debug aid must never be the thing
+    // that breaks a page.
+  }
+  if (!mount) {
+    console.warn(`${LOG_PREFIX} no mount found (${WEB5_SCOPES.join(', ')}) — tokens were written, but their resolved values cannot be read`);
+    return;
+  }
+
+  // One computed-style read for the whole batch: the expensive part is the style
+  // recalculation it forces, not the per-property lookups off the result.
+  const computed = getComputedStyle(mount);
+  const rows = applied.map(_ref => {
+    let [token, value] = _ref;
+    const bucket = bucketOf(token);
+    const target = bucket === 'brand' ? token : hostAliasFor(token);
+    const resolved = computed.getPropertyValue(token).trim();
+    const wanted = value.trim();
+    return {
+      token,
+      bucket,
+      'written as': target,
+      'store said': wanted,
+      'resolves to': resolved || '(nothing reads it)',
+      winner: !resolved ? 'NOBODY — no stylesheet consumes this token' : resolved === wanted ? 'STORE' : 'TEMPLATE'
+    };
+  });
+  const overridden = rows.filter(r => r.winner === 'TEMPLATE').length;
+  const inert = rows.filter(r => r.winner.startsWith('NOBODY')).length;
+
+  /* eslint-disable no-console */
+  console.groupCollapsed(`${LOG_PREFIX} ${rows.length} override(s) applied · ${overridden} kept by the template · ${inert} inert`);
+  console.table(rows);
+  if (inert > 0) {
+    console.info(`${LOG_PREFIX} "inert" means the value was written but no stylesheet reads that token — ` + `for a host token that means core has no \`var(--web5-host-…)\` wiring for it yet.`);
+  }
+  console.info(`${LOG_PREFIX} the marker <style data-web5-theme-overrides> looks empty in DevTools on purpose: ` + `rules are inserted through the CSSOM, never as text. Read them with ` + `document.querySelector('style[data-web5-theme-overrides]').sheet.cssRules[0].cssText`);
+  console.groupEnd();
+  /* eslint-enable no-console */
+}
+//# sourceMappingURL=themeDebug.js.map

package/dist/esm/client/themeDebug.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["WEB5_SCOPES","bucketOf","hostAliasFor","THEME_DEBUG_KEY","THEME_DEBUG_QUERY_PARAM","LOG_PREFIX","isTruthy","value","cached","isThemeDebugEnabled","URLSearchParams","window","location","search","get","localStorage","getItem","resetThemeDebugCache","traceThemeOverrides","applied","length","console","info","mount","document","querySelector","join","warn","computed","getComputedStyle","rows","map","_ref","token","bucket","target","resolved","getPropertyValue","trim","wanted","winner","overridden","filter","r","inert","startsWith","groupCollapsed","table","groupEnd"],"sources":["../../../src/client/themeDebug.ts"],"sourcesContent":["/**\n * Theme-override tracing (debug-only).\n *\n * Answers the one question the token pipeline cannot otherwise be asked:\n * **which layer actually won?**\n *\n * Since DL #193 a `brand` token is written as itself and everything else as its\n * `--web5-host-*` alias, which core's stylesheets consume as a `var()` fallback\n * a template can beat. That makes the outcome a cascade decision, and a cascade\n * decision is invisible — there is no callback, no return value, and nothing in\n * the DOM to read. Worse, `applyThemeOverrides` writes through the CSSOM\n * (`insertRule` + `setProperty`, never `textContent`) so that a hostile value\n * can never terminate a declaration, which means DevTools renders the marker as\n * `<style data-web5-theme-overrides=\"\">` — an empty tag, with the rules real but\n * nowhere in the DOM tree. Every part of that is deliberate and every part of it\n * looks broken.\n *\n * So this reads the resolved value back off the mount **after** the rule is in,\n * and reports what the browser actually decided:\n *\n *   [web5:theme] --radius   host   wrote --web5-host-radius=0rem  →  1.25rem  TEMPLATE\n *   [web5:theme] --primary  brand  wrote --primary=0 0% 9%        →  0 0% 9%  STORE\n *\n * Off by default. Enable with `?web5DebugTheme=1` (one-shot, wins over storage)\n * or `localStorage[\"web5_debug_theme\"] = \"1\"` (sticky) — the same shape as\n * `matchDebug`, so there is one convention to learn rather than two.\n *\n * It is gated rather than always-on because reading a computed value forces a\n * style recalculation, and this runs during page setup. One read is taken for\n * the whole batch, not one per token.\n */\nimport { WEB5_SCOPES } from '../hostScope';\nimport { bucketOf, hostAliasFor } from '../theme/tokenContract';\n\nexport const THEME_DEBUG_KEY = 'web5_debug_theme';\n\n/** Query param that forces theme tracing on, overriding localStorage. */\nexport const THEME_DEBUG_QUERY_PARAM = 'web5DebugTheme';\n\nconst LOG_PREFIX = '[web5:theme]';\n\nconst isTruthy = (value: unknown): boolean => value === '1' || value === 'true';\n\nlet cached: boolean | null = null;\n\n/** Whether theme tracing is enabled. Memoized — resolved once per page load. */\nexport const isThemeDebugEnabled = (): boolean => {\n  if (cached !== null) {\n    return cached;\n  }\n  cached = false;\n  try {\n    if (\n      isTruthy(\n        new URLSearchParams(window.location.search).get(\n          THEME_DEBUG_QUERY_PARAM,\n        ),\n      )\n    ) {\n      cached = true;\n      return cached;\n    }\n  } catch {\n    // window / URLSearchParams unavailable (SSR, non-DOM environments).\n  }\n  try {\n    cached = isTruthy(localStorage.getItem(THEME_DEBUG_KEY));\n  } catch {\n    // localStorage can throw in privacy mode / non-DOM environments.\n  }\n  return cached;\n};\n\n/** Test seam — the flag is memoized for the page, so tests must be able to clear it. */\nexport const resetThemeDebugCache = (): void => {\n  cached = null;\n};\n\ninterface TraceRow {\n  token: string;\n  bucket: string;\n  'written as': string;\n  'store said': string;\n  'resolves to': string;\n  winner: string;\n}\n\n/**\n * Report what each override did, after the rule is live.\n *\n * `applied` is what `applyThemeOverrides` actually wrote — already filtered for\n * key shape, so anything malformed has been dropped and warned about before\n * reaching here.\n */\nexport function traceThemeOverrides(applied: [string, string][]): void {\n  if (!isThemeDebugEnabled()) {\n    return;\n  }\n  if (applied.length === 0) {\n    // Silence here would be indistinguishable from tracing being broken, and\n    // \"no overrides reached the page\" is itself the answer often enough — a\n    // store with nothing imported means every token is the template's.\n    // eslint-disable-next-line no-console\n    console.info(\n      `${LOG_PREFIX} no overrides applied — nothing usable arrived for this store, so every token is whatever the template and core defaults say`,\n    );\n    return;\n  }\n  let mount: Element | null = null;\n  try {\n    mount = document.querySelector(WEB5_SCOPES.join(','));\n  } catch {\n    // Malformed selector cannot happen with the constant, but querySelector is\n    // the one call here that can throw, and a debug aid must never be the thing\n    // that breaks a page.\n  }\n  if (!mount) {\n    console.warn(\n      `${LOG_PREFIX} no mount found (${WEB5_SCOPES.join(\n        ', ',\n      )}) — tokens were written, but their resolved values cannot be read`,\n    );\n    return;\n  }\n\n  // One computed-style read for the whole batch: the expensive part is the style\n  // recalculation it forces, not the per-property lookups off the result.\n  const computed = getComputedStyle(mount);\n  const rows: TraceRow[] = applied.map(([token, value]) => {\n    const bucket = bucketOf(token);\n    const target = bucket === 'brand' ? token : hostAliasFor(token);\n    const resolved = computed.getPropertyValue(token).trim();\n    const wanted = value.trim();\n    return {\n      token,\n      bucket,\n      'written as': target,\n      'store said': wanted,\n      'resolves to': resolved || '(nothing reads it)',\n      winner: !resolved\n        ? 'NOBODY — no stylesheet consumes this token'\n        : resolved === wanted\n        ? 'STORE'\n        : 'TEMPLATE',\n    };\n  });\n\n  const overridden = rows.filter((r) => r.winner === 'TEMPLATE').length;\n  const inert = rows.filter((r) => r.winner.startsWith('NOBODY')).length;\n\n  /* eslint-disable no-console */\n  console.groupCollapsed(\n    `${LOG_PREFIX} ${rows.length} override(s) applied · ${overridden} kept by the template · ${inert} inert`,\n  );\n  console.table(rows);\n  if (inert > 0) {\n    console.info(\n      `${LOG_PREFIX} \"inert\" means the value was written but no stylesheet reads that token — ` +\n        `for a host token that means core has no \\`var(--web5-host-…)\\` wiring for it yet.`,\n    );\n  }\n  console.info(\n    `${LOG_PREFIX} the marker <style data-web5-theme-overrides> looks empty in DevTools on purpose: ` +\n      `rules are inserted through the CSSOM, never as text. Read them with ` +\n      `document.querySelector('style[data-web5-theme-overrides]').sheet.cssRules[0].cssText`,\n  );\n  console.groupEnd();\n  /* eslint-enable no-console */\n}\n"],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,WAAW,QAAQ,cAAc;AAC1C,SAASC,QAAQ,EAAEC,YAAY,QAAQ,wBAAwB;AAE/D,OAAO,MAAMC,eAAe,GAAG,kBAAkB;;AAEjD;AACA,OAAO,MAAMC,uBAAuB,GAAG,gBAAgB;AAEvD,MAAMC,UAAU,GAAG,cAAc;AAEjC,MAAMC,QAAQ,GAAIC,KAAc,IAAcA,KAAK,KAAK,GAAG,IAAIA,KAAK,KAAK,MAAM;AAE/E,IAAIC,MAAsB,GAAG,IAAI;;AAEjC;AACA,OAAO,MAAMC,mBAAmB,GAAGA,CAAA,KAAe;EAChD,IAAID,MAAM,KAAK,IAAI,EAAE;IACnB,OAAOA,MAAM;EACf;EACAA,MAAM,GAAG,KAAK;EACd,IAAI;IACF,IACEF,QAAQ,CACN,IAAII,eAAe,CAACC,MAAM,CAACC,QAAQ,CAACC,MAAM,CAAC,CAACC,GAAG,CAC7CV,uBACF,CACF,CAAC,EACD;MACAI,MAAM,GAAG,IAAI;MACb,OAAOA,MAAM;IACf;EACF,CAAC,CAAC,MAAM;IACN;EAAA;EAEF,IAAI;IACFA,MAAM,GAAGF,QAAQ,CAACS,YAAY,CAACC,OAAO,CAACb,eAAe,CAAC,CAAC;EAC1D,CAAC,CAAC,MAAM;IACN;EAAA;EAEF,OAAOK,MAAM;AACf,CAAC;;AAED;AACA,OAAO,MAAMS,oBAAoB,GAAGA,CAAA,KAAY;EAC9CT,MAAM,GAAG,IAAI;AACf,CAAC;AAWD;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASU,mBAAmBA,CAACC,OAA2B,EAAQ;EACrE,IAAI,CAACV,mBAAmB,CAAC,CAAC,EAAE;IAC1B;EACF;EACA,IAAIU,OAAO,CAACC,MAAM,KAAK,CAAC,EAAE;IACxB;IACA;IACA;IACA;IACAC,OAAO,CAACC,IAAI,CACV,GAAGjB,UAAU,8HACf,CAAC;IACD;EACF;EACA,IAAIkB,KAAqB,GAAG,IAAI;EAChC,IAAI;IACFA,KAAK,GAAGC,QAAQ,CAACC,aAAa,CAACzB,WAAW,CAAC0B,IAAI,CAAC,GAAG,CAAC,CAAC;EACvD,CAAC,CAAC,MAAM;IACN;IACA;IACA;EAAA;EAEF,IAAI,CAACH,KAAK,EAAE;IACVF,OAAO,CAACM,IAAI,CACV,GAAGtB,UAAU,oBAAoBL,WAAW,CAAC0B,IAAI,CAC/C,IACF,CAAC,mEACH,CAAC;IACD;EACF;;EAEA;EACA;EACA,MAAME,QAAQ,GAAGC,gBAAgB,CAACN,KAAK,CAAC;EACxC,MAAMO,IAAgB,GAAGX,OAAO,CAACY,GAAG,CAACC,IAAA,IAAoB;IAAA,IAAnB,CAACC,KAAK,EAAE1B,KAAK,CAAC,GAAAyB,IAAA;IAClD,MAAME,MAAM,GAAGjC,QAAQ,CAACgC,KAAK,CAAC;IAC9B,MAAME,MAAM,GAAGD,MAAM,KAAK,OAAO,GAAGD,KAAK,GAAG/B,YAAY,CAAC+B,KAAK,CAAC;IAC/D,MAAMG,QAAQ,GAAGR,QAAQ,CAACS,gBAAgB,CAACJ,KAAK,CAAC,CAACK,IAAI,CAAC,CAAC;IACxD,MAAMC,MAAM,GAAGhC,KAAK,CAAC+B,IAAI,CAAC,CAAC;IAC3B,OAAO;MACLL,KAAK;MACLC,MAAM;MACN,YAAY,EAAEC,MAAM;MACpB,YAAY,EAAEI,MAAM;MACpB,aAAa,EAAEH,QAAQ,IAAI,oBAAoB;MAC/CI,MAAM,EAAE,CAACJ,QAAQ,GACb,4CAA4C,GAC5CA,QAAQ,KAAKG,MAAM,GACnB,OAAO,GACP;IACN,CAAC;EACH,CAAC,CAAC;EAEF,MAAME,UAAU,GAAGX,IAAI,CAACY,MAAM,CAAEC,CAAC,IAAKA,CAAC,CAACH,MAAM,KAAK,UAAU,CAAC,CAACpB,MAAM;EACrE,MAAMwB,KAAK,GAAGd,IAAI,CAACY,MAAM,CAAEC,CAAC,IAAKA,CAAC,CAACH,MAAM,CAACK,UAAU,CAAC,QAAQ,CAAC,CAAC,CAACzB,MAAM;;EAEtE;EACAC,OAAO,CAACyB,cAAc,CACpB,GAAGzC,UAAU,IAAIyB,IAAI,CAACV,MAAM,0BAA0BqB,UAAU,2BAA2BG,KAAK,QAClG,CAAC;EACDvB,OAAO,CAAC0B,KAAK,CAACjB,IAAI,CAAC;EACnB,IAAIc,KAAK,GAAG,CAAC,EAAE;IACbvB,OAAO,CAACC,IAAI,CACV,GAAGjB,UAAU,4EAA4E,GACvF,mFACJ,CAAC;EACH;EACAgB,OAAO,CAACC,IAAI,CACV,GAAGjB,UAAU,oFAAoF,GAC/F,sEAAsE,GACtE,sFACJ,CAAC;EACDgB,OAAO,CAAC2B,QAAQ,CAAC,CAAC;EAClB;AACF","ignoreList":[]}

package/dist/esm/index.js

@@ -142,6 +142,8 @@ export { getClientBundleOverride, isTrustedBundleHost } from './client/clientBun
 export { TEMPLATES_CDN_BASE, TEMPLATES_MANIFEST_URL, getTemplateOverride, isTemplatePickerRequested, isValidTemplateId, resolveClientBundleUrl } from './client/clientBundleUrl.js';
 export { mergeClientConfig } from './client/mergeClientConfig.js';
 export { applyThemeOverrides, THEME_OVERRIDE_TOKENS } from './client/applyThemeOverrides.js';
+export { THEME_TOKEN_CONTRACT, BRAND_TOKENS, TOKEN_NAME_PATTERN, bucketOf, hostAliasFor } from './theme/tokenContract.js';
+export { isThemeDebugEnabled, THEME_DEBUG_KEY, THEME_DEBUG_QUERY_PARAM } from './client/themeDebug.js';
 
 // Placement renderer + DI helper (DL #088 D3.2, D3.4)
 export { PlacementResponseRenderer, PlacementSmoothHeight } from './components/placement/PlacementResponseRenderer.js';