@decocms/nextjs 8.1.0-next.0 → 8.5.0

package/src/instrumentation/index.ts

@@ -0,0 +1,337 @@
+/**
+ * `@decocms/nextjs/instrumentation`: `http.server.request.duration` for a
+ * Next.js site, from the request span Next.js already opens.
+ *
+ * Next.js measures every request it serves: `BaseServer.handleRequest` opens
+ * one root span per request and, when the response is done, sets its status,
+ * its method and, when Next routed it, the route's template (`/[slug]/p`,
+ * not the path). It creates spans only while a tracer provider is registered
+ * through `@opentelemetry/api` (the app's copy, or Next's compiled one when
+ * the app has none; both read the same global registration).
+ *
+ * `register()`, the site's `instrumentation.ts` hook, registers a provider
+ * whose only job is that span: when it ends, the request is recorded with
+ * `recordServerRequest` from `@decocms/blocks/metrics`, into the CMS's
+ * telemetry in the same process. No span is exported anywhere and every other
+ * span Next.js asks for is a shared non-recording one. With no
+ * `@opentelemetry/api` reachable, on the Edge runtime, or when another
+ * provider is already registered, it registers nothing and never throws.
+ *
+ * A site that registers its own OpenTelemetry SDK (`@vercel/otel`,
+ * `NodeSDK`) adds `serverRequestSpanProcessor()` to that SDK's span
+ * processors instead.
+ *
+ * Labels: `http.route` is Next's route template (`unmatched` when Next names
+ * none); RSC requests count under their page's route, as the requests they
+ * are. `cache` is `DRAFT` for a draft render (the proxy forwarded
+ * `x-deco-draft`, or the request was rewritten onto `/_draft`) and otherwise
+ * `BYPASS`: Next decides its cache (`x-nextjs-cache`) on the response, which
+ * the span never sees.
+ */
+
+import { recordServerRequest } from "@decocms/blocks/metrics";
+import type {
+  Context,
+  ContextManager,
+  Span,
+  SpanContext,
+  SpanOptions,
+  TextMapPropagator,
+  Tracer,
+  TracerProvider,
+} from "@opentelemetry/api";
+import { DRAFT_HEADER, DRAFT_ROUTE_PREFIX } from "../draft.ts";
+
+type Api = typeof import("@opentelemetry/api");
+
+/** The span type Next.js gives its one root span per request. */
+const ROOT_SPAN_TYPE = "BaseServer.handleRequest";
+const REGISTERED = Symbol.for("decocms.nextjs.instrumentation");
+/**
+ * Under `next start`, the router runs the proxy (`proxy.ts`/`middleware.ts`)
+ * through a `handleRequest` of its own, which ends by "bubbling" the proxy's
+ * result back to the router (`next.bubble`). That span is the proxy's, not a
+ * request: the request it hands on is measured by its own span.
+ */
+const BUBBLE = "next.bubble";
+
+type Attributes = Record<string, unknown>;
+
+interface AsyncLocalStorageLike<T> {
+  getStore(): T | undefined;
+  run<R>(store: T, fn: (...args: unknown[]) => R, ...args: unknown[]): R;
+  disable(): void;
+}
+
+/** What `serverRequestSpanProcessor()` reads from an ended span (an SDK's `ReadableSpan`). */
+interface EndedSpan {
+  readonly attributes: Attributes;
+  /** `[seconds, nanoseconds]`, as OpenTelemetry's `HrTime`. */
+  readonly duration: readonly [number, number];
+  readonly status?: { readonly code: number };
+}
+
+/** An OpenTelemetry SDK `SpanProcessor` that records nothing but the request metric. */
+export interface ServerRequestSpanProcessor {
+  onStart(span: unknown, parentContext: unknown): void;
+  onEnd(span: EndedSpan): void;
+  forceFlush(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+/** OpenTelemetry's `SpanStatusCode.ERROR`. */
+const STATUS_ERROR = 2;
+
+/** Records one ended `BaseServer.handleRequest` span. Never throws. */
+function recordRequestSpan(
+  attributes: Attributes,
+  seconds: number,
+  errored: boolean,
+  draft: boolean,
+): void {
+  const route = typeof attributes["http.route"] === "string" ? attributes["http.route"] : undefined;
+  const code = Number(attributes["http.status_code"]);
+  // Next sets the status before the span ends; a request that threw is a 5xx whatever it says.
+  const status = errored && !(code >= 500) ? 500 : code || 500;
+  // Never rejects; the span's route is already a string, so nothing to wait for.
+  void recordServerRequest({
+    route,
+    method: String(attributes["http.method"] ?? ""),
+    status,
+    cache: draft || isDraftRoute(route) ? "DRAFT" : "BYPASS",
+    seconds,
+  });
+}
+
+function isDraftRoute(route: string | undefined): boolean {
+  if (route === undefined) return false;
+  const path = route.replace(/^\/%5Fdraft(?=\/|$)/i, DRAFT_ROUTE_PREFIX);
+  return path === DRAFT_ROUTE_PREFIX || path.startsWith(`${DRAFT_ROUTE_PREFIX}/`);
+}
+
+/**
+ * For a site with its own OpenTelemetry SDK: a span processor that records
+ * `http.server.request.duration` from Next's request span and leaves every
+ * span to the SDK's other processors and exporters.
+ *
+ * ```ts
+ * registerOTel({ serviceName: "my-store", spanProcessors: ["auto", serverRequestSpanProcessor()] });
+ * ```
+ */
+export function serverRequestSpanProcessor(): ServerRequestSpanProcessor {
+  return {
+    onStart() {},
+    onEnd(span) {
+      try {
+        const attributes = span.attributes;
+        if (attributes?.["next.span_type"] !== ROOT_SPAN_TYPE || attributes[BUBBLE] === true)
+          return;
+        const [s, ns] = span.duration;
+        recordRequestSpan(attributes, s + ns / 1e9, span.status?.code === STATUS_ERROR, false);
+      } catch {
+        // A metric never breaks a request.
+      }
+    },
+    forceFlush: () => Promise.resolve(),
+    shutdown: () => Promise.resolve(),
+  };
+}
+
+/**
+ * The site's `instrumentation.ts` hook:
+ *
+ * ```ts
+ * // instrumentation.ts
+ * export { register } from "@decocms/nextjs/instrumentation";
+ * ```
+ *
+ * Registers the request-metric tracer provider, once per process. Does
+ * nothing on the Edge runtime (the Node.js server's request span covers the
+ * Edge pages it serves), without `@opentelemetry/api` (the app's or Next's),
+ * without `AsyncLocalStorage`, or when another provider is registered (it
+ * then says to use `serverRequestSpanProcessor()`). Never throws.
+ */
+export async function register(): Promise<void> {
+  try {
+    const global = globalThis as Record<PropertyKey, unknown>;
+    if (global[REGISTERED] === true || typeof global.EdgeRuntime === "string") return;
+    const Storage = global.AsyncLocalStorage as
+      | (new () => AsyncLocalStorageLike<Context>)
+      | undefined;
+    if (typeof Storage !== "function") return;
+    const api = await loadApi();
+    if (api === undefined) return;
+    global[REGISTERED] = true;
+    const draft = api.createContextKey("decocms.nextjs.draft");
+    if (!api.trace.setGlobalTracerProvider(requestTracerProvider(api, draft))) {
+      console.warn(
+        "[@decocms/nextjs] Another OpenTelemetry tracer provider is registered, so register() added nothing. " +
+          "To record http.server.request.duration, add serverRequestSpanProcessor() to that provider's span processors.",
+      );
+      return;
+    }
+    // Both may already be registered by something else; Next's spans work with either.
+    api.context.setGlobalContextManager(storageContextManager(api, new Storage()));
+    api.propagation.setGlobalPropagator(draftPropagator(draft));
+  } catch {
+    // Instrumentation never stops a server from starting.
+  }
+}
+
+/**
+ * The `@opentelemetry/api` Next.js uses: the app's own when installed (Next's
+ * bundlers alias it to Next's compiled copy when it isn't), else Next's
+ * compiled copy.
+ */
+async function loadApi(): Promise<Api | undefined> {
+  try {
+    return await import("@opentelemetry/api");
+  } catch {
+    try {
+      return (await import("next/dist/compiled/@opentelemetry/api/index.js")) as Api;
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+function requestTracerProvider(api: Api, DRAFT: symbol): TracerProvider {
+  const IN_REQUEST = api.createContextKey("decocms.nextjs.inRequest");
+  const inert = api.trace.wrapSpanContext(api.INVALID_SPAN_CONTEXT);
+
+  const tracer: Tracer = {
+    startSpan(_name: string, options?: SpanOptions, context?: Context): Span {
+      const ctx = context ?? api.context.active();
+      if (options?.attributes?.["next.span_type"] !== ROOT_SPAN_TYPE) return inert;
+      // A request Next serves inside another (a nested handleRequest) is already measured.
+      if (ctx.getValue(IN_REQUEST) === true) return inert;
+      return new RequestSpan(
+        api.INVALID_SPAN_CONTEXT,
+        options.attributes,
+        ctx.getValue(DRAFT) === true,
+      );
+    },
+    startActiveSpan(name: string, ...rest: unknown[]) {
+      const fn = rest[rest.length - 1] as (span: Span) => unknown;
+      const options = (rest.length > 1 ? rest[0] : undefined) as SpanOptions | undefined;
+      const context = (rest.length > 2 ? rest[1] : undefined) as Context | undefined;
+      const span = tracer.startSpan(name, options, context);
+      // Only the request span changes the context; every other span costs a call.
+      if (span === inert) return fn(span);
+      const ctx = api.trace
+        .setSpan(context ?? api.context.active(), span)
+        .setValue(IN_REQUEST, true);
+      return api.context.with(ctx, fn, undefined, span);
+    },
+  } as Tracer;
+
+  // Not named NoopTracerProvider: Next checks that name to decide whether tracing is on.
+  return { getTracer: () => tracer };
+}
+
+/** Marks the request's context when the proxy forwarded an accepted draft. */
+function draftPropagator(DRAFT: symbol): TextMapPropagator {
+  return {
+    inject() {},
+    extract(context, carrier, getter) {
+      try {
+        const value = getter.get(carrier, DRAFT_HEADER);
+        return value !== undefined && value !== "" ? context.setValue(DRAFT, true) : context;
+      } catch {
+        return context;
+      }
+    },
+    fields: () => [],
+  };
+}
+
+/** The request span: keeps only the attributes the metric needs and records on `end()`. */
+class RequestSpan implements Span {
+  readonly #context: SpanContext;
+  readonly #attributes: Attributes = {};
+  readonly #start = performance.now();
+  readonly #draft: boolean;
+  #errored = false;
+  #proxy = false;
+  #ended = false;
+
+  constructor(context: SpanContext, attributes: Attributes | undefined, draft: boolean) {
+    this.#context = context;
+    this.#draft = draft;
+    if (attributes) this.setAttributes(attributes);
+  }
+
+  spanContext(): SpanContext {
+    return this.#context;
+  }
+  setAttribute(key: string, value: unknown): this {
+    if (key === "http.route" || key === "http.status_code" || key === "http.method") {
+      this.#attributes[key] = value;
+    } else if (key === BUBBLE && value === true) {
+      this.#proxy = true;
+    }
+    return this;
+  }
+  setAttributes(attributes: Attributes): this {
+    for (const key in attributes) this.setAttribute(key, attributes[key]);
+    return this;
+  }
+  setStatus(status: { code: number }): this {
+    if (status?.code === STATUS_ERROR) this.#errored = true;
+    return this;
+  }
+  addEvent(): this {
+    return this;
+  }
+  addLink(): this {
+    return this;
+  }
+  addLinks(): this {
+    return this;
+  }
+  updateName(): this {
+    return this;
+  }
+  recordException(exception: unknown): void {
+    // The proxy's own invocation ends with an error marked `bubble`, whatever its type.
+    if ((exception as { bubble?: unknown } | null)?.bubble === true) this.#proxy = true;
+  }
+  isRecording(): boolean {
+    return !this.#ended;
+  }
+  end(): void {
+    if (this.#ended) return;
+    this.#ended = true;
+    if (this.#proxy) return;
+    try {
+      const seconds = (performance.now() - this.#start) / 1000;
+      recordRequestSpan(this.#attributes, seconds, this.#errored, this.#draft);
+    } catch {
+      // A metric never breaks a request.
+    }
+  }
+}
+
+/** OpenTelemetry's context manager over `AsyncLocalStorage` (what `@opentelemetry/context-async-hooks` does). */
+function storageContextManager(api: Api, storage: AsyncLocalStorageLike<Context>): ContextManager {
+  const manager: ContextManager = {
+    active: () => storage.getStore() ?? api.ROOT_CONTEXT,
+    with(context, fn, thisArg, ...args) {
+      const call = thisArg === undefined ? fn : fn.bind(thisArg);
+      return storage.run(context, call as (...a: unknown[]) => ReturnType<typeof fn>, ...args);
+    },
+    bind<T>(context: Context, target: T): T {
+      if (typeof target !== "function") return target;
+      const fn = target as unknown as (...a: unknown[]) => unknown;
+      return function (this: unknown, ...args: unknown[]) {
+        return manager.with(context, () => fn.apply(this, args));
+      } as unknown as T;
+    },
+    enable: () => manager,
+    disable() {
+      storage.disable();
+      return manager;
+    },
+  };
+  return manager;
+}

package/src/proxy/index.ts

@@ -0,0 +1,164 @@
+/**
+ * `@decocms/nextjs/proxy`: draft previews in a Next.js proxy (`proxy.ts`, or
+ * `middleware.ts` before Next 16). No React and no block map: pass the proxy
+ * a CMS handle made with an empty block map and the app's options, which
+ * shares the app's instance (one per process) without pulling the site's
+ * sections into the proxy bundle:
+ *
+ * ```ts
+ * // src/cms.proxy.ts
+ * export const proxyCms = createCMS({ blocks: {}, ...cmsConfig });
+ * ```
+ *
+ * A site with a proxy of its own calls the pieces (`decideDraft`, then
+ * `draftRequestHeaders` on the request it forwards, then `applyDraft` on the
+ * response); a site without one exports `draftProxy(...)`.
+ *
+ * Statically rendered pages can't read a draft, so a drafted request to one
+ * is rewritten onto a dynamic draft route (`/_draft/<path>`, mounted as
+ * `app/%5Fdraft/...`: a literal `_draft` folder is private in Next and never
+ * routes).
+ *
+ * The proxy measures no requests: it runs before Next routes and renders the
+ * page. `http.server.request.duration` comes from Next's own request span
+ * (`register` from `@decocms/nextjs/instrumentation`).
+ */
+import type { CMS } from "@decocms/blocks";
+import { type NextRequest, NextResponse } from "next/server.js";
+import { DRAFT_HEADER, DRAFT_ROUTE_PREFIX, draftResponseHeaders } from "../draft.ts";
+import {
+  allowedDraft,
+  draftCookie,
+  endsPreview,
+  fromDraftLink,
+  hasDraftSignal,
+  type PreviewPolicy,
+  requestLike,
+} from "../drafts.ts";
+
+export {
+  inferredPreviewHosts,
+  type PreviewPolicy,
+  previewHostDecision,
+  requestLike,
+} from "../drafts.ts";
+
+/** What the proxy needs from the CMS: the site's declared preview hosts and their check. */
+export type CMSHandle = Pick<CMS, "draftPointer" | "settings" | "forRelease">;
+
+/** What the proxy does with a request's draft state. */
+export interface DraftDecision {
+  /** The draft this request renders, after the host check; `null` for the release. */
+  pointer: string | null;
+  /** The `Set-Cookie` the response carries: storing a draft link's pointer, or ending a preview. */
+  setCookie: string | null;
+}
+
+export { DRAFT_ROUTE_PREFIX } from "../draft.ts";
+
+const INERT: DraftDecision = Object.freeze({ pointer: null, setCookie: null });
+
+/**
+ * The draft a request renders and the cookie its response sets, under
+ * `policy` (the same options the pages pass to `bindDraft`). A request with
+ * no `?__draft=` and no draft cookie never reaches the CMS.
+ */
+export async function decideDraft(
+  cms: CMSHandle,
+  request: NextRequest | Request,
+  policy: PreviewPolicy = {},
+): Promise<DraftDecision> {
+  const url = new URL(request.url);
+  const like = requestLike(request.headers, url.pathname + url.search, url.host);
+  if (like === null || !hasDraftSignal(like)) return INERT;
+  // Ending a preview is allowed on any host, so a cookie set earlier always goes.
+  if (endsPreview(like)) return { pointer: null, setCookie: draftCookie("", ["Max-Age=0"]) };
+  const pointer = await allowedDraft(cms, like, policy);
+  if (pointer === null) return INERT;
+  return {
+    pointer,
+    setCookie: fromDraftLink(like, pointer) ? draftCookie(encodeURIComponent(pointer)) : null,
+  };
+}
+
+/**
+ * The request headers to forward: the accepted pointer on `x-deco-draft`, so
+ * the root layout can bind the draft on the same request (a layout gets no
+ * `searchParams`, and on a draft link the cookie is only on the response).
+ * A copy that arrives from outside is always removed.
+ */
+export function draftRequestHeaders(
+  request: NextRequest | Request,
+  decision: DraftDecision,
+): Headers {
+  const headers = new Headers(request.headers);
+  if (decision.pointer) headers.set(DRAFT_HEADER, decision.pointer);
+  else headers.delete(DRAFT_HEADER);
+  return headers;
+}
+
+/** Whether `pathname` is on the draft route: a site answers a direct hit there with its 404. */
+export function isDraftRoutePath(pathname: string): boolean {
+  return pathname === DRAFT_ROUTE_PREFIX || pathname.startsWith(`${DRAFT_ROUTE_PREFIX}/`);
+}
+
+/**
+ * The rewrite of a drafted request onto the draft route, keeping its path and
+ * forwarding the pointer; `null` when the request isn't drafted or is already
+ * on the draft route.
+ */
+export function rewriteToDraftRoute(
+  request: NextRequest,
+  decision: DraftDecision,
+): NextResponse | null {
+  if (!decision.pointer) return null;
+  const url = request.nextUrl.clone();
+  if (isDraftRoutePath(url.pathname)) return null;
+  url.pathname = `${DRAFT_ROUTE_PREFIX}${url.pathname}`;
+  return NextResponse.rewrite(url, {
+    request: { headers: draftRequestHeaders(request, decision) },
+  });
+}
+
+/**
+ * The cookie and the response headers of a draft: `Set-Cookie`, and for a
+ * drafted response `Cache-Control: no-store, private`, `Vary: Cookie` and
+ * `X-Robots-Tag: noindex, nofollow` (`draftResponseHeaders`). With the
+ * pointer in a cookie a draft shares its URL with the published page, so a
+ * cache keyed on the URL alone would serve it to visitors.
+ */
+export function applyDraft<R extends Response>(response: R, decision: DraftDecision): R {
+  if (decision.setCookie) response.headers.append("set-cookie", decision.setCookie);
+  for (const [name, value] of Object.entries(draftResponseHeaders(decision.pointer))) {
+    response.headers.set(name, value);
+  }
+  return response;
+}
+
+export interface DraftProxyOptions extends PreviewPolicy {
+  /**
+   * Which drafted requests go to the draft route (a statically rendered
+   * page's). Default: every drafted request outside the draft route. Return
+   * `false` for a route that is already dynamic and binds the draft itself.
+   */
+  rewrite?: (request: NextRequest) => boolean;
+}
+
+/**
+ * The whole draft flow for a site with no proxy of its own:
+ * `export const proxy = draftProxy(proxyCms, { site: "my-store" })`.
+ */
+export function draftProxy(
+  cms: CMSHandle,
+  options: DraftProxyOptions = {},
+): (request: NextRequest) => Promise<NextResponse> {
+  const { rewrite = () => true, ...policy } = options;
+  return async (request) => {
+    const decision = await decideDraft(cms, request, policy);
+    const rewritten = rewrite(request) ? rewriteToDraftRoute(request, decision) : null;
+    const response =
+      rewritten ??
+      NextResponse.next({ request: { headers: draftRequestHeaders(request, decision) } });
+    return applyDraft(response, decision);
+  };
+}

package/src/server/index.ts

@@ -0,0 +1,77 @@
+/**
+ * `@decocms/nextjs/server`: draft previews in Server Components (pages,
+ * layouts, route handlers). Server only: it reads `next/headers`.
+ *
+ * A page (and, through the `x-deco-draft` header the proxy forwards, the root
+ * layout) binds the request's draft before it reads content, then reads
+ * through `contentClient(cms)`:
+ *
+ * ```tsx
+ * export default async function Page({ searchParams }) {
+ *   await bindDraft(cms, { searchParams: await searchParams, site: "my-store" });
+ *   const client = contentClient(cms);
+ *   …
+ *   return <>{sections}<DraftPreviewIndicator /></>;
+ * }
+ * ```
+ *
+ * The host check is the proxy's (`decideDraft`), repeated here with the same
+ * options, so a route the proxy doesn't match, or a forged `x-deco-draft`,
+ * still gets the release on a host that may not preview.
+ */
+
+import type { Client, CMS } from "@decocms/blocks";
+import { headers } from "next/headers.js";
+import { DRAFT_HEADER, DRAFT_PARAM } from "../draft.ts";
+import { allowedDraft, isDraftPreviewEnabled, type PreviewPolicy, requestLike } from "../drafts.ts";
+import { activeDraftPointer, draftSlot } from "./slot.ts";
+
+export { type PreviewPolicy, requestLike } from "../drafts.ts";
+export { activeDraftPointer };
+
+/** A page's `searchParams` prop, awaited. */
+export type SearchParams = Record<string, string | string[] | undefined>;
+
+export interface BindDraftOptions extends PreviewPolicy {
+  /** The page's own `searchParams` (a layout has none: it reads the proxy's `x-deco-draft`). */
+  searchParams?: SearchParams;
+}
+
+function firstParam(searchParams: SearchParams | undefined, key: string): string | null {
+  const raw = searchParams?.[key];
+  return (Array.isArray(raw) ? raw[0] : raw) ?? null;
+}
+
+/**
+ * Binds the request's draft, if any: the page's own `?__draft=` first (`off`
+ * leaves preview), then the pointer the proxy forwarded on `x-deco-draft`,
+ * then the draft cookie, each on a host the options allow. Returns whether a
+ * draft was bound. With previews off on every host it returns `false`
+ * without reading the request, so a static page stays static.
+ */
+export async function bindDraft(
+  cms: Pick<CMS, "draftPointer" | "settings" | "forRelease">,
+  options: BindDraftOptions = {},
+): Promise<boolean> {
+  const { searchParams, ...policy } = options;
+  if (!(await isDraftPreviewEnabled(cms, policy))) return false;
+  const param = firstParam(searchParams, DRAFT_PARAM);
+  if (param === "off") return false;
+  const requestHeaders = await headers();
+  const forwarded = param ?? requestHeaders.get(DRAFT_HEADER);
+  const query = forwarded ? `?${DRAFT_PARAM}=${encodeURIComponent(forwarded)}` : "";
+  const request = requestLike(requestHeaders as Headers, `/${query}`);
+  const pointer = request ? await allowedDraft(cms, request, policy) : null;
+  if (pointer === null) return false;
+  draftSlot().pointer = pointer;
+  return true;
+}
+
+/**
+ * The content client for this request: the draft `bindDraft` bound, or the
+ * release.
+ */
+export function contentClient(cms: Pick<CMS, "forDraft" | "forRelease">): Client {
+  const pointer = activeDraftPointer();
+  return pointer ? cms.forDraft(pointer) : cms.forRelease();
+}

package/src/server/slot.ts

@@ -0,0 +1,14 @@
+/**
+ * The draft a request renders, held for the request's Server Components.
+ * React's `cache()` gives one slot per request in the React Server
+ * Components graph, the scope a draft needs; no `next/headers` here, so the
+ * root components can read it without binding anything.
+ */
+import { cache } from "react";
+
+export const draftSlot = cache((): { pointer: string | null } => ({ pointer: null }));
+
+/** The draft pointer bound to this request (`bindDraft`), or `null` when it renders the release. */
+export function activeDraftPointer(): string | null {
+  return draftSlot().pointer;
+}

package/src/studio.ts

@@ -0,0 +1,54 @@
+/**
+ * Where Deco Studio runs: the origins its site editor frames a site from and
+ * talks to it from (`postMessage`). One list, so the Studio bridge
+ * (`StudioBridge`), `withDeco()`'s dev origins and a site's own
+ * `frame-ancestors` never drift apart. This package's own copy: it never
+ * imports `@decocms/tanstack`.
+ *
+ * No module state and no framework code: safe in a browser bundle.
+ */
+
+/**
+ * Studio's origins, in the CSP source form (`https://*.decocms.com` matches
+ * any subdomain). Test an origin with {@link isStudioOrigin}: the list holds a
+ * wildcard, so `includes()` isn't the check.
+ */
+export const STUDIO_ORIGINS: readonly string[] = Object.freeze([
+  "https://studio.decocms.com",
+  "https://studio-stg.decocms.com",
+  "https://decocms.com",
+  "https://*.decocms.com",
+]);
+
+/**
+ * The `frame-ancestors` sources a site sends so Studio can show it in the
+ * site editor: the site itself, {@link STUDIO_ORIGINS}, and v7's
+ * `https://*.deco.studio`. For a site that writes its own CSP; add the
+ * loopback origins in local development (`http://localhost:*`), where a
+ * Studio runs on the same machine.
+ */
+export const STUDIO_FRAME_ANCESTORS: readonly string[] = Object.freeze([
+  "'self'",
+  ...STUDIO_ORIGINS,
+  "https://*.deco.studio",
+]);
+
+/**
+ * Whether `origin` (a `MessageEvent.origin`, an `Origin` header) is one of
+ * {@link STUDIO_ORIGINS}: `https`, the default port, and `decocms.com` or a
+ * name under it.
+ */
+export function isStudioOrigin(origin: string | null | undefined): boolean {
+  if (typeof origin !== "string" || origin === "") return false;
+  let url: URL;
+  try {
+    url = new URL(origin);
+  } catch {
+    return false;
+  }
+  // An origin is the scheme and host alone: `https://decocms.com/x` or one with
+  // credentials isn't one.
+  if (url.origin !== origin || url.protocol !== "https:" || url.port !== "") return false;
+  const host = url.hostname;
+  return host === "decocms.com" || host.endsWith(".decocms.com");
+}

package/src/ClientOnlySection.tsx

@@ -1,20 +0,0 @@
-"use client";
-
-import dynamic from "next/dynamic";
-import type { ComponentType } from "react";
-
-interface ClientOnlySectionProps {
-  loader: () => Promise<{ default: ComponentType<any> }>;
-  props: Record<string, unknown>;
-}
-
-const cache = new Map<() => Promise<{ default: ComponentType<any> }>, ComponentType<any>>();
-
-export function ClientOnlySection({ loader, props }: ClientOnlySectionProps) {
-  let Dynamic = cache.get(loader);
-  if (!Dynamic) {
-    Dynamic = dynamic(loader, { ssr: false });
-    cache.set(loader, Dynamic);
-  }
-  return <Dynamic {...props} />;
-}