@decocms/tanstack 7.72.0 → 8.1.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/tanstack",
-  "version": "7.72.0",
+  "version": "8.1.0-next.0",
   "type": "module",
   "description": "Deco framework binding for TanStack Start + Cloudflare Workers",
   "repository": {
@@ -9,6 +9,10 @@
     "directory": "packages/tanstack"
   },
   "main": "./src/index.ts",
+  "sideEffects": [
+    "./src/vite/**",
+    "./src/daemon/**"
+  ],
   "exports": {
     ".": "./src/index.ts",
     "./vite": "./src/vite/plugin.js",
@@ -27,9 +31,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.72.0",
-    "@decocms/blocks-admin": "7.72.0",
-    "@decocms/blocks-cli": "7.72.0",
+    "@decocms/blocks": "8.1.0-next.0",
+    "@decocms/blocks-admin": "8.1.0-next.0",
+    "@decocms/blocks-cli": "8.1.0-next.0",
     "@deco-cx/warp-node": "^0.3.16",
     "fast-json-patch": "^3.1.0",
     "ws": "^8.18.0"

package/src/__conformance__/observability.test.ts

@@ -0,0 +1,221 @@
+// @vitest-environment node
+/**
+ * Conformance: the framework-binding half of telemetry.mdx ("What's sent"),
+ * telemetry-internals.mdx ("Sending in the background") and caching.mdx
+ * ("Upstream data"), for `@decocms/tanstack` on Cloudflare Workers.
+ *
+ * A site on Workers creates its CMS with `createCMS({ telemetry })` from
+ * `@decocms/blocks` and serves through the binding's worker entry. The docs
+ * say the binding then adds inbound request and edge-cache metrics to that
+ * CMS's telemetry, sends batches inside `ctx.waitUntil`, and caches upstream
+ * responses (made through `createInstrumentedFetch`) with the Cache API,
+ * except while a draft is being rendered.
+ */
+import { gunzipSync } from "node:zlib";
+import { createCMS, DRAFT_COOKIE, resetForTests } from "@decocms/blocks";
+import { setBlocks } from "@decocms/blocks/cms";
+import { createInstrumentedFetch } from "@decocms/blocks/fetch";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createDecoWorkerEntry } from "../sdk/workerEntry";
+
+const ENDPOINT = "https://otel.example.com";
+
+let clock = 0;
+let waits: Promise<unknown>[] = [];
+const ctx = {
+  waitUntil: (promise: Promise<unknown>) => void waits.push(promise),
+  passThroughOnException: () => {},
+};
+
+interface Sent {
+  url: string;
+  text: string;
+  body: any;
+}
+
+let sent: Sent[] = [];
+let upstreamCalls: string[] = [];
+
+beforeEach(() => {
+  resetForTests();
+  // The only worker entry @decocms/tanstack has is v7's, which needs v7's block
+  // registry loaded even for an app that only uses createCMS.
+  setBlocks({});
+  clock = 0;
+  waits = [];
+  sent = [];
+  upstreamCalls = [];
+  const now = Date.now.bind(Date);
+  vi.spyOn(Date, "now").mockImplementation(() => now() + clock);
+  vi.stubEnv("OTEL_EXPORTER_OTLP_ENDPOINT", "");
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
+      const url = String(input instanceof Request ? input.url : input);
+      if (url.startsWith(ENDPOINT)) {
+        const raw = Buffer.from(init?.body as Uint8Array);
+        const gz = new Headers(init?.headers).get("content-encoding") === "gzip";
+        const text = gz ? gunzipSync(raw).toString() : String(raw);
+        sent.push({ url, text, body: JSON.parse(text) });
+        return new Response(null, { status: 200 });
+      }
+      upstreamCalls.push(url);
+      return new Response(JSON.stringify({ hits: [] }), {
+        status: 200,
+        headers: { "content-type": "application/json", "cache-control": "max-age=60" },
+      });
+    }),
+  );
+});
+
+afterEach(() => {
+  delete (globalThis as Record<symbol, unknown>)[Symbol.for("decocms.blocks.background")];
+  vi.unstubAllGlobals();
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+  resetForTests();
+});
+
+/** A Cache API stand-in (`caches.default`) that remembers what was put. */
+function fakeCaches() {
+  const store = new Map<string, Response>();
+  const puts: string[] = [];
+  const cache = {
+    match: vi.fn(async (request: Request | string) => {
+      const key = typeof request === "string" ? request : request.url;
+      return store.get(key)?.clone();
+    }),
+    put: vi.fn(async (request: Request | string, response: Response) => {
+      const key = typeof request === "string" ? request : request.url;
+      puts.push(key);
+      store.set(key, response.clone());
+    }),
+    delete: vi.fn(async () => true),
+  };
+  vi.stubGlobal("caches", { default: cache, open: async () => cache });
+  return { cache, puts };
+}
+
+/** Lets every queued background task run, one batch window (10 s) after the last. */
+async function drain(): Promise<void> {
+  for (let i = 0; i < 5; i++) {
+    clock += 10_000;
+    const pending = waits.splice(0);
+    if (pending.length === 0) break;
+    await Promise.all(pending);
+  }
+}
+
+function metrics() {
+  return sent
+    .filter((s) => s.url.endsWith("/v1/metrics"))
+    .flatMap((s) => s.body.resourceMetrics[0].scopeMetrics[0].metrics);
+}
+
+function attrs(list: { key: string; value: Record<string, unknown> }[] = []) {
+  return Object.fromEntries(list.map(({ key, value }) => [key, Object.values(value)[0]]));
+}
+
+const search = createInstrumentedFetch({ provider: "acme-search" });
+
+/** The app's server entry: a product page that calls an upstream API through the instrumented fetch. */
+const serverEntry = {
+  fetch: async (request: Request) => {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith("/products/")) {
+      await search("https://search.example/v1/search?q=shirt", { operation: "search" });
+      return new Response("<html>product</html>", {
+        status: 200,
+        headers: { "content-type": "text/html" },
+      });
+    }
+    return new Response("not found", { status: 404 });
+  },
+};
+
+function cms() {
+  return createCMS({
+    blocks: {},
+    content: { revision: "rev-1", root: "tanstack-conformance/.deco", blocks: {} },
+    telemetry: { endpoint: ENDPOINT },
+  });
+}
+
+async function serve(worker: ReturnType<typeof createDecoWorkerEntry>, path: string, headers = {}) {
+  const response = await worker.fetch(
+    new Request(`https://shop.example${path}`, { headers }),
+    {},
+    ctx,
+  );
+  await response.text();
+  return response;
+}
+
+describe("sending in the background (telemetry-internals.mdx)", () => {
+  it("tin-06: on Workers, batches go out after the response, inside ctx.waitUntil", async () => {
+    cms();
+    const worker = createDecoWorkerEntry(serverEntry, { observability: false });
+    await serve(worker, "/products/abc-123");
+    expect(sent).toEqual([]); // nothing went out in front of the response
+    clock += 10_000;
+    await serve(worker, "/products/abc-123");
+    expect(waits.length).toBeGreaterThan(0);
+    await drain();
+    expect(metrics().map((m) => m.name)).toContain("http.client.request.duration");
+  });
+});
+
+describe("what the binding adds (telemetry.mdx › What's sent)", () => {
+  it("tel-09: the binding adds no measurements of its own (inbound requests and the page cache are the framework's)", async () => {
+    cms();
+    const worker = createDecoWorkerEntry(serverEntry, { observability: false });
+    await serve(worker, "/products/abc-123?x=1");
+    clock += 10_000;
+    await serve(worker, "/products/abc-123?x=1");
+    await drain();
+    const names = new Set(metrics().map((m) => m.name));
+    expect(names).toContain("http.client.request.duration");
+    expect(names).not.toContain("http.server.request.duration");
+    expect(names).not.toContain("deco.cache.requests");
+    expect([...names].every((name) => name === "http.client.request.duration")).toBe(true);
+  });
+});
+
+describe("upstream data (caching.mdx)", () => {
+  it("cache-03/tel-15/cache-05: upstream GETs are cached with the Cache API; a hit is labeled cached=true", async () => {
+    const { cache } = fakeCaches();
+    cms();
+    const worker = createDecoWorkerEntry(serverEntry, { observability: false });
+    // Two different pages (so the page cache can't answer) calling the same upstream URL.
+    await serve(worker, "/products/a");
+    await serve(worker, "/products/b");
+    expect(upstreamCalls).toHaveLength(1);
+    expect(cache.put).toHaveBeenCalled();
+    clock += 10_000;
+    await serve(worker, "/products/other");
+    await drain();
+    const client = metrics().find((m) => m.name === "http.client.request.duration");
+    const labels = client.histogram.dataPoints.map((p: any) => attrs(p.attributes).cached);
+    expect(labels).toContain(true);
+    expect(labels).toContain(false);
+  });
+
+  it("cache-06: while a draft is rendered, upstream calls bypass the cache", async () => {
+    const { cache, puts } = fakeCaches();
+    cms();
+    const worker = createDecoWorkerEntry(serverEntry, { observability: false });
+    // Without a draft, the second call is a cache hit (the precondition).
+    await serve(worker, "/products/a");
+    await serve(worker, "/products/b");
+    expect(upstreamCalls).toHaveLength(1);
+    const putsBefore = puts.length;
+    cache.match.mockClear();
+    const draft = {
+      cookie: `${DRAFT_COOKIE}=${encodeURIComponent("content.example/drafts/1@v1")}`,
+    };
+    await serve(worker, "/products/c", draft);
+    await serve(worker, "/products/d", draft);
+    expect(upstreamCalls).toHaveLength(3);
+    expect(puts.length).toBe(putsBefore);
+  });
+});

package/src/index.ts

@@ -1,7 +1,17 @@
 export {
+  DecoPageRenderer,
+  DecoRootLayout,
+  DraftPreviewIndicator,
+  NavigationProgress,
+  PreviewProviders,
+  SectionList,
+  SectionRenderer,
+  StableOutlet,
+} from "./hooks";
+export {
+  CmsPage,
   cmsHomeRouteConfig,
   cmsRouteConfig,
-  CmsPage,
   decoInvokeRouteConfig,
   decoMetaRouteConfig,
   decoRenderRouteConfig,
@@ -11,33 +21,23 @@ export {
   NotFoundPage,
   withSiteGlobals,
 } from "./routes";
-export {
-  DecoPageRenderer,
-  DecoRootLayout,
-  DraftPreviewIndicator,
-  NavigationProgress,
-  PreviewProviders,
-  SectionList,
-  SectionRenderer,
-  StableOutlet,
-} from "./hooks";
-export { createDecoWorkerEntry } from "./sdk/workerEntry";
-export { setupTanstackFastDeploy } from "./setupFastDeploy";
+export type { CreateDecoRouterOptions } from "./sdk/router";
 export {
   createDecoRouter,
   decoParseSearch,
   decoStringifySearch,
 } from "./sdk/router";
-export type { CreateDecoRouterOptions } from "./sdk/router";
-export {
-  buildSpeculationRules,
-  DEFAULT_EXCLUDED_HREF_MATCHES,
-} from "./sdk/speculationRules";
 export type {
   SpeculationAction,
   SpeculationEagerness,
   SpeculationRulesConfig,
 } from "./sdk/speculationRules";
+export {
+  buildSpeculationRules,
+  DEFAULT_EXCLUDED_HREF_MATCHES,
+} from "./sdk/speculationRules";
+export { createDecoWorkerEntry } from "./sdk/workerEntry";
+export { setupTanstackFastDeploy } from "./setupFastDeploy";
 // createInvokeFn is intentionally NOT re-exported from this root barrel.
 // Its body contains a `createServerFn(...).handler(...)` call that is not a
 // top-level variable declarator (it's returned from a factory function) --
@@ -57,3 +57,5 @@ export type {
 // bundle; importing it from here would drag `createDecoWorkerEntry` (and the
 // whole server graph behind it) into that bundle. Import it from the dedicated
 // "@decocms/tanstack/sdk/serverFnFetch" subpath instead.
+// Next major (v8): the binding's documented surface. See /next/api-reference#loaders.
+export { kvLoader } from "./v8/kvLoader";

package/src/sdk/backgroundTasks.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Workers run no timers between requests: core background work (release
+ * checks, telemetry batches) runs after the response, inside ctx.waitUntil
+ * (hosted-publishing.mdx, hosted-releases-internals.mdx, telemetry-internals.mdx).
+ */
+import { createCMS, type Loader, resetForTests } from "@decocms/blocks";
+import { setBlocks } from "@decocms/blocks/cms";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createDecoWorkerEntry } from "./workerEntry";
+
+const HOOK = Symbol.for("decocms.blocks.background");
+
+beforeEach(() => {
+  resetForTests();
+  setBlocks({}); // the v7 path this entry still runs reads redirects from it
+});
+afterEach(() => {
+  delete (globalThis as Record<symbol, unknown>)[HOOK];
+  resetForTests();
+});
+
+function context() {
+  const waited: Promise<unknown>[] = [];
+  return {
+    waited,
+    ctx: { waitUntil: (p: Promise<unknown>) => void waited.push(p), passThroughOnException() {} },
+  };
+}
+
+describe("createDecoWorkerEntry: background work", () => {
+  it("runs a due release check after the response, inside ctx.waitUntil", async () => {
+    const update = vi.fn(async () => ({ updated: false }));
+    const loader: Loader = {
+      load: async () => ({ revision: "r1", blocks: {} }),
+      update,
+    };
+    const cms = createCMS({ blocks: {}, content: loader });
+    let checkedBeforeResponse = true;
+    const worker = createDecoWorkerEntry(
+      {
+        fetch: async () => {
+          cms.forRelease();
+          await Promise.resolve();
+          checkedBeforeResponse = update.mock.calls.length > 0;
+          return new Response("ok");
+        },
+      },
+      { observability: false },
+    );
+    const { waited, ctx } = context();
+    const response = await worker.fetch(new Request("https://example.com/"), {}, ctx);
+    expect(await response.text()).toBe("ok");
+    expect(checkedBeforeResponse).toBe(false);
+    expect(waited).toHaveLength(1);
+    await Promise.all(waited);
+    expect(update).toHaveBeenCalledTimes(1);
+  });
+
+  it("calls waitUntil only when there's something queued", async () => {
+    const worker = createDecoWorkerEntry(
+      { fetch: async () => new Response("ok") },
+      { observability: false },
+    );
+    const { waited, ctx } = context();
+    await worker.fetch(new Request("https://example.com/"), {}, ctx);
+    expect(waited).toHaveLength(0);
+  });
+});

package/src/sdk/backgroundTasks.ts

@@ -0,0 +1,38 @@
+/**
+ * Runs `@decocms/blocks` background work (release checks, telemetry batches)
+ * after each response, inside `ctx.waitUntil`. Workers run no timers between
+ * requests, so the core's timer fallback would never fire or would be bound
+ * to a finished request. See /next/hosted-releases-internals and
+ * /next/telemetry-internals#sending-in-the-background.
+ *
+ * The hook is installed once per isolate under the `Symbol.for` key the core
+ * looks for; its queue lives on the hook itself, so two copies of this module
+ * share one queue.
+ */
+
+const HOOK = Symbol.for("decocms.blocks.background");
+
+type Task = () => Promise<void>;
+type Hook = ((task: Task) => void) & { queue: Task[] };
+
+function hook(): Hook {
+  const g = globalThis as unknown as Record<symbol, Hook | undefined>;
+  const existing = g[HOOK];
+  if (typeof existing === "function" && Array.isArray(existing.queue)) return existing;
+  const queue: Task[] = [];
+  const installed = Object.assign((task: Task) => void queue.push(task), { queue });
+  g[HOOK] = installed;
+  return installed;
+}
+
+/** Installs the hook (idempotent): from now on, core background work queues here. */
+export function installBackgroundHook(): void {
+  hook();
+}
+
+/** Runs everything queued so far inside `ctx.waitUntil`. */
+export function runBackgroundTasks(ctx: { waitUntil(promise: Promise<unknown>): void }): void {
+  const tasks = hook().queue.splice(0);
+  if (tasks.length === 0) return;
+  ctx.waitUntil(Promise.all(tasks.map((task) => task().catch(() => {}))));
+}

package/src/sdk/workerEntry.ts

@@ -25,6 +25,7 @@
  * ```
  */
 
+import { draftPointer } from "@decocms/blocks";
 import {
   getRevision,
   getSectionOptions,
@@ -92,6 +93,8 @@ import { getRenderShellConfig } from "@decocms/blocks-admin/admin/setup";
 import { reconfigureAppsOnce } from "@decocms/blocks-admin/apps/autoconfig";
 import { buildHtmlShell } from "@decocms/blocks-admin/sdk/htmlShell";
 import { getAppMiddleware } from "@decocms/blocks-admin/sdk/setupApps";
+import { installUpstreamCache } from "../v8/binding";
+import { installBackgroundHook, runBackgroundTasks } from "./backgroundTasks";
 import { CSEG_BAG_KEY, CSEG_PARAM, segmentToken } from "./cdnSegment";
 import {
   applyDraftCookieAndHeaders,
@@ -1287,6 +1290,8 @@ export function createDecoWorkerEntry(
     // `?__draft=` param OR the navigation cookie (SPA nav after entry), gated
     // on an allowed preview host — see requestCarriesDraft.
     if (requestCarriesDraft(request, url)) return false;
+    // A next-major draft (`?__draft=` or the `deco-draft` cookie): same rule.
+    if (draftPointer(request) !== null) return false;
     if (url.searchParams.has("__deco_preview")) return false;
     if (url.searchParams.has("pathTemplate")) return false;
     // Forced matcher results must never be served from (or stored in) the
@@ -2169,6 +2174,21 @@ export function createDecoWorkerEntry(
   // `DECO_OTEL_*_ENDPOINT` env vars are configured, telemetry flows
   // without any change to the site's worker-entry. When the env vars are
   // absent the wrap is a no-op (no exporters created, no flush calls).
+  // `@decocms/blocks` background work (release checks, telemetry batches)
+  // queued during a request runs after its response, inside ctx.waitUntil.
+  installBackgroundHook();
+  // Next major: upstream GETs made with createInstrumentedFetch are cached
+  // with the Cache API (see ../v8/binding.ts).
+  installUpstreamCache();
+  const respond = handler.fetch;
+  handler.fetch = async (request, env, ctx) => {
+    try {
+      return await respond(request, env, ctx);
+    } finally {
+      runBackgroundTasks(ctx);
+    }
+  };
+
   return observabilityOpt === false
     ? handler
     : instrumentWorker(handler, (observabilityOpt as OtelOptions | undefined) ?? {});

package/src/v8/__conformance__/delivery.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment node
+/**
+ * Docs conformance, Workers binding: hosted.mdx ("Release checks on Workers
+ * run after the response, inside ctx.waitUntil, on their own"),
+ * hosted-releases-internals.mdx (idle scheduling on Workers) and
+ * hosted-publishing.mdx ("Large content on Workers": kvLoader as `content`).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createCMS, resetForTests } from "@decocms/blocks";
+import { computeContentRevision } from "@decocms/blocks/protocol";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { kvLoader } from "../kvLoader";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const WORKSPACE = path.resolve(HERE, "../../../../..");
+const ORIGIN = "https://delivery.decocms.com";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+  resetForTests();
+});
+
+const seo = (props: { title: string; description: string }) => props;
+
+describe("hosted-publishing: large content on Workers", () => {
+  it("HP-14: kvLoader as content; a missing key fails reads until the first release check", async () => {
+    const blocks = { SummerSEO: { __resolveType: "seo", title: "Released", description: "d" } };
+    const revision = await computeContentRevision(blocks);
+    const asset = `/sites/acme/revisions/${revision}.json`;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async (input: string | URL | Request) => {
+        const url = String(input);
+        if (url === `${ORIGIN}/sites/acme/channels/production.json`) {
+          return Response.json({ format: 1, generation: 1, revision, snapshot: asset });
+        }
+        if (url === `${ORIGIN}${asset}`) return Response.json({ revision, blocks });
+        return new Response("not found", { status: 404 });
+      }),
+    );
+    const namespace = { get: vi.fn(async () => null) }; // the deploy didn't write the key
+    const cms = createCMS({
+      blocks: { seo },
+      content: kvLoader(namespace, { key: "decofile:abc" }),
+      site: "acme",
+      token: "t",
+    });
+    const [, error] = await cms.forRelease().resolve("SummerSEO");
+    expect(error?.code).toBe("LOADER_FAILED");
+    expect(await cms.update()).toEqual({ updated: true });
+    const [value, after] = await cms.forRelease().resolve<{ title: string }>("SummerSEO");
+    expect(after).toBeNull();
+    expect(value?.title).toBe("Released");
+  });
+});
+
+describe("hosted: release checks on Workers", () => {
+  it("H-10/HRI-4: the documented Workers setup runs due checks inside ctx.waitUntil, with no user code", () => {
+    // The documented TanStack Start setup (tanstack-start-descriptors.mdx,
+    // examples/tanstack-smoke) runs Start's own server entry:
+    const wrangler = fs.readFileSync(
+      path.join(WORKSPACE, "examples/tanstack-smoke/wrangler.jsonc"),
+      "utf8",
+    );
+    expect(wrangler).toContain('"main": "@tanstack/react-start/server-entry"');
+    // So something in the next-major surface (core or binding) must route the
+    // core's background work into ctx.waitUntil on its own: install the
+    // `Symbol.for("decocms.blocks.background")` hook, or use Workers'
+    // `waitUntil` from "cloudflare:workers". Today only the v7
+    // `createDecoWorkerEntry` (sdk/workerEntry.ts) installs that hook, and the
+    // documented setup never runs it, so checks fall back to a timer.
+    const roots = [
+      path.join(WORKSPACE, "packages/blocks/src/v8"),
+      path.join(WORKSPACE, "packages/tanstack/src/v8"),
+    ];
+    const installers: string[] = [];
+    const walk = (dir: string) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (entry.name !== "__conformance__") walk(full);
+        } else if (/\.tsx?$/.test(entry.name) && !/\.test\.tsx?$/.test(entry.name)) {
+          const text = fs.readFileSync(full, "utf8");
+          if (
+            /installBackgroundHook|from "cloudflare:workers"|\[(BACKGROUND_HOOK|HOOK)\]\s*=(?!=)/.test(
+              text,
+            )
+          ) {
+            installers.push(path.relative(WORKSPACE, full));
+          }
+        }
+      }
+    };
+    for (const dir of roots) walk(dir);
+    expect(installers).not.toEqual([]);
+  });
+});

package/src/v8/binding.ts

@@ -0,0 +1,70 @@
+/**
+ * What `@decocms/tanstack` adds to a next-major site on Cloudflare Workers
+ * (see /next/caching#upstream-data): GETs made through
+ * `createInstrumentedFetch` are served from the Cloudflare Cache API,
+ * honouring the upstream's `cache-control`, and bypass it while a draft is
+ * rendered. Hits carry the instrumented fetch's `cached=true` label.
+ *
+ * It reaches the core through a `Symbol.for` hook on `globalThis`
+ * (`decocms.blocks.upstreamCache`; the core imports nothing from a binding).
+ * Nothing here is exported from the package; the worker entry calls it.
+ */
+import { draftPointer } from "@decocms/blocks";
+// The worker entry runs every request inside RequestContext, whose storage
+// resolves to a no-op stub in browser bundles (this module is reachable from
+// the package root, which client code imports).
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+
+const UPSTREAM_CACHE = Symbol.for("decocms.blocks.upstreamCache");
+
+/** Whether the request being served renders a draft (then upstream caching is off). */
+function renderingDraft(): boolean {
+  try {
+    return draftPointer(RequestContext.request) !== null;
+  } catch {
+    return false; // outside a request
+  }
+}
+
+/** Whether a response may be kept in a shared cache, per its `cache-control`. */
+function cacheable(response: Response): boolean {
+  if (response.status !== 200) return false;
+  const control = response.headers.get("cache-control")?.toLowerCase() ?? "";
+  if (/\b(no-store|no-cache|private)\b/.test(control)) return false;
+  return /\b(s-maxage|max-age)=[1-9]/.test(control);
+}
+
+/**
+ * Installs the upstream cache (idempotent). Requests that carry a user's
+ * credentials (`authorization`, `cookie`) are never cached, and nothing is
+ * read or written while a draft is rendered.
+ */
+export function installUpstreamCache(): void {
+  const g = globalThis as Record<symbol, unknown>;
+  if (typeof g[UPSTREAM_CACHE] === "function") return;
+  g[UPSTREAM_CACHE] = async (
+    input: string | URL | Request,
+    init: RequestInit,
+    fetch: typeof globalThis.fetch,
+  ): Promise<{ response: Response; cached: boolean }> => {
+    const cache = (globalThis as { caches?: { default?: Cache } }).caches?.default;
+    const request = new Request(input, init);
+    if (
+      cache === undefined ||
+      renderingDraft() ||
+      request.headers.has("authorization") ||
+      request.headers.has("cookie")
+    ) {
+      return { response: await fetch(input, init), cached: false };
+    }
+    const hit = await cache.match(request.url).catch(() => undefined);
+    if (hit) return { response: hit, cached: true };
+    const response = await fetch(input, init);
+    if (cacheable(response)) {
+      // Awaited: the Cache API is local to the data center, and the next
+      // request for the same URL should already find it.
+      await cache.put(request.url, response.clone()).catch(() => {});
+    }
+    return { response, cached: false };
+  };
+}

package/src/v8/kvLoader.bundle.test.ts

@@ -0,0 +1,42 @@
+import { execFileSync } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const here = dirname(fileURLToPath(import.meta.url));
+// The esbuild CLI, not its JS API: the API breaks across Vitest's realm
+// boundary (see packages/blocks/src/cms/client.browserBundle.test.ts).
+const esbuildBin = join(here, "../../../../node_modules/.bin/esbuild");
+
+/**
+ * The docs import `kvLoader` from the package root, which still re-exports
+ * the v7 binding. `"sideEffects"` in package.json lets a bundler drop every
+ * root module the site doesn't use; without it the Worker ships the v7
+ * runtime (react-dom/server, Start server-core, OpenTelemetry...).
+ */
+describe("kvLoader bundle", () => {
+  it("imports from the package root without pulling in the v7 binding", () => {
+    const output = execFileSync(
+      esbuildBin,
+      [
+        "--bundle",
+        "--format=esm",
+        "--platform=neutral",
+        "--minify",
+        "--main-fields=module,main",
+        "--external:react",
+        "--external:react-dom",
+        "--external:@tanstack/*",
+        "--external:node:*",
+        "--log-level=error",
+      ],
+      {
+        cwd: join(here, "../.."),
+        input: 'export { kvLoader } from "@decocms/tanstack";',
+        encoding: "utf-8",
+      },
+    );
+    expect(output).toContain("kvLoader");
+    expect(output.length).toBeLessThan(2048);
+  });
+});

package/src/v8/kvLoader.test.ts

@@ -0,0 +1,74 @@
+import { createCMS, resetForTests, type Snapshot } from "@decocms/blocks";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { kvLoader } from "./kvLoader";
+
+const snapshot: Snapshot = {
+  revision: "r1",
+  blocks: { Hello: { __resolveType: "greeting", name: "world" } },
+};
+
+function kv(values: Record<string, unknown>) {
+  return { get: vi.fn(async (key: string, _type: "json") => values[key] ?? null) };
+}
+
+afterEach(() => resetForTests());
+
+describe("kvLoader", () => {
+  it("reads the snapshot under its key once per isolate", async () => {
+    const namespace = kv({ "decofile:abc": snapshot });
+    const loader = kvLoader(namespace, { key: "decofile:abc" });
+    expect(await loader.load()).toEqual(snapshot);
+    expect(await loader.load("api.deco.example/drafts/x@v1")).toEqual(snapshot);
+    expect(namespace.get).toHaveBeenCalledTimes(1);
+    expect(namespace.get).toHaveBeenCalledWith("decofile:abc", "json");
+    expect(loader.update).toBeUndefined();
+  });
+
+  it("shares one in-flight read between concurrent loads", async () => {
+    let release!: (value: unknown) => void;
+    const namespace = { get: vi.fn(() => new Promise((resolve) => (release = resolve))) };
+    const loader = kvLoader(namespace, { key: "content" });
+    const first = loader.load();
+    const second = loader.load();
+    release(snapshot);
+    expect(await first).toEqual(snapshot);
+    expect(await second).toEqual(snapshot);
+    expect(namespace.get).toHaveBeenCalledTimes(1);
+  });
+
+  it("fails on a missing key and reads KV again on the next call", async () => {
+    const values: Record<string, unknown> = {};
+    const namespace = kv(values);
+    const loader = kvLoader(namespace, { key: "decofile:abc" });
+    await expect(loader.load()).rejects.toThrow(/decofile:abc/);
+    values["decofile:abc"] = snapshot;
+    expect(await loader.load()).toEqual(snapshot);
+    expect(namespace.get).toHaveBeenCalledTimes(2);
+  });
+
+  it("serves a CMS without reading KV per request", async () => {
+    const namespace = kv({ content: snapshot });
+    const cms = createCMS({
+      blocks: { greeting: (input: { name: string }) => `Hello, ${input.name}` },
+      content: kvLoader(namespace, { key: "content" }),
+    });
+    expect(await cms.forRelease().resolve("Hello")).toEqual(["Hello, world", null]);
+    expect(await cms.forRelease().resolve("Hello")).toEqual(["Hello, world", null]);
+    expect(namespace.get).toHaveBeenCalledTimes(1);
+  });
+
+  it("surfaces a missing key as LOADER_FAILED", async () => {
+    const cms = createCMS({ blocks: {}, content: kvLoader(kv({}), { key: "content" }) });
+    const [, error] = await cms.forRelease().list("page");
+    expect(error?.code).toBe("LOADER_FAILED");
+  });
+
+  it("surfaces a value that isn't a snapshot as LOADER_FAILED", async () => {
+    const cms = createCMS({
+      blocks: {},
+      content: kvLoader(kv({ content: {} }), { key: "content" }),
+    });
+    const [, error] = await cms.forRelease().list("page");
+    expect(error?.code).toBe("LOADER_FAILED");
+  });
+});

package/src/v8/kvLoader.ts

@@ -0,0 +1,43 @@
+/**
+ * `kvLoader(namespace, { key })`: the content snapshot your deploy stored in a
+ * Workers KV namespace, for sites whose content is too large to bundle. See
+ * /next/api-reference#loaders and /next/hosted-publishing#large-content-on-workers.
+ */
+import type { Loader, Snapshot } from "@decocms/blocks";
+
+/** The one KV method this loader calls; a Workers `KVNamespace` binding fits it. */
+export interface KVNamespaceLike {
+  get(key: string, type: "json"): Promise<unknown>;
+}
+
+/**
+ * Reads the snapshot under `key` once per isolate and keeps it. It ignores
+ * draft pointers and has no `update()`: the deploy writes the key before the
+ * Worker takes traffic, and it doesn't change while the Worker runs. A missing
+ * key or a failed read isn't kept, so the next request reads KV again.
+ *
+ * The kept read is a promise shared across requests, so the Worker needs the
+ * `no_handle_cross_request_promise_resolution` compatibility flag, as the CMS
+ * itself does (see /next/tanstack-start-descriptors).
+ */
+export function kvLoader(namespace: KVNamespaceLike, options: { key: string }): Loader {
+  const { key } = options;
+  let snapshot: Promise<Snapshot> | undefined;
+  return {
+    load() {
+      if (snapshot === undefined) {
+        const pending = namespace.get(key, "json").then((value) => {
+          if (value === null || value === undefined) {
+            throw new Error(`kvLoader: no content snapshot under the KV key "${key}"`);
+          }
+          return value as Snapshot;
+        });
+        snapshot = pending;
+        pending.catch(() => {
+          if (snapshot === pending) snapshot = undefined;
+        });
+      }
+      return snapshot;
+    },
+  };
+}