@decocms/blocks-admin 8.0.0 → 8.1.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-admin",
-  "version": "8.0.0",
+  "version": "8.1.0-next.0",
   "type": "module",
   "description": "Deco admin protocol: /live/_meta, /.decofile, /deco/invoke, /deco/render, plus admin-facing site setup and commerce-app auto-configuration",
   "repository": {
@@ -25,7 +25,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "8.0.0"
+    "@decocms/blocks": "8.1.0-next.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/admin/index.ts

@@ -25,7 +25,7 @@ export {
   setInvokeLoaders,
 } from "./invoke";
 export { LIVE_CONTROLS_SCRIPT } from "./liveControls";
-export { handleMeta, setMetaData } from "./meta";
+export { handleMeta, setMetaData, setMetaLoader } from "./meta";
 export { handleRender, setPreviewWrapper, setRenderShell } from "./render";
 export {
   type PreviewResolution,

package/src/admin/invoke.test.ts

@@ -58,7 +58,9 @@ describe("handleInvoke — Set-Cookie propagation (single)", () => {
     });
 
     const request = makeInvokeRequest("vtex/actions/addItemsToCart");
-    const response = await RequestContext.run(request, () => handleInvoke(request));
+    const response = await RequestContext.run(request, () =>
+      handleInvoke(request),
+    );
 
     const cookies = response.headers.getSetCookie();
     expect(cookies).toHaveLength(3);
@@ -77,7 +79,9 @@ describe("handleInvoke — Set-Cookie propagation (single)", () => {
     });
 
     const request = makeInvokeRequest("vtex/actions/foo");
-    const response = await RequestContext.run(request, () => handleInvoke(request));
+    const response = await RequestContext.run(request, () =>
+      handleInvoke(request),
+    );
 
     // The regressed bug appended a single comma-joined string, so
     // `getSetCookie()` returned a 1-element array. The fix appends each
@@ -94,7 +98,9 @@ describe("handleInvoke — Set-Cookie propagation (single)", () => {
     });
 
     const request = makeInvokeRequest("vtex/actions/withHeader");
-    const response = await RequestContext.run(request, () => handleInvoke(request));
+    const response = await RequestContext.run(request, () =>
+      handleInvoke(request),
+    );
     expect(response.headers.get("x-vtex-trace-id")).toBe("abc-123");
   });
 
@@ -104,7 +110,9 @@ describe("handleInvoke — Set-Cookie propagation (single)", () => {
     });
 
     const request = makeInvokeRequest("vtex/loaders/productList");
-    const response = await RequestContext.run(request, () => handleInvoke(request));
+    const response = await RequestContext.run(request, () =>
+      handleInvoke(request),
+    );
     expect(response.headers.getSetCookie()).toEqual([]);
   });
 });
@@ -131,7 +139,9 @@ describe("handleInvoke — Set-Cookie propagation (batch)", () => {
       "vtex/actions/addItemsToCart": { orderFormId: "x" },
       "vtex/loaders/productList": {},
     });
-    const response = await RequestContext.run(request, () => handleInvoke(request));
+    const response = await RequestContext.run(request, () =>
+      handleInvoke(request),
+    );
 
     const cookies = response.headers.getSetCookie();
     expect(cookies).toHaveLength(3);
@@ -155,7 +165,8 @@ describe("handleInvoke — draft binding", () => {
     clearDraftCache();
     setBlocks({ "site/x": { value: "published" } });
     registerInvokeHandlers({
-      "site/loaders/x.ts": async () => (loadBlocks() as Record<string, any>)["site/x"],
+      "site/loaders/x.ts": async () =>
+        (loadBlocks() as Record<string, any>)["site/x"],
     });
   });
   afterEach(() => {
@@ -166,11 +177,14 @@ describe("handleInvoke — draft binding", () => {
   });
 
   function invokeReq(headers: Record<string, string>): Request {
-    return new Request("https://preview.example/deco/invoke/site/loaders/x.ts", {
-      method: "POST",
-      headers: { "content-type": "application/json", ...headers },
-      body: "{}",
-    });
+    return new Request(
+      "https://preview.example/deco/invoke/site/loaders/x.ts",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json", ...headers },
+        body: "{}",
+      },
+    );
   }
 
   it("resolves loaders against the DRAFT when the request carries an allowed draft cookie", async () => {
@@ -183,7 +197,8 @@ describe("handleInvoke — draft binding", () => {
     const res = await handleInvoke(
       invokeReq({
         "x-forwarded-host": "preview.example",
-        cookie: "__deco_draft=abc.preview-studio.decocms.com@vX",
+        cookie:
+          "__deco_draft=studio.decocms.com/api/o/decofile/m/main%3Ftoken%3Dt@vX",
       }),
     );
     expect(await res.json()).toEqual({ value: "draft" });
@@ -197,7 +212,9 @@ describe("handleInvoke — draft binding", () => {
       return new Response("{}");
     }) as unknown as typeof fetch;
 
-    const res = await handleInvoke(invokeReq({ "x-forwarded-host": "preview.example" }));
+    const res = await handleInvoke(
+      invokeReq({ "x-forwarded-host": "preview.example" }),
+    );
     expect(await res.json()).toEqual({ value: "published" });
     expect(called).toBe(false);
   });
@@ -212,7 +229,8 @@ describe("handleInvoke — draft binding", () => {
     const res = await handleInvoke(
       invokeReq({
         "x-forwarded-host": "prod.example",
-        cookie: "__deco_draft=abc.preview-studio.decocms.com@vX",
+        cookie:
+          "__deco_draft=studio.decocms.com/api/o/decofile/m/main%3Ftoken%3Dt@vX",
       }),
     );
     expect(await res.json()).toEqual({ value: "published" });

package/src/admin/invoke.ts

@@ -13,7 +13,7 @@
  * copies those headers into the final HTTP Response.
  */
 
-import { resolveDraftForRequest, withBlocksOverride } from "@decocms/blocks/cms";
+import { resolveDraftForRequest, withDraftBlocks } from "@decocms/blocks/cms";
 import { RequestContext } from "@decocms/blocks/sdk/requestContext";
 
 export type InvokeLoader = (props: any, request: Request) => Promise<any>;
@@ -95,11 +95,13 @@ function forwardCtxHeadersTo(response: Response): void {
 }
 
 const isDev =
-  typeof globalThis.process !== "undefined" && globalThis.process.env?.NODE_ENV === "development";
+  typeof globalThis.process !== "undefined" &&
+  globalThis.process.env?.NODE_ENV === "development";
 
 function selectFields(data: unknown, select?: string[]): unknown {
   if (!select?.length || !data || typeof data !== "object") return data;
-  if (Array.isArray(data)) return data.map((item) => selectFields(item, select));
+  if (Array.isArray(data))
+    return data.map((item) => selectFields(item, select));
   const result: Record<string, unknown> = {};
   for (const key of select) {
     if (key in (data as Record<string, unknown>)) {
@@ -131,7 +133,9 @@ async function parseBody(request: Request): Promise<any> {
       for (const [key, value] of formData.entries()) {
         if (obj[key] !== undefined) {
           // Multiple values → array
-          const existing = Array.isArray(obj[key]) ? (obj[key] as unknown[]) : [obj[key]];
+          const existing = Array.isArray(obj[key])
+            ? (obj[key] as unknown[])
+            : [obj[key]];
           existing.push(value);
           obj[key] = existing;
         } else {
@@ -193,10 +197,9 @@ function unknownHandlerMessage(key: string): string {
   const kind = isAction ? "action" : isLoader ? "loader" : "loader/action";
   const dir = isAction ? "src/actions/" : "src/loaders/";
   const cliHint = "npm run generate:loaders";
-  const setupHint =
-    isAction
-      ? "setInvokeActions(() => COMMERCE_ACTIONS)"
-      : "setInvokeLoaders(() => COMMERCE_LOADERS)";
+  const setupHint = isAction
+    ? "setInvokeActions(() => COMMERCE_ACTIONS)"
+    : "setInvokeLoaders(() => COMMERCE_LOADERS)";
   return (
     `Unknown handler: ${key}. ` +
     `Check that the ${kind} exists in ${dir} (file path must match the key — ` +
@@ -221,16 +224,17 @@ function warnMissingHandlerOnce(key: string): void {
  * refs; without this, `/deco/invoke` — a separate request from the page render,
  * so the page's request-scoped draft binding never reaches it — would resolve
  * against PUBLISHED blocks and hand a reviewer stale content in any
- * client-fetched (lazy/on-scroll) or self-fetched section. `withBlocksOverride`
+ * client-fetched (lazy/on-scroll) or self-fetched section. `withDraftBlocks`
  * uses AsyncLocalStorage, so each concurrent invoke gets its own override with
  * no cross-request bleed (the same isolation the layout-cache race taught us to
- * keep). Inert unless the draft gate passes — no draft, no wrap, published path
- * untouched.
+ * keep) — and composes the draft as a SNAPSHOT, the same semantics the page
+ * render applies, so a block deleted in the draft is deleted here too. Inert
+ * unless the draft gate passes — no draft, no wrap, published path untouched.
  */
 export async function handleInvoke(request: Request): Promise<Response> {
   const draftBlocks = await resolveDraftForRequest(request);
   return draftBlocks
-    ? withBlocksOverride(draftBlocks, () => dispatchInvoke(request))
+    ? withDraftBlocks(draftBlocks, () => dispatchInvoke(request))
     : dispatchInvoke(request);
 }
 
@@ -258,7 +262,10 @@ async function dispatchInvoke(request: Request): Promise<Response> {
         return result;
       }
       const filtered = selectFields(result, select);
-      const response = new Response(JSON.stringify(filtered), { status: 200, headers: JSON_HEADERS });
+      const response = new Response(JSON.stringify(filtered), {
+        status: 200,
+        headers: JSON_HEADERS,
+      });
       forwardCtxHeadersTo(response);
       return response;
     } catch (error) {
@@ -267,7 +274,12 @@ async function dispatchInvoke(request: Request): Promise<Response> {
   }
 
   // Batch invoke
-  if (request.method === "POST" && body && typeof body === "object" && !Array.isArray(body)) {
+  if (
+    request.method === "POST" &&
+    body &&
+    typeof body === "object" &&
+    !Array.isArray(body)
+  ) {
     const results: Record<string, unknown> = {};
 
     const entries = Object.entries(body as Record<string, unknown>);
@@ -286,7 +298,11 @@ async function dispatchInvoke(request: Request): Promise<Response> {
             // RequestContext.responseHeaders (which forwardCtxHeadersTo()
             // below propagates onto the batch response).
             if (result instanceof Response) {
-              try { result = await result.json(); } catch { result = null; }
+              try {
+                result = await result.json();
+              } catch {
+                result = null;
+              }
             }
             results[key] = selectFields(result, select);
           } catch (error) {
@@ -299,7 +315,10 @@ async function dispatchInvoke(request: Request): Promise<Response> {
       }),
     );
 
-    const response = new Response(JSON.stringify(results), { status: 200, headers: JSON_HEADERS });
+    const response = new Response(JSON.stringify(results), {
+      status: 200,
+      headers: JSON_HEADERS,
+    });
     // All batch handlers share the same RequestContext, so any Set-Cookie
     // they appended (e.g. from VTEX vtexFetchWithCookies) is in
     // `responseHeaders` by now. Forward it as N distinct Set-Cookie headers.

package/src/admin/meta.ts

@@ -8,6 +8,8 @@ import { composeMeta, type MetaResponse } from "@decocms/blocks/cms";
 const G = globalThis as unknown as {
   __deco_meta_data?: MetaResponse | null;
   __deco_meta_etag?: string | null;
+  __deco_meta_loader?: (() => Promise<MetaResponse>) | null;
+  __deco_meta_loading?: Promise<MetaResponse | null> | null;
 };
 
 function getMetaData(): MetaResponse | null {
@@ -35,6 +37,60 @@ function setCachedEtag(etag: string | null) {
  */
 export function invalidateMetaCache() {
   setCachedEtag(null);
+  // Drop the composed schema too, but ONLY when it can be rebuilt. With a
+  // loader registered the next request re-imports and re-composes (composeMeta
+  // injects page schemas over the current blocks, so a decofile change really
+  // does invalidate it). With data set explicitly via `setMetaData` there is
+  // nothing to reload — clearing it would 503 the admin permanently.
+  if (G.__deco_meta_loader) setMetaDataInternal(null);
+}
+
+/**
+ * Register the schema loader instead of resolving it now.
+ *
+ * The schema is a JSON Schema bundle covering every section and app, and it is
+ * needed by exactly one route: `/live/_meta`. Loading it at boot meant every
+ * isolate parsed it and pinned the composed graph on `globalThis` for its whole
+ * life — for traffic that never touches the admin. Same shape as the decofile
+ * bug: a large JSON graph permanently reachable from a module-level binding.
+ *
+ * `createAdminSetup` has always documented this as lazy; it just wasn't.
+ */
+export function setMetaLoader(loader: () => Promise<MetaResponse>) {
+  G.__deco_meta_loader = loader;
+}
+
+/**
+ * The composed schema, importing + composing it on first use.
+ *
+ * Concurrent first requests share one in-flight load. A failed load is NOT
+ * latched: the rejection is swallowed to `null` (the caller answers 503) and
+ * the next request retries, so a transient import failure can't disable the
+ * admin for the isolate's life.
+ */
+async function ensureMetaData(): Promise<MetaResponse | null> {
+  const existing = getMetaData();
+  if (existing) return existing;
+
+  const loader = G.__deco_meta_loader;
+  if (!loader) return null;
+
+  G.__deco_meta_loading ??= loader()
+    .then((data) => {
+      const composed = composeMeta(data);
+      setMetaDataInternal(composed);
+      setCachedEtag(null);
+      return composed;
+    })
+    .catch((err) => {
+      console.warn("[deco] admin meta schema failed to load:", err);
+      return null;
+    })
+    .finally(() => {
+      G.__deco_meta_loading = null;
+    });
+
+  return G.__deco_meta_loading;
 }
 
 /**
@@ -62,8 +118,8 @@ function getEtag(): string {
   return etag;
 }
 
-export function handleMeta(request: Request): Response {
-  const metaData = getMetaData();
+export async function handleMeta(request: Request): Promise<Response> {
+  const metaData = await ensureMetaData();
   if (!metaData) {
     return new Response(JSON.stringify({ error: "Schema not initialized" }), {
       status: 503,

package/src/admin/metaLazy.test.ts

@@ -0,0 +1,124 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { MetaResponse } from "@decocms/blocks/cms";
+import { createAdminSetup } from "../createAdminSetup";
+import { handleMeta, invalidateMetaCache, setMetaData, setMetaLoader } from "./meta";
+
+/**
+ * The admin JSON Schema bundle covers every section and app, and exactly one
+ * route needs it. Loading it at boot made every isolate parse it and pin the
+ * composed graph on globalThis for its whole life — for traffic that never
+ * touches the admin. Same shape as the decofile bug.
+ *
+ * These tests pin the property that matters: nothing loads the schema until a
+ * request asks for it.
+ */
+
+const G = globalThis as unknown as Record<string, unknown>;
+
+function reset() {
+  G.__deco_meta_data = null;
+  G.__deco_meta_etag = null;
+  G.__deco_meta_loader = null;
+  G.__deco_meta_loading = null;
+}
+
+const SCHEMA = {
+  definitions: { "site/sections/Hero.tsx": { type: "object" } },
+} as unknown as MetaResponse;
+const req = () => new Request("https://site.test/live/_meta");
+
+beforeEach(reset);
+
+describe("lazy admin meta schema", () => {
+  it("does NOT invoke the loader at setup time", () => {
+    const meta = vi.fn(() => Promise.resolve(SCHEMA));
+    createAdminSetup({ meta, css: "/app.css" });
+    // The whole point: boot must not touch the schema.
+    expect(meta).not.toHaveBeenCalled();
+  });
+
+  it("invokes it on the first /live/_meta, once", async () => {
+    const meta = vi.fn(() => Promise.resolve(SCHEMA));
+    createAdminSetup({ meta, css: "/app.css" });
+
+    const first = await handleMeta(req());
+    expect(first.status).toBe(200);
+    expect(meta).toHaveBeenCalledTimes(1);
+
+    await handleMeta(req());
+    expect(meta).toHaveBeenCalledTimes(1);
+  });
+
+  it("shares one in-flight load across concurrent first requests", async () => {
+    let release!: (v: unknown) => void;
+    const meta = vi.fn(
+      () =>
+        new Promise<never>((r) => {
+          release = r as never;
+        }),
+    );
+    setMetaLoader(meta as unknown as () => Promise<typeof SCHEMA>);
+
+    const all = Promise.all([handleMeta(req()), handleMeta(req()), handleMeta(req())]);
+    release(SCHEMA);
+    const responses = await all;
+
+    expect(meta).toHaveBeenCalledTimes(1);
+    for (const r of responses) expect(r.status).toBe(200);
+  });
+
+  it("serves the COMPOSED schema, not the raw input", async () => {
+    setMetaLoader(() => Promise.resolve(SCHEMA));
+    const body = (await (await handleMeta(req())).json()) as { framework?: unknown };
+    // `framework` is composeMeta's own sentinel (it is the field it sets and
+    // then uses as its idempotency guard), so its presence proves the lazy
+    // path still composes rather than serving the file through.
+    expect(body.framework).toBeDefined();
+  });
+
+  it("retries after a failed load instead of latching a dead isolate", async () => {
+    const meta = vi
+      .fn<() => Promise<typeof SCHEMA>>()
+      .mockRejectedValueOnce(new Error("chunk load failed"))
+      .mockResolvedValueOnce(SCHEMA);
+    setMetaLoader(meta);
+
+    expect((await handleMeta(req())).status).toBe(503);
+    expect((await handleMeta(req())).status).toBe(200);
+    expect(meta).toHaveBeenCalledTimes(2);
+  });
+
+  it("503s when no loader and no data were ever provided", async () => {
+    expect((await handleMeta(req())).status).toBe(503);
+  });
+
+  it("still honors an explicitly set schema, with no loader", async () => {
+    setMetaData(SCHEMA);
+    expect((await handleMeta(req())).status).toBe(200);
+  });
+
+  it("keeps explicitly-set data across invalidation — there is nothing to reload", async () => {
+    // Clearing it would 503 the admin permanently for a site on setMetaData.
+    setMetaData(SCHEMA);
+    invalidateMetaCache();
+    expect((await handleMeta(req())).status).toBe(200);
+  });
+
+  it("re-composes after invalidation when a loader can rebuild it", async () => {
+    const meta = vi.fn(() => Promise.resolve(SCHEMA));
+    setMetaLoader(meta);
+    await handleMeta(req());
+    invalidateMetaCache();
+    await handleMeta(req());
+    expect(meta).toHaveBeenCalledTimes(2);
+  });
+
+  it("answers 304 to a matching If-None-Match", async () => {
+    setMetaLoader(() => Promise.resolve(SCHEMA));
+    const etag = (await handleMeta(req())).headers.get("etag")!;
+    const res = await handleMeta(
+      new Request("https://site.test/live/_meta", { headers: { "if-none-match": etag } }),
+    );
+    expect(res.status).toBe(304);
+  });
+});

package/src/admin/render.ts

@@ -31,6 +31,18 @@ function wrapInHtmlShell(sectionHtml: string): string {
   return buildHtmlShell({ body: sectionHtml, script: LIVE_CONTROLS_SCRIPT });
 }
 
+/**
+ * DOM id for a section's wrapper element. Must stay in sync with the
+ * production renderer (`DecoPageRenderer.tsx`) so the admin's in-place
+ * Fast Preview replace can match `[data-manifest-key]` / `#id` 1:1.
+ */
+function sectionDomId(key: string): string {
+  return key
+    .replace(/\//g, "-")
+    .replace(/\.tsx$/, "")
+    .replace(/^site-sections-/, "");
+}
+
 /**
  * Render a single ResolvedSection to an HTML string.
  * Uses the pre-cached renderToString and the preview wrapper.
@@ -44,8 +56,17 @@ async function renderResolvedSection(section: ResolvedSection): Promise<string>
   const renderToString = await getRenderToString();
   const mod = await sectionLoader();
   const element = createElement(mod.default, section.props);
+  // Match the production wrapper (DecoPageRenderer.tsx) so the admin's
+  // in-place Fast Preview replace can map each section to its live-DOM
+  // counterpart via [data-manifest-key]. Without it, sections rendered on
+  // the /live/previews path come back unwrapped and end up glued together.
+  const sectionEl = createElement(
+    "section",
+    { id: sectionDomId(section.key), "data-manifest-key": section.key },
+    element,
+  );
   const Wrapper = getPreviewWrapper();
-  const wrapped = Wrapper ? createElement(Wrapper, null, element) : element;
+  const wrapped = Wrapper ? createElement(Wrapper, null, sectionEl) : sectionEl;
   return renderToString(wrapped);
 }
 

package/src/admin/resolvePreview.test.ts

@@ -126,4 +126,29 @@ describe("resolvePreviewRequest", () => {
     expect(html).toContain("hero-html");
     expect(html).toContain("editor::inject");
   });
+
+  it("wraps each rendered section in <section data-manifest-key> so the in-place preview replace can map it", async () => {
+    setBlocks({
+      "/pages/home": {
+        __resolveType: WELL_KNOWN_TYPES.PAGE,
+        sections: [
+          { __resolveType: HERO, label: "a" },
+          { __resolveType: HERO, label: "b" },
+        ],
+      },
+    });
+
+    const response = await handleRender(
+      new Request(`http://localhost/live/previews/${encodeURIComponent("/pages/home")}`),
+    );
+    const html = await response.text();
+
+    // Same wrapper markup as production (DecoPageRenderer.tsx): id derived from
+    // the section key, data-manifest-key set to the raw key.
+    expect(html).toContain(`<section id="Hero" data-manifest-key="${HERO}">`);
+    // Both sections are individually wrapped — not concatenated into one blob.
+    expect(html.match(/data-manifest-key/g)?.length).toBe(2);
+    expect(html).toContain("hero-a");
+    expect(html).toContain("hero-b");
+  });
 });

package/src/admin/resolvePreview.ts

@@ -162,7 +162,11 @@ export async function resolvePreviewRequest(request: Request): Promise<PreviewRe
       return { type: "unknown", component };
     }
 
-    const resolvedProps = (await resolveValue(props)) as Record<string, unknown>;
+    const resolvedProps = (await resolveValue(
+      props,
+      undefined,
+      buildPreviewMatcherCtx(request),
+    )) as Record<string, unknown>;
     const { __resolveType: _, ...cleanProps } = resolvedProps;
     return {
       type: "sections",

package/src/apps/autoconfig.ts

@@ -70,6 +70,30 @@ export interface AppRegistryEntry {
 
 export type AppRegistry = readonly AppRegistryEntry[];
 
+// One-shot re-configuration registered by autoconfigApps() and triggered by the
+// first request (reconfigureAppsOnce). See reconfigureAppsOnce() below for why.
+let pendingReinit: (() => Promise<void>) | null = null;
+let reinitPromise: Promise<void> | null = null;
+
+/**
+ * Re-run app configuration once, the first time it's called from within a
+ * request scope. Idempotent — subsequent calls await the same in-flight promise
+ * (or return immediately once done).
+ *
+ * Why this exists: autoconfigApps() runs at module-init (setup.ts), BEFORE any
+ * request. In CF Workers production/preview the `env` binding (holding
+ * DECO_CRYPTO_KEY) is only available inside the fetch handler, so the startup
+ * pass decrypts nothing and configures apps with null credentials. workerEntry
+ * calls this after setRuntimeEnv(env) so configure() re-runs with the real key
+ * now reachable via getRuntimeEnv() inside crypto.ts's getEnvVar().
+ */
+export function reconfigureAppsOnce(): Promise<void> {
+  if (reinitPromise) return reinitPromise;
+  if (!pendingReinit) return Promise.resolve(); // nothing registered yet
+  reinitPromise = pendingReinit();
+  return reinitPromise;
+}
+
 async function configureAllApps(
   blocks: Record<string, unknown>,
   registry: AppRegistry,
@@ -137,12 +161,39 @@ export async function autoconfigApps(
     await setupApps(apps);
   }
 
+  // Latest blocks, kept current by onChange so the first-request re-init below
+  // uses fresh content if the decofile was reloaded before the first request.
+  let latestBlocks = blocks;
+
   // Re-configure on admin hot-reload
   onChange(async (newBlocks) => {
     if (typeof document !== "undefined") return;
+    latestBlocks = newBlocks;
     const updatedApps = await configureAllApps(newBlocks, registry);
     if (updatedApps.length > 0) {
       await setupApps(updatedApps);
     }
   });
+
+  // Register the one-shot re-init fired on the first request (where the CF
+  // Workers `env` — and thus DECO_CRYPTO_KEY — becomes reachable). See
+  // reconfigureAppsOnce() for the full rationale.
+  pendingReinit = async () => {
+    const reconfigured = await configureAllApps(latestBlocks, registry);
+    if (reconfigured.length > 0) {
+      await setupApps(reconfigured);
+    }
+  };
+}
+
+/**
+ * Test-only: clear the one-shot re-init state.
+ *
+ * `pendingReinit` / `reinitPromise` are module-level and latching by design
+ * (see `reconfigureAppsOnce`), so without this a test that registers apps
+ * leaks that registration into every later test in the same module graph.
+ */
+export function __resetAutoconfigStateForTests(): void {
+  pendingReinit = null;
+  reinitPromise = null;
 }

package/src/createAdminSetup.ts

@@ -6,17 +6,17 @@
  * here because these four steps need admin/index.ts's setters, which
  * runtime cannot import without creating a circular dependency.
  */
-import {
-  setInvokeLoaders,
-  setMetaData,
-  setPreviewWrapper,
-  setRenderShell,
-} from "./admin/index";
+import { setInvokeLoaders, setMetaLoader, setPreviewWrapper, setRenderShell } from "./admin/index";
 
 export interface AdminSetupOptions {
   /**
-   * Lazy loader for admin meta schema — only fetched when admin requests it:
+   * Lazy loader for admin meta schema — only invoked on the first `/live/_meta`
+   * request, never at boot:
    * `() => import("./server/admin/meta.gen.json").then(m => m.default)`
+   *
+   * Keep it a dynamic `import()`. A static import would defeat the laziness:
+   * the module graph would pull the schema in at boot no matter when this thunk
+   * runs.
    */
   meta: () => Promise<any>;
 
@@ -43,8 +43,12 @@ export interface AdminSetupOptions {
  * createSiteSetup() (@decocms/blocks/setup).
  */
 export function createAdminSetup(options: AdminSetupOptions): void {
-  // 7. Admin meta schema (lazy)
-  options.meta().then((data) => setMetaData(data));
+  // 7. Admin meta schema — REGISTERED, not loaded. The schema is a JSON Schema
+  // bundle covering every section and app, and exactly one route needs it
+  // (`/live/_meta`). Invoking the thunk here made every isolate parse it at boot
+  // and pin the composed graph for its whole life, for traffic that never
+  // touches the admin.
+  setMetaLoader(options.meta);
 
   // 8. Render shell
   setRenderShell({