@wix/web5-core 1.63.1 → 1.63.3

package/dist/cjs/theme/colorFormat.js

@@ -0,0 +1,105 @@
+"use strict";
+
+exports.__esModule = true;
+exports.hexToHslTriplet = hexToHslTriplet;
+exports.hslTripletToHex = hslTripletToHex;
+exports.isHslTriplet = isHslTriplet;
+/**
+ * Between the two spellings of a colour: the token's and the colour input's.
+ *
+ * A theme token is an HSL triplet with no wrapper — `262 83% 58%` — because the
+ * core bridge supplies the wrapper (`--color-primary: hsl(var(--primary))`), so
+ * a token carrying `hsl(...)` or a hex value produces `hsl(#7c3aed)` and the
+ * whole role falls back to nothing. `<input type="color">` speaks only
+ * `#rrggbb`. The owner panel therefore has to translate on every read and every
+ * write, and getting it wrong is invisible until a merchant's brand colour
+ * quietly stops applying.
+ *
+ * Round-tripping is deliberately NOT exact, and cannot be: 16.7M hex values map
+ * onto an HSL space this rounds to one decimal, so `hex → triplet → hex` can
+ * land a step away. What IS guaranteed is that the triplet is well-formed and
+ * within gamut, which is what the CSS needs; a merchant dragging a picker never
+ * sees the difference, and nothing downstream compares two colours for equality.
+ */
+
+/** `262 83% 58%` — the only spelling a colour token may carry. */
+const TRIPLET = /^(\d{1,3}(?:\.\d+)?)\s+(\d{1,3}(?:\.\d+)?)%\s+(\d{1,3}(?:\.\d+)?)%$/;
+const clamp = (n, min, max) => Math.min(max, Math.max(min, n));
+
+/** Trims to one decimal without leaving `58.0` behind. */
+const round = n => String(Math.round(n * 10) / 10);
+
+/** Whether a value is a bare HSL triplet — the shape a colour token must carry. */
+function isHslTriplet(value) {
+  const parts = TRIPLET.exec(value.trim());
+  if (!parts) {
+    return false;
+  }
+  const [, h, s, l] = parts;
+  return Number(h) <= 360 && Number(s) <= 100 && Number(l) <= 100;
+}
+
+/**
+ * `#7c3aed` → `262.1 83.3% 57.8%`.
+ *
+ * Returns null for anything that is not a 3- or 6-digit hex colour, so a caller
+ * writing a token can refuse rather than store a value CSS will drop.
+ */
+function hexToHslTriplet(hex) {
+  const raw = hex.trim().replace(/^#/, '');
+  const full = raw.length === 3 ? raw.split('').map(c => c + c).join('') : raw;
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) {
+    return null;
+  }
+  const r = parseInt(full.slice(0, 2), 16) / 255;
+  const g = parseInt(full.slice(2, 4), 16) / 255;
+  const b = parseInt(full.slice(4, 6), 16) / 255;
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  const d = max - min;
+
+  // Grey: hue and saturation are both meaningless, and any hue would do. Zero
+  // is the conventional answer and keeps the value stable across edits.
+  if (d === 0) {
+    return `0 0% ${round(l * 100)}%`;
+  }
+  const s = d / (1 - Math.abs(2 * l - 1));
+  let h;
+  if (max === r) {
+    h = (g - b) / d % 6;
+  } else if (max === g) {
+    h = (b - r) / d + 2;
+  } else {
+    h = (r - g) / d + 4;
+  }
+  h *= 60;
+  if (h < 0) {
+    h += 360;
+  }
+  return `${round(h)} ${round(s * 100)}% ${round(l * 100)}%`;
+}
+
+/**
+ * `262 83% 58%` → `#7c3aed`, for seeding a colour input.
+ *
+ * Returns null rather than a guess when the value is not a triplet — a token
+ * holding something else is a bug worth seeing as a blank control rather than
+ * as an arbitrary colour the merchant did not choose.
+ */
+function hslTripletToHex(triplet) {
+  const parts = TRIPLET.exec(triplet.trim());
+  if (!parts) {
+    return null;
+  }
+  const h = clamp(Number(parts[1]), 0, 360);
+  const s = clamp(Number(parts[2]), 0, 100) / 100;
+  const l = clamp(Number(parts[3]), 0, 100) / 100;
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const x = c * (1 - Math.abs(h / 60 % 2 - 1));
+  const m = l - c / 2;
+  const [r, g, b] = h < 60 ? [c, x, 0] : h < 120 ? [x, c, 0] : h < 180 ? [0, c, x] : h < 240 ? [0, x, c] : h < 300 ? [x, 0, c] : [c, 0, x];
+  const channel = v => Math.round((v + m) * 255).toString(16).padStart(2, '0');
+  return `#${channel(r)}${channel(g)}${channel(b)}`;
+}
+//# sourceMappingURL=colorFormat.js.map

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

@@ -0,0 +1 @@
+{"version":3,"names":["TRIPLET","clamp","n","min","max","Math","round","String","isHslTriplet","value","parts","exec","trim","h","s","l","Number","hexToHslTriplet","hex","raw","replace","full","length","split","map","c","join","test","r","parseInt","slice","g","b","d","abs","hslTripletToHex","triplet","x","m","channel","v","toString","padStart"],"sources":["../../../src/theme/colorFormat.ts"],"sourcesContent":["/**\n * Between the two spellings of a colour: the token's and the colour input's.\n *\n * A theme token is an HSL triplet with no wrapper — `262 83% 58%` — because the\n * core bridge supplies the wrapper (`--color-primary: hsl(var(--primary))`), so\n * a token carrying `hsl(...)` or a hex value produces `hsl(#7c3aed)` and the\n * whole role falls back to nothing. `<input type=\"color\">` speaks only\n * `#rrggbb`. The owner panel therefore has to translate on every read and every\n * write, and getting it wrong is invisible until a merchant's brand colour\n * quietly stops applying.\n *\n * Round-tripping is deliberately NOT exact, and cannot be: 16.7M hex values map\n * onto an HSL space this rounds to one decimal, so `hex → triplet → hex` can\n * land a step away. What IS guaranteed is that the triplet is well-formed and\n * within gamut, which is what the CSS needs; a merchant dragging a picker never\n * sees the difference, and nothing downstream compares two colours for equality.\n */\n\n/** `262 83% 58%` — the only spelling a colour token may carry. */\nconst TRIPLET = /^(\\d{1,3}(?:\\.\\d+)?)\\s+(\\d{1,3}(?:\\.\\d+)?)%\\s+(\\d{1,3}(?:\\.\\d+)?)%$/;\n\nconst clamp = (n: number, min: number, max: number): number =>\n  Math.min(max, Math.max(min, n));\n\n/** Trims to one decimal without leaving `58.0` behind. */\nconst round = (n: number): string => String(Math.round(n * 10) / 10);\n\n/** Whether a value is a bare HSL triplet — the shape a colour token must carry. */\nexport function isHslTriplet(value: string): boolean {\n  const parts = TRIPLET.exec(value.trim());\n  if (!parts) {\n    return false;\n  }\n  const [, h, s, l] = parts;\n  return Number(h) <= 360 && Number(s) <= 100 && Number(l) <= 100;\n}\n\n/**\n * `#7c3aed` → `262.1 83.3% 57.8%`.\n *\n * Returns null for anything that is not a 3- or 6-digit hex colour, so a caller\n * writing a token can refuse rather than store a value CSS will drop.\n */\nexport function hexToHslTriplet(hex: string): string | null {\n  const raw = hex.trim().replace(/^#/, '');\n  const full =\n    raw.length === 3\n      ? raw\n          .split('')\n          .map((c) => c + c)\n          .join('')\n      : raw;\n  if (!/^[0-9a-fA-F]{6}$/.test(full)) {\n    return null;\n  }\n\n  const r = parseInt(full.slice(0, 2), 16) / 255;\n  const g = parseInt(full.slice(2, 4), 16) / 255;\n  const b = parseInt(full.slice(4, 6), 16) / 255;\n\n  const max = Math.max(r, g, b);\n  const min = Math.min(r, g, b);\n  const l = (max + min) / 2;\n  const d = max - min;\n\n  // Grey: hue and saturation are both meaningless, and any hue would do. Zero\n  // is the conventional answer and keeps the value stable across edits.\n  if (d === 0) {\n    return `0 0% ${round(l * 100)}%`;\n  }\n\n  const s = d / (1 - Math.abs(2 * l - 1));\n  let h: number;\n  if (max === r) {\n    h = ((g - b) / d) % 6;\n  } else if (max === g) {\n    h = (b - r) / d + 2;\n  } else {\n    h = (r - g) / d + 4;\n  }\n  h *= 60;\n  if (h < 0) {\n    h += 360;\n  }\n\n  return `${round(h)} ${round(s * 100)}% ${round(l * 100)}%`;\n}\n\n/**\n * `262 83% 58%` → `#7c3aed`, for seeding a colour input.\n *\n * Returns null rather than a guess when the value is not a triplet — a token\n * holding something else is a bug worth seeing as a blank control rather than\n * as an arbitrary colour the merchant did not choose.\n */\nexport function hslTripletToHex(triplet: string): string | null {\n  const parts = TRIPLET.exec(triplet.trim());\n  if (!parts) {\n    return null;\n  }\n  const h = clamp(Number(parts[1]), 0, 360);\n  const s = clamp(Number(parts[2]), 0, 100) / 100;\n  const l = clamp(Number(parts[3]), 0, 100) / 100;\n\n  const c = (1 - Math.abs(2 * l - 1)) * s;\n  const x = c * (1 - Math.abs(((h / 60) % 2) - 1));\n  const m = l - c / 2;\n\n  const [r, g, b] =\n    h < 60\n      ? [c, x, 0]\n      : h < 120\n      ? [x, c, 0]\n      : h < 180\n      ? [0, c, x]\n      : h < 240\n      ? [0, x, c]\n      : h < 300\n      ? [x, 0, c]\n      : [c, 0, x];\n\n  const channel = (v: number): string =>\n    Math.round((v + m) * 255)\n      .toString(16)\n      .padStart(2, '0');\n\n  return `#${channel(r)}${channel(g)}${channel(b)}`;\n}\n"],"mappings":"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","ignoreList":[]}

package/dist/cjs/theme/tokenContract.js

@@ -1,7 +1,7 @@
 "use strict";
 
 exports.__esModule = true;
-exports.TOKEN_NAME_PATTERN = exports.THEME_TOKEN_CONTRACT = exports.BRAND_TOKENS = void 0;
+exports.TOKEN_NAME_PATTERN = exports.THEME_TOKEN_CONTRACT = exports.EDITABLE_TOKENS = exports.BRAND_TOKENS = void 0;
 exports.bucketOf = bucketOf;
 exports.hostAliasFor = hostAliasFor;
 /**
@@ -64,10 +64,23 @@ exports.hostAliasFor = hostAliasFor;
 
 /** Which layer wins when both a store and a template state this token. */
 
+/**
+ * A colour role. Giving one a label is what puts it in the owner's panel.
+ *
+ * The two travel together on purpose: `editable` without a label is a control
+ * with no name, and a label on a token nobody may set is a promise the panel
+ * cannot keep. One argument, one decision.
+ *
+ * Labels are the merchant's words rather than the token's — "Buttons & links",
+ * not "primary". Someone choosing their shop's colours is not reading a design
+ * system, and `--primary-foreground` is not a colour anyone picks: it is
+ * whatever stays legible ON primary, which the theme derives. Exposing the
+ * derived half is how a panel produces white text on a white button.
+ */
 const brandColor = label => ({
   bucket: 'brand',
   type: 'color-hsl',
-  editable: false,
+  editable: label !== undefined,
   ...(label === undefined ? {} : {
     label
   })
@@ -84,21 +97,21 @@ const brandColor = label => ({
  */
 const THEME_TOKEN_CONTRACT = exports.THEME_TOKEN_CONTRACT = Object.freeze({
   // ── brand · colour roles (18) ────────────────────────────────────────────
-  '--background': brandColor(),
-  '--foreground': brandColor(),
+  '--background': brandColor('Page background'),
+  '--foreground': brandColor('Text'),
   '--card': brandColor(),
   '--card-foreground': brandColor(),
   '--popover': brandColor(),
   '--popover-foreground': brandColor(),
-  '--primary': brandColor(),
+  '--primary': brandColor('Buttons & links'),
   '--primary-foreground': brandColor(),
   '--secondary': brandColor(),
   '--secondary-foreground': brandColor(),
   '--muted': brandColor(),
   '--muted-foreground': brandColor(),
-  '--accent': brandColor(),
+  '--accent': brandColor('Highlights'),
   '--accent-foreground': brandColor(),
-  '--border': brandColor(),
+  '--border': brandColor('Lines & borders'),
   '--input': brandColor(),
   '--ring': brandColor(),
   /**
@@ -108,7 +121,7 @@ const THEME_TOKEN_CONTRACT = exports.THEME_TOKEN_CONTRACT = Object.freeze({
    * 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(),
+  '--heading': brandColor('Headings'),
   // ── brand · type (2) ─────────────────────────────────────────────────────
   '--font-sans': {
     bucket: 'brand',
@@ -150,6 +163,17 @@ const BRAND_TOKENS = exports.BRAND_TOKENS = Object.freeze(new Set(Object.entries
  */
 const TOKEN_NAME_PATTERN = exports.TOKEN_NAME_PATTERN = /^--[a-z0-9-]+$/;
 
+/**
+ * What the owner's panel offers, in the order it offers it.
+ *
+ * Derived from the contract rather than listed again beside it, so a token
+ * cannot be editable in one place and absent from the other. The order is the
+ * declaration order above, which reads outside-in — the page, then its text,
+ * then the things drawn on it — and is a better first impression than
+ * alphabetical or than the order the tokens happen to be defined for CSS.
+ */
+const EDITABLE_TOKENS = exports.EDITABLE_TOKENS = Object.freeze(Object.entries(THEME_TOKEN_CONTRACT).filter(([, entry]) => entry.editable));
+
 /** `--radius` → `--web5-host-radius`. Derived, never stored: one fewer thing to get wrong. */
 function hostAliasFor(token) {
   return `--web5-host-${token.slice(2)}`;

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

@@ -1 +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":[]}
+{"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","EDITABLE_TOKENS","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\n/**\n * A colour role. Giving one a label is what puts it in the owner's panel.\n *\n * The two travel together on purpose: `editable` without a label is a control\n * with no name, and a label on a token nobody may set is a promise the panel\n * cannot keep. One argument, one decision.\n *\n * Labels are the merchant's words rather than the token's — \"Buttons & links\",\n * not \"primary\". Someone choosing their shop's colours is not reading a design\n * system, and `--primary-foreground` is not a colour anyone picks: it is\n * whatever stays legible ON primary, which the theme derives. Exposing the\n * derived half is how a panel produces white text on a white button.\n */\nconst brandColor = (label?: string): TokenContractEntry => ({\n  bucket: 'brand',\n  type: 'color-hsl',\n  editable: label !== undefined,\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('Page background'),\n    '--foreground': brandColor('Text'),\n    '--card': brandColor(),\n    '--card-foreground': brandColor(),\n    '--popover': brandColor(),\n    '--popover-foreground': brandColor(),\n    '--primary': brandColor('Buttons & links'),\n    '--primary-foreground': brandColor(),\n    '--secondary': brandColor(),\n    '--secondary-foreground': brandColor(),\n    '--muted': brandColor(),\n    '--muted-foreground': brandColor(),\n    '--accent': brandColor('Highlights'),\n    '--accent-foreground': brandColor(),\n    '--border': brandColor('Lines & borders'),\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('Headings'),\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/**\n * What the owner's panel offers, in the order it offers it.\n *\n * Derived from the contract rather than listed again beside it, so a token\n * cannot be editable in one place and absent from the other. The order is the\n * declaration order above, which reads outside-in — the page, then its text,\n * then the things drawn on it — and is a better first impression than\n * alphabetical or than the order the tokens happen to be defined for CSS.\n */\nexport const EDITABLE_TOKENS: readonly (readonly [\n  token: string,\n  entry: TokenContractEntry,\n])[] = Object.freeze(\n  Object.entries(THEME_TOKEN_CONTRACT).filter(([, entry]) => entry.editable),\n) as readonly (readonly [string, TokenContractEntry])[];\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":";;;;;;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;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AAEA;;AAUA;;AAYA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,MAAMA,UAAU,GAAIC,KAAc,KAA0B;EAC1DC,MAAM,EAAE,OAAO;EACfC,IAAI,EAAE,WAAW;EACjBC,QAAQ,EAAEH,KAAK,KAAKI,SAAS;EAC7B,IAAIJ,KAAK,KAAKI,SAAS,GAAG,CAAC,CAAC,GAAG;IAAEJ;EAAM,CAAC;AAC1C,CAAC,CAAC;;AAEF;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMK,oBAAkE,GAAAC,OAAA,CAAAD,oBAAA,GAC7EE,MAAM,CAACC,MAAM,CAAC;EACZ;EACA,cAAc,EAAET,UAAU,CAAC,iBAAiB,CAAC;EAC7C,cAAc,EAAEA,UAAU,CAAC,MAAM,CAAC;EAClC,QAAQ,EAAEA,UAAU,CAAC,CAAC;EACtB,mBAAmB,EAAEA,UAAU,CAAC,CAAC;EACjC,WAAW,EAAEA,UAAU,CAAC,CAAC;EACzB,sBAAsB,EAAEA,UAAU,CAAC,CAAC;EACpC,WAAW,EAAEA,UAAU,CAAC,iBAAiB,CAAC;EAC1C,sBAAsB,EAAEA,UAAU,CAAC,CAAC;EACpC,aAAa,EAAEA,UAAU,CAAC,CAAC;EAC3B,wBAAwB,EAAEA,UAAU,CAAC,CAAC;EACtC,SAAS,EAAEA,UAAU,CAAC,CAAC;EACvB,oBAAoB,EAAEA,UAAU,CAAC,CAAC;EAClC,UAAU,EAAEA,UAAU,CAAC,YAAY,CAAC;EACpC,qBAAqB,EAAEA,UAAU,CAAC,CAAC;EACnC,UAAU,EAAEA,UAAU,CAAC,iBAAiB,CAAC;EACzC,SAAS,EAAEA,UAAU,CAAC,CAAC;EACvB,QAAQ,EAAEA,UAAU,CAAC,CAAC;EAEtB;AACJ;AACA;AACA;AACA;AACA;AACA;EACI,WAAW,EAAEA,UAAU,CAAC,UAAU,CAAC;EAEnC;EACA,aAAa,EAAE;IAAEE,MAAM,EAAE,OAAO;IAAEC,IAAI,EAAE,YAAY;IAAEC,QAAQ,EAAE;EAAM,CAAC;EACvE,gBAAgB,EAAE;IAAEF,MAAM,EAAE,OAAO;IAAEC,IAAI,EAAE,YAAY;IAAEC,QAAQ,EAAE;EAAM,CAAC;EAE1E;EACA;AACJ;AACA;AACA;AACA;EACI,UAAU,EAAE;IACVF,MAAM,EAAE,MAAM;IACdC,IAAI,EAAE,QAAQ;IACdC,QAAQ,EAAE,IAAI;IACdH,KAAK,EAAE;EACT;AACF,CAAC,CAAC;;AAEJ;AACA;AACA;AACA;AACO,MAAMS,YAAiC,GAAAH,OAAA,CAAAG,YAAA,GAAGF,MAAM,CAACC,MAAM,CAC5D,IAAIE,GAAG,CACLH,MAAM,CAACI,OAAO,CAACN,oBAAoB,CAAC,CACjCO,MAAM,CAAC,CAAC,GAAGC,KAAK,CAAC,KAAKA,KAAK,CAACZ,MAAM,KAAK,OAAO,CAAC,CAC/Ca,GAAG,CAAC,CAAC,CAACC,KAAK,CAAC,KAAKA,KAAK,CAC3B,CACF,CAAwB;;AAExB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMC,kBAAkB,GAAAV,OAAA,CAAAU,kBAAA,GAAG,gBAAgB;;AAElD;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,MAAMC,eAGT,GAAAX,OAAA,CAAAW,eAAA,GAAGV,MAAM,CAACC,MAAM,CAClBD,MAAM,CAACI,OAAO,CAACN,oBAAoB,CAAC,CAACO,MAAM,CAAC,CAAC,GAAGC,KAAK,CAAC,KAAKA,KAAK,CAACV,QAAQ,CAC3E,CAAuD;;AAEvD;AACO,SAASe,YAAYA,CAACH,KAAa,EAAU;EAClD,OAAO,eAAeA,KAAK,CAACI,KAAK,CAAC,CAAC,CAAC,EAAE;AACxC;;AAEA;AACO,SAASC,QAAQA,CAACL,KAAa,EAAe;EAAA,IAAAM,qBAAA;EACnD,OAAO,EAAAA,qBAAA,GAAAhB,oBAAoB,CAACU,KAAK,CAAC,qBAA3BM,qBAAA,CAA6BpB,MAAM,KAAI,MAAM;AACtD","ignoreList":[]}

package/dist/esm/client/applyThemeOverrides.js

@@ -31,6 +31,13 @@
  * - **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.
+ * - **The shop owner is the last word (DL #193)**: `userOverrides` carries the
+ *   choices a human made in the owner panel, and every one of them is written
+ *   as the real token whatever its bucket. Bucketing exists to arbitrate a
+ *   disagreement between a store and a template; an owner who opened a panel
+ *   and set a value has already settled that argument, so aliasing theirs would
+ *   let the template overrule the person who chose. They are written last, so a
+ *   token both maps carry resolves to the owner's value.
  * - **Idempotent**: one marker element per document, replaced wholesale on
  *   re-apply; empty/absent input removes it.
  */
@@ -61,12 +68,10 @@ 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;
-  }
-  const existing = document.head.querySelector(`style[${MARKER_ATTR}]`);
-  const entries = Object.entries(overrides ?? {}).filter(_ref => {
+
+/** Drops keys that are not well-formed custom properties, warning about each. */
+function wellFormedEntries(overrides) {
+  return Object.entries(overrides ?? {}).filter(_ref => {
     let [key] = _ref;
     const wellFormed = KEY_PATTERN.test(key);
     if (!wellFormed) {
@@ -74,7 +79,15 @@ export function applyThemeOverrides(overrides) {
     }
     return wellFormed;
   });
-  if (entries.length === 0) {
+}
+export function applyThemeOverrides(overrides, userOverrides) {
+  if (typeof document === 'undefined') {
+    return;
+  }
+  const existing = document.head.querySelector(`style[${MARKER_ATTR}]`);
+  const entries = wellFormedEntries(overrides);
+  const userEntries = wellFormedEntries(userOverrides);
+  if (entries.length === 0 && userEntries.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
@@ -93,18 +106,30 @@ 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);
+  const write = (key, value, target, source) => {
     try {
       rule.style.setProperty(target, value);
-      applied.push([key, value]);
+      applied.push({
+        token: key,
+        value,
+        writtenAs: target,
+        source
+      });
     } catch {
       // An engine that rejects the value leaves the token at its baked
       // default — degraded theming, never broken CSS.
     }
+  };
+  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.
+    write(key, value, bucketOf(key) === 'brand' ? key : hostAliasFor(key), 'store');
+  }
+  // Owner choices last and never aliased: within one declaration block the last
+  // write of a property wins, so a token both maps carry ends up the owner's.
+  for (const [key, value] of userEntries) {
+    write(key, value, key, 'user');
   }
   // Replace-on-reapply: the fresh element is appended (so it stays last in
   // document order) before the stale one is dropped.

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

@@ -1 +1 @@
-{"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":[]}
+{"version":3,"names":["WEB5_SCOPE","traceThemeOverrides","THEME_TOKEN_CONTRACT","bucketOf","hostAliasFor","THEME_OVERRIDE_TOKENS","Set","Object","keys","KEY_PATTERN","MARKER_ATTR","wellFormedEntries","overrides","entries","filter","_ref","key","wellFormed","test","console","warn","applyThemeOverrides","userOverrides","document","existing","head","querySelector","userEntries","length","remove","style","createElement","setAttribute","appendChild","sheet","insertRule","rule","cssRules","applied","write","value","target","source","setProperty","push","token","writtenAs"],"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 * - **The shop owner is the last word (DL #193)**: `userOverrides` carries the\n *   choices a human made in the owner panel, and every one of them is written\n *   as the real token whatever its bucket. Bucketing exists to arbitrate a\n *   disagreement between a store and a template; an owner who opened a panel\n *   and set a value has already settled that argument, so aliasing theirs would\n *   let the template overrule the person who chose. They are written last, so a\n *   token both maps carry resolves to the owner's value.\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 {\n  traceThemeOverrides,\n  type AppliedToken,\n  type ThemeOverrideSource,\n} 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\n/** Drops keys that are not well-formed custom properties, warning about each. */\nfunction wellFormedEntries(\n  overrides?: Record<string, string> | null,\n): [string, string][] {\n  return 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\nexport function applyThemeOverrides(\n  overrides?: Record<string, string> | null,\n  userOverrides?: 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 = wellFormedEntries(overrides);\n  const userEntries = wellFormedEntries(userOverrides);\n\n  if (entries.length === 0 && userEntries.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: AppliedToken[] = [];\n  const write = (\n    key: string,\n    value: string,\n    target: string,\n    source: ThemeOverrideSource,\n  ): void => {\n    try {\n      rule.style.setProperty(target, value);\n      applied.push({ token: key, value, writtenAs: target, source });\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\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    write(\n      key,\n      value,\n      bucketOf(key) === 'brand' ? key : hostAliasFor(key),\n      'store',\n    );\n  }\n  // Owner choices last and never aliased: within one declaration block the last\n  // write of a property wins, so a token both maps carry ends up the owner's.\n  for (const [key, value] of userEntries) {\n    write(key, value, key, 'user');\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;AACA;AACA;AACA;AACA;AACA;AACA;AACA,SAASA,UAAU,QAAQ,cAAc;AACzC,SACEC,mBAAmB,QAGd,cAAc;AACrB,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;AACA,SAASC,iBAAiBA,CACxBC,SAAyC,EACrB;EACpB,OAAOL,MAAM,CAACM,OAAO,CAACD,SAAS,IAAI,CAAC,CAAC,CAAC,CAACE,MAAM,CAACC,IAAA,IAAW;IAAA,IAAV,CAACC,GAAG,CAAC,GAAAD,IAAA;IAClD,MAAME,UAAU,GAAGR,WAAW,CAACS,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;AACJ;AAEA,OAAO,SAASI,mBAAmBA,CACjCT,SAAyC,EACzCU,aAA6C,EACvC;EACN,IAAI,OAAOC,QAAQ,KAAK,WAAW,EAAE;IACnC;EACF;EAEA,MAAMC,QAAQ,GAAGD,QAAQ,CAACE,IAAI,CAACC,aAAa,CAAC,SAAShB,WAAW,GAAG,CAAC;EACrE,MAAMG,OAAO,GAAGF,iBAAiB,CAACC,SAAS,CAAC;EAC5C,MAAMe,WAAW,GAAGhB,iBAAiB,CAACW,aAAa,CAAC;EAEpD,IAAIT,OAAO,CAACe,MAAM,KAAK,CAAC,IAAID,WAAW,CAACC,MAAM,KAAK,CAAC,EAAE;IACpDJ,QAAQ,YAARA,QAAQ,CAAEK,MAAM,CAAC,CAAC;IAClB;IACA;IACA;IACA5B,mBAAmB,CAAC,EAAE,CAAC;IACvB;EACF;EAEA,MAAM6B,KAAK,GAAGP,QAAQ,CAACQ,aAAa,CAAC,OAAO,CAAC;EAC7CD,KAAK,CAACE,YAAY,CAACtB,WAAW,EAAE,EAAE,CAAC;EACnCa,QAAQ,CAACE,IAAI,CAACQ,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,GAAGnC,UAAU,KAAK,EAAE,CAAC,CAAC;EACvC,MAAMoC,IAAI,GAAGF,KAAK,CAACG,QAAQ,CAAC,CAAC,CAAiB;EAC9C,MAAMC,OAAuB,GAAG,EAAE;EAClC,MAAMC,KAAK,GAAGA,CACZvB,GAAW,EACXwB,KAAa,EACbC,MAAc,EACdC,MAA2B,KAClB;IACT,IAAI;MACFN,IAAI,CAACN,KAAK,CAACa,WAAW,CAACF,MAAM,EAAED,KAAK,CAAC;MACrCF,OAAO,CAACM,IAAI,CAAC;QAAEC,KAAK,EAAE7B,GAAG;QAAEwB,KAAK;QAAEM,SAAS,EAAEL,MAAM;QAAEC;MAAO,CAAC,CAAC;IAChE,CAAC,CAAC,MAAM;MACN;MACA;IAAA;EAEJ,CAAC;EAED,KAAK,MAAM,CAAC1B,GAAG,EAAEwB,KAAK,CAAC,IAAI3B,OAAO,EAAE;IAClC;IACA;IACA;IACA0B,KAAK,CACHvB,GAAG,EACHwB,KAAK,EACLrC,QAAQ,CAACa,GAAG,CAAC,KAAK,OAAO,GAAGA,GAAG,GAAGZ,YAAY,CAACY,GAAG,CAAC,EACnD,OACF,CAAC;EACH;EACA;EACA;EACA,KAAK,MAAM,CAACA,GAAG,EAAEwB,KAAK,CAAC,IAAIb,WAAW,EAAE;IACtCY,KAAK,CAACvB,GAAG,EAAEwB,KAAK,EAAExB,GAAG,EAAE,MAAM,CAAC;EAChC;EACA;EACA;EACAQ,QAAQ,YAARA,QAAQ,CAAEK,MAAM,CAAC,CAAC;EAClB;EACA;EACA5B,mBAAmB,CAACqC,OAAO,CAAC;AAC9B","ignoreList":[]}

package/dist/esm/client/themeDebug.js

@@ -20,6 +20,7 @@
  *
  *   [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
+ *   [web5:theme] --radius   owner  wrote --radius=2rem            →  2rem     OWNER
  *
  * Off by default. Enable with `?web5DebugTheme=1` (one-shot, wins over storage)
  * or `localStorage["web5_debug_theme"] = "1"` (sticky) — the same shape as
@@ -30,7 +31,7 @@
  * the whole batch, not one per token.
  */
 import { WEB5_SCOPES } from '../hostScope.js';
-import { bucketOf, hostAliasFor } from '../theme/tokenContract.js';
+import { bucketOf } from '../theme/tokenContract.js';
 export const THEME_DEBUG_KEY = 'web5_debug_theme';
 
 /** Query param that forces theme tracing on, overriding localStorage. */
@@ -65,6 +66,11 @@ export const isThemeDebugEnabled = () => {
 export const resetThemeDebugCache = () => {
   cached = null;
 };
+
+/** Which layer asked for a value: the platform import, or a human. */
+
+/** One token as it was actually written to the mount rule. */
+
 /**
  * Report what each override did, after the rule is live.
  *
@@ -100,19 +106,32 @@ export function traceThemeOverrides(applied) {
   // 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);
+  // An owner's write is the last one into the rule, so when both layers name a
+  // token the resolved value is theirs — check the owner first or a store value
+  // that happens to match would be credited with a win it did not have.
+  const byToken = new Map();
+  for (const entry of applied) {
+    const held = byToken.get(entry.token);
+    if (!held || entry.source === 'user') {
+      byToken.set(entry.token, entry);
+    }
+  }
+  const rows = [...byToken.values()].map(entry => {
+    const {
+      token,
+      value,
+      writtenAs,
+      source
+    } = entry;
     const resolved = computed.getPropertyValue(token).trim();
     const wanted = value.trim();
     return {
       token,
-      bucket,
-      'written as': target,
-      'store said': wanted,
+      bucket: source === 'user' ? 'owner' : bucketOf(token),
+      'written as': writtenAs,
+      'asked for': wanted,
       'resolves to': resolved || '(nothing reads it)',
-      winner: !resolved ? 'NOBODY — no stylesheet consumes this token' : resolved === wanted ? 'STORE' : 'TEMPLATE'
+      winner: !resolved ? 'NOBODY — no stylesheet consumes this token' : resolved !== wanted ? 'TEMPLATE' : source === 'user' ? 'OWNER' : 'STORE'
     };
   });
   const overridden = rows.filter(r => r.winner === 'TEMPLATE').length;

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

@@ -1 +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":"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","ignoreList":[]}
+{"version":3,"names":["WEB5_SCOPES","bucketOf","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","byToken","Map","entry","held","token","source","set","rows","values","map","writtenAs","resolved","getPropertyValue","trim","wanted","bucket","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 *   [web5:theme] --radius   owner  wrote --radius=2rem            →  2rem     OWNER\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 } 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\n/** Which layer asked for a value: the platform import, or a human. */\nexport type ThemeOverrideSource = 'store' | 'user';\n\n/** One token as it was actually written to the mount rule. */\nexport interface AppliedToken {\n  token: string;\n  value: string;\n  writtenAs: string;\n  source: ThemeOverrideSource;\n}\n\ninterface TraceRow {\n  token: string;\n  bucket: string;\n  'written as': string;\n  'asked for': 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: AppliedToken[]): 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  // An owner's write is the last one into the rule, so when both layers name a\n  // token the resolved value is theirs — check the owner first or a store value\n  // that happens to match would be credited with a win it did not have.\n  const byToken = new Map<string, AppliedToken>();\n  for (const entry of applied) {\n    const held = byToken.get(entry.token);\n    if (!held || entry.source === 'user') {\n      byToken.set(entry.token, entry);\n    }\n  }\n  const rows: TraceRow[] = [...byToken.values()].map((entry) => {\n    const { token, value, writtenAs, source } = entry;\n    const resolved = computed.getPropertyValue(token).trim();\n    const wanted = value.trim();\n    return {\n      token,\n      bucket: source === 'user' ? 'owner' : bucketOf(token),\n      'written as': writtenAs,\n      'asked for': wanted,\n      'resolves to': resolved || '(nothing reads it)',\n      winner: !resolved\n        ? 'NOBODY — no stylesheet consumes this token'\n        : resolved !== wanted\n        ? 'TEMPLATE'\n        : source === 'user'\n        ? 'OWNER'\n        : 'STORE',\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":"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","ignoreList":[]}

package/dist/esm/index.js

@@ -142,8 +142,9 @@ 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 { THEME_TOKEN_CONTRACT, BRAND_TOKENS, EDITABLE_TOKENS, TOKEN_NAME_PATTERN, bucketOf, hostAliasFor } from './theme/tokenContract.js';
 export { isThemeDebugEnabled, THEME_DEBUG_KEY, THEME_DEBUG_QUERY_PARAM } from './client/themeDebug.js';
+export { hexToHslTriplet, hslTripletToHex, isHslTriplet } from './theme/colorFormat.js';
 
 // Placement renderer + DI helper (DL #088 D3.2, D3.4)
 export { PlacementResponseRenderer, PlacementSmoothHeight } from './components/placement/PlacementResponseRenderer.js';