@decocms/blocks 7.35.0 → 7.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks",
-  "version": "7.35.0",
+  "version": "7.37.0",
   "type": "module",
   "engines": {
     "node": ">=24"

package/src/cms/draftSource.test.ts

@@ -28,79 +28,94 @@ beforeEach(() => {
 });
 
 describe("parseDraftPointer", () => {
-  it("parses authority@version, lowercasing the authority", () => {
-    expect(parseDraftPointer("ABC.Preview-Studio.decocms.com@FF00")).toEqual({
-      host: "abc.preview-studio.decocms.com",
-      version: "FF00",
+  it("parses <authority><path>@<version>, lowercasing the authority", () => {
+    expect(
+      parseDraftPointer(
+        "Studio.decocms.com/api/fila/decofile/vm-1/main?token=Tok.abc@8c1d44e",
+      ),
+    ).toEqual({
+      host: "studio.decocms.com",
+      path: "/api/fila/decofile/vm-1/main?token=Tok.abc",
+      version: "8c1d44e",
     });
   });
 
-  it("keeps an explicit port on the authority", () => {
-    expect(parseDraftPointer("abc.localhost:60534@v1")).toEqual({
-      host: "abc.localhost:60534",
+  it("keeps an explicit port on the authority, incl. bare localhost", () => {
+    expect(parseDraftPointer("localhost:4000/api/o/decofile/m/b@v1")).toEqual({
+      host: "localhost:4000",
+      path: "/api/o/decofile/m/b",
       version: "v1",
     });
   });
 
-  it("rejects more than one @", () => {
-    // A naive split("@") accepts this and silently uses the first two
-    // segments — the exact hole found while spiking the fetch path.
-    expect(parseDraftPointer("a.example@b@c")).toBeNull();
+  it("splits on the LAST @ — an earlier @ fails validation, never half-reads", () => {
+    // The path charset excludes `@`, so a smuggled one lands in `path` and
+    // fails PATH_RE rather than shifting the version boundary.
+    expect(parseDraftPointer("a.example/x@y/z@v1")).toBeNull();
+    expect(parseDraftPointer("a@b@c")).toBeNull();
+  });
+
+  it("requires a rooted path — authority-only tokens are gone", () => {
+    // Non-backcompat: the daemon-era `<authority>@<version>` form is invalid.
+    expect(parseDraftPointer("abc.preview-studio.decocms.com@v1")).toBeNull();
+    expect(parseDraftPointer("a.example@v1")).toBeNull();
   });
 
-  it("rejects anything that could escape the authority", () => {
-    // No scheme, no path, no userinfo — the token carries an authority only,
-    // so `javascript:`/`file:`/full URLs fail structurally at parse time.
-    expect(parseDraftPointer("https://evil.example@v1")).toBeNull();
-    expect(parseDraftPointer("evil.example/x@v1")).toBeNull();
-    expect(parseDraftPointer("a.example:80:80@v1")).toBeNull();
-    expect(parseDraftPointer("a.example:abc@v1")).toBeNull();
-    expect(parseDraftPointer(".leading.dot@v1")).toBeNull();
-    expect(parseDraftPointer("bare-label@v1")).toBeNull();
+  it("rejects anything that could escape the authority or path", () => {
+    // No scheme, no userinfo, no fragment/space in the path — a full URL
+    // fails structurally at parse time.
+    expect(parseDraftPointer("https://evil.example/x@v1")).toBeNull();
+    expect(parseDraftPointer("a.example:80:80/x@v1")).toBeNull();
+    expect(parseDraftPointer("a.example:abc/x@v1")).toBeNull();
+    expect(parseDraftPointer(".leading.dot/x@v1")).toBeNull();
+    expect(parseDraftPointer("a.example/x#frag@v1")).toBeNull();
+    expect(parseDraftPointer("a.example/x y@v1")).toBeNull();
   });
 
   it("validates the version charset — it becomes a cache key", () => {
-    expect(parseDraftPointer("a.example@")).toBeNull();
-    expect(parseDraftPointer(`a.example@${"x".repeat(65)}`)).toBeNull();
-    expect(parseDraftPointer("a.example@v 1")).toBeNull();
+    expect(parseDraftPointer("a.example/x@")).toBeNull();
+    expect(parseDraftPointer(`a.example/x@${"x".repeat(65)}`)).toBeNull();
+    expect(parseDraftPointer("a.example/x@v 1")).toBeNull();
     expect(parseDraftPointer(null)).toBeNull();
   });
 });
 
 describe("previewApiOriginForHost", () => {
   it("admits authorities under the default deco domains", () => {
+    // Hosted Studio (the decofile API origin) via the .decocms.com suffix.
+    expect(previewApiOriginForHost("studio.decocms.com", {})).toBe(
+      "https://studio.decocms.com",
+    );
+    // Preview daemons keep working under the same suffix.
     expect(previewApiOriginForHost("abc.preview-studio.decocms.com", {})).toBe(
       "https://abc.preview-studio.decocms.com",
     );
-    expect(previewApiOriginForHost("abc.local.studio.decocms.com", {})).toBe(
-      "https://abc.local.studio.decocms.com",
+    // Local dev: exact-host entries, http, explicit port allowed.
+    expect(previewApiOriginForHost("localhost:4000", {})).toBe(
+      "http://localhost:4000",
+    );
+    // The native app's dev origin serves TLS (locally-trusted cert): https,
+    // but the explicit port is still allowed.
+    expect(previewApiOriginForHost("local.studio.decocms.com:4420", {})).toBe(
+      "https://local.studio.decocms.com:4420",
     );
     expect(previewApiOriginForHost("abc.localhost:60534", {})).toBe(
       "http://abc.localhost:60534",
     );
-    // -stg is its own suffix, not a substring match of .preview-studio.decocms.com —
-    // both must be listed explicitly (regressed once: staging draft pointers
-    // silently fell back to published content with no visible error).
-    expect(
-      previewApiOriginForHost("abc.preview-studio-stg.decocms.com", {}),
-    ).toBe("https://abc.preview-studio-stg.decocms.com");
   });
 
   it("rejects hosts outside the domains — the token proposes, config disposes", () => {
     expect(previewApiOriginForHost("evil.example", {})).toBeNull();
     // Dot-prefixed suffixes guarantee a label boundary: a lookalike domain
     // that merely ends with the same characters cannot pass.
-    expect(
-      previewApiOriginForHost("evil-preview-studio.decocms.com", {}),
-    ).toBeNull();
-    // The domain itself (no label in front) is not a draft host.
-    expect(
-      previewApiOriginForHost("preview-studio.decocms.com", {}),
-    ).toBeNull();
+    expect(previewApiOriginForHost("evil-decocms.com", {})).toBeNull();
+    // The suffix domain itself (no label in front) is not admitted.
+    expect(previewApiOriginForHost("decocms.com", {})).toBeNull();
   });
 
-  it("allows an explicit port only under localhost-ish domains", () => {
+  it("allows an explicit port only for local entries", () => {
     // A public-domain token must not steer the fetch at odd ports.
+    expect(previewApiOriginForHost("studio.decocms.com:8500", {})).toBeNull();
     expect(
       previewApiOriginForHost("abc.preview-studio.decocms.com:8500", {}),
     ).toBeNull();
@@ -111,9 +126,7 @@ describe("previewApiOriginForHost", () => {
     expect(previewApiOriginForHost("abc.staging.example", env)).toBe(
       "https://abc.staging.example",
     );
-    expect(
-      previewApiOriginForHost("abc.preview-studio.decocms.com", env),
-    ).toBeNull();
+    expect(previewApiOriginForHost("studio.decocms.com", env)).toBeNull();
   });
 });
 
@@ -134,11 +147,14 @@ describe("gating", () => {
   });
 });
 
+// Canonical Studio decofile-API pointer prefix (authority + path, no version).
+const P = "studio.decocms.com/api/fila/decofile/vm-1/main?token=tok.abc";
+
 describe("resolveDraftDecofile", () => {
-  it("fetches exactly the token's validated origin", async () => {
+  it("fetches the token's path on its validated origin", async () => {
     const calls: string[] = [];
     const blocks = await resolveDraftDecofile({
-      pointer: "abc.preview-studio.decocms.com@v1",
+      pointer: `${P}@v1`,
       env: ENV_ON,
       fetchImpl: (async (url: string) => {
         calls.push(String(url));
@@ -147,15 +163,18 @@ describe("resolveDraftDecofile", () => {
     });
 
     expect(blocks).toEqual({ "pages-home": { title: "draft" } });
+    // The pointer's version rides along as `v=`, making the URL fully
+    // content-addressed so Studio can answer with CDN-cacheable immutable
+    // headers when it matches the served sha.
     expect(calls).toEqual([
-      "https://abc.preview-studio.decocms.com/_sandbox/decofile",
+      "https://studio.decocms.com/api/fila/decofile/vm-1/main?token=tok.abc&v=v1",
     ]);
   });
 
   it("is inert without a host allowlist — no fetch at all", async () => {
     let called = false;
     const blocks = await resolveDraftDecofile({
-      pointer: "abc.preview-studio.decocms.com@v1",
+      pointer: `${P}@v1`,
       env: {},
       fetchImpl: (async () => {
         called = true;
@@ -166,18 +185,32 @@ describe("resolveDraftDecofile", () => {
     expect(called).toBe(false);
   });
 
-  it("refuses a parseable token whose origin no domain admits — no fetch", async () => {
+  it("refuses a parseable token whose origin no domain admits — no fetch, no cache", async () => {
     let called = false;
-    const blocks = await resolveDraftDecofile({
-      pointer: "abc.evil.example@v1",
-      env: ENV_ON,
-      fetchImpl: (async () => {
-        called = true;
-        return jsonResponse({});
-      }) as unknown as typeof fetch,
-    });
-    expect(blocks).toBeNull();
+    const fetchImpl = (async () => {
+      called = true;
+      return jsonResponse({});
+    }) as unknown as typeof fetch;
+    expect(
+      await resolveDraftDecofile({
+        pointer: "abc.evil.example/x@v1",
+        env: ENV_ON,
+        fetchImpl,
+      }),
+    ).toBeNull();
     expect(called).toBe(false);
+
+    // Origin validation runs BEFORE the cache: a version already cached from
+    // an allowed origin must not be served for a disallowed authority.
+    await resolveDraftDecofile({ pointer: `${P}@vX`, env: ENV_ON, fetchImpl });
+    expect(called).toBe(true);
+    expect(
+      await resolveDraftDecofile({
+        pointer: "abc.evil.example/x@vX",
+        env: ENV_ON,
+        fetchImpl,
+      }),
+    ).toBeNull();
   });
 
   it("caches by version — one fetch per version, not per request", async () => {
@@ -186,7 +219,6 @@ describe("resolveDraftDecofile", () => {
       fetches++;
       return jsonResponse({ n: fetches });
     }) as unknown as typeof fetch;
-    const P = "abc.preview-studio.decocms.com";
 
     const a = await resolveDraftDecofile({
       pointer: `${P}@v1`,
@@ -211,7 +243,6 @@ describe("resolveDraftDecofile", () => {
       fetches++;
       return jsonResponse({ n: fetches });
     }) as unknown as typeof fetch;
-    const P = "abc.preview-studio.decocms.com";
 
     for (const v of ["v1", "v2", "v3", "v4"]) {
       await resolveDraftDecofile({
@@ -228,7 +259,6 @@ describe("resolveDraftDecofile", () => {
   });
 
   it("degrades to published on unreachable / non-2xx / unparseable", async () => {
-    const P = "abc.preview-studio.decocms.com";
     for (const fetchImpl of [
       async () => {
         throw new Error("ECONNREFUSED");
@@ -254,12 +284,13 @@ describe("resolveDraftDecofile", () => {
 
 // DEFAULT_PREVIEW_API_DOMAINS is part of the public contract — pin it.
 describe("DEFAULT_PREVIEW_API_DOMAINS", () => {
-  it("ships the deco-operated origins, dot-prefixed", () => {
+  it("ships the deco-operated origins plus local-dev exact hosts", () => {
     expect(DEFAULT_PREVIEW_API_DOMAINS).toEqual([
-      ".preview-studio.decocms.com",
-      ".preview-studio-stg.decocms.com",
-      ".local.studio.decocms.com",
+      "local.studio.decocms.com",
+      "localhost",
+      "127.0.0.1",
       ".localhost",
+      ".decocms.com",
     ]);
   });
 });
@@ -337,7 +368,7 @@ describe("resolveDraftForRequest", () => {
         method: "POST",
         headers: {
           "x-forwarded-host": host,
-          cookie: "__deco_draft=abc.preview-studio.decocms.com@v1",
+          cookie: `__deco_draft=${encodeURIComponent(`${P}@v1`)}`,
         },
       },
     );

package/src/cms/draftSource.ts

@@ -1,11 +1,12 @@
 /**
- * Draft preview — pull-based decofile override.
+ * Draft preview — pull-based decofile snapshot.
  *
- * A Studio preview serves the working-tree draft at
- * `GET <origin>/_sandbox/decofile`; a production site pulls it and renders its
- * own real pages against it. This replaces pushing the decofile into a POST
- * body, which only deco's own runtime honours — Next.js and most frameworks
- * render on GET only.
+ * Studio serves the draft decofile (the merged `.deco/blocks/*.json` at the
+ * branch head) from its decofile API
+ * (`GET <origin>/api/<org>/decofile/<virtualMcpId>/<branch>?token=…`); a
+ * production site pulls it and renders its own real pages against it. This
+ * replaces pushing the decofile into a POST body, which only deco's own
+ * runtime honours — Next.js and most frameworks render on GET only.
  *
  * This module is the framework-agnostic half: token parsing, origin
  * validation, fetching, and version caching. Binding a resolved draft to a
@@ -23,60 +24,83 @@
  */
 
 /**
- * A parsed `?__draft=` token: `<host[:port]>@<version>`.
+ * A parsed `?__draft=` token: `<host[:port]><path[?query]>@<version>`.
  *
- * The token carries the AUTHORITY of the draft content API, never a scheme or
- * path — a full URL would be an SSRF vector, and the scheme is derived from
- * the matched domain instead. Reserved evolution: a future signed token uses a
- * distinguishable prefix (e.g. `s1.`), so this strict two-part parse rejects
- * it cleanly rather than half-reading it.
+ * The token carries the AUTHORITY + PATH of the draft content API, never a
+ * scheme — a full URL would be an SSRF vector, and the scheme is derived from
+ * the matched domain instead. The path is REQUIRED and typically addresses
+ * Studio's decofile API (`/api/<org>/decofile/<virtualMcpId>/<branch>?token=…`);
+ * its query carries the signed draft grant.
  */
 export interface DraftPointer {
-  /** Content-API authority, e.g. `abc.preview-studio.decocms.com` or `abc.localhost:60534`. */
+  /** Content-API authority, e.g. `studio.decocms.com` or `localhost:4000`. */
   host: string;
-  /** Opaque content version (the server's ETag). Immutable → safe cache key. */
+  /** Path (+ query) on that authority serving the decofile JSON. */
+  path: string;
+  /** Opaque content version (the branch head sha / server ETag). Immutable → safe cache key. */
   version: string;
 }
 
-/** Lowercase DNS hostname, at least two labels (a bare label can't match any domain). */
+/** Lowercase DNS hostname. A single label is allowed — exact-host domain
+ * entries (`localhost`, `local.studio.decocms.com`) can admit it. */
 const HOST_RE =
-  /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+  /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/;
 const PORT_RE = /^[0-9]{1,5}$/;
 const VERSION_RE = /^[A-Za-z0-9._-]{1,64}$/;
+/** Rooted path with an optional query; conservative charset, no `@`/`#`/space. */
+const PATH_RE = /^\/[A-Za-z0-9/_.%~=&?-]*$/;
 
 /**
- * Parse `<host[:port]>@<version>`. Null on anything unexpected — callers fall
- * back to published content. Requires EXACTLY one `@`: a naive split accepts
- * `a@b@c` and silently uses the first two segments.
+ * Parse `<host[:port]><path>@<version>`. Null on anything unexpected — callers
+ * fall back to published content. Splits on the LAST `@` (neither the path
+ * charset nor a signed token may contain one, so a stray `@` fails validation
+ * rather than being half-read).
  */
 export function parseDraftPointer(
   raw: string | null | undefined,
 ): DraftPointer | null {
   if (!raw) return null;
-  const parts = raw.split("@");
-  if (parts.length !== 2) return null;
-  const [authority, version] = parts;
-  if (!authority || !version || !VERSION_RE.test(version)) return null;
-
-  const [host, port, extra] = authority.toLowerCase().split(":");
+  const at = raw.lastIndexOf("@");
+  if (at <= 0 || at === raw.length - 1) return null;
+  const authorityAndPath = raw.slice(0, at);
+  const version = raw.slice(at + 1);
+  if (!VERSION_RE.test(version)) return null;
+
+  const slash = authorityAndPath.indexOf("/");
+  if (slash === -1) return null;
+  const authority = authorityAndPath.slice(0, slash).toLowerCase();
+  const path = authorityAndPath.slice(slash);
+  if (!PATH_RE.test(path)) return null;
+
+  const [host, port, extra] = authority.split(":");
   if (extra !== undefined) return null;
   if (!host || !HOST_RE.test(host)) return null;
   if (port !== undefined && !PORT_RE.test(port)) return null;
 
-  return { host: port === undefined ? host : `${host}:${port}`, version };
+  return {
+    host: port === undefined ? host : `${host}:${port}`,
+    path,
+    version,
+  };
 }
 
 /**
  * Domains the draft content API may live under — deco-operated, so shipping
  * them as defaults adds no SSRF surface. `DECO_PREVIEW_API_DOMAINS` overrides
- * the whole list when set. Entries are dot-prefixed suffixes, which guarantees
- * a label boundary on match (`evil-preview-studio.decocms.com` cannot pass).
+ * the whole list when set.
+ *
+ * Two entry shapes: a dot-prefixed entry is a suffix match with a guaranteed
+ * label boundary (`evil-decocms.com` cannot pass `.decocms.com`); a bare entry
+ * is an exact-host match (needed for `localhost` and dev origins, which no
+ * suffix can admit). Order matters only for the local/port rule: the first
+ * matching entry decides whether a port and `http` are allowed.
  */
 export const DEFAULT_PREVIEW_API_DOMAINS = [
-  ".preview-studio.decocms.com",
-  ".preview-studio-stg.decocms.com",
-  ".local.studio.decocms.com",
+  "local.studio.decocms.com", // native/web dev origin (http, explicit port)
+  "localhost",
+  "127.0.0.1", // loopback dev — `localhost` can resolve to a different (IPv6) server
   ".localhost",
+  ".decocms.com", // hosted Studio (decofile API) + preview daemons
 ];
 
 function readApiDomains(env: Record<string, string | undefined>): string[] {
@@ -103,13 +127,26 @@ export function previewApiOriginForHost(
 ): string | null {
   const [host, port] = authority.toLowerCase().split(":");
   if (!host) return null;
-  const domain = readApiDomains(envOrProcess(env)).find(
-    (d) => host.length > d.length && host.endsWith(d),
+  const domain = readApiDomains(envOrProcess(env)).find((d) =>
+    d.startsWith(".") ? host.length > d.length && host.endsWith(d) : host === d,
   );
   if (!domain) return null;
-  const local = domain.includes("localhost");
+  // Local entries may carry an explicit port; public domains may not (a
+  // public-domain token must not steer the fetch at odd ports).
+  const local =
+    domain === "localhost" ||
+    domain === "127.0.0.1" ||
+    domain.endsWith(".localhost") ||
+    domain === "local.studio.decocms.com";
   if (port !== undefined && !local) return null;
-  return `${local ? "http" : "https"}://${host}${port === undefined ? "" : `:${port}`}`;
+  // Scheme is derived, never taken from the token. Plain-loopback dev hosts
+  // are http; local.studio.decocms.com is the native app's TLS dev origin
+  // (locally-trusted cert), so it — like every public domain — is https.
+  const insecure =
+    domain === "localhost" ||
+    domain === "127.0.0.1" ||
+    domain.endsWith(".localhost");
+  return `${insecure ? "http" : "https"}://${host}${port === undefined ? "" : `:${port}`}`;
 }
 
 /**
@@ -217,7 +254,7 @@ export function clearDraftCache(): void {
 }
 
 export interface ResolveDraftOptions {
-  /** Raw `<host[:port]>@<version>` token from the request. */
+  /** Raw `<host[:port]><path>@<version>` token from the request. */
   pointer: string | null | undefined;
   /** Defaults to `process.env`. */
   env?: Record<string, string | undefined>;
@@ -241,16 +278,28 @@ export async function resolveDraftDecofile(
   const parsed = parseDraftPointer(options.pointer);
   if (!parsed) return null;
 
-  const cached = byVersion.get(parsed.version);
-  if (cached) return cached;
-
+  // Origin validation BEFORE the cache: a cached version must never be served
+  // for a pointer whose authority the configuration would reject.
   const origin = previewApiOriginForHost(parsed.host, env);
   if (!origin) return null;
 
+  const cached = byVersion.get(parsed.version);
+  if (cached) return cached;
+
   const doFetch = options.fetchImpl ?? fetch;
+  // The pointer's version rides along as `v=`, making the fetch URL fully
+  // content-addressed (path + token + version). Today the server serves it
+  // no-store either way — token-protected drafts are deliberately NOT
+  // shared-cacheable (edge caches can't re-validate the grant, so revocation
+  // wouldn't propagate). The param still earns its place: version-tagged
+  // access logs, and it's the prerequisite for edge-validated caching later
+  // (a CDN worker checking the token per request, keyed on path+version)
+  // without another runtime deploy.
+  const url = new URL(parsed.path, origin);
+  url.searchParams.append("v", parsed.version);
   let res: Response;
   try {
-    res = await doFetch(`${origin}/_sandbox/decofile`, { cache: "no-store" });
+    res = await doFetch(url.toString(), { cache: "no-store" });
   } catch {
     return null;
   }
@@ -355,7 +404,12 @@ export async function resolveDraftForRequest(
 
 type DraftOverrideGetter = () => Record<string, unknown> | null | undefined;
 
-let getDraftOverride: DraftOverrideGetter = () => undefined;
+// globalThis-backed like the hosts above: bundlers can duplicate this module
+// across graphs (nested node_modules installs, RSC layer splits), and a getter
+// registered on one instance's module variable is invisible to the copy
+// `loadBlocks()` imports — the framework binding then resolves the draft while
+// the render silently serves published content.
+const GG = globalThis as { __decoDraftOverrideGetter?: DraftOverrideGetter };
 
 /**
  * Inject the request-scoped draft getter.
@@ -366,7 +420,7 @@ let getDraftOverride: DraftOverrideGetter = () => undefined;
  * Never called → returns undefined → `loadBlocks()` behaves exactly as before.
  */
 export function setDraftOverrideGetter(getter: DraftOverrideGetter): void {
-  getDraftOverride = getter;
+  GG.__decoDraftOverrideGetter = getter;
 }
 
 /** The current request's draft blocks, if a binding registered one. */
@@ -374,5 +428,5 @@ export function getRequestDraftOverride():
   | Record<string, unknown>
   | null
   | undefined {
-  return getDraftOverride();
+  return GG.__decoDraftOverrideGetter?.();
 }

package/src/cms/index.ts

@@ -1,4 +1,7 @@
-export type { ApplySectionConventionsInput, SectionMetaEntry } from "./applySectionConventions";
+export type {
+  ApplySectionConventionsInput,
+  SectionMetaEntry,
+} from "./applySectionConventions";
 export { applySectionConventions } from "./applySectionConventions";
 export type { BlockSnapshot, BlockSource, KVNamespace } from "./blockSource";
 export {
@@ -43,8 +46,13 @@ export {
   onChange,
   setBlocks,
   withBlocksOverride,
+  withDraftBlocks,
 } from "./loader";
-export type { OnBeforeResolveProps, SectionModule, SectionOptions } from "./registry";
+export type {
+  OnBeforeResolveProps,
+  SectionModule,
+  SectionOptions,
+} from "./registry";
 export {
   getResolvedComponent,
   getSection,

package/src/cms/loader.test.ts

@@ -1,6 +1,13 @@
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { setDraftOverrideGetter } from "./draftSource";
-import { findPageByPath, loadBlocks, matchPath, setBlocks } from "./loader";
+import {
+  findPageByPath,
+  loadBlocks,
+  matchPath,
+  setBlocks,
+  withBlocksOverride,
+  withDraftBlocks,
+} from "./loader";
 
 // Mirrors the behavior of the original deco-cx/deco Fresh framework
 // (runtime/features/render.tsx), which uses native `URLPattern` directly
@@ -28,7 +35,9 @@ describe("matchPath", () => {
 
   describe("named params (:slug)", () => {
     it("captures a single param", () => {
-      expect(matchPath("/foo/:slug", "/foo/sabonete")).toEqual({ slug: "sabonete" });
+      expect(matchPath("/foo/:slug", "/foo/sabonete")).toEqual({
+        slug: "sabonete",
+      });
     });
 
     it("captures a param sandwiched between literals (VTEX PDP)", () => {
@@ -75,7 +84,9 @@ describe("matchPath", () => {
     });
 
     it("matches with the optional group absent", () => {
-      expect(matchPath("/{granado/}?*", "/perfumaria")).toEqual({ "0": "perfumaria" });
+      expect(matchPath("/{granado/}?*", "/perfumaria")).toEqual({
+        "0": "perfumaria",
+      });
     });
 
     it("matches root when optional prefix and splat collapse to empty", () => {
@@ -83,17 +94,26 @@ describe("matchPath", () => {
     });
 
     it("matches with an optional prefix before a literal segment", () => {
-      expect(matchPath("/{granado/}?campanhas/*", "/granado/campanhas/destaques-2023")).toEqual({
+      expect(
+        matchPath(
+          "/{granado/}?campanhas/*",
+          "/granado/campanhas/destaques-2023",
+        ),
+      ).toEqual({
         "0": "destaques-2023",
       });
-      expect(matchPath("/{granado/}?campanhas/*", "/campanhas/destaques-2023")).toEqual({
+      expect(
+        matchPath("/{granado/}?campanhas/*", "/campanhas/destaques-2023"),
+      ).toEqual({
         "0": "destaques-2023",
       });
     });
 
     it("matches an optional suffix group present and absent", () => {
       expect(matchPath("/black-friday{/70-off}?", "/black-friday")).toEqual({});
-      expect(matchPath("/black-friday{/70-off}?", "/black-friday/70-off")).toEqual({});
+      expect(
+        matchPath("/black-friday{/70-off}?", "/black-friday/70-off"),
+      ).toEqual({});
     });
   });
 
@@ -113,7 +133,9 @@ describe("matchPath", () => {
       // biome-ignore lint/performance/noDelete: restoring exact global state
       delete g.URLPattern;
       try {
-        expect(() => matchPath("/foo/:slug", "/foo/bar")).toThrow(/URLPattern.*Node\.js >= 24/s);
+        expect(() => matchPath("/foo/:slug", "/foo/bar")).toThrow(
+          /URLPattern.*Node\.js >= 24/s,
+        );
       } finally {
         if (saved !== undefined) g.URLPattern = saved;
       }
@@ -202,12 +224,11 @@ describe("findPageByPath specificity", () => {
 
 describe("loadBlocks draft override — key percent-encoding", () => {
   // The published decofile encodes special characters in block keys
-  // (`pages-Home%20(principal)-1`); the Studio draft-preview sandbox emits them
-  // raw (`pages-Home (principal)-1`). A naive key-merge ADDS the raw-keyed
-  // draft block instead of REPLACING the encoded published one, leaving two
-  // `pages-` blocks with path "/" — and findPageByPath returns the first
-  // (published) one, so the draft edit silently never renders. This shipped and
-  // made ~73% of casaevideo's pages (home + afiliados included) ignore drafts.
+  // (`pages-Home%20(principal)-1`); the Studio draft emits them raw
+  // (`pages-Home (principal)-1`). Under snapshot semantics the draft REPLACES
+  // the file-backed base wholesale, so an encoded/raw twin pair can never
+  // coexist — these regression tests (from the merge era, when ~73% of
+  // casaevideo's pages silently ignored drafts) now pin that property.
 
   afterEach(() => {
     setBlocks({});
@@ -281,3 +302,76 @@ describe("loadBlocks draft override — key percent-encoding", () => {
     expect(pageBlocks).toHaveLength(0);
   });
 });
+
+describe("loadBlocks draft snapshot semantics", () => {
+  afterEach(() => {
+    setBlocks({});
+    setDraftOverrideGetter(() => undefined);
+  });
+
+  it("a block absent from the draft is deleted — the draft is the complete truth", () => {
+    setBlocks({
+      "pages-home-1": { name: "Home", path: "/", sections: [{}] },
+      "pages-old-2": { name: "Old", path: "/old", sections: [{}] },
+    });
+    setDraftOverrideGetter(() => ({
+      "pages-home-1": { name: "Home", path: "/", sections: [{}] },
+    }));
+
+    const keys = Object.keys(loadBlocks());
+    expect(keys).toEqual(["pages-home-1"]);
+    expect(findPageByPath("/old")).toBeNull();
+  });
+
+  it("synthetic CSV-redirect base blocks survive the snapshot", () => {
+    setBlocks({
+      "__csv_redirects__bulk.csv": { redirects: [{ from: "/a", to: "/b" }] },
+      "pages-home-1": { name: "Home", path: "/", sections: [{}] },
+    });
+    setDraftOverrideGetter(() => ({
+      "pages-home-1": { name: "Home", path: "/", sections: [{}] },
+    }));
+
+    const blocks = loadBlocks();
+    expect(blocks["__csv_redirects__bulk.csv"]).toEqual({
+      redirects: [{ from: "/a", to: "/b" }],
+    });
+  });
+
+  it("withDraftBlocks applies snapshot semantics; withBlocksOverride keeps merge", () => {
+    setBlocks({
+      "pages-home-1": { name: "Home", path: "/", sections: [{}] },
+      "pages-other-2": { name: "Other", path: "/other", sections: [{}] },
+    });
+    const draft = {
+      "pages-home-1": { name: "Home", path: "/", sections: [{}] },
+    };
+
+    // Snapshot: the base-only block is gone.
+    withDraftBlocks(draft, () => {
+      expect(Object.keys(loadBlocks())).toEqual(["pages-home-1"]);
+    });
+
+    // Merge (admin partial payloads): the base-only block survives.
+    withBlocksOverride(draft, () => {
+      expect(Object.keys(loadBlocks()).sort()).toEqual([
+        "pages-home-1",
+        "pages-other-2",
+      ]);
+    });
+  });
+
+  it("an explicit scope wins over the ambient draft", () => {
+    setBlocks({ "pages-home-1": { name: "Home", path: "/", sections: [{}] } });
+    setDraftOverrideGetter(() => ({
+      "pages-ambient-9": { name: "A", path: "/a", sections: [{}] },
+    }));
+
+    withDraftBlocks(
+      { "pages-scoped-3": { name: "S", path: "/s", sections: [{}] } },
+      () => {
+        expect(Object.keys(loadBlocks())).toEqual(["pages-scoped-3"]);
+      },
+    );
+  });
+});

package/src/cms/loader.ts

@@ -31,7 +31,21 @@ interface ALSLike<T> {
 // node:async_hooks with an empty shim). The namespace import avoids Rollup's
 // named-export validation, and the runtime check prevents construction errors.
 const ALS = (asyncHooks as any).AsyncLocalStorage;
-const blocksOverrideStorage: ALSLike<Record<string, unknown>> = ALS
+
+/**
+ * A scoped blocks override, tagged with how it composes over the base:
+ * - `merge`: a PARTIAL decofile (admin preview payloads) — entries replace or
+ *   delete their base twins, everything else survives (see mergeOverride).
+ * - `snapshot`: a COMPLETE decofile (draft preview) — it replaces the
+ *   file-backed base entirely; only synthetic base blocks survive (see
+ *   applyDraftSnapshot).
+ */
+interface BlocksOverride {
+  mode: "merge" | "snapshot";
+  blocks: Record<string, unknown>;
+}
+
+const blocksOverrideStorage: ALSLike<BlocksOverride> = ALS
   ? new ALS()
   : { getStore: () => undefined, run: (_s: any, fn: any) => fn() };
 
@@ -39,7 +53,10 @@ const blocksOverrideStorage: ALSLike<Record<string, unknown>> = ALS
 // Change listeners
 // ---------------------------------------------------------------------------
 
-type ChangeListener = (blocks: Record<string, unknown>, revision: string) => void;
+type ChangeListener = (
+  blocks: Record<string, unknown>,
+  revision: string,
+) => void;
 const changeListeners: ChangeListener[] = [];
 
 /** Register a callback invoked whenever setBlocks() changes the decofile. */
@@ -139,9 +156,40 @@ function mergeOverride(
 }
 
 /**
- * Load the current blocks. If running inside a `withBlocksOverride` scope
- * (admin preview) or a request carrying a draft-preview override, that
- * override is merged on top of the base blocks.
+ * Base blocks that are NOT file-backed: synthesized by the generator (CSV
+ * redirect loaders, keyed `__csv_redirects__<file>`). A draft snapshot is the
+ * complete truth of `.deco/blocks/` but knows nothing about these, so they
+ * survive the snapshot instead of vanishing from the preview.
+ */
+const SYNTHETIC_BLOCK_KEY_PREFIX = "__csv_redirects__";
+
+/**
+ * Compose a draft SNAPSHOT over the base blocks: the draft is the complete
+ * decofile at the branch head, so it REPLACES every file-backed base block —
+ * a block absent from the draft was deleted and must not render. Only
+ * synthetic base blocks (see SYNTHETIC_BLOCK_KEY_PREFIX) survive. `null`
+ * draft values are tolerated as deletions for defensiveness.
+ */
+function applyDraftSnapshot(
+  base: Record<string, unknown>,
+  draft: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(base)) {
+    if (key.startsWith(SYNTHETIC_BLOCK_KEY_PREFIX)) out[key] = value;
+  }
+  for (const [key, value] of Object.entries(draft)) {
+    if (value === null || value === undefined) continue;
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Load the current blocks. If running inside a `withBlocksOverride` /
+ * `withDraftBlocks` scope (admin preview / draft endpoints) or a request
+ * carrying an ambient draft, that override composes over the base blocks
+ * according to its mode.
  */
 export function loadBlocks(): Record<string, unknown> {
   // Re-sync from globalThis in case setBlocks was called in another module instance
@@ -150,11 +198,17 @@ export function loadBlocks(): Record<string, unknown> {
     revision = G.__deco.revision ?? null;
   }
 
-  // `withBlocksOverride` (an explicit admin render of a specific payload) wins
-  // over an ambient draft: the caller named the exact blocks to render, so a
-  // draft pointer on the same request must not silently replace them.
-  const override = blocksOverrideStorage.getStore() ?? getRequestDraftOverride();
-  if (override) return mergeOverride(blockData, override);
+  // An explicit scope (the caller named the exact blocks to render) wins over
+  // an ambient draft: a draft pointer on the same request must not silently
+  // replace it.
+  const scoped = blocksOverrideStorage.getStore();
+  if (scoped) {
+    return scoped.mode === "merge"
+      ? mergeOverride(blockData, scoped.blocks)
+      : applyDraftSnapshot(blockData, scoped.blocks);
+  }
+  const draft = getRequestDraftOverride();
+  if (draft) return applyDraftSnapshot(blockData, draft);
   return blockData;
 }
 
@@ -171,8 +225,25 @@ export function getRevision(): string | null {
  * for the duration of the render. Other concurrent requests are not
  * affected (AsyncLocalStorage is per-request scoped).
  */
-export function withBlocksOverride<T>(override: Record<string, unknown>, fn: () => T): T {
-  return blocksOverrideStorage.run(override, fn);
+export function withBlocksOverride<T>(
+  override: Record<string, unknown>,
+  fn: () => T,
+): T {
+  return blocksOverrideStorage.run({ mode: "merge", blocks: override }, fn);
+}
+
+/**
+ * Run a function with a COMPLETE draft decofile (snapshot semantics — see
+ * applyDraftSnapshot). Used by secondary endpoints (`/deco/invoke`) that
+ * re-resolve the page's draft from the raw request: the draft must compose
+ * exactly like the page render, deletions included, or a lazy section could
+ * render a block the page no longer has.
+ */
+export function withDraftBlocks<T>(
+  draft: Record<string, unknown>,
+  fn: () => T,
+): T {
+  return blocksOverrideStorage.run({ mode: "snapshot", blocks: draft }, fn);
 }
 
 // Higher key wins. Compared lexicographically:
@@ -213,7 +284,11 @@ function pathSpecificityKey(path: string): [number, number, number] {
 
 export function getAllPages(): Array<{ key: string; page: DecoPage }> {
   const blocks = loadBlocks();
-  const pages: Array<{ key: string; page: DecoPage; key2: [number, number, number] }> = [];
+  const pages: Array<{
+    key: string;
+    page: DecoPage;
+    key2: [number, number, number];
+  }> = [];
 
   for (const [key, block] of Object.entries(blocks)) {
     if (!key.startsWith("pages-")) continue;
@@ -281,7 +356,10 @@ declare const URLPattern: {
  * `URLPattern` is native in browsers, workerd, Deno, and Node >= 24 (this
  * package's `engines` floor). Node 22 and older lack it.
  */
-export function matchPath(pattern: string, urlPath: string): Record<string, string> | null {
+export function matchPath(
+  pattern: string,
+  urlPath: string,
+): Record<string, string> | null {
   if (typeof URLPattern === "undefined") {
     throw new Error(
       "@decocms/blocks: this runtime has no URLPattern Web API, so CMS page " +