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

package/cli/writers.mjs

@@ -0,0 +1,148 @@
+// @ts-check
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import * as t from "./templates.mjs";
+
+/**
+ * The mechanical edits `init` makes (stage 2 plan, Task 4). Every writer is
+ * idempotent and never overwrites a file the app already has with different
+ * content: it reports it instead, so nothing the developer wrote is lost. The
+ * edits that need judgement (root layout, proxy, the content model) are left to
+ * the Claude Code step.
+ */
+
+/**
+ * @typedef {{ siteKey: string, theme: string, style: "flat" | "glass" }} SiteValues
+ * @typedef {{ written: string[], skipped: { path: string, reason: string }[] }} WriteReport
+ */
+
+/** @param {string} cwd */
+function codeRoot(cwd) {
+  return existsSync(path.join(cwd, "src", "app")) ? "src" : ".";
+}
+
+/** @param {string} cwd */
+function hasTestRunner(cwd) {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(cwd, "package.json"), "utf8"));
+    const all = { ...pkg.dependencies, ...pkg.devDependencies };
+    return "vitest" in all || "jest" in all;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {{ cwd: string, values: SiteValues, modules: string[] }} ctx
+ * @returns {Promise<WriteReport>}
+ */
+export async function writeSiteFiles({ cwd, values, modules }) {
+  const root = codeRoot(cwd);
+  const content = modules.includes("content");
+  const analytics = modules.includes("analytics");
+  // From app/api/<group>/<name>/route.ts back up to the code root's lib/.
+  const toLib = "../../../../lib";
+
+  /** @type {[string, string, { keepExisting?: boolean }?][]} */
+  const files = [];
+  const at = (/** @type {string} */ p) => (root === "." ? p : `${root}/${p}`);
+  if (content || analytics) files.push([at("lib/studio.ts"), t.studioTs(values)]);
+  if (content) {
+    files.push([at("lib/brand.ts"), t.brandTs(values)]);
+    files.push([at("lib/content-manifest.ts"), t.contentManifestTs(), { keepExisting: true }]);
+    files.push([at("lib/content.ts"), t.contentTs()]);
+    files.push([at("app/api/content/manifest/route.ts"), t.manifestRouteTs(toLib)]);
+    files.push([at("app/api/content/revalidate/route.ts"), t.revalidateRouteTs()]);
+  }
+  if (analytics) files.push([at("app/api/analytics/collect/route.ts"), t.collectRouteTs(toLib, content)]);
+
+  /** @type {WriteReport} */
+  const report = { written: [], skipped: [] };
+
+  if (content) {
+    if (hasTestRunner(cwd)) files.push(["tests/studio-frame-ancestors.test.ts", t.frameAncestorsTestTs()]);
+    else {
+      report.skipped.push({
+        path: "tests/studio-frame-ancestors.test.ts",
+        reason: "this app has no test runner yet; the Claude Code step can add Vitest and this test",
+      });
+    }
+  }
+
+  for (const [rel, body, opts] of files) {
+    const abs = path.join(cwd, rel);
+    if (existsSync(abs)) {
+      const current = readFileSync(abs, "utf8");
+      if (current === body || opts?.keepExisting) continue;
+      report.skipped.push({ path: rel, reason: "already exists with different content; merge the Studio version by hand" });
+      continue;
+    }
+    mkdirSync(path.dirname(abs), { recursive: true });
+    writeFileSync(abs, body);
+    report.written.push(rel);
+  }
+  return report;
+}
+
+const IMPORT_LINE = 'import { withStudio } from "@web-my-money/studio-consumer/next";';
+const CONFIG_NAMES = ["next.config.ts", "next.config.mjs", "next.config.js"];
+
+/**
+ * Wrap the app's next.config with withStudio. Recognises the two shapes nearly
+ * every config has (`export default name;` and `export default { … };`); any
+ * other shape is left untouched and the exact edit is returned instead.
+ *
+ * @param {{ cwd: string }} ctx
+ * @returns {Promise<"wrapped" | "already" | { manual: string }>}
+ */
+export async function wrapNextConfig({ cwd }) {
+  const name = CONFIG_NAMES.find((n) => existsSync(path.join(cwd, n)));
+  if (!name) {
+    writeFileSync(path.join(cwd, "next.config.mjs"), `${IMPORT_LINE}\n\nexport default withStudio({});\n`);
+    return "wrapped";
+  }
+  const file = path.join(cwd, name);
+  const src = readFileSync(file, "utf8");
+  if (src.includes("withStudio(")) return "already";
+
+  const manual = {
+    manual:
+      `Edit ${name} by hand: add\n  ${IMPORT_LINE}\nat the top, and wrap the exported config: export default withStudio(yourConfig);`,
+  };
+
+  let out = null;
+  const named = /^export default ([A-Za-z_$][\w$]*);[ \t]*$/m;
+  if (named.test(src)) {
+    out = src.replace(named, "export default withStudio($1);");
+  } else if (/^export default \{/m.test(src)) {
+    const start = src.search(/^export default \{/m);
+    const open = start + "export default ".length;
+    // Find the brace that closes the exported object. Only wrap when that object
+    // is the last thing in the file: a brace inside a string, or code after the
+    // export, makes the match uncertain, and a wrong splice breaks the config.
+    let depth = 0;
+    let close = -1;
+    for (let i = open; i < src.length; i++) {
+      if (src[i] === "{") depth++;
+      else if (src[i] === "}" && --depth === 0) {
+        close = i;
+        break;
+      }
+    }
+    const rest = close === -1 ? "x" : src.slice(close + 1).replace(/^;/, "");
+    if (close !== -1 && rest.trim() === "") {
+      out = `${src.slice(0, start)}export default withStudio(${src.slice(open, close + 1)});${rest}`;
+    }
+  }
+  if (!out) return manual;
+
+  // The import goes after the last existing import, or at the very top.
+  const lines = out.split("\n");
+  let last = -1;
+  lines.forEach((l, i) => {
+    if (/^import\s/.test(l)) last = i;
+  });
+  lines.splice(last + 1, 0, IMPORT_LINE);
+  writeFileSync(file, lines.join("\n"));
+  return "wrapped";
+}

package/package.json

@@ -1,29 +1,33 @@
-{
-  "name": "@web-my-money/studio-consumer",
-  "version": "2.2.0",
-  "description": "Consumer-side integration for WMM Studio: content, analytics, attribution.",
-  "license": "UNLICENSED",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Web-My-Money/wmm-studio.git",
-    "directory": "packages/studio-consumer"
-  },
-  "type": "module",
-  "sideEffects": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "exports": {
-    "./analytics": "./src/analytics/index.ts",
-    "./content": "./src/content/index.ts",
-    "./attribution": "./src/attribution/index.ts",
-    "./headers": "./src/content/headers.mjs",
-    "./brand": "./src/brand/index.ts",
-    "./image": "./src/image/index.ts"
-  },
-  "peerDependencies": {
-    "next": ">=16",
-    "react": ">=19"
-  },
-  "files": ["src"]
-}
+{
+  "name": "@web-my-money/studio-consumer",
+  "version": "2.3.0",
+  "description": "Consumer-side integration for WMM Studio: content, analytics, attribution.",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Web-My-Money/wmm-studio.git",
+    "directory": "packages/studio-consumer"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    "./analytics": "./src/analytics/index.ts",
+    "./content": "./src/content/index.ts",
+    "./attribution": "./src/attribution/index.ts",
+    "./headers": "./src/content/headers.mjs",
+    "./brand": "./src/brand/index.ts",
+    "./image": "./src/image/index.ts",
+    "./next": "./src/next/index.mjs"
+  },
+  "peerDependencies": {
+    "next": ">=16",
+    "react": ">=19"
+  },
+  "bin": {
+    "studio-consumer": "./bin/studio-consumer.mjs"
+  },
+  "files": ["src", "bin", "cli", "skills"]
+}

package/skills/onboard-site/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: onboard-site
+description: Finish connecting this Next.js app to WMM Studio after `npx @web-my-money/studio-consumer init` has run. Wires the root layout and the proxy/middleware, then proposes which text should be editable in Studio and writes the content manifest once the developer approves. Use when the init command opens Claude Code on /onboard-site.
+---
+
+# Finish connecting this app to WMM Studio
+
+The `init` command already did the mechanical part: it installed
+`@web-my-money/studio-consumer`, wrapped `next.config` with `withStudio`, and wrote
+`lib/studio.ts` (the site key), `lib/brand.ts`, `lib/content.ts`, a starter
+`lib/content-manifest.ts` and the API routes under `app/api/`. (In a `src/` app all of
+these live under `src/`.) Your job is the part that needs judgement on someone else's
+code.
+
+**The developer may never have seen Studio before.** Explain each change in one plain
+sentence, show the diff, and wait for a yes before writing it. Never rewrite a file
+wholesale; make the smallest edit that does the job. Never remove an existing redirect,
+rewrite, header or script.
+
+Read `.wmm-onboarding/state.json` first: it lists the modules this site uses
+(`content`, `analytics`, `forms`, `attribution`, `ab`, …). Skip anything for a module
+that is not listed.
+
+## 1. Root layout (`app/layout.tsx`, or the layout that renders `<html>`)
+
+- **Brand (content):** `import { brandRootAttributes } from "@web-my-money/studio-consumer/brand";`
+  and `import { brand } from "<relative path>/lib/brand";`, then spread
+  `{...brandRootAttributes(brand)}` on `<html>`. Keep every attribute already there.
+- **Click-to-edit (content):** render `<WmmEditOverlay studioOrigin={process.env.NEXT_PUBLIC_STUDIO_ORIGIN} />`
+  from `@web-my-money/studio-consumer/content` once, inside `<body>`.
+- **Analytics (analytics):** render `<FunnelAnalytics />` and `<EngagementTracking />` from
+  `@web-my-money/studio-consumer/analytics` once, inside `<body>`.
+- **Overrides (content):** wherever the app loads its dictionary for a locale (often a
+  `[lang]` layout or a `getDictionary` helper), pass it through
+  `await applyDictOverrides(dict, locale)` from `lib/content.ts` before rendering. This is
+  what makes an edit in Studio appear on the page; without it the checklist goes green
+  and edits never show. If the app has no dictionary, say so and use `getLocalizedSlot`
+  for each editable value in step 3 instead.
+
+## 2. Proxy / middleware (analytics)
+
+Studio's analytics and A/B testing need the `wmm_vid` visitor cookie, which
+`withVisitorCookie` from `@web-my-money/studio-consumer/analytics` sets.
+
+- Next 16 uses `proxy.ts` (older apps: `middleware.ts`), at the code root.
+- **None exists:** create `proxy.ts` that returns `withVisitorCookie(request)`, with a
+  matcher that skips `_next`, `api` and static files.
+- **One exists:** compose, never replace. Call `withVisitorCookie(request)` for the
+  pass-through case, and keep every existing redirect and rewrite exactly as it is. If the
+  existing code returns its own `NextResponse`, show the developer the two options (set
+  the cookie on that response, or call `withVisitorCookie` first) and let them choose.
+
+## 3. Choose the editable text (content)
+
+This is the real decision in the whole onboarding. **Do not decide it alone.**
+
+1. Find the copy: the per-locale dictionary (e.g. `dictionaries/en.json`, `es.json`), or,
+   if there is none, the text in the page components.
+2. Propose a table grouped by page and section, one row per candidate:
+
+   | Key | Current text (EN) | Editable? | Why |
+   |---|---|---|---|
+
+   Keys are `page.section.thing` (e.g. `home.hero.headline`). Give a one-line reason for
+   **every "no"**. Lean towards "no" for, and always justify:
+   - legal and compliance text (privacy, terms, disclaimers, medical or financial claims);
+   - form field names, validation and error messages;
+   - analytics, tracking and pixel ids;
+   - icons and component references (never editable);
+   - anything the code uses as an identifier, a route or a CSS class.
+   Lean towards "yes" for headlines, sub-headlines, body copy, calls to action, testimonials
+   and images a marketer would change.
+3. Wait for the developer to approve or edit the table.
+4. Then fill in `lib/content-manifest.ts`, keeping its `getManifest()` shape and the
+   `siteKey: SITE_KEY` it returns:
+   - a slot only for text the code actually renders;
+   - `type`: `text` (or `richtext`, `image`, `list`, `select` where that fits);
+   - `dictPath` for dictionary text (the override is merged into the dictionary, no
+     component changes needed); no `dictPath` for images or other non-dictionary values,
+     which are read with `getSlot` and passed down as props;
+   - `default` is read from the dictionary (`en`/`es` imports), **never retyped**, so it
+     cannot go stale;
+   - `label` in plain words a client understands ("Home: hero headline");
+   - `group` per page section, `sortOrder` in reading order.
+
+If `lib/content-manifest.ts` already had real slots before `init` ran, keep them and only
+add what the developer approves.
+
+## 4. Check, then hand back
+
+Run `npm run verify` (or the app's equivalent: typecheck, lint, test, build). Fix what it
+reports. If the app has no test runner and `tests/studio-frame-ancestors.test.ts` was not
+written, offer to add Vitest and that test.
+
+When everything passes, tell the developer in one sentence what changed, and that they can
+close Claude Code (type `/exit`) so the `init` command continues with the next step.

package/src/analytics/index.ts

@@ -1,37 +1,37 @@
-/** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "2.2.0";
-
-export {
-  resolveVariant,
-  bucketFor,
-  CONTROL,
-  VARIANT,
-  VISITOR_COOKIE,
-  type RunningExperiment,
-} from "./bucketing";
-
-export {
-  trackFunnelEvent,
-  registerExperiments,
-  flushFunnelEvents,
-  currentSessionId,
-  funnelAnalyticsEnabled,
-  consentGranted,
-  resetFunnelAnalytics,
-  type FunnelEventProps,
-} from "./collector";
-
-export { useFormAnalytics, type FormAnalytics, type FormAnalyticsOptions } from "./use-form-analytics";
-
-export {
-  FunnelAnalytics,
-  EngagementTracking,
-  AbArm,
-  THRESHOLDS,
-  crossedThresholds,
-  labelFor,
-} from "./components";
-
-export { createCollectHandler } from "./collect-handler";
-
-export { withVisitorCookie } from "./proxy";
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "2.3.0";
+
+export {
+  resolveVariant,
+  bucketFor,
+  CONTROL,
+  VARIANT,
+  VISITOR_COOKIE,
+  type RunningExperiment,
+} from "./bucketing";
+
+export {
+  trackFunnelEvent,
+  registerExperiments,
+  flushFunnelEvents,
+  currentSessionId,
+  funnelAnalyticsEnabled,
+  consentGranted,
+  resetFunnelAnalytics,
+  type FunnelEventProps,
+} from "./collector";
+
+export { useFormAnalytics, type FormAnalytics, type FormAnalyticsOptions } from "./use-form-analytics";
+
+export {
+  FunnelAnalytics,
+  EngagementTracking,
+  AbArm,
+  THRESHOLDS,
+  crossedThresholds,
+  labelFor,
+} from "./components";
+
+export { createCollectHandler } from "./collect-handler";
+
+export { withVisitorCookie } from "./proxy";

package/src/attribution/index.ts

@@ -1,14 +1,14 @@
-/** Proves at runtime which build a consumer is actually running. */
-export const PACKAGE_VERSION = "2.2.0";
-
-export {
-  getAttribution,
-  captureAttribution,
-  getAttributionPayload,
-  computeAttribution,
-  flattenAttribution,
-  hasCampaignSignal,
-} from "./store";
-export type { Attribution, Touch, AttributionPayload } from "./store";
-
-export { sessionIdField, SESSION_ID_FIELD } from "./crm";
+/** Proves at runtime which build a consumer is actually running. */
+export const PACKAGE_VERSION = "2.3.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/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.3.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.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>,
@@ -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 } },