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

package/README.md

@@ -12,8 +12,59 @@ 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) }} />
+```
 
-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.1.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/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.1.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.1.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.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 };
+}

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.1.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,23 @@ 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> {
   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.1.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)}%`;
+}