@decocms/tanstack 8.0.0 → 8.1.0-next.0

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;
+    },
+  };
+}

package/src/vite/plugin.js

@@ -84,6 +84,12 @@ function resolveBuildHash() {
   return Date.now().toString(36);
 }
 
+// Virtual id for meta.gen.json on the server: the real path wrapped so the id
+// does NOT end in `.json` (Vite's `vite:json` would re-parse our JS output).
+const META_GEN_PREFIX = "\0deco-meta:";
+const META_GEN_SUFFIX = ".deco-meta.js";
+const metaGenSsrId = (file) => META_GEN_PREFIX + file + META_GEN_SUFFIX;
+
 // Bare-specifier stubs resolved by ID before Vite touches them.
 /** @type {Record<string, string>} */
 const CLIENT_STUBS = {
@@ -154,8 +160,78 @@ const STUB_SOURCE = {
   "\0stub:bare-fs": "export const promises = {}; export default { promises };",
 };
 
-/** @returns {import("vite").PluginOption} */
-export function decoVitePlugin() {
+/**
+ * Argv (after the generate-schema.ts script path) for a meta.gen.json run.
+ *
+ * generate-schema ALWAYS composes before writing, so the emitted meta.gen.json
+ * carries every framework `website/*` block (Page, matchers, __SECTION_REF__,
+ * Resolvable). This matters because meta.gen.json is committed and Studio reads
+ * it as-is (no composeMeta at read time) — an uncomposed rewrite would silently
+ * break the admin editors, e.g. the date matcher powering variant rules
+ * disappearing (a production storefront regression). Mirrors `npm run generate`'s schema
+ * step. Both invocation sites in configureServer derive their args here so they
+ * can never drift apart.
+ *
+ * @param {string} siteName
+ * @returns {string[]}
+ */
+export function generateSchemaArgs(siteName) {
+  return ["--site", siteName];
+}
+
+/**
+ * Env var a deploy pipeline sets to declare "I seed `decofile:<deployment-id>`
+ * into KV BEFORE activating this version". Set by the cfworkers-builder under
+ * exactly the condition that guards its seed step, so the stub below and the
+ * seed can never drift apart.
+ */
+const SEEDED_DEPLOY_ENV = "DECO_SEEDED_DEPLOY";
+
+/** Whether this build runs inside a pipeline that seeds KV before activation. */
+function isSeededDeployPipeline() {
+  const v = process.env[SEEDED_DEPLOY_ENV];
+  return v === "1" || v === "true";
+}
+
+/**
+ * @param {object} [opts]
+ * @param {boolean | "auto"} [opts.fastDeploy="auto"] Stub `blocks.gen` out of
+ *   the SERVER bundle too, so the worker's only copy of the decofile is the one
+ *   hydrated from KV at cold start.
+ *
+ *   Without this, a fast-deploy site holds the decofile TWICE: the bundled
+ *   `JSON.parse(...)` graph stays permanently reachable through the site's
+ *   `import { blocks } from ".deco/blocks.gen"` module binding, and
+ *   `ensureBlocksHydrated` adds a second graph via `setBlocks()`. For a 10MB
+ *   decofile that is tens of MB of avoidable isolate memory, on a platform
+ *   whose per-isolate cap is 128MB and has no GC knob.
+ *
+ *   It is gated because it removes the fallback: with no bundled snapshot, a
+ *   cold start that cannot read KV has no content to serve, and
+ *   `ensureBlocksHydrated` fails the request loudly (5xx) rather than serving
+ *   an empty site that the edge would then cache — see `kvHydration.ts`. That
+ *   is only safe when the deploy pipeline seeds `decofile:<deployment-id>`
+ *   BEFORE the new version activates.
+ *
+ *   `"auto"` (default) stubs only when the pipeline declares it seeds, via
+ *   `DECO_SEEDED_DEPLOY`. A site building through Cloudflare Workers Builds or
+ *   a manual `wrangler deploy` never sets it, so it keeps the bundled snapshot
+ *   and behaves exactly as before — no site-side config, no way to half-enable
+ *   it. `true` forces the stub, `false` disables it. A stubbed bundle also
+ *   needs `DECO_FAST_DEPLOY=1` and a `DECO_KV` binding at runtime — without
+ *   them `ensureBlocksHydrated` fails every request rather than serve `{}`.
+ * @returns {import("vite").PluginOption}
+ */
+export function decoVitePlugin({ fastDeploy = "auto" } = {}) {
+  // Resolved once: the pipeline's answer cannot change mid-build.
+  const stubBlocks = fastDeploy === "auto" ? isSeededDeployPipeline() : fastDeploy === true;
+  // Set from the `config` hook (which Vite always runs before `load`). The
+  // fastDeploy stub must apply to production builds ONLY: `vite dev` has no KV
+  // to hydrate from, and the dev bootstrap below deliberately relies on reading
+  // the `.json` sibling that the stub bypasses — stubbing there blanks the
+  // local site.
+  let isBuild = false;
+
   /** @type {import("vite").Plugin} */
   const plugin = {
     name: "deco-server-only-stubs",
@@ -165,6 +241,32 @@ export function decoVitePlugin() {
       // SSR-only stubs — must be checked first since the client guard below
       // returns undefined for everything that hasn't matched yet on SSR.
       if (options?.ssr && SSR_STUBS[id]) return SSR_STUBS[id];
+      // meta.gen.json on the SERVER → a virtual id that does NOT end in
+      // `.json`. `load` below emits JS (`JSON.parse("...")`), and Vite's
+      // `vite:json` transform runs on every id matching `\.json$` regardless
+      // of who loaded it — it would try to JSON.parse that JS and fail the
+      // build ("Failed to parse JSON file").
+      if (options?.ssr && importer && id.endsWith("meta.gen.json")) {
+        if (id.startsWith(".") || path.isAbsolute(id)) {
+          const file = path.resolve(path.dirname(importer), id);
+          if (existsSync(file)) return metaGenSsrId(file);
+          // Absent (pre-generate-schema) — let Vite report it normally.
+          return undefined;
+        }
+        // Alias / bare specifier (`~/.deco/meta.gen.json`, tsconfig paths…):
+        // let the rest of the pipeline resolve it, then wrap — otherwise it
+        // falls through to vite:json and loses the JSON.parse optimization.
+        if (typeof this?.resolve === "function") {
+          return this.resolve(id, importer, { ...options, skipSelf: true }).then(
+            (r) =>
+              r && !r.external && r.id.endsWith("meta.gen.json") && existsSync(r.id)
+                ? metaGenSsrId(r.id)
+                : undefined,
+            // A resolver in the chain threw — let Vite's normal resolution report it.
+            () => undefined,
+          );
+        }
+      }
       // Server builds keep the real modules.
       if (options?.ssr) return undefined;
       // Bare-specifier exact-match stubs (react-dom/server, node:stream, etc.).
@@ -188,6 +290,16 @@ export function decoVitePlugin() {
           return "export const blocks = {};";
         }
 
+        // Fast-deploy: stub on the SERVER too. The worker hydrates the decofile
+        // from KV at cold start, so shipping it in the bundle would just pin a
+        // second, permanently-reachable copy in isolate memory (the site's
+        // `import { blocks }` binding keeps the bundled graph alive for the
+        // isolate's whole life, even after `setBlocks()` swaps in the KV one).
+        // Build only — see `isBuild` above.
+        if (stubBlocks && isBuild) {
+          return "export const blocks = {};";
+        }
+
         // SSR: read .json sibling and emit JSON.parse(...) wrapper.
         // This avoids the Vite SSR module runner hanging on large dynamic
         // imports and lets V8 use its fast JSON parser (~2-10x vs object literal).
@@ -202,6 +314,26 @@ export function decoVitePlugin() {
         // backward-compatible sites that haven't regenerated).
       }
 
+      // meta.gen.json — the admin JSON Schema bundle, on the SERVER.
+      //
+      // Vite's JSON plugin would turn it into an object literal, which V8 must
+      // run through the full JS parser. Emitting `JSON.parse("...")` instead
+      // (same treatment blocks.gen gets, and the same reason) uses V8's fast
+      // JSON parser and — the part that matters for memory — keeps the schema
+      // as ONE string until something actually calls the parse. Since
+      // `createAdminSetup` now only invokes its loader on the first
+      // `/live/_meta`, an isolate that never serves the admin never
+      // materializes the object graph at all.
+      //
+      // The client is stubbed in `resolveId` above and never reaches here.
+      if (id.startsWith(META_GEN_PREFIX) && id.endsWith(META_GEN_SUFFIX)) {
+        const file = id.slice(META_GEN_PREFIX.length, -META_GEN_SUFFIX.length);
+        // Virtual id → Vite won't watch the file on its own.
+        this.addWatchFile?.(file);
+        const raw = readFileSync(file, "utf-8");
+        return `export default JSON.parse(${JSON.stringify(raw)});`;
+      }
+
       // loaders.gen.ts — the site's invoke registry (`export const siteLoaders`).
       // It registers every site loader/action behind a dynamic `import()`, so if
       // it stays in the CLIENT module graph (it's reachable via
@@ -454,6 +586,8 @@ export function decoVitePlugin() {
       // re-run generate-schema.ts so meta.gen.json stays in sync during dev.
       // No --out is passed to the generator below, so it writes to its own
       // default (.deco/meta.gen.json) — this constant must track that default.
+      // Both invocations get their args from generateSchemaArgs() so they can't
+      // drift apart (see its doc comment).
       const schemaWatchDirs = ["src"];
       const schemaOutFile = path.resolve(cwd, ".deco/meta.gen.json");
 
@@ -477,7 +611,7 @@ export function decoVitePlugin() {
           cwd,
           "node_modules/@decocms/blocks-cli/scripts/generate-schema.ts",
         );
-        const cmd = `npx tsx ${JSON.stringify(scriptPath)} --site ${schemaSiteName}`;
+        const cmd = `npx tsx ${JSON.stringify(scriptPath)} ${generateSchemaArgs(schemaSiteName).join(" ")}`;
         exec(cmd, { cwd }, (err) => {
             schemaInFlight = false;
             if (err) {
@@ -486,7 +620,7 @@ export function decoVitePlugin() {
               console.log(`[deco] meta.gen.json updated (${Date.now() - start}ms)`);
               // Invalidate the meta.gen.json module so SSR picks up fresh schema
               const mod =
-                server.environments?.ssr?.moduleGraph?.getModuleById(schemaOutFile);
+                server.environments?.ssr?.moduleGraph?.getModuleById(metaGenSsrId(schemaOutFile));
               if (mod) {
                 server.environments.ssr.moduleGraph.invalidateModule(mod);
               }
@@ -526,7 +660,7 @@ export function decoVitePlugin() {
             cwd,
             "node_modules/@decocms/blocks-cli/scripts/generate-schema.ts",
           );
-          execFileSync("npx", ["tsx", scriptPath, "--site", schemaSiteName], {
+          execFileSync("npx", ["tsx", scriptPath, ...generateSchemaArgs(schemaSiteName)], {
             cwd,
             stdio: "inherit",
           });
@@ -666,13 +800,43 @@ export function decoVitePlugin() {
     },
 
     config(_cfg, { command }) {
+      // Gate the fastDeploy SSR stub in `load()` to production builds.
+      isBuild = command === "build";
+
       /** @type {import("vite").UserConfig} */
       const cfg = {};
 
+      // Supply a default TanStack Start entry when the site has none.
+      //
+      // `#tanstack-start-entry` is a subpath import of
+      // @tanstack/start-client-core; with no `src/start.ts` it resolves to a
+      // fake entry exporting `startInstance = undefined`, and the site gets no
+      // `serverFns.fetch` hook. That hook is what appends the cache segment to
+      // `/_serverFn` URLs (see sdk/cdnSegment), so without it CDN caching of
+      // SPA navigation can never engage.
+      //
+      // Aliasing it here means a site gets that from a version bump instead of
+      // a per-site PR. Strictly conditional on the file being absent: a site
+      // that owns its `src/start.ts` must keep it, since ours would otherwise
+      // silently replace whatever else it configures.
+      const siteStartEntry = ["ts", "tsx", "js", "jsx"]
+        .map((ext) => path.join(process.cwd(), "src", `start.${ext}`))
+        .find((f) => existsSync(f));
+
+      if (!siteStartEntry) {
+        cfg.resolve = {
+          ...cfg.resolve,
+          alias: {
+            ...cfg.resolve?.alias,
+            "#tanstack-start-entry": "@decocms/tanstack/sdk/startEntry",
+          },
+        };
+      }
+
       // Allow tunnel domains through Vite's host check.
-      // .deco.studio is the new admin frontend; both real-world Deco sites
-      // (casaevideo-storefront, baggagio-tanstack) duplicated this list to
-      // include it — bundling it here removes that boilerplate.
+      // .deco.studio is the new admin frontend; multiple real-world Deco sites
+      // duplicated this list to include it — bundling it here removes that
+      // boilerplate.
       if (process.env.DECO_SITE_NAME) {
         cfg.server = {
           allowedHosts: [".deco.host", ".decocdn.com", ".deco.studio"],
@@ -691,6 +855,14 @@ export function decoVitePlugin() {
       cfg.define = {
         ...cfg.define,
         __DECO_BUILD_HASH__: JSON.stringify(buildHash),
+        // Tells the runtime whether this bundle actually ships a decofile.
+        // `ensureBlocksHydrated` needs a build-time answer: with no bundled
+        // snapshot, its "warn and serve bundled" recovery would serve an EMPTY
+        // site with 200s. Inferring it from an empty in-memory map at runtime
+        // is not equivalent — draft-preview overrides can make a stubbed bundle
+        // look populated, and a legitimately-empty decofile (new site) would
+        // look stubbed.
+        __DECO_BLOCKS_STUBBED__: JSON.stringify(stubBlocks && command === "build"),
       };
 
       // Only split chunks for production builds — dev uses unbundled ESM.