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

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

package/src/content/manifest-handler.ts

@@ -1,4 +1,4 @@
-import { NextResponse } from "next/server";
+import { connection, NextResponse } from "next/server";
 import type { SiteBrand } from "../brand/index";
 import type { ContentManifest } from "./payload";
 
@@ -12,14 +12,11 @@ import type { ContentManifest } from "./payload";
  * Takes the app's own `getManifest` so the manifest itself — the content model —
  * stays in the consuming app, not in this package.
  *
- * The consumer's route file must ALSO export `export const dynamic =
- * "force-dynamic";` alongside `export const GET = createManifestHandler(...)`.
- * The source route carried that export at module scope, and Next requires it
- * literally in the route file — re-exporting it through this factory would not
- * register with Next's route config, so this package cannot carry it for you.
- * Leaving it off silently changes the route from always-fresh to
- * statically-cached at build time, which means Studio's manifest sync would
- * reconcile against stale slot defaults instead of the live dictionary.
+ * The handler waits for a real request (`connection()`), so the route is always
+ * fresh: with or without `cacheComponents`. No `export const dynamic` is needed
+ * in the route file any more, and under `cacheComponents` Next refuses one. An
+ * existing `export const dynamic = "force-dynamic"` in an app WITHOUT
+ * cacheComponents is harmless and can stay.
  */
 export function createManifestHandler(
   getManifest: () => Promise<ContentManifest>,
@@ -40,6 +37,11 @@ export function createManifestHandler(
     );
   }
   return async function GET() {
+    // Wait for a real request. In an app with `cacheComponents` on, a GET route
+    // that reads no request data is prerendered at build time, so Studio would
+    // sync against a stale manifest; `export const dynamic` is not allowed there.
+    // Without cacheComponents this is a no-op (GET routes are dynamic already).
+    await connection();
     const manifest = await getManifest();
     return NextResponse.json(
       { ...manifest, brand: { theme: brand.theme, style: brand.style, wmmSite: brand.wmmSite } },

package/src/image/index.ts

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

package/src/next/index.d.mts

@@ -0,0 +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[]> };

package/src/next/index.mjs

@@ -0,0 +1,103 @@
+// @ts-check
+import { studioFrameAncestors } from "../content/headers.mjs";
+
+/**
+ * `withStudio(nextConfig)` — the one next.config edit the onboarding command
+ * makes (spec 2026-10-09 §3.3). Plain ESM for the same reason as headers.mjs:
+ * Next loads next.config through native `import()`, which cannot reach the
+ * package's `.ts` entries.
+ *
+ * - transpiles this package (it ships TypeScript source);
+ * - lets Studio frame the site's pages for click-to-edit, and nothing else:
+ *   `frame-ancestors 'self' <studio>` on every page. An existing
+ *   Content-Security-Policy is spliced into, never duplicated: browsers apply
+ *   the strictest of several CSP headers, so a second one would silently win
+ *   or lose;
+ * - refuses X-Frame-Options, which has no allowlist and would block Studio.
+ *
+ * Wrapping twice is the same as wrapping once.
+ */
+
+const PACKAGE = "@web-my-money/studio-consumer";
+const DEFAULT_ORIGINS = ["https://studio.webmymoney.com"];
+const WRAPPED = Symbol.for("wmm.withStudio");
+
+/**
+ * @typedef {{ key: string, value: string }} HeaderEntry
+ * @typedef {{ source: string, headers: HeaderEntry[] } & Record<string, unknown>} HeaderRule
+ * @typedef {{ transpilePackages?: string[], headers?: () => Promise<HeaderRule[]> } & Record<string, unknown>} NextLikeConfig
+ */
+
+/**
+ * @param {string} csp
+ * @param {string} directive
+ */
+function spliceFrameAncestors(csp, directive) {
+  const parts = csp
+    .split(";")
+    .map((p) => p.trim())
+    .filter(Boolean);
+  const at = parts.findIndex((p) => /^frame-ancestors(\s|$)/i.test(p));
+  if (at === -1) parts.push(directive);
+  else parts[at] = directive;
+  return parts.join("; ");
+}
+
+/**
+ * @template {NextLikeConfig} T
+ * @param {T} config
+ * @param {{ studioOrigins?: string[] }} [opts]
+ * @returns {T & { transpilePackages: string[], headers: () => Promise<HeaderRule[]> }}
+ */
+export function withStudio(config, opts = {}) {
+  if (/** @type {Record<symbol, unknown>} */ (/** @type {unknown} */ (config))[WRAPPED]) {
+    return /** @type {T & { transpilePackages: string[], headers: () => Promise<HeaderRule[]> }} */ (config);
+  }
+  // Validates the origins now (wildcards, paths), so a bad list fails the build.
+  const directive = studioFrameAncestors(opts.studioOrigins ?? DEFAULT_ORIGINS).value;
+  const original = config.headers;
+
+  const transpilePackages = [...(config.transpilePackages ?? [])];
+  if (!transpilePackages.includes(PACKAGE)) transpilePackages.push(PACKAGE);
+
+  /** @returns {Promise<HeaderRule[]>} */
+  async function headers() {
+    const rules = original ? [...(await original())] : [];
+    for (const rule of rules) {
+      for (const h of rule.headers ?? []) {
+        if (h.key.toLowerCase() === "x-frame-options") {
+          throw new Error(
+            `withStudio: remove X-Frame-Options from the "${rule.source}" rule. It cannot allow Studio to frame the page; withStudio sets frame-ancestors instead.`,
+          );
+        }
+      }
+    }
+    const out = rules.map((rule) => ({
+      ...rule,
+      headers: (rule.headers ?? []).map((h) => {
+        if (h.key.toLowerCase() !== "content-security-policy") return h;
+        return { key: h.key, value: spliceFrameAncestors(h.value, directive) };
+      }),
+    }));
+    // Every page must carry the directive. A CSP on a narrow route, or on a
+    // /:path* rule that only applies sometimes (has/missing), does not cover
+    // the rest, so an unconditional /:path* rule gets one too.
+    const unconditional = (/** @type {HeaderRule} */ r) => r.source === "/:path*" && !("has" in r) && !("missing" in r);
+    const covered = out.some(
+      (r) => unconditional(r) && r.headers.some((h) => h.key.toLowerCase() === "content-security-policy"),
+    );
+    if (!covered) {
+      const all = out.find(unconditional);
+      if (all) all.headers = [...all.headers, { key: "Content-Security-Policy", value: directive }];
+      else out.push({ source: "/:path*", headers: [{ key: "Content-Security-Policy", value: directive }] });
+    }
+    return out;
+  }
+
+  const wrapped = { ...config, transpilePackages, headers };
+  // Non-enumerable: Next validates config keys and would warn about a marker.
+  Object.defineProperty(wrapped, WRAPPED, { value: true, enumerable: false });
+  return /** @type {T & { transpilePackages: string[], headers: () => Promise<HeaderRule[]> }} */ (
+    /** @type {unknown} */ (wrapped)
+  );
+}