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

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