@web-my-money/studio-consumer 1.0.0

package/src/analytics/use-form-analytics.ts

@@ -0,0 +1,256 @@
+"use client";
+
+import { useEffect, useMemo, useRef } from "react";
+import { trackFunnelEvent, type FunnelEventProps } from "./collector";
+
+/**
+ * Funnel analytics for the Studio form renderer
+ * (wmm-studio `docs/analytics/02-form-instrumentation.md`).
+ *
+ * All of the timing, visibility and dedupe logic lives here rather than in the
+ * renderer, for two reasons: the renderer stays readable, and this is unit
+ * testable against a fake clock without mounting a single component.
+ *
+ * THE RULE THIS OBEYS: analytics must never affect form behaviour. The form is
+ * live lead capture on a page with paid traffic behind it, so —
+ *
+ *  - every method swallows its own errors,
+ *  - nothing here is ever awaited,
+ *  - nothing here is React state, so no emit can trigger a render, re-run an
+ *    effect, or become a dependency of anything that gates validation.
+ *
+ * A dropped event costs a row in a chart. A blocked submit costs a lead.
+ */
+
+export type FormAnalytics = {
+  /**
+   * The form became visible (or mounted). Fires `form_view` once.
+   *
+   * Pass the form's ordered step ids. They are what lets a dashboard show a step
+   * nobody has reached yet.
+   *
+   * Without them, step structure can only be inferred from the events that have
+   * actually fired, so a four-step form whose visitors all stop at step 1 looks
+   * like a one-step form — and a dashboard reading it will say so. A form knows
+   * its own shape at mount; this is the one place it can say it out loud.
+   */
+  view(stepIds?: readonly string[]): void;
+  /** A step became active. Starts that step's visible-time clock. */
+  stepView(stepIndex: number, stepId: string): void;
+  /** A step was passed and left forwards. Carries visible time on the step. */
+  stepComplete(stepIndex: number, stepId: string): void;
+  /** The visitor went backwards. `stepIndex`/`stepId` are the DESTINATION. */
+  stepBack(stepIndex: number, stepId: string): void;
+  /** First interaction with any field emits `form_start` once, with the field. */
+  fieldInteraction(field: string): void;
+  /** A validation error was shown to the visitor. */
+  fieldError(field: string, errorKind: string): void;
+  /** The lead was captured / the form completed. Emits `form_submit` once. */
+  submit(): void;
+};
+
+type Emit = (name: string, props: FunnelEventProps) => void;
+
+export type FormAnalyticsOptions = {
+  /** Stable identity for the form. The published slot key where there is one. */
+  formKey: string;
+  /**
+   * False disables every emit. Used for Studio's builder preview: an editor
+   * clicking through a draft must not write events that look like visitor
+   * traffic.
+   */
+  enabled?: boolean;
+  /** Injectable for tests. Defaults to the real collector. */
+  emit?: Emit;
+  /** Injectable clock, so time-on-step is asserted rather than slept through. */
+  now?: () => number;
+};
+
+/**
+ * Visible-time accounting for the active step.
+ *
+ * `msOnStep` measures time the step was actually on screen: the clock pauses
+ * while the tab is hidden and resumes on return. Without pausing, someone who
+ * leaves a tab open over lunch reports a forty-minute step and drags the median
+ * for everyone else — and the median is the number the dashboard shows.
+ */
+type StepClock = {
+  stepIndex: number;
+  stepId: string;
+  /** Visible ms banked from earlier foreground stretches. */
+  bankedMs: number;
+  /** When the current foreground stretch began; null while hidden. */
+  resumedAt: number | null;
+};
+
+export function useFormAnalytics({
+  formKey,
+  enabled = true,
+  emit = trackFunnelEvent,
+  now = Date.now,
+}: FormAnalyticsOptions): FormAnalytics {
+  const clock = useRef<StepClock | null>(null);
+  const viewed = useRef(false);
+  const started = useRef(false);
+  const submitted = useRef(false);
+  /** Keys of `(formKey, stepId)` already abandoned, so a hide/show/hide cycle emits one. */
+  const abandoned = useRef<Set<string>>(new Set());
+
+  // Refs so the visibility listener and the returned methods always read current
+  // values without being re-bound, and without `enabled` becoming
+  // effect dependencies that could re-register the listener mid-form.
+  //
+  // Synced in an effect rather than during render (writing a ref while rendering
+  // is a React violation). This hook's effects are registered before the calling
+  // component's, so the sync always runs before the first `stepView` emit — and
+  // the ref is seeded with the first render's values anyway, so even the very
+  // first read is correct.
+  const config = useRef({ formKey, enabled, emit, now });
+  useEffect(() => {
+    config.current = { formKey, enabled, emit, now };
+  }, [formKey, enabled, emit, now]);
+
+  const api = useMemo<FormAnalytics>(() => {
+    /** Every public method funnels through here; nothing escapes. */
+    const send = (name: string, props: FunnelEventProps = {}) => {
+      const { formKey: key, enabled: on, emit: send_ } = config.current;
+      if (!on) return;
+      try {
+        send_(name, { formKey: key, ...props });
+      } catch {
+        /* a tracking bug must not break a form */
+      }
+    };
+
+    const visibleMs = (): number => {
+      const c = clock.current;
+      if (!c) return 0;
+      const live = c.resumedAt === null ? 0 : config.current.now() - c.resumedAt;
+      return c.bankedMs + live;
+    };
+
+    return {
+      view(stepIds) {
+        if (viewed.current) return;
+        viewed.current = true;
+        /*
+          The step list rides on `label`, which is a plain text column already
+          carried by every event. No migration, and nothing else uses `label` on a
+          `form_view`. Comma-joined because step ids are slugs by convention and
+          cannot contain a comma; a defensive filter keeps that true even if one
+          ever does.
+        */
+        const declared = (stepIds ?? [])
+          .filter((id) => typeof id === "string" && id.length > 0 && !id.includes(","))
+          .join(",");
+        send("form_view", declared ? { label: declared } : {});
+      },
+
+      stepView(stepIndex, stepId) {
+        clock.current = {
+          stepIndex,
+          stepId,
+          bankedMs: 0,
+          resumedAt: config.current.now(),
+        };
+        send("form_step_view", { stepIndex, stepId });
+      },
+
+      stepComplete(stepIndex, stepId) {
+        const msOnStep = clock.current?.stepId === stepId ? visibleMs() : undefined;
+        send("form_step_complete", {
+          stepIndex,
+          stepId,
+          ...(msOnStep === undefined ? {} : { msOnStep }),
+        });
+      },
+
+      stepBack(stepIndex, stepId) {
+        send("form_step_back", { stepIndex, stepId });
+      },
+
+      fieldInteraction(field) {
+        if (started.current) return;
+        started.current = true;
+        // Carries the visible time BEFORE the first field was touched.
+        //
+        // Step 1's clock starts when the step becomes visible, which for a form
+        // rendered into the page is page load — so its `msOnStep` on completion
+        // is "arrival to submit", not "time spent filling the step". That number
+        // is real but it is mostly page-reading time, and read as step friction
+        // it points at the wrong thing entirely.
+        //
+        // Emitting the elapsed time here splits it: this is time-to-engage, and
+        // `msOnStep` on completion minus this is time actually filling in. Both
+        // are useful; conflating them silently is not.
+        send("form_start", { field, msOnStep: visibleMs() });
+      },
+
+      fieldError(field, errorKind) {
+        send("form_field_error", { field, errorKind });
+      },
+
+      submit() {
+        if (submitted.current) return;
+        submitted.current = true;
+        send("form_submit");
+      },
+    };
+    // Intentionally empty: the returned object reads everything through refs, so
+    // it must be stable for the lifetime of the form. A changing identity here
+    // would re-run the caller's effects and re-emit step views.
+  }, []);
+
+  /**
+   * Abandon detection, and the pause half of the step clock.
+   *
+   * `visibilitychange` → hidden, NOT `unload`: unload does not fire reliably on
+   * mobile Safari, which is exactly where abandons happen. The collector flushes
+   * on the same event via `sendBeacon`, so the abandon queued here still leaves
+   * the page.
+   */
+  useEffect(() => {
+    if (typeof document === "undefined") return;
+
+    const onVisibilityChange = () => {
+      try {
+        const c = clock.current;
+        if (document.visibilityState === "hidden") {
+          if (!c) return;
+          // Bank the foreground stretch first, so the abandon reports the dwell
+          // time up to the moment the visitor left.
+          if (c.resumedAt !== null) {
+            c.bankedMs += config.current.now() - c.resumedAt;
+            c.resumedAt = null;
+          }
+          if (submitted.current) return;
+
+          const { formKey: key, enabled: on, emit: send_ } = config.current;
+          if (!on) return;
+          const dedupeKey = `${key}|${c.stepId}`;
+          if (abandoned.current.has(dedupeKey)) return;
+          abandoned.current.add(dedupeKey);
+
+          send_("form_abandon", {
+            formKey: key,
+            stepIndex: c.stepIndex,
+            stepId: c.stepId,
+            msOnStep: c.bankedMs,
+          });
+          return;
+        }
+
+        // Back on screen: resume the clock. `resumedAt` is only null while
+        // hidden, so this cannot double-count a stretch.
+        if (c && c.resumedAt === null) c.resumedAt = config.current.now();
+      } catch {
+        /* never let analytics surface on the page */
+      }
+    };
+
+    document.addEventListener("visibilitychange", onVisibilityChange);
+    return () => document.removeEventListener("visibilitychange", onVisibilityChange);
+  }, []);
+
+  return api;
+}

package/src/attribution/crm.ts

@@ -0,0 +1,20 @@
+import { currentSessionId } from "../analytics/collector";
+
+/**
+ * The CRM custom field that makes a lead traceable to the page that produced it.
+ *
+ * The name is a cross-system contract: Studio's CRM webhook reads it off the
+ * contact and stores it as `crm_events.session_id`, which is what the revenue
+ * join keys on. Rename it and every lead silently stops being attributable —
+ * nothing errors, the contact is still created, and the funnel just shows no
+ * leads.
+ *
+ * Null rather than an empty string when there is no session: a contact carrying
+ * an empty field looks joined and is not.
+ */
+export const SESSION_ID_FIELD = "WMM Session ID";
+
+export function sessionIdField(): Record<string, string> | null {
+  const sessionId = currentSessionId();
+  return sessionId ? { [SESSION_ID_FIELD]: sessionId } : null;
+}

package/src/attribution/index.ts

@@ -0,0 +1,14 @@
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "1.0.0";
+
+export {
+  getAttribution,
+  captureAttribution,
+  getAttributionPayload,
+  computeAttribution,
+  flattenAttribution,
+  hasCampaignSignal,
+} from "./store";
+export type { Attribution, Touch, AttributionPayload } from "./store";
+
+export { sessionIdField, SESSION_ID_FIELD } from "./crm";

package/src/attribution/store.ts

@@ -0,0 +1,225 @@
+/**
+ * Client-side ad-attribution capture.
+ *
+ * Ad clicks land on the site carrying `utm_*`, `fbclid`, `gclid` (and Meta's
+ * `_fbc`/`_fbp` cookies). Because our forms create the GHL contact server-side
+ * via API — bypassing GHL's own tracking script — none of that reaches the
+ * lead unless we carry it ourselves. This module captures it on first load,
+ * persists first-touch + last-touch, and hands a flat payload to every form so
+ * the API routes can forward it into GHL.
+ *
+ * Client-only (reads window/document/cookies) but window-guarded so it can be
+ * imported anywhere without breaking SSR.
+ */
+
+import { currentSessionId } from "../analytics/collector";
+
+const STORAGE_KEY = "wmm_attribution";
+const FIRST_TOUCH_MAX_AGE_DAYS = 90;
+
+// utm_id = the ad-platform campaign id (Meta/GA4 "manual campaign id"), passed
+// via dynamic URL params like {{campaign.id}} — kept for campaign-level reporting.
+const UTM_KEYS = ["utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "utm_id"] as const;
+// gbraid/wbraid are Google's privacy-era click ids (iOS / app→web) sent instead
+// of gclid when gclid isn't available — needed for Google Ads iOS conversions.
+const CLICK_ID_KEYS = ["gclid", "gbraid", "wbraid", "fbclid", "msclkid"] as const;
+
+export type Touch = Partial<Record<(typeof UTM_KEYS)[number] | (typeof CLICK_ID_KEYS)[number], string>> & {
+  referrer?: string;
+  landing_page?: string;
+  timestamp?: string;
+};
+
+export type Attribution = {
+  first: Touch;
+  last: Touch;
+  fbc?: string;
+  fbp?: string;
+};
+
+/** Flat shape merged into a form submission and consumed by the server mapper. */
+export type AttributionPayload = Touch & {
+  fbc?: string;
+  fbp?: string;
+  /**
+   * The analytics session that produced this submit. Not ad attribution — it
+   * rides this payload because this payload is the one channel that already
+   * reaches every lead route, so the alternative is the same three lines
+   * repeated in seven routes and forgotten in the eighth.
+   */
+  wmm_session_id?: string;
+  first_utm_source?: string;
+  first_utm_medium?: string;
+  first_utm_campaign?: string;
+  first_landing_page?: string;
+  first_referrer?: string;
+  first_timestamp?: string;
+};
+
+function isBrowser(): boolean {
+  return typeof window !== "undefined";
+}
+
+function readCookie(name: string): string | undefined {
+  if (!isBrowser()) return undefined;
+  const match = document.cookie.match(new RegExp(`(?:^|; )${name}=([^;]*)`));
+  return match ? decodeURIComponent(match[1]!) : undefined;
+}
+
+/** Only external referrers are attribution-worthy — internal navigation isn't. */
+function externalReferrer(): string | undefined {
+  if (!isBrowser()) return undefined;
+  const ref = document.referrer;
+  if (!ref) return undefined;
+  try {
+    if (new URL(ref).host === window.location.host) return undefined;
+  } catch {
+    return undefined;
+  }
+  return ref;
+}
+
+function readCurrentTouch(): Touch {
+  if (!isBrowser()) return {};
+  const params = new URLSearchParams(window.location.search);
+  const touch: Touch = {};
+  for (const key of [...UTM_KEYS, ...CLICK_ID_KEYS]) {
+    const value = params.get(key);
+    if (value) touch[key] = value;
+  }
+  const ref = externalReferrer();
+  if (ref) touch.referrer = ref;
+  touch.landing_page = window.location.origin + window.location.pathname;
+  touch.timestamp = new Date().toISOString();
+  return touch;
+}
+
+/** A touch is "campaign-bearing" if it has any UTM or click id — not just a bare referrer/landing. */
+export function hasCampaignSignal(touch: Touch): boolean {
+  return [...UTM_KEYS, ...CLICK_ID_KEYS].some((k) => Boolean(touch[k]));
+}
+
+/**
+ * Pure first/last-touch reducer — no browser I/O, so it's directly testable.
+ * First touch is written once and preserved; last touch advances only when the
+ * new visit carries a campaign signal (otherwise the prior last touch stands).
+ */
+export function computeAttribution(
+  stored: Attribution | null,
+  current: Touch,
+  cookies: { fbc?: string; fbp?: string } = {},
+): Attribution {
+  const currentHasSignal = hasCampaignSignal(current);
+  const storedFirstHasData = Boolean(stored?.first && Object.keys(stored.first).length > 0);
+
+  const first = storedFirstHasData
+    ? stored!.first
+    : currentHasSignal || current.referrer
+      ? current
+      : {};
+
+  const last = currentHasSignal ? current : stored?.last ?? first;
+
+  return {
+    first,
+    last,
+    fbc: cookies.fbc ?? stored?.fbc,
+    fbp: cookies.fbp ?? stored?.fbp,
+  };
+}
+
+/** Pure flatten — turns stored attribution into the flat submission payload. */
+export function flattenAttribution(attribution: Attribution): AttributionPayload {
+  const { first, last, fbc, fbp } = attribution;
+  const payload: AttributionPayload = {
+    ...last,
+    ...(fbc ? { fbc } : {}),
+    ...(fbp ? { fbp } : {}),
+  };
+
+  if (first.utm_source) payload.first_utm_source = first.utm_source;
+  if (first.utm_medium) payload.first_utm_medium = first.utm_medium;
+  if (first.utm_campaign) payload.first_utm_campaign = first.utm_campaign;
+  if (first.landing_page) payload.first_landing_page = first.landing_page;
+  if (first.referrer) payload.first_referrer = first.referrer;
+  if (first.timestamp) payload.first_timestamp = first.timestamp;
+
+  return payload;
+}
+
+function loadStored(): Attribution | null {
+  if (!isBrowser()) return null;
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY) ?? readCookie(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Attribution;
+    if (parsed && typeof parsed === "object" && parsed.first && parsed.last) return parsed;
+  } catch {
+    /* corrupt or unavailable — treat as no prior attribution */
+  }
+  return null;
+}
+
+function persist(attribution: Attribution): void {
+  if (!isBrowser()) return;
+  const raw = JSON.stringify(attribution);
+  try {
+    window.localStorage.setItem(STORAGE_KEY, raw);
+  } catch {
+    /* localStorage may be blocked; cookie below is the fallback */
+  }
+  const maxAge = FIRST_TOUCH_MAX_AGE_DAYS * 24 * 60 * 60;
+  document.cookie = `${STORAGE_KEY}=${encodeURIComponent(raw)}; path=/; max-age=${maxAge}; SameSite=Lax`;
+}
+
+/**
+ * Meta's click cookie. If `_fbc` isn't set yet but an `fbclid` is on the URL,
+ * synthesize it in Meta's documented format so CAPI can match the click.
+ */
+function resolveFbc(currentTouch: Touch): string | undefined {
+  const cookie = readCookie("_fbc");
+  if (cookie) return cookie;
+  const fbclid = currentTouch.fbclid;
+  if (fbclid) return `fb.1.${Date.now()}.${fbclid}`;
+  return undefined;
+}
+
+/**
+ * Capture attribution from the current URL and merge into stored first/last
+ * touch. Idempotent and safe to call on every page mount. Returns the merged
+ * attribution (or null on the server).
+ */
+export function captureAttribution(): Attribution | null {
+  if (!isBrowser()) return null;
+
+  const current = readCurrentTouch();
+  const stored = loadStored();
+  const next = computeAttribution(stored, current, {
+    fbc: resolveFbc(current),
+    fbp: readCookie("_fbp"),
+  });
+
+  persist(next);
+  return next;
+}
+
+/** Read stored attribution without re-capturing. */
+export function getAttribution(): Attribution | null {
+  return loadStored();
+}
+
+/** Flatten stored attribution into the payload merged into form submissions. */
+export function getAttributionPayload(): AttributionPayload {
+  const attribution = loadStored() ?? captureAttribution();
+  const payload = attribution ? flattenAttribution(attribution) : {};
+  // Read, never minted, and never allowed to throw: a lead must be submittable
+  // with no analytics session at all. See docs/analytics/03 §3 — "a lost
+  // attribution row is acceptable; a lost lead is not."
+  try {
+    const sessionId = currentSessionId();
+    if (sessionId) payload.wmm_session_id = sessionId;
+  } catch {
+    /* no session available — submit without it */
+  }
+  return payload;
+}

package/src/content/dict-overrides.ts

@@ -0,0 +1,101 @@
+/**
+ * Merging a Studio slot override into a dictionary.
+ *
+ * Extracted from lib/content.ts so the Studio slot-preview bridge can run the
+ * SAME merge in the browser that the server runs during a real render. That
+ * sharing is the point, not a convenience: a preview built on a second
+ * implementation of this logic would drift from production and quietly start
+ * lying about what a publish will look like — which is the one thing a preview
+ * exists not to do.
+ *
+ * Deliberately free of `server-only` and of any import that pulls it in.
+ */
+
+/** Resolve a `{ en, es }` localized value to the locale string; pass anything
+ *  else through unchanged. */
+export function resolveLocalized(v: unknown, isEs: boolean): unknown {
+  // An ARRAY of localized pairs — a list item's `localizedTextList` field, e.g. a
+  // med-spa system step's `tags` — resolves element by element. Needed because an
+  // array is not itself a localized pair, so without this branch it falls through
+  // untouched and the page receives `[{ en, es }, …]` where it renders strings.
+  if (Array.isArray(v)) return v.map((el) => resolveLocalized(el, isEs));
+  if (v && typeof v === "object" && ("en" in v || "es" in v)) {
+    const o = v as { en?: string; es?: string };
+    return (isEs ? o.es : o.en) || o.en;
+  }
+  return v;
+}
+
+/** Flatten a list item: resolve every `{ en, es }` field to the locale string,
+ *  leaving locale-invariant fields (author, company, video, hidden, …) as-is. */
+export function resolveLocalizedFields(item: unknown, isEs: boolean): unknown {
+  if (!item || typeof item !== "object") return item;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(item as Record<string, unknown>)) {
+    out[k] = resolveLocalized(v, isEs);
+  }
+  return out;
+}
+
+/** Set a nested value by dot-path; no-op if an intermediate segment is missing. */
+export function setPath(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const parts = path.split(".");
+  let cursor: Record<string, unknown> = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const next = cursor[parts[i]];
+    if (next === null || typeof next !== "object") return;
+    cursor = next as Record<string, unknown>;
+  }
+  cursor[parts[parts.length - 1]] = value;
+}
+
+/**
+ * The value a slot override contributes at its `dictPath`, or `undefined` when it
+ * contributes nothing and the dict should be left alone.
+ *
+ * `undefined` covers three distinct "leave it" cases that all have to behave the
+ * same way: the slot isn't overridden, a `list` override whose `items` isn't an
+ * array (malformed — better to render the code copy than an empty section), and a
+ * localized pair that resolves to nothing.
+ */
+export function overrideValueForDict(
+  type: string,
+  override: unknown,
+  isEs: boolean,
+): unknown {
+  if (override === null || override === undefined) return undefined;
+
+  if (type === "list") {
+    const items = (override as { items?: unknown[] }).items;
+    if (!Array.isArray(items)) return undefined;
+    return items.map((item) => resolveLocalizedFields(item, isEs));
+  }
+
+  const value = resolveLocalized(override, isEs);
+  return value === null ? undefined : value;
+}
+
+/**
+ * A copy of `dict` with one slot override applied at `dictPath`.
+ *
+ * The clone is what makes this safe to call from React state on every keystroke:
+ * the caller's dict is never mutated, so re-applying a different draft always
+ * starts from the published baseline instead of compounding edits.
+ */
+export function withSlotOverride<T>(
+  dict: T,
+  slot: { type: string; dictPath: string },
+  override: unknown,
+  isEs: boolean,
+): T {
+  const value = overrideValueForDict(slot.type, override, isEs);
+  if (value === undefined) return dict;
+
+  const clone = structuredClone(dict);
+  setPath(clone as Record<string, unknown>, slot.dictPath, value);
+  return clone;
+}

package/src/content/headers.d.ts

@@ -0,0 +1,11 @@
+// Hand-maintained alongside headers.mjs. Nothing type-checks the .mjs against
+// this file, so keep the signature exact when the implementation changes.
+
+/**
+ * Returns the `Content-Security-Policy: frame-ancestors` header a Studio-edited
+ * app must emit (and the `X-Frame-Options` header it must NOT emit alongside).
+ * Throws on a wildcard origin or an origin with a path/search/hash.
+ */
+export declare function studioFrameAncestors(
+  studioOrigins: readonly string[],
+): { key: string; value: string };

package/src/content/headers.mjs

@@ -0,0 +1,40 @@
+/**
+ * The framing rule for an app Studio edits.
+ *
+ * Studio's click-to-edit frames the REAL page, not a preview route, so a bare
+ * `frame-ancestors 'self'` turns the editor into a grey box — which shipped once,
+ * with the site still serving, the build still passing, and the only symptom in
+ * another repository's UI.
+ *
+ * One header, never two. `X-Frame-Options` has no allowlist, so it cannot express
+ * "self plus Studio" and re-breaks the editor wherever it is still honoured.
+ *
+ * Authored as plain ESM (not compiled from TypeScript) so `next.config.mjs`,
+ * which Next loads through native `import()`, can reach it directly. Types
+ * live alongside in `headers.d.ts`, hand-maintained.
+ *
+ * @param {readonly string[]} studioOrigins
+ * @returns {{ key: string, value: string }}
+ */
+export function studioFrameAncestors(studioOrigins) {
+  for (const origin of studioOrigins) {
+    if (origin.includes("*")) {
+      throw new Error(
+        `Wildcard origin "${origin}" would allow everyone: any host matching it can be claimed.`,
+      );
+    }
+    let parsed;
+    try {
+      parsed = new URL(origin);
+    } catch {
+      throw new Error(`"${origin}" is not an origin.`);
+    }
+    if (parsed.pathname !== "/" || parsed.search || parsed.hash) {
+      throw new Error(`"${origin}" has a path; frame-ancestors matches origins only.`);
+    }
+  }
+  return {
+    key: "Content-Security-Policy",
+    value: ["frame-ancestors 'self'", ...studioOrigins].join(" "),
+  };
+}