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

package/README.md

@@ -7,10 +7,10 @@ are Next.js apps that already transpile workspace and scoped packages, so
 publishing compiled output here would only add a compile-and-publish cycle
 for no gain.
 
-## Connect a site: one command (2.3.0)
+## Connect a site: one command (2.3.0; new sites 2.4.0)
 
 In Studio, open the site, Site settings, **Get the setup command**, then in the
-app's folder:
+app's folder (or, for a brand-new site, in an empty folder):
 
 ```bash
 npx @web-my-money/studio-consumer init <code>
@@ -23,6 +23,11 @@ editable text, verifies, opens a pull request, waits for the deploy and asks
 Studio to sync. Rerun it after any stop; it resumes. `init --explain` shows the
 plan without changing anything.
 
+In an empty folder (2.4.0) it first creates the client's private repository from
+`Web-My-Money/wmm-site-template`, pulls it in and puts the site's key and name in
+place of the template's markers; the Claude step then sets the client's colours
+and first copy instead of wiring a layout.
+
 ## Entry points
 
 - `@web-my-money/studio-consumer/analytics`
@@ -104,3 +109,15 @@ export const POST = createCollectHandler({
 
 Without it, events carry no arm and the site stays out of any A/B comparison.
 
+
+## Visitor identity (2.4.1)
+
+Two fixes taken in from WMM Website, where they had been made after the package was split out:
+
+- The browser collector writes the `wmm_vid` cookie itself when the page arrived without one, so a
+  site may set the cookie in its proxy only on routes that run A/B tests (keeping every other page
+  CDN-cacheable) and a visitor still keeps one identity across the site. Arms are labelled only from
+  the cookie the page arrived with, never from one the browser just wrote.
+- `withVisitorCookie` puts a new visitor's id on the request as well as the response, so their very
+  first render is bucketed. Before, a first visit rendered control while its events carried the new
+  id's arm.

package/cli/claude-step.mjs

@@ -4,7 +4,7 @@ import path from "node:path";
 import { fileURLToPath } from "node:url";
 
 /**
- * Step 7 of `init`: the edits that need judgement on someone else's code (root
+ * Step 8 of `init`: the edits that need judgement on someone else's code (root
  * layout, proxy/middleware, which text is editable) are done by Claude Code, on
  * the developer's own subscription, through the `onboard-site` skill this
  * package ships. Each edit is shown and approved before it is written.

package/cli/init.mjs

@@ -9,6 +9,7 @@ import { preflight } from "./preflight.mjs";
 import { cliProvisioner } from "./provisioner.mjs";
 import { writeSiteFiles, wrapNextConfig } from "./writers.mjs";
 import { claudeStep } from "./claude-step.mjs";
+import { personalise, pullTemplateRepo, templateKeyProblem } from "./scaffold.mjs";
 
 /**
  * `npx @web-my-money/studio-consumer init <code>`: connect an existing Next.js
@@ -37,7 +38,7 @@ const POLL_TIMES = 60;
  *   cwd: string, ui: Ui, run: Runner, fetchImpl: Fetch, sleep: (ms: number) => Promise<void>,
  *   studioUrl: string, code: string | null, state: OnboardingState | null,
  *   provisioner: AnyProvisioner | null, provisionerScope?: string,
- *   injectedProvisioner: AnyProvisioner | null,
+ *   injectedProvisioner: AnyProvisioner | null, mode?: "new" | "existing",
  * }} Ctx
  */
 
@@ -48,7 +49,8 @@ const STEPS = [
     title: "Check your setup",
     why: "Makes sure Node, GitHub, Vercel and this app are ready before anything changes.",
     async run(ctx) {
-      await preflight({ cwd: ctx.cwd, run: ctx.run, ui: ctx.ui, resuming: ctx.state !== null });
+      const r = await preflight({ cwd: ctx.cwd, run: ctx.run, ui: ctx.ui, resuming: ctx.state !== null });
+      ctx.mode = r.mode;
     },
   },
   {
@@ -89,13 +91,61 @@ const STEPS = [
       ctx.ui.info(`Connected to ${ctx.state.siteName} (${ctx.state.siteKey}). Modules: ${ctx.state.modules.join(", ")}.`);
     },
   },
+  {
+    id: "create",
+    title: "Create the site from WMM's template",
+    why: "For a new site: makes the client's own repository from WMM's site template and puts it in this folder.",
+    async run(ctx) {
+      const s = need(ctx);
+      // Saved state wins over this run's preflight: once the template is checked
+      // out the folder looks like an existing app, but it still needs finishing.
+      if (ctx.mode !== "new" && s.mode !== "new") {
+        return ctx.ui.info("This is an existing app, so there is nothing to create.");
+      }
+      const problem = templateKeyProblem(s.siteKey);
+      if (problem) ctx.ui.stop(problem);
+      const repo = `Web-My-Money/${s.siteKey}`;
+      if (!s.repoCreated) {
+        const ok = await ctx.ui.confirm(`Create the private repository ${repo} from WMM's site template, in this folder?`);
+        if (!ok) ctx.ui.stop("A new site needs its repository. Run this again when you are ready.");
+        try {
+          await provisioner(ctx).createRepoFromTemplate(s.siteKey);
+          ctx.ui.info(`Created ${repo}.`);
+        } catch (e) {
+          if (!(e instanceof Error && /already exists/i.test(e.message))) throw e;
+          // Most often an earlier run created it and stopped before saving that.
+          const mine = await ctx.ui.confirm(
+            `${repo} already exists on GitHub. Is it this site's repository, made from WMM's template (for example by an earlier run of this command)? Pull it into this folder?`,
+          );
+          if (!mine) {
+            ctx.ui.stop(
+              `${repo} already exists, so this command will not create it again. If it is this site, clone it and run this command inside it.`,
+              `gh repo clone ${repo}`,
+            );
+          }
+        }
+        // Remembered at once: a rerun after a later stop must neither create
+        // the repository twice nor forget that this is a new site.
+        s.repoCreated = true;
+        s.mode = "new";
+        saveState(ctx.cwd, s);
+      }
+      const pulled = await pullTemplateRepo({ cwd: ctx.cwd, run: ctx.run, sleep: ctx.sleep, name: s.siteKey });
+      if (!pulled.ok) ctx.ui.stop(pulled.message, pulled.nextCommand);
+      const changed = await personalise({ cwd: ctx.cwd, run: ctx.run, siteKey: s.siteKey, siteName: s.siteName });
+      // The template's colours are scoped to the site key, so it is the theme.
+      s.mode = "new";
+      s.theme = s.siteKey;
+      ctx.ui.info(`Made the template ${s.siteName}'s (${changed.length} files).`);
+    },
+  },
   {
     id: "install",
     title: "Install the package",
     why: "Adds WMM Studio's package to this app.",
     async run(ctx) {
-      const r = await ctx.run("npm", ["install", "--install-links", "@web-my-money/studio-consumer@^2.3"], { cwd: ctx.cwd });
-      if (r.code !== 0) ctx.ui.stop("npm could not install the package.", "npm install --install-links @web-my-money/studio-consumer@^2.3");
+      const r = await ctx.run("npm", ["install", "--install-links", "@web-my-money/studio-consumer@^2.4"], { cwd: ctx.cwd });
+      if (r.code !== 0) ctx.ui.stop("npm could not install the package.", "npm install --install-links @web-my-money/studio-consumer@^2.4");
     },
   },
   {
@@ -104,7 +154,7 @@ const STEPS = [
     why: "Writes the small files Studio talks to, and lets Studio show this site inside its editor.",
     async run(ctx) {
       const s = need(ctx);
-      if (s.modules.includes("content")) {
+      if (s.modules.includes("content") && s.mode !== "new") {
         s.theme = await ctx.ui.ask(
           "Brand theme id for this site (the client's theme in WMM's design system)",
           s.theme ?? s.siteKey,

package/cli/preflight.mjs

@@ -1,6 +1,7 @@
 // @ts-check
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { isOwnGitignore } from "./state.mjs";
 
 /**
  * Step 1 of the onboarding command: check the machine and the app BEFORE
@@ -11,6 +12,9 @@ import path from "node:path";
 /** @typedef {import("./run.mjs").Runner} Runner */
 /** @typedef {import("./ui.mjs").Ui} Ui */
 
+/** Not content: git, a stopped run's progress, and files the operating system drops in folders. */
+const IGNORED = new Set([".git", ".wmm-onboarding", ".DS_Store", "Thumbs.db", "desktop.ini"]);
+
 /** @param {string} version */
 function majorOf(version) {
   const m = /(\d+)/.exec(version);
@@ -18,8 +22,11 @@ function majorOf(version) {
 }
 
 /**
+ * `new`: an empty folder, where the site is created from WMM's template.
+ * `existing`: a Next.js app, wired in place.
+ *
  * @param {{ cwd: string, run: Runner, ui: Ui, resuming?: boolean }} ctx
- * @returns {Promise<{ mode: "existing", nextMajor: number | null }>}
+ * @returns {Promise<{ mode: "new" | "existing", nextMajor: number | null }>}
  */
 export async function preflight({ cwd, run, ui, resuming = false }) {
   const node = majorOf(process.versions.node) ?? 0;
@@ -29,13 +36,16 @@ export async function preflight({ cwd, run, ui, resuming = false }) {
 
   const pkgPath = path.join(cwd, "package.json");
   if (!existsSync(pkgPath)) {
-    const entries = readdirSync(cwd).filter((f) => f !== ".git");
-    if (entries.length === 0) {
-      ui.stop(
-        "This folder is empty, so it would be a new site from WMM's template. That path opens once the template is upgraded to Next.js 16; for now, run this inside an existing Next.js app.",
-      );
+    // A stopped first run leaves its progress folder behind; that is still empty.
+    const entries = readdirSync(cwd).filter(
+      (f) => !IGNORED.has(f) && !(f === ".gitignore" && isOwnGitignore(cwd)),
+    );
+    if (entries.length > 0) {
+      ui.stop("Run this inside the app's folder (the one that has package.json), or in an empty folder to start a new site.");
     }
-    ui.stop("Run this inside the app's folder: the one that has package.json.");
+    // A new site: no app and no repository yet, only the accounts that create them.
+    await signedIn(cwd, run, ui);
+    return { mode: "new", nextMajor: null };
   }
 
   const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
@@ -49,13 +59,7 @@ export async function preflight({ cwd, run, ui, resuming = false }) {
     );
   }
 
-  const gh = await run("gh", ["auth", "status"], { cwd });
-  if (gh.code === 127) ui.stop("The GitHub CLI is not installed.", "Install it from https://cli.github.com");
-  if (gh.code !== 0) ui.stop("You are not signed in to GitHub.", "gh auth login");
-
-  const vercel = await run("vercel", ["whoami"], { cwd });
-  if (vercel.code === 127) ui.stop("The Vercel CLI is not installed.", "npm install -g vercel");
-  if (vercel.code !== 0) ui.stop("You are not signed in to Vercel.", "vercel login");
+  await signedIn(cwd, run, ui);
 
   const git = await run("git", ["status", "--porcelain"], { cwd });
   if (git.code !== 0) ui.stop("This folder is not a git repository yet.", "git init");
@@ -67,12 +71,33 @@ export async function preflight({ cwd, run, ui, resuming = false }) {
     );
   }
 
+  return { mode: "existing", nextMajor };
+}
+
+/**
+ * GitHub and Vercel sign-ins (the command acts through them), plus a warning
+ * when Claude Code is missing.
+ *
+ * @param {string} cwd
+ * @param {Runner} run
+ * @param {Ui} ui
+ */
+async function signedIn(cwd, run, ui) {
+  const git = await run("git", ["--version"], { cwd });
+  if (git.code === 127) ui.stop("Git is not installed.", "Install it from https://git-scm.com");
+
+  const gh = await run("gh", ["auth", "status"], { cwd });
+  if (gh.code === 127) ui.stop("The GitHub CLI is not installed.", "Install it from https://cli.github.com");
+  if (gh.code !== 0) ui.stop("You are not signed in to GitHub.", "gh auth login");
+
+  const vercel = await run("vercel", ["whoami"], { cwd });
+  if (vercel.code === 127) ui.stop("The Vercel CLI is not installed.", "npm install -g vercel");
+  if (vercel.code !== 0) ui.stop("You are not signed in to Vercel.", "vercel login");
+
   const claude = await run("claude", ["--version"], { cwd });
   if (claude.code !== 0) {
     ui.info(
-      "Heads up: Claude Code is not installed. You will need it at step 7, where it helps wire your layout and choose the editable text. Install: https://claude.com/claude-code",
+      "Heads up: Claude Code is not installed. You will need it later, where it helps wire your layout and choose the editable text. Install: https://claude.com/claude-code",
     );
   }
-
-  return { mode: "existing", nextMajor };
 }

package/cli/provisioner.mjs

@@ -48,14 +48,15 @@ export function cliProvisioner({ cwd, run, scope }) {
 
   return {
     async createRepoFromTemplate(name) {
+      // No --clone: it would clone into ./<name>, and this folder already holds
+      // the command's progress. The command pulls the repository in itself.
       await must("gh", [
         "repo",
         "create",
         `Web-My-Money/${name}`,
         "--private",
         "--template",
-        "Web-My-Money/wmm-app-template",
-        "--clone",
+        "Web-My-Money/wmm-site-template",
       ]);
     },
     async createRepoFromSource(name) {

package/cli/scaffold.mjs

@@ -0,0 +1,155 @@
+// @ts-check
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { isOwnGitignore } from "./state.mjs";
+
+/**
+ * A new site from WMM's template (spec 2026-10-09 §3.2): pull the repository
+ * GitHub created from `Web-My-Money/wmm-site-template` into the developer's
+ * folder, then make it this site's.
+ */
+
+/** @typedef {import("./run.mjs").Runner} Runner */
+
+/** The only two strings in the template that become this site's (see its README). */
+export const MARKERS = { key: "wmm-template-site", name: "WMM Template Site" };
+
+const FETCH_TRIES = 10;
+const FETCH_WAIT_MS = 3000;
+
+/**
+ * GitHub copies a template into the new repository in the background, so for a
+ * few seconds the repository has no `main`. That case is waited out; any other
+ * failure (usually git not signed in to GitHub) stops at once with the fix.
+ *
+ * @param {{ cwd: string, run: Runner, sleep: (ms: number) => Promise<void>, name: string }} ctx
+ * @returns {Promise<{ ok: true } | { ok: false, message: string, nextCommand?: string }>}
+ */
+export async function pullTemplateRepo({ cwd, run, sleep, name }) {
+  const url = `https://github.com/Web-My-Money/${name}.git`;
+  if (!existsSync(path.join(cwd, ".git"))) {
+    const init = await run("git", ["init", "-b", "main"], { cwd });
+    if (init.code !== 0) return { ok: false, message: `git could not start a repository here: ${lastLine(init)}` };
+  }
+  const origin = await run("git", ["remote", "get-url", "origin"], { cwd });
+  if (origin.code !== 0) {
+    const add = await run("git", ["remote", "add", "origin", url], { cwd });
+    if (add.code !== 0) return { ok: false, message: `git could not add the new repository: ${lastLine(add)}` };
+  } else {
+    // A folder already tied to some other repository would fetch the wrong one forever.
+    const current = origin.stdout.trim();
+    const ours = new RegExp(`github\\.com[/:]Web-My-Money/${name}(\\.git)?$`, "i");
+    if (!ours.test(current)) {
+      return {
+        ok: false,
+        message: `This folder's git remote points at ${current}, not at Web-My-Money/${name}. Point it at the new site's repository, then run this again.`,
+        nextCommand: `git remote set-url origin ${url}`,
+      };
+    }
+  }
+
+  for (let i = 0; i < FETCH_TRIES; i++) {
+    const r = await run("git", ["fetch", "origin", "main"], { cwd });
+    if (r.code === 0) {
+      // The progress file's one-line .gitignore would block checking out the
+      // template's own (which already ignores the progress folder).
+      if (isOwnGitignore(cwd)) rmSync(path.join(cwd, ".gitignore"));
+      const co = await run("git", ["checkout", "-B", "main", "origin/main"], { cwd });
+      if (co.code !== 0) return { ok: false, message: `git could not check out the new site: ${lastLine(co)}` };
+      return { ok: true };
+    }
+    if (!/couldn't find remote ref/i.test(r.stderr)) {
+      return {
+        ok: false,
+        message: `git could not download the new repository: ${lastLine(r)}. If git is not signed in to GitHub, this fixes it; then run this again.`,
+        nextCommand: "gh auth setup-git",
+      };
+    }
+    if (i < FETCH_TRIES - 1) await sleep(FETCH_WAIT_MS);
+  }
+  return { ok: false, message: "GitHub is still preparing the repository. Run this again in a minute; it continues from here." };
+}
+
+// The same rule and reserved ids as defineSiteBrand (src/brand/index.ts): in a
+// template site the key IS the theme id, so it must be a valid client theme.
+const THEME_ID = /^[a-z][a-z0-9-]{0,40}$/;
+const WMM_THEMES = ["wmm", "site", "light", "dark"];
+
+/**
+ * Why a site key cannot be used for a site made from the template, or null.
+ * Checked before anything is created, so a bad key never leaves a repository behind.
+ *
+ * @param {string} siteKey
+ * @returns {string | null}
+ */
+export function templateKeyProblem(siteKey) {
+  if (THEME_ID.test(siteKey) && !WMM_THEMES.includes(siteKey)) return null;
+  return `The site key "${siteKey}" cannot be used for a site made from WMM's template: it becomes the brand theme id, so it must start with a letter, use only lowercase letters, digits and dashes, be at most 41 characters, and not be one of ${WMM_THEMES.join(", ")}. Add the site again in Studio with a key like that.`;
+}
+
+/** @param {{ stdout: string, stderr: string }} r */
+function lastLine(r) {
+  return (r.stderr || r.stdout).trim().split(/\r?\n/).slice(-1)[0] ?? "";
+}
+
+/**
+ * Replace the template's markers in every tracked file, escaped for where they
+ * land, and swap the template's README for one about this site.
+ *
+ * @param {{ cwd: string, run: Runner, siteKey: string, siteName: string }} ctx
+ * @returns {Promise<string[]>} the files that changed
+ */
+export async function personalise({ cwd, run, siteKey, siteName }) {
+  const problem = templateKeyProblem(siteKey);
+  if (problem) throw new Error(problem);
+  const listed = await run("git", ["ls-files"], { cwd });
+  const files = listed.stdout.split(/\r?\n/).map((f) => f.trim()).filter(Boolean);
+
+  /** @type {string[]} */
+  const changed = [];
+  for (const rel of files) {
+    const abs = path.join(cwd, rel);
+    if (!existsSync(abs)) continue;
+    if (rel === "README.md") {
+      writeFileSync(abs, siteReadme(siteName));
+      changed.push(rel);
+      continue;
+    }
+    const body = readFileSync(abs, "utf8");
+    if (body.includes("\0")) continue; // binary
+    if (!body.includes(MARKERS.key) && !body.includes(MARKERS.name)) continue;
+    const next = body.replaceAll(MARKERS.key, siteKey).replaceAll(MARKERS.name, nameFor(rel, siteName));
+    writeFileSync(abs, next);
+    changed.push(rel);
+  }
+  return changed;
+}
+
+/**
+ * The display name, escaped for the file it lands in: inside a JSON or code
+ * string it must not end the string; inside a CSS comment it must not end the
+ * comment.
+ *
+ * @param {string} rel
+ * @param {string} name
+ */
+function nameFor(rel, name) {
+  if (/\.(json|[cm]?[jt]sx?)$/.test(rel)) return JSON.stringify(name).slice(1, -1);
+  if (rel.endsWith(".css")) return name.replaceAll("*/", "");
+  return name;
+}
+
+/** @param {string} name */
+function siteReadme(name) {
+  return `# ${name}
+
+${name}'s website, built from WMM's site template and connected to WMM Studio.
+
+- Copy: \`dictionaries/en.json\` and \`es.json\` (same keys in both).
+- Brand colours: \`app/client-theme.css\`.
+- What the client can edit in Studio: \`lib/content-manifest.ts\`.
+- Rules for working on this site: \`CLAUDE.md\`.
+
+Before every push: \`npm run verify\`.
+`;
+}

package/cli/state.mjs

@@ -10,12 +10,24 @@ import path from "node:path";
  * @typedef {{
  *   siteKey: string, siteName: string, studioUrl: string, manifestUrl: string,
  *   revalidateUrl: string, modules: string[], readyToken: string, done: string[],
- *   theme?: string, scope?: string, baseBranch?: string, siteHasKey?: boolean
+ *   theme?: string, scope?: string, baseBranch?: string, siteHasKey?: boolean,
+ *   mode?: "new" | "existing", repoCreated?: boolean
  * }} OnboardingState
  */
 
 const DIR = ".wmm-onboarding";
 
+/**
+ * True when `.gitignore` is the one-line file saveState wrote into a folder that
+ * had none: the command's own file, safe to treat as absent.
+ *
+ * @param {string} cwd
+ */
+export function isOwnGitignore(cwd) {
+  const file = path.join(cwd, ".gitignore");
+  return existsSync(file) && readFileSync(file, "utf8").trim() === `${DIR}/`;
+}
+
 /** @param {string} cwd @returns {OnboardingState | null} */
 export function loadState(cwd) {
   const file = path.join(cwd, DIR, "state.json");

package/package.json

@@ -1,33 +1,33 @@
-{
-  "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"]
-}
+{
+  "name": "@web-my-money/studio-consumer",
+  "version": "2.4.1",
+  "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

@@ -1,96 +1,125 @@
----
-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.
+---
+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. For a new site made from WMM's template, sets the client's colours and first copy instead. 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.
+
+## 0. A new site from WMM's template (`"mode": "new"` in state.json)
+
+The site was just created from `Web-My-Money/wmm-site-template`, so sections 1 and 2 are
+already done: the layout (`app/[lang]/layout.tsx`) has the brand attributes, the editor
+overlay and analytics, and `proxy.ts` sets the visitor cookie. Check they are there, say so in
+one line, and skip to the client's details. Read `CLAUDE.md` for the site's rules.
+
+1. Ask the developer, one question at a time:
+   - the business name exactly as the client writes it, and one sentence on what they do and
+     for whom;
+   - the brand's primary and accent colours as hex codes (from the client's logo or brand
+     guide; "not yet" is a fine answer: leave the magenta placeholder and say so);
+   - which language visitors should land in by default (English or Spanish);
+   - where the main button should go (the client's booking calendar or form link), if known.
+2. Then propose, as one diff per file, and write only after a yes:
+   - `app/client-theme.css`: the colours (`--primary`, `--accent`, and a readable
+     `--primary-foreground`: white on a dark primary, near-black on a light one);
+   - `dictionaries/en.json` and `es.json`: `meta`, `hero` and `services` from what the
+     developer told you, in both languages (Spanish neutral, no regional slang). Keep every
+     key; the two files must keep identical keys;
+   - `lib/i18n.ts`: `DEFAULT_LOCALE`, only if it changes;
+   - the main button's link in `app/[lang]/page.tsx` (the `TODO` on the closing banner).
+3. **Never invent reviews, results, prices or credentials.** Leave the review placeholders
+   and the FAQ answers you do not know, and list them as "still needed from the client".
+4. Section 3 below is a review here, not a rebuild: `lib/content-manifest.ts` already makes
+   the home page's marketing text editable. Show the list of slots, ask whether anything should
+   be added or removed, and change it only on a yes.
+5. Go to section 4.
+
+## 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/collector.ts

@@ -75,7 +75,7 @@ function armFor(path: string): string | undefined {
   try {
     const { variant, experimentKey } = resolveVariant(
       path,
-      cookieVisitorId(),
+      serverSeenVisitorId(),
       runningExperiments,
     );
     return experimentKey ? variant : undefined;
@@ -268,17 +268,57 @@ function cookieVisitorId(): string | null {
   }
 }
 
+/**
+ * Mirror the visitor id into the `wmm_vid` cookie.
+ *
+ * The proxy only mints this cookie on routes that can run an A/B test, so that
+ * the rest of the site stays cacheable. The collector still needs it everywhere
+ * — it stamps `visitorId` on an event from the cookie and from nothing else, and
+ * an event without one drops out of the comparison — and a visitor who lands on a
+ * static page first must keep the same identity when they later reach /med-spa,
+ * where the server reads the cookie. Writing it here, before the first event is
+ * built, covers both: the id is the one already in storage, so it never changes.
+ *
+ * Same attributes the proxy uses, for the same reasons: first-party, readable by
+ * the browser, no PII, the maximum lifetime Chrome honours.
+ */
+function writeVisitorCookie(id: string): void {
+  try {
+    document.cookie =
+      `wmm_vid=${encodeURIComponent(id)}; Max-Age=${400 * 24 * 60 * 60}; Path=/; SameSite=Lax; Secure`;
+  } catch {
+    // Cookies blocked: events fall back to the storage id on the client, which is
+    // the pre-existing behaviour for a visitor the middleware never reached.
+  }
+}
+
+/**
+ * The cookie as it arrived with this document — the identity the server could
+ * have bucketed this render with.
+ *
+ * Captured on first use and never refreshed, because this module now writes the
+ * cookie itself (see writeVisitorCookie). Reading it live would make the arm
+ * label depend on a cookie the server never saw: a page the proxy did not stamp
+ * would get one written here and then be labelled with an arm nobody assigned.
+ * The label must only ever come from an id that was on the request.
+ */
+let seenAtLoad: string | null | undefined;
+function serverSeenVisitorId(): string | null {
+  if (seenAtLoad === undefined) seenAtLoad = cookieVisitorId();
+  return seenAtLoad;
+}
+
 function visitorId(): string {
-  const fromCookie = cookieVisitorId();
+  const fromCookie = serverSeenVisitorId();
   if (fromCookie) return fromCookie;
 
-  // No cookie: middleware has not run for this document (a cached shell, a route
-  // it does not match). Fall back to storage so events are still attributable.
-  const existing = readStore(VISITOR_KEY);
-  if (existing) return existing;
-  const fresh = uuid();
-  writeStore(VISITOR_KEY, fresh);
-  return fresh;
+  // No cookie: this route is not one the proxy mints it on, or the visitor
+  // blocked it. Use the stored id, creating one on first sight, and publish it as
+  // the cookie so the server and the collector see the same identity.
+  const id = readStore(VISITOR_KEY) ?? uuid();
+  writeStore(VISITOR_KEY, id);
+  if (cookieVisitorId() !== id) writeVisitorCookie(id);
+  return id;
 }
 
 /**

package/src/analytics/index.ts

@@ -1,37 +1,37 @@
-/** 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";
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "2.4.1";
+
+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/analytics/proxy.ts

@@ -26,6 +26,14 @@ function newVisitorId(): string {
 export function withVisitorCookie(req: NextRequest): NextResponse {
   const { pathname } = req.nextUrl;
 
+  // A first-time visitor has no cookie yet. Mint the id here and put it on the
+  // REQUEST too, so this very render buckets them. Setting it only on the
+  // response rendered control on the first page view while the browser stamped
+  // the new id's arm on events, filing visitors who saw control under B.
+  const existingVisitorId = req.cookies.get(VISITOR_COOKIE)?.value;
+  const visitorId = existingVisitorId || newVisitorId();
+  if (!existingVisitorId) req.cookies.set(VISITOR_COOKIE, visitorId);
+
   // The path, as a request header.
   //
   // Server components cannot read their own pathname, and A/B assignment has to
@@ -71,10 +79,10 @@ export function withVisitorCookie(req: NextRequest): NextResponse {
    * Not httpOnly, on purpose: the collector reads it in the browser. It carries
    * no PII — it is a random id, exactly like the localStorage value it replaces.
    */
-  if (!req.cookies.get(VISITOR_COOKIE)?.value) {
+  if (!existingVisitorId) {
     response.cookies.set({
       name: VISITOR_COOKIE,
-      value: newVisitorId(),
+      value: visitorId,
       maxAge: VISITOR_COOKIE_MAX_AGE,
       path: "/",
       sameSite: "lax",

package/src/attribution/index.ts

@@ -1,14 +1,14 @@
-/** 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";
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "2.4.1";
+
+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.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 };
-}
+/**
+ * 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.4.1";
+
+/** 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 };
+}

package/src/content/index.ts

@@ -1,27 +1,27 @@
-/** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "2.3.0";
-
-export {
-  createContentClient,
-  type ContentClient,
-  type ContentManifest,
-  type ManifestSlot,
-  type StudioForm,
-} from "./payload";
-export { createManifestHandler } from "./manifest-handler";
-export { createRevalidateHandler } from "./revalidate-handler";
-export { studioFrameAncestors } from "./headers";
-export {
-  overrideValueForDict,
-  resolveLocalized,
-  setPath,
-  withSlotOverride,
-} from "./dict-overrides";
-export {
-  WmmEditOverlay,
-  StudioSlotPreviewBridge,
-  StudioFormPreviewBridge,
-  type PreviewableSlot,
-  type StudioPreviewFormProps,
-  type StudioPreviewFormComponent,
-} from "./preview";
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "2.4.1";
+
+export {
+  createContentClient,
+  type ContentClient,
+  type ContentManifest,
+  type ManifestSlot,
+  type StudioForm,
+} from "./payload";
+export { createManifestHandler } from "./manifest-handler";
+export { createRevalidateHandler } from "./revalidate-handler";
+export { studioFrameAncestors } from "./headers";
+export {
+  overrideValueForDict,
+  resolveLocalized,
+  setPath,
+  withSlotOverride,
+} from "./dict-overrides";
+export {
+  WmmEditOverlay,
+  StudioSlotPreviewBridge,
+  StudioFormPreviewBridge,
+  type PreviewableSlot,
+  type StudioPreviewFormProps,
+  type StudioPreviewFormComponent,
+} from "./preview";

package/src/image/index.ts

@@ -1,14 +1,14 @@
-/** Pure; safe in client components. */
-export const PACKAGE_VERSION = "2.3.0";
-
-/**
- * CSS `object-position` for a Studio image value's focal point (spec §6.2).
- * Anything missing or out of range reads as the centre — the browser default —
- * so an image without a focal point renders exactly as before.
- */
-export function focalObjectPosition(value: unknown): string {
-  const f = (value as { focal?: { x?: unknown; y?: unknown } } | null | undefined)?.focal;
-  const ok = (n: unknown): n is number => typeof n === "number" && n >= 0 && n <= 1;
-  if (!f || !ok(f.x) || !ok(f.y)) return "50% 50%";
-  return `${Math.round(f.x * 100)}% ${Math.round(f.y * 100)}%`;
-}
+/** Pure; safe in client components. */
+export const PACKAGE_VERSION = "2.4.1";
+
+/**
+ * CSS `object-position` for a Studio image value's focal point (spec §6.2).
+ * Anything missing or out of range reads as the centre — the browser default —
+ * so an image without a focal point renders exactly as before.
+ */
+export function focalObjectPosition(value: unknown): string {
+  const f = (value as { focal?: { x?: unknown; y?: unknown } } | null | undefined)?.focal;
+  const ok = (n: unknown): n is number => typeof n === "number" && n >= 0 && n <= 1;
+  if (!f || !ok(f.x) || !ok(f.y)) return "50% 50%";
+  return `${Math.round(f.x * 100)}% ${Math.round(f.y * 100)}%`;
+}

package/src/next/index.d.mts

@@ -1,13 +1,13 @@
-// Hand-maintained alongside index.mjs.
-
-type HeaderRule = { source: string; headers: { key: string; value: string }[] };
-
-/**
- * Wrap a site's next.config so Studio can edit it: transpiles this package,
- * sets `frame-ancestors 'self' <studio>` (spliced into an existing CSP), and
- * refuses X-Frame-Options. Wrapping twice is the same as once.
- */
-export declare function withStudio<T extends object>(
-  config: T,
-  opts?: { studioOrigins?: string[] },
-): T & { transpilePackages: string[]; headers: () => Promise<HeaderRule[]> };
+// Hand-maintained alongside index.mjs.
+
+type HeaderRule = { source: string; headers: { key: string; value: string }[] };
+
+/**
+ * Wrap a site's next.config so Studio can edit it: transpiles this package,
+ * sets `frame-ancestors 'self' <studio>` (spliced into an existing CSP), and
+ * refuses X-Frame-Options. Wrapping twice is the same as once.
+ */
+export declare function withStudio<T extends object>(
+  config: T,
+  opts?: { studioOrigins?: string[] },
+): T & { transpilePackages: string[]; headers: () => Promise<HeaderRule[]> };