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

package/src/content/index.ts

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

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>,
@@ -31,7 +28,20 @@ export function createManifestHandler(
    */
   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() {
+    // 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.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)}%`;
-}
+/** 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)}%`;
+}

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)
+  );
+}