@decocms/tanstack 8.0.0 → 8.1.0-next.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/tanstack",
-  "version": "8.0.0",
+  "version": "8.1.0-next.0",
   "type": "module",
   "description": "Deco framework binding for TanStack Start + Cloudflare Workers",
   "repository": {
@@ -9,13 +9,20 @@
     "directory": "packages/tanstack"
   },
   "main": "./src/index.ts",
+  "sideEffects": [
+    "./src/vite/**",
+    "./src/daemon/**"
+  ],
   "exports": {
     ".": "./src/index.ts",
     "./vite": "./src/vite/plugin.js",
     "./daemon": "./src/daemon/index.ts",
     "./sdk/createInvoke": "./src/sdk/createInvoke.ts",
     "./sdk/cookiePassthrough": "./src/sdk/cookiePassthrough.ts",
-    "./sdk/deferredSectionLoader": "./src/sdk/deferredSectionLoader.ts"
+    "./sdk/deferredSectionLoader": "./src/sdk/deferredSectionLoader.ts",
+    "./sdk/serverFnFetch": "./src/sdk/serverFnFetch.ts",
+    "./sdk/startEntry": "./src/sdk/startEntry.ts",
+    "./sdk/cdnSegment": "./src/sdk/cdnSegment.ts"
   },
   "scripts": {
     "build": "tsc",
@@ -24,9 +31,9 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "8.0.0",
-    "@decocms/blocks-admin": "8.0.0",
-    "@decocms/blocks-cli": "8.0.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/hooks/CdnSegmentMarker.tsx

@@ -0,0 +1,38 @@
+/**
+ * Publishes the CDN segment token this server computed, so `decoServerFnFetch`
+ * can echo it back on `/_serverFn` URLs.
+ *
+ * Only the server can produce this value: the segment includes dimensions the
+ * browser cannot observe — region is resolved from `request.cf.regionCode`.
+ * A client that derives its own token therefore never matches on a
+ * regionalized store, which is exactly why this component exists.
+ *
+ *  - **Server:** read the token from the RequestContext bag (filled by
+ *    `createDecoWorkerEntry`) and emit a tiny inline `<script>`.
+ *  - **Client:** the bag is a no-op stub, so the read yields undefined and this
+ *    renders nothing — the global set during SSR is already on `window`.
+ *
+ * Safe in a cached response: the Worker's edge cache keys on the segment, so a
+ * stored entry carries the token of its own segment. And a stale token is
+ * harmless by construction — the Worker verifies by recomputing and falls back
+ * to `no-store` when it doesn't match.
+ */
+
+import { getRequestNonce } from "@decocms/blocks/sdk/nonce";
+import { RequestContext } from "@decocms/blocks/sdk/requestContext";
+import { CSEG_BAG_KEY, CSEG_GLOBAL } from "../sdk/cdnSegment";
+
+export function CdnSegmentMarker() {
+  const token = RequestContext.getBag<string>(CSEG_BAG_KEY);
+  if (!token) return null;
+  return (
+    <script
+      nonce={getRequestNonce()}
+      // A hash this server computed, not user input. JSON.stringify keeps it
+      // inert regardless.
+      dangerouslySetInnerHTML={{
+        __html: `window.${CSEG_GLOBAL}=${JSON.stringify(token)}`,
+      }}
+    />
+  );
+}

package/src/hooks/DecoPageRenderer.tsx

@@ -11,6 +11,7 @@ import {
 import { Await, ClientOnly } from "@tanstack/react-router";
 import type { SectionOptions } from "@decocms/blocks/cms/client";
 import {
+  getDeferredTrigger,
   getResolvedComponent,
   getSectionOptions,
   getSectionRegistry,
@@ -307,9 +308,9 @@ function DeferredSectionWrapper({
     const el = ref.current;
     if (!el) return;
 
-    if (typeof IntersectionObserver === "undefined") {
+    const key = stableKey;
+    const load = () => {
       triggered.current = true;
-      const key0 = stableKey;
       loadFn({
         component: deferred.component,
         pagePath,
@@ -317,37 +318,72 @@ function DeferredSectionWrapper({
         index: deferred.index,
       })
         .then((result) => {
-          if (result) deferredSectionCache.set(key0, { section: result, ts: Date.now() });
+          if (result) deferredSectionCache.set(key, { section: result, ts: Date.now() });
           setSection(result);
         })
         .catch((e) => setError(e));
+    };
+
+    // `"load"` — dispatch on mount, no scroll needed.
+    //
+    // This is what Deco on Fresh does: `DispatchAsyncRender` with
+    // `partialTriggerMode: "load"` clicks the hidden partial trigger as soon as
+    // the island hydrates, so a page ships a light skeleton HTML and then fills
+    // in every deferred section about half a second later. Sites migrating from
+    // Fresh need it for parity — under `"intersection"` alone, everything below
+    // the fold does not exist until the user scrolls: the document stays short
+    // and below-the-fold analytics impressions never fire.
+    //
+    // Opt-in per site via `setAsyncRenderingConfig({ deferredTrigger: "load" })`;
+    // the default stays `"intersection"`, so a framework bump changes nothing.
+    if (getDeferredTrigger() === "load" || typeof IntersectionObserver === "undefined") {
+      load();
       return;
     }
 
-    const observer = new IntersectionObserver(
-      ([entry]) => {
-        if (entry?.isIntersecting && !triggered.current) {
-          triggered.current = true;
-          observer.disconnect();
-          const key1 = stableKey;
-          loadFn({
-            component: deferred.component,
-            pagePath,
-            pageUrl,
-            index: deferred.index,
-          })
-            .then((result) => {
-              if (result) deferredSectionCache.set(key1, { section: result, ts: Date.now() });
-              setSection(result);
-            })
-            .catch((e) => setError(e));
-        }
-      },
-      { rootMargin: "300px" },
-    );
-
-    observer.observe(el);
-    return () => observer.disconnect();
+    let observer: IntersectionObserver | undefined;
+    const startObserving = () => {
+      if (triggered.current) return;
+      observer = new IntersectionObserver(
+        ([entry]) => {
+          if (entry?.isIntersecting && !triggered.current) {
+            observer?.disconnect();
+            load();
+          }
+        },
+        { rootMargin: "300px" },
+      );
+      observer.observe(el);
+    };
+
+    // Wait one frame before observing, so the router's scroll reset lands first.
+    //
+    // On a client (SPA) navigation the scroll position is still wherever the
+    // user left the PREVIOUS page when this effect runs. TanStack resets it from
+    // the `onRendered` event, which is emitted in a `useLayoutEffect`
+    // (react-router's `OnRendered`) that depends on the `resolvedLocation` store
+    // — and that store is written from ANOTHER `useLayoutEffect` (Transitioner).
+    // So the reset necessarily lands one commit after the one that mounts these
+    // skeletons, and React flushes this commit's passive effects before starting
+    // that follow-up render. Verified ordering: observe → scroll reset.
+    //
+    // Observing synchronously therefore evaluates intersection against the stale
+    // scroll offset: a user navigating from the bottom of a long page has every
+    // skeleton "in view" at once, so every deferred section fires its serverFn
+    // POST simultaneously on commit — the exact thundering herd deferral exists
+    // to avoid. One frame is enough to let the reset apply.
+    //
+    // `triggered` is re-checked inside, so a section that resolved from cache in
+    // the meantime never starts an observer.
+    if (typeof requestAnimationFrame === "undefined") {
+      startObserving();
+      return () => observer?.disconnect();
+    }
+    const raf = requestAnimationFrame(startObserving);
+    return () => {
+      cancelAnimationFrame(raf);
+      observer?.disconnect();
+    };
   }, [deferred.component, deferred.index, deferred.propsHash, pagePath, pageUrl, section, loadFn]);
 
   if (error) {
@@ -406,9 +442,22 @@ function DeferredSectionWrapper({
     .replace(/\.tsx$/, "")
     .replace(/^site-sections-/, "");
 
+  // Wrap in the same SectionErrorBoundary the resolved branches use above.
+  // Without this, the child at this position goes straight from `skeleton`
+  // to `<SectionErrorBoundary>...</SectionErrorBoundary>` once `section` is
+  // set — a type change React can't reconcile, forcing a full unmount of
+  // the skeleton subtree and mount of the resolved subtree even when the
+  // section's own LoadingFallback renders the real component with reduced
+  // props (a documented convention — see Footer.tsx/ETCImageContent.tsx in
+  // a production storefront migration's T64). That unmount/remount is what
+  // produces a hard rect-collapse-to-{0,0,0,0} layout-shift entry instead
+  // of an ordinary prop-driven resize. Keeping the wrapper identical across
+  // both branches lets React diff by type at the child position instead.
   return (
     <section ref={ref} id={sectionId} data-manifest-key={deferred.key} data-deferred="true">
-      {skeleton}
+      <SectionErrorBoundary sectionKey={deferred.key} fallback={errorFallback}>
+        {skeleton}
+      </SectionErrorBoundary>
     </section>
   );
 }
@@ -482,6 +531,11 @@ interface Props {
    * Unawaited promises for deferred sections, keyed by `d_<index>`.
    * Created by the route loader for TanStack native SSR streaming.
    * When provided, takes precedence over `loadDeferredSectionFn`.
+   *
+   * SSR-ONLY: promises cannot cross the server-fn JSON boundary, so a client
+   * (SPA) navigation never receives them. Any site that defers sections needs
+   * `loadDeferredSectionFn` wired regardless — it is the only path that works
+   * for both SSR and client nav.
    */
   deferredPromises?: Record<string, Promise<ResolvedSection | null>>;
   pagePath?: string;
@@ -496,7 +550,15 @@ interface Props {
   device?: Device;
   loadingFallback?: ReactNode;
   errorFallback?: ReactNode;
-  /** @deprecated Use deferredPromises instead (TanStack native streaming). */
+  /**
+   * IntersectionObserver-driven loader for deferred sections — wire this to
+   * `deferredSectionLoader` from `@decocms/tanstack`.
+   *
+   * NOT deprecated: `deferredPromises` only covers SSR (promises can't be
+   * serialized through a server fn), so this is the only deferred-resolution
+   * path available on a client (SPA) navigation. Without it, deferred sections
+   * on a SPA transition render a skeleton that never resolves.
+   */
   loadDeferredSectionFn?: (data: {
     component: string;
     rawProps?: Record<string, unknown>;