@web-my-money/studio-consumer 2.1.0 → 2.3.0

package/cli/writers.mjs

@@ -0,0 +1,148 @@
+// @ts-check
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import * as t from "./templates.mjs";
+
+/**
+ * The mechanical edits `init` makes (stage 2 plan, Task 4). Every writer is
+ * idempotent and never overwrites a file the app already has with different
+ * content: it reports it instead, so nothing the developer wrote is lost. The
+ * edits that need judgement (root layout, proxy, the content model) are left to
+ * the Claude Code step.
+ */
+
+/**
+ * @typedef {{ siteKey: string, theme: string, style: "flat" | "glass" }} SiteValues
+ * @typedef {{ written: string[], skipped: { path: string, reason: string }[] }} WriteReport
+ */
+
+/** @param {string} cwd */
+function codeRoot(cwd) {
+  return existsSync(path.join(cwd, "src", "app")) ? "src" : ".";
+}
+
+/** @param {string} cwd */
+function hasTestRunner(cwd) {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(cwd, "package.json"), "utf8"));
+    const all = { ...pkg.dependencies, ...pkg.devDependencies };
+    return "vitest" in all || "jest" in all;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {{ cwd: string, values: SiteValues, modules: string[] }} ctx
+ * @returns {Promise<WriteReport>}
+ */
+export async function writeSiteFiles({ cwd, values, modules }) {
+  const root = codeRoot(cwd);
+  const content = modules.includes("content");
+  const analytics = modules.includes("analytics");
+  // From app/api/<group>/<name>/route.ts back up to the code root's lib/.
+  const toLib = "../../../../lib";
+
+  /** @type {[string, string, { keepExisting?: boolean }?][]} */
+  const files = [];
+  const at = (/** @type {string} */ p) => (root === "." ? p : `${root}/${p}`);
+  if (content || analytics) files.push([at("lib/studio.ts"), t.studioTs(values)]);
+  if (content) {
+    files.push([at("lib/brand.ts"), t.brandTs(values)]);
+    files.push([at("lib/content-manifest.ts"), t.contentManifestTs(), { keepExisting: true }]);
+    files.push([at("lib/content.ts"), t.contentTs()]);
+    files.push([at("app/api/content/manifest/route.ts"), t.manifestRouteTs(toLib)]);
+    files.push([at("app/api/content/revalidate/route.ts"), t.revalidateRouteTs()]);
+  }
+  if (analytics) files.push([at("app/api/analytics/collect/route.ts"), t.collectRouteTs(toLib, content)]);
+
+  /** @type {WriteReport} */
+  const report = { written: [], skipped: [] };
+
+  if (content) {
+    if (hasTestRunner(cwd)) files.push(["tests/studio-frame-ancestors.test.ts", t.frameAncestorsTestTs()]);
+    else {
+      report.skipped.push({
+        path: "tests/studio-frame-ancestors.test.ts",
+        reason: "this app has no test runner yet; the Claude Code step can add Vitest and this test",
+      });
+    }
+  }
+
+  for (const [rel, body, opts] of files) {
+    const abs = path.join(cwd, rel);
+    if (existsSync(abs)) {
+      const current = readFileSync(abs, "utf8");
+      if (current === body || opts?.keepExisting) continue;
+      report.skipped.push({ path: rel, reason: "already exists with different content; merge the Studio version by hand" });
+      continue;
+    }
+    mkdirSync(path.dirname(abs), { recursive: true });
+    writeFileSync(abs, body);
+    report.written.push(rel);
+  }
+  return report;
+}
+
+const IMPORT_LINE = 'import { withStudio } from "@web-my-money/studio-consumer/next";';
+const CONFIG_NAMES = ["next.config.ts", "next.config.mjs", "next.config.js"];
+
+/**
+ * Wrap the app's next.config with withStudio. Recognises the two shapes nearly
+ * every config has (`export default name;` and `export default { … };`); any
+ * other shape is left untouched and the exact edit is returned instead.
+ *
+ * @param {{ cwd: string }} ctx
+ * @returns {Promise<"wrapped" | "already" | { manual: string }>}
+ */
+export async function wrapNextConfig({ cwd }) {
+  const name = CONFIG_NAMES.find((n) => existsSync(path.join(cwd, n)));
+  if (!name) {
+    writeFileSync(path.join(cwd, "next.config.mjs"), `${IMPORT_LINE}\n\nexport default withStudio({});\n`);
+    return "wrapped";
+  }
+  const file = path.join(cwd, name);
+  const src = readFileSync(file, "utf8");
+  if (src.includes("withStudio(")) return "already";
+
+  const manual = {
+    manual:
+      `Edit ${name} by hand: add\n  ${IMPORT_LINE}\nat the top, and wrap the exported config: export default withStudio(yourConfig);`,
+  };
+
+  let out = null;
+  const named = /^export default ([A-Za-z_$][\w$]*);[ \t]*$/m;
+  if (named.test(src)) {
+    out = src.replace(named, "export default withStudio($1);");
+  } else if (/^export default \{/m.test(src)) {
+    const start = src.search(/^export default \{/m);
+    const open = start + "export default ".length;
+    // Find the brace that closes the exported object. Only wrap when that object
+    // is the last thing in the file: a brace inside a string, or code after the
+    // export, makes the match uncertain, and a wrong splice breaks the config.
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < src.length; i++) {
+      if (src[i] === "{") depth++;
+      else if (src[i] === "}" && --depth === 0) {
+        close = i;
+        break;
+      }
+    }
+    const rest = close === -1 ? "x" : src.slice(close + 1).replace(/^;/, "");
+    if (close !== -1 && rest.trim() === "") {
+      out = `${src.slice(0, start)}export default withStudio(${src.slice(open, close + 1)});${rest}`;
+    }
+  }
+  if (!out) return manual;
+
+  // The import goes after the last existing import, or at the very top.
+  const lines = out.split("\n");
+  let last = -1;
+  lines.forEach((l, i) => {
+    if (/^import\s/.test(l)) last = i;
+  });
+  lines.splice(last + 1, 0, IMPORT_LINE);
+  writeFileSync(file, lines.join("\n"));
+  return "wrapped";
+}

package/package.json

@@ -1,29 +1,33 @@
-{
-  "name": "@web-my-money/studio-consumer",
-  "version": "2.1.0",
-  "description": "Consumer-side integration for WMM Studio: content, analytics, attribution.",
-  "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Web-My-Money/wmm-studio.git",
-    "directory": "packages/studio-consumer"
-  },
-  "type": "module",
-  "sideEffects": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "exports": {
-    "./analytics": "./src/analytics/index.ts",
-    "./content": "./src/content/index.ts",
-    "./attribution": "./src/attribution/index.ts",
-    "./headers": "./src/content/headers.mjs",
-    "./brand": "./src/brand/index.ts",
-    "./image": "./src/image/index.ts"
-  },
-  "peerDependencies": {
-    "next": ">=16",
-    "react": ">=19"
-  },
-  "files": ["src"]
-}
+{
+  "name": "@web-my-money/studio-consumer",
+  "version": "2.3.0",
+  "description": "Consumer-side integration for WMM Studio: content, analytics, attribution.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Web-My-Money/wmm-studio.git",
+    "directory": "packages/studio-consumer"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./analytics": "./src/analytics/index.ts",
+    "./content": "./src/content/index.ts",
+    "./attribution": "./src/attribution/index.ts",
+    "./headers": "./src/content/headers.mjs",
+    "./brand": "./src/brand/index.ts",
+    "./image": "./src/image/index.ts",
+    "./next": "./src/next/index.mjs"
+  },
+  "peerDependencies": {
+    "next": ">=16",
+    "react": ">=19"
+  },
+  "bin": {
+    "studio-consumer": "./bin/studio-consumer.mjs"
+  },
+  "files": ["src", "bin", "cli", "skills"]
+}

package/skills/onboard-site/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: onboard-site
+description: Finish connecting this Next.js app to WMM Studio after `npx @web-my-money/studio-consumer init` has run. Wires the root layout and the proxy/middleware, then proposes which text should be editable in Studio and writes the content manifest once the developer approves. Use when the init command opens Claude Code on /onboard-site.
+---
+
+# Finish connecting this app to WMM Studio
+
+The `init` command already did the mechanical part: it installed
+`@web-my-money/studio-consumer`, wrapped `next.config` with `withStudio`, and wrote
+`lib/studio.ts` (the site key), `lib/brand.ts`, `lib/content.ts`, a starter
+`lib/content-manifest.ts` and the API routes under `app/api/`. (In a `src/` app all of
+these live under `src/`.) Your job is the part that needs judgement on someone else's
+code.
+
+**The developer may never have seen Studio before.** Explain each change in one plain
+sentence, show the diff, and wait for a yes before writing it. Never rewrite a file
+wholesale; make the smallest edit that does the job. Never remove an existing redirect,
+rewrite, header or script.
+
+Read `.wmm-onboarding/state.json` first: it lists the modules this site uses
+(`content`, `analytics`, `forms`, `attribution`, `ab`, …). Skip anything for a module
+that is not listed.
+
+## 1. Root layout (`app/layout.tsx`, or the layout that renders `<html>`)
+
+- **Brand (content):** `import { brandRootAttributes } from "@web-my-money/studio-consumer/brand";`
+  and `import { brand } from "<relative path>/lib/brand";`, then spread
+  `{...brandRootAttributes(brand)}` on `<html>`. Keep every attribute already there.
+- **Click-to-edit (content):** render `<WmmEditOverlay studioOrigin={process.env.NEXT_PUBLIC_STUDIO_ORIGIN} />`
+  from `@web-my-money/studio-consumer/content` once, inside `<body>`.
+- **Analytics (analytics):** render `<FunnelAnalytics />` and `<EngagementTracking />` from
+  `@web-my-money/studio-consumer/analytics` once, inside `<body>`.
+- **Overrides (content):** wherever the app loads its dictionary for a locale (often a
+  `[lang]` layout or a `getDictionary` helper), pass it through
+  `await applyDictOverrides(dict, locale)` from `lib/content.ts` before rendering. This is
+  what makes an edit in Studio appear on the page; without it the checklist goes green
+  and edits never show. If the app has no dictionary, say so and use `getLocalizedSlot`
+  for each editable value in step 3 instead.
+
+## 2. Proxy / middleware (analytics)
+
+Studio's analytics and A/B testing need the `wmm_vid` visitor cookie, which
+`withVisitorCookie` from `@web-my-money/studio-consumer/analytics` sets.
+
+- Next 16 uses `proxy.ts` (older apps: `middleware.ts`), at the code root.
+- **None exists:** create `proxy.ts` that returns `withVisitorCookie(request)`, with a
+  matcher that skips `_next`, `api` and static files.
+- **One exists:** compose, never replace. Call `withVisitorCookie(request)` for the
+  pass-through case, and keep every existing redirect and rewrite exactly as it is. If the
+  existing code returns its own `NextResponse`, show the developer the two options (set
+  the cookie on that response, or call `withVisitorCookie` first) and let them choose.
+
+## 3. Choose the editable text (content)
+
+This is the real decision in the whole onboarding. **Do not decide it alone.**
+
+1. Find the copy: the per-locale dictionary (e.g. `dictionaries/en.json`, `es.json`), or,
+   if there is none, the text in the page components.
+2. Propose a table grouped by page and section, one row per candidate:
+
+   | Key | Current text (EN) | Editable? | Why |
+   |---|---|---|---|
+
+   Keys are `page.section.thing` (e.g. `home.hero.headline`). Give a one-line reason for
+   **every "no"**. Lean towards "no" for, and always justify:
+   - legal and compliance text (privacy, terms, disclaimers, medical or financial claims);
+   - form field names, validation and error messages;
+   - analytics, tracking and pixel ids;
+   - icons and component references (never editable);
+   - anything the code uses as an identifier, a route or a CSS class.
+   Lean towards "yes" for headlines, sub-headlines, body copy, calls to action, testimonials
+   and images a marketer would change.
+3. Wait for the developer to approve or edit the table.
+4. Then fill in `lib/content-manifest.ts`, keeping its `getManifest()` shape and the
+   `siteKey: SITE_KEY` it returns:
+   - a slot only for text the code actually renders;
+   - `type`: `text` (or `richtext`, `image`, `list`, `select` where that fits);
+   - `dictPath` for dictionary text (the override is merged into the dictionary, no
+     component changes needed); no `dictPath` for images or other non-dictionary values,
+     which are read with `getSlot` and passed down as props;
+   - `default` is read from the dictionary (`en`/`es` imports), **never retyped**, so it
+     cannot go stale;
+   - `label` in plain words a client understands ("Home: hero headline");
+   - `group` per page section, `sortOrder` in reading order.
+
+If `lib/content-manifest.ts` already had real slots before `init` ran, keep them and only
+add what the developer approves.
+
+## 4. Check, then hand back
+
+Run `npm run verify` (or the app's equivalent: typecheck, lint, test, build). Fix what it
+reports. If the app has no test runner and `tests/studio-frame-ancestors.test.ts` was not
+written, offer to add Vitest and that test.
+
+When everything passes, tell the developer in one sentence what changed, and that they can
+close Claude Code (type `/exit`) so the `init` command continues with the next step.

package/src/analytics/collect-handler.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from "next/server";
+import { resolveVariant, VISITOR_COOKIE, type RunningExperiment } from "./bucketing";
 
 /**
  * First-party analytics collector (wmm-studio docs/analytics/01-pipeline.md §5.1).
@@ -13,6 +14,9 @@ import { NextResponse } from "next/server";
  * surface an error on a marketing page or interfere with a form — so failures
  * are logged here and are invisible to the visitor.
  *
+ * Same-origin only, and the A/B arm is resolved HERE from the visitor cookie,
+ * never taken from the payload (parity with WMM Website's own route, 2026-10-09).
+ *
  * Inert with no `FUNNEL_INGEST_URL`: nothing is forwarded and the site behaves
  * exactly as it did before this route existed. That is the correct state before
  * rollout, which is what lets this merge ahead of being switched on.
@@ -61,6 +65,34 @@ function warnOnceAboutKeyShape(key: string): void {
   );
 }
 
+/**
+ * Only the site's own pages post here. Browsers send `Sec-Fetch-Site` (or at least
+ * an `Origin`) on a same-origin beacon; a bare script or a third-party page does
+ * not. Headers can be forged by hand, so this is a speed bump, not a lock; what
+ * actually protects the A/B numbers is the server-side arm below.
+ */
+function isSameOrigin(req: Request): boolean {
+  const fetchSite = req.headers.get("sec-fetch-site");
+  if (fetchSite) return fetchSite === "same-origin";
+  const origin = req.headers.get("origin");
+  if (!origin) return false;
+  try {
+    return new URL(origin).host === new URL(req.url).host;
+  } catch {
+    return false;
+  }
+}
+
+function readCookie(req: Request, name: string): string | null {
+  const header = req.headers.get("cookie");
+  if (!header) return null;
+  for (const part of header.split(";")) {
+    const [k, ...v] = part.trim().split("=");
+    if (k === name) return decodeURIComponent(v.join("="));
+  }
+  return null;
+}
+
 /** Test-only: forget that the one-time warning has already been printed. */
 export function resetIngestKeyShapeWarning(): void {
   warnedAboutKeyShape = false;
@@ -70,6 +102,13 @@ export function createCollectHandler(config: {
   siteKey: string;
   ingestUrl: string;
   ingestKey: string;
+  /**
+   * The site's running experiments (pass the content client's
+   * `getRunningExperiments`). With it, each event's A/B arm is resolved here
+   * from the `wmm_vid` cookie; without it, events carry no arm. The browser's
+   * own `variant` is discarded either way.
+   */
+  getRunningExperiments?: () => Promise<RunningExperiment[]>;
 }): (request: Request) => Promise<Response> {
   return async function POST(request: Request): Promise<Response> {
     const url = config.ingestUrl || DEFAULT_INGEST_URL;
@@ -77,6 +116,7 @@ export function createCollectHandler(config: {
     // The token is the only thing that genuinely has to be configured per site.
     if (!token) return noContent();
     warnOnceAboutKeyShape(token);
+    if (!isSameOrigin(request)) return noContent();
 
     let events: unknown[];
     try {
@@ -93,13 +133,39 @@ export function createCollectHandler(config: {
       return noContent();
     }
 
+    // The A/B arm is decided here, from the visitor cookie and the experiment list
+    // the page render used — never taken from the payload. A posted `variant` could
+    // otherwise put any visitor into any arm and move an experiment's result. No
+    // cookie means the arm is unknowable, so none is sent.
+    const visitorId = readCookie(request, VISITOR_COOKIE);
+    const experiments: RunningExperiment[] =
+      visitorId && config.getRunningExperiments
+        ? await config.getRunningExperiments().catch(() => [])
+        : [];
+
     // The site key is stamped here, never trusted from the client: a browser must
     // not be able to write events into another site's namespace by editing a
     // payload. Anything the client sent under that key is overwritten.
-    const stamped = events.map((e) => ({
-      ...(e && typeof e === "object" ? e : {}),
-      siteKey: config.siteKey,
-    }));
+    const stamped = events
+      .filter(
+        (e): e is Record<string, unknown> =>
+          !!e &&
+          typeof e === "object" &&
+          typeof (e as { path?: unknown }).path === "string" &&
+          (e as { path: string }).path.startsWith("/"),
+      )
+      .map((e) => {
+        const { variant: _clientVariant, ...rest } = e;
+        const path = (rest.path as string).split("?")[0];
+        const arm = visitorId ? resolveVariant(path, visitorId, experiments) : null;
+        return {
+          ...rest,
+          ...(visitorId ? { visitorId } : {}),
+          ...(arm?.experimentKey ? { variant: arm.variant } : {}),
+          siteKey: config.siteKey,
+        };
+      });
+    if (stamped.length === 0) return noContent();
 
     try {
       const res = await fetch(url, {

package/src/analytics/index.ts

@@ -1,37 +1,37 @@
-/** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "2.1.0";
-
-export {
-  resolveVariant,
-  bucketFor,
-  CONTROL,
-  VARIANT,
-  VISITOR_COOKIE,
-  type RunningExperiment,
-} from "./bucketing";
-
-export {
-  trackFunnelEvent,
-  registerExperiments,
-  flushFunnelEvents,
-  currentSessionId,
-  funnelAnalyticsEnabled,
-  consentGranted,
-  resetFunnelAnalytics,
-  type FunnelEventProps,
-} from "./collector";
-
-export { useFormAnalytics, type FormAnalytics, type FormAnalyticsOptions } from "./use-form-analytics";
-
-export {
-  FunnelAnalytics,
-  EngagementTracking,
-  AbArm,
-  THRESHOLDS,
-  crossedThresholds,
-  labelFor,
-} from "./components";
-
-export { createCollectHandler } from "./collect-handler";
-
-export { withVisitorCookie } from "./proxy";
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "2.3.0";
+
+export {
+  resolveVariant,
+  bucketFor,
+  CONTROL,
+  VARIANT,
+  VISITOR_COOKIE,
+  type RunningExperiment,
+} from "./bucketing";
+
+export {
+  trackFunnelEvent,
+  registerExperiments,
+  flushFunnelEvents,
+  currentSessionId,
+  funnelAnalyticsEnabled,
+  consentGranted,
+  resetFunnelAnalytics,
+  type FunnelEventProps,
+} from "./collector";
+
+export { useFormAnalytics, type FormAnalytics, type FormAnalyticsOptions } from "./use-form-analytics";
+
+export {
+  FunnelAnalytics,
+  EngagementTracking,
+  AbArm,
+  THRESHOLDS,
+  crossedThresholds,
+  labelFor,
+} from "./components";
+
+export { createCollectHandler } from "./collect-handler";
+
+export { withVisitorCookie } from "./proxy";

package/src/attribution/index.ts

@@ -1,14 +1,14 @@
-/** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "2.1.0";
-
-export {
-  getAttribution,
-  captureAttribution,
-  getAttributionPayload,
-  computeAttribution,
-  flattenAttribution,
-  hasCampaignSignal,
-} from "./store";
-export type { Attribution, Touch, AttributionPayload } from "./store";
-
-export { sessionIdField, SESSION_ID_FIELD } from "./crm";
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "2.3.0";
+
+export {
+  getAttribution,
+  captureAttribution,
+  getAttributionPayload,
+  computeAttribution,
+  flattenAttribution,
+  hasCampaignSignal,
+} from "./store";
+export type { Attribution, Touch, AttributionPayload } from "./store";
+
+export { sessionIdField, SESSION_ID_FIELD } from "./crm";

package/src/brand/index.ts

@@ -1,66 +1,66 @@
-/**
- * Site brand — the theme boundary (Studio spec 2026-10-08, phase 5).
- *
- * A client site declares its brand in CODE, in its root layout:
- *
- *   const brand = defineSiteBrand({ theme: "acme", style: "flat" });
- *   <html lang="en" {...brandRootAttributes(brand)}>
- *
- * and passes the same `brand` to `createManifestHandler`, so Studio records it.
- *
- * FAIL CLOSED. With no `data-theme`, @web-my-money/tokens falls back to WMM's
- * palette (CSS) and to "dark" (JS). A client site must never get there by
- * omission, so every invalid input THROWS — and because this runs while the root
- * layout renders, a throw is a failed build, not a quietly wrong page.
- *
- * Pure on purpose: no `server-only`, no Next imports, safe in any component.
- */
-
-export const PACKAGE_VERSION = "2.1.0";
-
-/** Theme ids owned by WMM in the tokens package (themes.json `owner: "wmm"`). */
-export const WMM_THEMES = ["wmm", "site", "light", "dark"] as const;
-
-const STYLES = ["flat", "glass"] as const;
-const THEME_ID = /^[a-z][a-z0-9-]{0,40}$/;
-
-export type SiteBrand = {
-  readonly theme: string;
-  readonly style: (typeof STYLES)[number];
-  readonly wmmSite: boolean;
-};
-
-export function defineSiteBrand(input: {
-  theme: string;
-  style: (typeof STYLES)[number];
-  wmmSite?: boolean;
-}): SiteBrand {
-  const { theme, style } = input;
-  const wmmSite = input.wmmSite === true;
-
-  // Refused rather than trimmed/lowercased: normalising here would make the id
-  // in the code and the id in the stylesheet two different strings.
-  if (typeof theme !== "string" || !THEME_ID.test(theme)) {
-    throw new Error(
-      `defineSiteBrand: theme ${JSON.stringify(theme)} is not a valid theme id ` +
-        "(lowercase letters, digits and dashes, starting with a letter).",
-    );
-  }
-  if ((WMM_THEMES as readonly string[]).includes(theme) && !wmmSite) {
-    throw new Error(
-      `defineSiteBrand: "${theme}" is WMM's own theme. A client site needs its own ` +
-        "theme from the design system (gen-client-theme). Only a WMM site may pass wmmSite: true.",
-    );
-  }
-  if (!(STYLES as readonly string[]).includes(style)) {
-    throw new Error(`defineSiteBrand: style must be "flat" or "glass", got ${JSON.stringify(style)}.`);
-  }
-  return Object.freeze({ theme, style, wmmSite });
-}
-
-export function brandRootAttributes(brand: SiteBrand): {
-  "data-theme": string;
-  "data-style": string;
-} {
-  return { "data-theme": brand.theme, "data-style": brand.style };
-}
+/**
+ * Site brand — the theme boundary (Studio spec 2026-10-08, phase 5).
+ *
+ * A client site declares its brand in CODE, in its root layout:
+ *
+ *   const brand = defineSiteBrand({ theme: "acme", style: "flat" });
+ *   <html lang="en" {...brandRootAttributes(brand)}>
+ *
+ * and passes the same `brand` to `createManifestHandler`, so Studio records it.
+ *
+ * FAIL CLOSED. With no `data-theme`, @web-my-money/tokens falls back to WMM's
+ * palette (CSS) and to "dark" (JS). A client site must never get there by
+ * omission, so every invalid input THROWS — and because this runs while the root
+ * layout renders, a throw is a failed build, not a quietly wrong page.
+ *
+ * Pure on purpose: no `server-only`, no Next imports, safe in any component.
+ */
+
+export const PACKAGE_VERSION = "2.3.0";
+
+/** Theme ids owned by WMM in the tokens package (themes.json `owner: "wmm"`). */
+export const WMM_THEMES = ["wmm", "site", "light", "dark"] as const;
+
+const STYLES = ["flat", "glass"] as const;
+const THEME_ID = /^[a-z][a-z0-9-]{0,40}$/;
+
+export type SiteBrand = {
+  readonly theme: string;
+  readonly style: (typeof STYLES)[number];
+  readonly wmmSite: boolean;
+};
+
+export function defineSiteBrand(input: {
+  theme: string;
+  style: (typeof STYLES)[number];
+  wmmSite?: boolean;
+}): SiteBrand {
+  const { theme, style } = input;
+  const wmmSite = input.wmmSite === true;
+
+  // Refused rather than trimmed/lowercased: normalising here would make the id
+  // in the code and the id in the stylesheet two different strings.
+  if (typeof theme !== "string" || !THEME_ID.test(theme)) {
+    throw new Error(
+      `defineSiteBrand: theme ${JSON.stringify(theme)} is not a valid theme id ` +
+        "(lowercase letters, digits and dashes, starting with a letter).",
+    );
+  }
+  if ((WMM_THEMES as readonly string[]).includes(theme) && !wmmSite) {
+    throw new Error(
+      `defineSiteBrand: "${theme}" is WMM's own theme. A client site needs its own ` +
+        "theme from the design system (gen-client-theme). Only a WMM site may pass wmmSite: true.",
+    );
+  }
+  if (!(STYLES as readonly string[]).includes(style)) {
+    throw new Error(`defineSiteBrand: style must be "flat" or "glass", got ${JSON.stringify(style)}.`);
+  }
+  return Object.freeze({ theme, style, wmmSite });
+}
+
+export function brandRootAttributes(brand: SiteBrand): {
+  "data-theme": string;
+  "data-style": string;
+} {
+  return { "data-theme": brand.theme, "data-style": brand.style };
+}