@web-my-money/studio-consumer 1.0.0 → 2.2.0

package/README.md

@@ -12,8 +12,77 @@ for no gain.
 - `@web-my-money/studio-consumer/analytics`
 - `@web-my-money/studio-consumer/content`
 - `@web-my-money/studio-consumer/attribution`
+- `@web-my-money/studio-consumer/headers`
+- `@web-my-money/studio-consumer/brand` (2.0.0)
+- `@web-my-money/studio-consumer/image` (2.1.0)
+
+Each entry point exports `PACKAGE_VERSION`, to prove at runtime that a consumer
+is resolving this package rather than a stale copy.
+
+## Brand (2.0.0, breaking)
+
+A site declares its brand theme in code. Every invalid input throws, and this
+runs while the root layout renders, so a site with no brand, a malformed theme
+id, or WMM's own theme fails its build instead of silently inheriting WMM's
+palette.
+
+```ts
+// lib/brand.ts — its own module: Next refuses unknown named exports from a layout file
+import { defineSiteBrand } from "@web-my-money/studio-consumer/brand";
+
+export const brand = defineSiteBrand({ theme: "acme", style: "flat" });
+```
+
+```tsx
+// app/layout.tsx
+import { brandRootAttributes } from "@web-my-money/studio-consumer/brand";
+import { brand } from "@/lib/brand";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return <html lang="en" {...brandRootAttributes(brand)}><body>{children}</body></html>;
+}
+```
+
+```ts
+// app/api/content/manifest/route.ts
+import { brand } from "@/lib/brand";
+
+export const GET = createManifestHandler(getManifest, brand);
+export const dynamic = "force-dynamic";
+```
+
+`createManifestHandler` now REQUIRES the brand (the breaking change in 2.0.0), so
+Studio records the theme the site ships. Only a WMM site may use a WMM theme
+(`wmm`, `site`, `light`, `dark`), by passing `wmmSite: true`.
+
+## Image focal point (2.1.0)
+
+An image value edited in Studio can carry `focal: { x, y }` (0–1 from the
+top-left): where the subject is. Apply it so responsive crops keep the subject
+in frame. No focal point, or a malformed one, reads as the centre, which is the
+browser default, so existing images render exactly as before.
+
+```tsx
+import { focalObjectPosition } from "@web-my-money/studio-consumer/image";
+
+<img src={value.url} alt={value.alt.en} style={{ objectFit: "cover", objectPosition: focalObjectPosition(value) }} />
+```
+
+## Analytics collector (2.2.0)
+
+`createCollectHandler` only accepts posts from the site's own pages (`Sec-Fetch-Site`,
+falling back to `Origin`), and it decides each event's A/B arm on the server from the
+`wmm_vid` cookie. The browser's own `variant` is always discarded. Pass the content
+client's `getRunningExperiments` so the arm can be resolved:
+
+```ts
+export const POST = createCollectHandler({
+  siteKey: SITE_KEY,
+  ingestUrl: process.env.FUNNEL_INGEST_URL ?? "",
+  ingestKey: process.env.FUNNEL_INGEST_TOKEN ?? "",
+  getRunningExperiments: () => content.getRunningExperiments(),
+});
+```
+
+Without it, events carry no arm and the site stays out of any A/B comparison.
 
-This package is currently a skeleton: each entry point exports only a
-`PACKAGE_VERSION` constant, used to prove at runtime that a consumer is
-resolving this package rather than a stale copy. Content, analytics, and
-attribution logic land in later tasks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@web-my-money/studio-consumer",
-  "version": "1.0.0",
+  "version": "2.2.0",
   "description": "Consumer-side integration for WMM Studio: content, analytics, attribution.",
   "license": "UNLICENSED",
   "repository": {
@@ -17,7 +17,9 @@
     "./analytics": "./src/analytics/index.ts",
     "./content": "./src/content/index.ts",
     "./attribution": "./src/attribution/index.ts",
-    "./headers": "./src/content/headers.mjs"
+    "./headers": "./src/content/headers.mjs",
+    "./brand": "./src/brand/index.ts",
+    "./image": "./src/image/index.ts"
   },
   "peerDependencies": {
     "next": ">=16",

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,5 +1,5 @@
 /** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "1.0.0";
+export const PACKAGE_VERSION = "2.2.0";
 
 export {
   resolveVariant,

package/src/attribution/index.ts

@@ -1,5 +1,5 @@
 /** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "1.0.0";
+export const PACKAGE_VERSION = "2.2.0";
 
 export {
   getAttribution,

package/src/brand/index.ts

@@ -0,0 +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.2.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 };
+}

package/src/content/index.ts

@@ -1,5 +1,5 @@
 /** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "1.0.0";
+export const PACKAGE_VERSION = "2.2.0";
 
 export {
   createContentClient,

package/src/content/manifest-handler.ts

@@ -1,4 +1,5 @@
 import { NextResponse } from "next/server";
+import type { SiteBrand } from "../brand/index";
 import type { ContentManifest } from "./payload";
 
 /**
@@ -22,13 +23,31 @@ import type { ContentManifest } from "./payload";
  */
 export function createManifestHandler(
   getManifest: () => Promise<ContentManifest>,
+  /**
+   * REQUIRED (2.0.0). The site's brand, from `defineSiteBrand`. Written into the
+   * manifest so Studio records which theme this site ships — a site cannot
+   * publish a manifest without declaring one. Spread LAST so nothing in the
+   * app's own manifest can override it.
+   */
+  brand: SiteBrand,
 ): () => Promise<Response> {
+  // TypeScript requires the brand; a JS caller or a cast can still skip it. Fail
+  // where the mistake is (the site's build), not at Studio's sync. Frozen is the
+  // mark of defineSiteBrand, which validated it.
+  if (!brand || !Object.isFrozen(brand)) {
+    throw new Error(
+      "createManifestHandler: pass the site's brand from defineSiteBrand(...) as the second argument.",
+    );
+  }
   return async function GET() {
     const manifest = await getManifest();
-    return NextResponse.json(manifest, {
-      headers: {
-        "Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
+    return NextResponse.json(
+      { ...manifest, brand: { theme: brand.theme, style: brand.style, wmmSite: brand.wmmSite } },
+      {
+        headers: {
+          "Cache-Control": "public, s-maxage=60, stale-while-revalidate=300",
+        },
       },
-    });
+    );
   };
 }

package/src/image/index.ts

@@ -0,0 +1,14 @@
+/** Pure; safe in client components. */
+export const PACKAGE_VERSION = "2.2.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)}%`;
+}