@decocms/blocks-cli 7.12.1 → 7.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/blocks-cli",
-  "version": "7.12.1",
+  "version": "7.15.0",
   "type": "module",
   "description": "Deco codegen (generate-blocks, generate-schema, generate-invoke) and Fresh-to-TanStack migration tooling",
   "repository": {
@@ -30,7 +30,7 @@
     "lint:unused": "knip"
   },
   "dependencies": {
-    "@decocms/blocks": "7.12.1",
+    "@decocms/blocks": "7.15.0",
     "ts-morph": "^27.0.0",
     "tsx": "^4.22.5"
   },

package/scripts/generate-loaders.test.ts

@@ -0,0 +1,64 @@
+/**
+ * Verifies the generated `.deco/loaders.gen.ts` shape: loaders route through
+ * `createLoaderEntry` (so their cache/cacheKey exports drive dedup) while
+ * actions stay plain pass-throughs (never cached/deduped).
+ *
+ * The script is spawned as a subprocess (`npx tsx generate-loaders.ts`) exactly
+ * how sites invoke it.
+ */
+import * as cp from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+const SCRIPT = path.resolve(__dirname, "generate-loaders.ts");
+
+function run(cwd: string): { stdout: string; stderr: string; code: number } {
+  const r = cp.spawnSync("npx", ["tsx", SCRIPT], { encoding: "utf8", cwd });
+  return { stdout: r.stdout || "", stderr: r.stderr || "", code: r.status ?? -1 };
+}
+
+describe("generate-loaders — loader vs action emit", () => {
+  let dir: string;
+  let out: string;
+
+  beforeAll(() => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-loaders-"));
+    const write = (rel: string, content: string) => {
+      const abs = path.join(dir, rel);
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content);
+    };
+    write("src/loaders/related.ts", "export default async () => [];\n");
+    write("src/actions/addToCart.ts", "export default async () => ({});\n");
+
+    const r = run(dir);
+    expect(r.code).toBe(0);
+    out = fs.readFileSync(path.join(dir, ".deco/loaders.gen.ts"), "utf8");
+  });
+
+  afterAll(() => {
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("imports createLoaderEntry when any loader is present", () => {
+    expect(out).toContain(
+      'import { createLoaderEntry } from "@decocms/blocks/sdk/cachedLoader";',
+    );
+  });
+
+  it("wraps loaders (both alias keys) with createLoaderEntry under the non-.ts name", () => {
+    expect(out).toContain(
+      '"site/loaders/related": createLoaderEntry("site/loaders/related", () => import(',
+    );
+    expect(out).toContain(
+      '"site/loaders/related.ts": createLoaderEntry("site/loaders/related", () => import(',
+    );
+  });
+
+  it("keeps actions as plain pass-throughs — never routed through createLoaderEntry", () => {
+    expect(out).toContain('"site/actions/addToCart": async (props: any, request?: Request) => {');
+    expect(out).not.toContain('createLoaderEntry("site/actions/addToCart"');
+  });
+});

package/scripts/generate-loaders.ts

@@ -158,6 +158,12 @@ function isReferenced(key: string): boolean {
 interface LoaderEntry {
   key: string;
   importPath: string;
+  /**
+   * Loaders route through `createLoaderEntry` so their `cache`/`cacheKey`
+   * exports drive single-flight dedup. Actions MUST NOT be cached/deduped
+   * (they mutate) — they stay plain pass-throughs.
+   */
+  kind: "loader" | "action";
 }
 
 const entries: LoaderEntry[] = [];
@@ -175,6 +181,7 @@ for (const filePath of walkDir(loadersDir)) {
   entries.push({
     key,
     importPath: relativeImportPath(outFile, filePath),
+    kind: "loader",
   });
 }
 
@@ -190,33 +197,56 @@ for (const filePath of walkDir(actionsDir)) {
   entries.push({
     key,
     importPath: relativeImportPath(outFile, filePath),
+    kind: "action",
   });
 }
 
 entries.sort((a, b) => a.key.localeCompare(b.key));
 
+const hasLoaderEntries = entries.some((e) => e.kind === "loader");
+
 const lines: string[] = [
   "// Auto-generated by @decocms/blocks-cli/scripts/generate-loaders.ts",
   "// Do not edit manually. Run `npm run generate:loaders` to update.",
   "//",
-  "// Pass-through loader/action entries for COMMERCE_LOADERS.",
-  "// Custom-wired entries should be excluded via --exclude and added manually in setup.ts.",
+  "// Loader entries route through createLoaderEntry so their cache/cacheKey",
+  "// exports drive single-flight dedup (concurrent identical calls in one",
+  "// render collapse to one upstream call). Actions stay plain pass-throughs",
+  "// (never cached/deduped). Custom-wired entries should be excluded via",
+  "// --exclude and added manually in setup.ts.",
   "",
-  "export const siteLoaders: Record<string, (props: any, request?: Request) => Promise<any>> = {",
 ];
+if (hasLoaderEntries) {
+  lines.push('import { createLoaderEntry } from "@decocms/blocks/sdk/cachedLoader";');
+  lines.push("");
+}
+lines.push(
+  "export const siteLoaders: Record<string, (props: any, request?: Request) => Promise<any>> = {",
+);
 
 // Cast the dynamic-import default to `any` so legacy 3-arg
 // `(props, req, ctx)` Fresh/Deno loaders still type-check. Any ctx-dependent
 // path in the loader body throws at runtime and must be refactored.
 for (const entry of entries) {
-  lines.push(`  "${entry.key}": async (props: any, request?: Request) => {`);
-  lines.push(`    const mod = await import("${entry.importPath}");`);
-  lines.push("    return (mod.default as any)(props, request);");
-  lines.push("  },");
-  lines.push(`  "${entry.key}.ts": async (props: any, request?: Request) => {`);
-  lines.push(`    const mod = await import("${entry.importPath}");`);
-  lines.push("    return (mod.default as any)(props, request);");
-  lines.push("  },");
+  if (entry.kind === "loader") {
+    // Both alias keys share the same dedup namespace (the non-.ts name) so a
+    // render that references either collapses onto one in-flight call.
+    lines.push(
+      `  "${entry.key}": createLoaderEntry("${entry.key}", () => import("${entry.importPath}")),`,
+    );
+    lines.push(
+      `  "${entry.key}.ts": createLoaderEntry("${entry.key}", () => import("${entry.importPath}")),`,
+    );
+  } else {
+    lines.push(`  "${entry.key}": async (props: any, request?: Request) => {`);
+    lines.push(`    const mod = await import("${entry.importPath}");`);
+    lines.push("    return (mod.default as any)(props, request);");
+    lines.push("  },");
+    lines.push(`  "${entry.key}.ts": async (props: any, request?: Request) => {`);
+    lines.push(`    const mod = await import("${entry.importPath}");`);
+    lines.push("    return (mod.default as any)(props, request);");
+    lines.push("  },");
+  }
 }
 
 lines.push("};");

package/scripts/migrate/post-cleanup/rules.ts

@@ -1677,6 +1677,93 @@ const ruleVtexProxyHandlerMissing: Rule = {
   },
 };
 
+/* ------------------------------------------------------------------ */
+/* Rule 15 — module-level signal .value reads without useStore         */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Detects the "frozen UI" pattern: a module-level signal whose `.value`
+ * is read inside a React component without a `useStore()` subscription.
+ *
+ * In Preact, `.value` reads are automatically reactive. In React they
+ * are just synchronous property accesses — no subscription is registered,
+ * so the component renders once with the initial value and never updates.
+ *
+ * Two-pass approach:
+ *   1. Find every `const name = signal(...)` at module scope (line starts
+ *      with optional `export const` — indented declarations inside
+ *      functions are skipped). First declaration wins when the same name
+ *      appears in multiple files (Map keyed by name deduplicates).
+ *   2. For each .tsx consumer, check per-signal: does it read `name.value`
+ *      AND lack a `useStore(name.store` call? Both conditions must hold for
+ *      a finding — a file that subscribes to signal A but reads signal B
+ *      raw is still flagged for B.
+ */
+const MODULE_SIGNAL_RE =
+  /^(?:export\s+)?const\s+([A-Za-z_$][A-Za-z0-9_$]*)\s*=\s*(?:\w+\.)?signal\s*\(/m;
+
+const ruleSignalValueReads: Rule = {
+  id: "signal-value-reads",
+  title: "Module-level signal .value reads without useStore()",
+  run({ siteDir, fs }: RuleContext): Finding[] {
+    const tsFiles = fs.glob(siteDir, "src/**/*.{ts,tsx}", SRC_GLOB_EXCLUDES);
+
+    // Pass 1: collect module-level signal declarations, first occurrence wins.
+    // Map<signalName, declaredIn> deduplicates names across files so Pass 2
+    // never emits two findings for the same (file, signalName) pair.
+    const moduleSignals = new Map<string, string>();
+    for (const abs of tsFiles) {
+      const content = fs.readText(abs);
+      const re = new RegExp(MODULE_SIGNAL_RE.source, "gm");
+      let match: RegExpExecArray | null;
+      while ((match = re.exec(content)) !== null) {
+        const name = match[1];
+        if (!moduleSignals.has(name)) {
+          moduleSignals.set(name, abs.slice(siteDir.length + 1));
+        }
+      }
+    }
+
+    if (moduleSignals.size === 0) return [];
+
+    // Pre-compile per-signal regexes once — avoids N×M compilations in Pass 2.
+    const valueReMap = new Map<string, RegExp>(
+      [...moduleSignals.keys()].map((name) => [name, new RegExp(`\\b${name}\\.value\\b`)]),
+    );
+
+    // Pass 2: for each .tsx file, check per-signal whether .value is read
+    // without a matching useStore(name.store call in the same file.
+    const tsxFiles = tsFiles.filter((f) => f.endsWith(".tsx"));
+    const findings: Finding[] = [];
+
+    for (const abs of tsxFiles) {
+      const content = fs.readText(abs);
+      const rel = abs.slice(siteDir.length + 1);
+
+      for (const [name, declaredIn] of moduleSignals) {
+        const valueRe = valueReMap.get(name)!;
+        if (!valueRe.test(content)) continue;
+        // Per-signal subscription check: useStore(name.store is the canonical
+        // subscription pattern. A file that subscribes to a different signal
+        // is not considered subscribed to this one.
+        const subscribedRe = new RegExp(`\\buseStore\\s*\\(\\s*${name}\\.store\\b`);
+        if (subscribedRe.test(content)) continue;
+
+        findings.push({
+          rule: "signal-value-reads",
+          severity: "warning",
+          file: rel,
+          message: `'${name}.value' read without useStore() — component will not re-render when the signal changes`,
+          fix: `Use useStore(${name}.store, (s) => s) to subscribe, or replace with useQuery / useMutation`,
+          meta: { signalName: name, declaredIn },
+        });
+      }
+    }
+
+    return findings;
+  },
+};
+
 export const ALL_RULES: Rule[] = [
   ruleDeadLibShims,
   ruleObsoleteVitePlugins,
@@ -1692,6 +1779,7 @@ export const ALL_RULES: Rule[] = [
   ruleLockfileMissing,
   ruleLockfileDrift,
   rulePackageManagerMissing,
+  ruleSignalValueReads,
 ];
 
 /** Exported for direct unit tests. */
@@ -1715,5 +1803,6 @@ export const _internals = {
     ruleLockfileMissing,
     ruleLockfileDrift,
     rulePackageManagerMissing,
+    ruleSignalValueReads,
   },
 };

package/scripts/migrate/post-cleanup/runner.test.ts

@@ -1793,3 +1793,184 @@ describe("rule: package-manager-missing", () => {
     expect(updated.packageManager).toMatch(/^bun@/);
   });
 });
+
+/* ------------------------------------------------------------------ */
+/* signal-value-reads rule                                             */
+/* ------------------------------------------------------------------ */
+
+describe("rule: signal-value-reads", () => {
+  it("flags a .tsx file that reads a module-level signal .value without useStore()", () => {
+    const fs = makeFs({
+      "/site/src/sdk/useAutocomplete.ts":
+        'import { signal } from "@decocms/blocks/sdk/signal";\n' +
+        "export const loading = signal(false);\n" +
+        "export const suggestions = signal(null);\n",
+      "/site/src/components/Searchbar.tsx":
+        'import { loading, suggestions } from "~/sdk/useAutocomplete";\n' +
+        "export default function Searchbar() {\n" +
+        "  const { products = [] } = suggestions.value ?? {};\n" +
+        "  return loading.value ? <Spinner /> : <ul>{products.map(p => <li>{p.name}</li>)}</ul>;\n" +
+        "}\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "signal-value-reads")!;
+    // Two signals read without useStore — one finding per signal per file.
+    expect(r.findings.length).toBeGreaterThanOrEqual(1);
+    const files = r.findings.map((f) => f.file);
+    expect(files.every((f) => f === "src/components/Searchbar.tsx")).toBe(true);
+    expect(r.findings[0].severity).toBe("warning");
+    expect(r.findings[0].fix).toContain("useStore");
+  });
+
+  it("does NOT flag when the .tsx file also calls useStore()", () => {
+    const fs = makeFs({
+      "/site/src/sdk/useAutocomplete.ts":
+        'import { signal } from "@decocms/blocks/sdk/signal";\n' +
+        "export const loading = signal(false);\n",
+      "/site/src/components/Searchbar.tsx":
+        'import { useStore } from "@tanstack/react-store";\n' +
+        'import { loading } from "~/sdk/useAutocomplete";\n' +
+        "export default function Searchbar() {\n" +
+        "  const isLoading = useStore(loading.store, (s) => s);\n" +
+        "  return isLoading ? <Spinner /> : <div />;\n" +
+        "}\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "signal-value-reads")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does NOT flag signal declared inside a function body (not module-level)", () => {
+    const fs = makeFs({
+      "/site/src/hooks/useCounter.ts":
+        'import { signal } from "@decocms/blocks/sdk/signal";\n' +
+        "export function useCounter() {\n" +
+        "  const count = signal(0);\n" + // indented — not module-level
+        "  return count;\n" +
+        "}\n",
+      "/site/src/components/Counter.tsx":
+        'import { useCounter } from "~/hooks/useCounter";\n' +
+        "export default function Counter() {\n" +
+        "  const count = useCounter();\n" +
+        "  return <div>{count.value}</div>;\n" +
+        "}\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "signal-value-reads")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does NOT flag .ts files (non-.tsx), which are not React render bodies", () => {
+    const fs = makeFs({
+      "/site/src/sdk/state.ts":
+        'import { signal } from "@decocms/blocks/sdk/signal";\n' +
+        "export const count = signal(0);\n",
+      // A plain .ts file that reads .value — not a React component, no JSX.
+      "/site/src/utils/helper.ts":
+        'import { count } from "~/sdk/state";\n' +
+        "export function getCount() { return count.value; }\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "signal-value-reads")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("flags only the unsubscribed signal when two signals coexist, one subscribed and one not", () => {
+    const fs = makeFs({
+      "/site/src/sdk/state.ts":
+        'import { signal } from "@decocms/blocks/sdk/signal";\n' +
+        "export const loading = signal(false);\n" +
+        'export const query = signal("");\n',
+      // loading is correctly subscribed via useStore(loading.store, ...).
+      // query.value is read raw — no useStore(query.store) call anywhere.
+      // Per-signal check: loading should produce no finding; query should.
+      "/site/src/components/Search.tsx":
+        'import { useStore } from "@tanstack/react-store";\n' +
+        'import { loading, query } from "~/sdk/state";\n' +
+        "export default function Search() {\n" +
+        "  const isLoading = useStore(loading.store, (s) => s);\n" +
+        "  return isLoading ? null : <div>{query.value}</div>;\n" +
+        "}\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "signal-value-reads")!;
+    // loading is subscribed — no finding for it.
+    // query.value is read without useStore(query.store) — one finding.
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.signalName).toBe("query");
+    expect(r.findings[0].file).toBe("src/components/Search.tsx");
+  });
+
+  it("does NOT flag when the .tsx file calls useStore with the exact signal's store", () => {
+    const fs = makeFs({
+      "/site/src/sdk/state.ts":
+        'import { signal } from "@decocms/blocks/sdk/signal";\n' +
+        "export const count = signal(0);\n",
+      "/site/src/components/Counter.tsx":
+        'import { useStore } from "@tanstack/react-store";\n' +
+        'import { count } from "~/sdk/state";\n' +
+        "export default function Counter() {\n" +
+        "  const n = useStore(count.store, (s) => s);\n" +
+        "  return <div>{count.value}</div>;\n" + // .value present but store is subscribed
+        "}\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "signal-value-reads")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does not produce duplicate findings when two source files declare the same signal name", () => {
+    const fs = makeFs({
+      "/site/src/sdk/useAutocomplete.ts":
+        'import { signal } from "@decocms/blocks/sdk/signal";\n' +
+        "export const loading = signal(false);\n",
+      // A re-export file also declares the same name — realistic in partial migrations.
+      "/site/src/re-exports.ts":
+        'import { signal } from "@decocms/blocks/sdk/signal";\n' +
+        "export const loading = signal(false);\n",
+      "/site/src/components/Searchbar.tsx":
+        'import { loading } from "~/sdk/useAutocomplete";\n' +
+        "export default function Searchbar() {\n" +
+        "  return loading.value ? <Spinner /> : <div />;\n" +
+        "}\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "signal-value-reads")!;
+    // Only one finding despite two source files declaring "loading".
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.signalName).toBe("loading");
+  });
+
+  it("returns zero findings on a site with no signal declarations", () => {
+    const fs = makeFs({
+      "/site/src/components/Static.tsx":
+        "export default function Static() { return <div>hello</div>; }\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "signal-value-reads")!;
+    expect(r.findings).toEqual([]);
+  });
+
+  it("does NOT support auto-fix (correct replacement varies per case)", () => {
+    const fs = makeFs({});
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "signal-value-reads")!;
+    expect(r.supportsAutoFix).toBe(false);
+  });
+
+  it("includes signalName and declaredIn in finding meta", () => {
+    const fs = makeFs({
+      "/site/src/sdk/signals.ts":
+        'import { signal } from "@decocms/blocks/sdk/signal";\n' +
+        "export const mySignal = signal(0);\n",
+      "/site/src/components/Widget.tsx":
+        'import { mySignal } from "~/sdk/signals";\n' +
+        "export default function Widget() { return <div>{mySignal.value}</div>; }\n",
+    });
+    const report = runAudit(SITE, fs);
+    const r = report.rules.find((r) => r.rule === "signal-value-reads")!;
+    expect(r.findings).toHaveLength(1);
+    expect(r.findings[0].meta?.signalName).toBe("mySignal");
+    expect(r.findings[0].meta?.declaredIn).toBe("src/sdk/signals.ts");
+  });
+});

package/scripts/migrate/templates/server-entry.ts

@@ -121,9 +121,7 @@ import {
 } from "@decocms/blocks-admin";
 import { shouldProxyToVtex, createVtexCheckoutProxy } from "@decocms/apps-vtex/utils/proxy";
 import { extractVtexContext } from "@decocms/apps-vtex/middleware";
-import { loadRedirects, matchRedirect } from "@decocms/blocks/sdk/redirects";
 import { withABTesting } from "@decocms/blocks/sdk/abTesting";
-import { loadBlocks } from "@decocms/blocks/cms";
 
 // ---------------------------------------------------------------------------
 // VTEX checkout proxy — configured via @decocms/apps-vtex factory
@@ -152,11 +150,6 @@ const CSP_DIRECTIVES = [
 
 const serverEntry = createServerEntry({ fetch: handler.fetch });
 
-// ---------------------------------------------------------------------------
-// CMS Redirects — loaded once at module level from .deco/blocks/
-// ---------------------------------------------------------------------------
-const cmsRedirects = loadRedirects(loadBlocks());
-
 const MOBILE_RE = /mobile|android|iphone/i;
 
 const decoWorker = createDecoWorkerEntry(serverEntry, {
@@ -205,17 +198,6 @@ const decoWorker = createDecoWorkerEntry(serverEntry, {
 
 const abTestedWorker = withABTesting(decoWorker, {
   kvBinding: "SITES_KV",
-  preHandler: (request, url) => {
-    const redirect = matchRedirect(url.pathname, cmsRedirects);
-    if (redirect) {
-      const target = url.search ? \`\${redirect.to}\${url.search}\` : redirect.to;
-      return new Response(null, {
-        status: redirect.status,
-        headers: { Location: target },
-      });
-    }
-    return null;
-  },
   shouldBypassAB: (_request, url) => {
     if (url.pathname === "/login" || url.pathname === "/login/" ||
         url.pathname === "/logout" || url.pathname === "/logout/") return false;

package/scripts/migrate/transforms/dead-code.ts

@@ -4,59 +4,19 @@ import type { TransformResult } from "../types";
  * Removes dead code patterns from the old Deco stack that don't work
  * in TanStack Start:
  *
- * - `export const cache = "stale-while-revalidate"` (old cache system)
- * - `export const cacheKey = ...` (old cache key generation)
  * - `crypto.subtle.digestSync(...)` (Deno-only sync API)
+ * - non-active platform branches (see `stripNonPlatformCode`)
  *
+ * NOTE: `export const cache` / `export const cacheKey` are KEPT — they are no
+ * longer dead. `@decocms/blocks` wires them via `createLoaderEntry` so
+ * `cache: "stale-while-revalidate"` drives single-flight dedup keyed by
+ * `cacheKey(props, req)` (the #339 N+1 fix). Only flagged in the notes so the
+ * author verifies the `(props, req)` signature.
  * NOTE: `export const loader` is kept — it's a server-side function the CMS calls.
  * NOTE: invoke.* calls are NOT migrated — they are RPC calls to the server
  * where the CMS config (API keys, etc.) is available. The runtime.ts invoke
  * proxy handles routing them to /deco/invoke/*.
  */
-/**
- * Remove an `export const <name> = ...` block using brace-counting
- * so nested `{}` (for loops, if/else) don't cause premature truncation.
- */
-function removeExportConstBlock(src: string, name: string): string {
-  const pattern = new RegExp(`^export\\s+const\\s+${name}\\s*=`, "m");
-  const match = pattern.exec(src);
-  if (!match) return src;
-
-  // Find the arrow `=>` first, then the opening `{` of the body.
-  // This avoids matching destructuring braces in parameters like
-  // `export const loader = ({ groups }: Props) => { ... }`
-  let pos = match.index + match[0].length;
-  // Look for `=>`
-  const arrowIdx = src.indexOf("=>", pos);
-  if (arrowIdx === -1) {
-    // No arrow function — try simple brace from current position
-    while (pos < src.length && src[pos] !== "{") pos++;
-  } else {
-    // Start searching for `{` after the arrow
-    pos = arrowIdx + 2;
-    while (pos < src.length && src[pos] !== "{") pos++;
-  }
-  if (pos >= src.length) return src; // no brace body, skip
-
-  // Count braces to find the matching closing brace
-  let depth = 0;
-  const start = match.index;
-  for (; pos < src.length; pos++) {
-    if (src[pos] === "{") depth++;
-    else if (src[pos] === "}") {
-      depth--;
-      if (depth === 0) {
-        // Skip optional semicolon and trailing newline
-        let end = pos + 1;
-        if (end < src.length && src[end] === ";") end++;
-        if (end < src.length && src[end] === "\n") end++;
-        return src.slice(0, start) + src.slice(end);
-      }
-    }
-  }
-  return src; // unbalanced braces, don't touch
-}
-
 const ALL_PLATFORMS = ["vtex", "shopify", "linx", "vnda", "wake", "nuvemshop"];
 
 /**
@@ -169,36 +129,22 @@ export function transformDeadCode(content: string, platform?: string): Transform
   let changed = false;
   let result = content;
 
-  // Remove old cache export: export const cache = "stale-while-revalidate" or { maxAge: ... }
+  // KEEP `export const cache` / `export const cacheKey`. These are NO LONGER
+  // dead: `@decocms/blocks` wires them via `createLoaderEntry` (generated in
+  // `.deco/loaders.gen.ts`) so `cache: "stale-while-revalidate"` opts the loader
+  // into single-flight dedup keyed by `cacheKey(props, req)`. Stripping them
+  // would silently reintroduce the #339 N+1 (same loader run once per section).
+  // Flag them so the author verifies the `(props, req)` signature — old
+  // `deco-cx/apps` `cacheKey(props, req, ctx)` loses its 3rd `ctx` arg here.
   if (/^export\s+const\s+cache\s*=/m.test(result)) {
-    // String form: export const cache = "stale-while-revalidate";
-    result = result.replace(
-      /^export\s+const\s+cache\s*=\s*["'][^"']*["'];?\s*\n?/gm,
-      "",
-    );
-    // Object form: export const cache = { maxAge: 60 * 10 };
-    result = result.replace(
-      /^export\s+const\s+cache\s*=\s*\{[^}]*\};?\s*\n?/gm,
-      "",
+    notes.push(
+      "KEPT `export const cache` — now drives single-flight dedup via createLoaderEntry (run `generate` to wire it).",
     );
-    // Multiline object form (use brace-counting)
-    if (/^export\s+const\s+cache\s*=/m.test(result)) {
-      result = removeExportConstBlock(result, "cache");
-    }
-    changed = true;
-    notes.push("Removed dead `export const cache` (old caching system)");
   }
-
-  // Remove old cacheKey export (can be multiline with brace-counting)
   if (/^export\s+const\s+cacheKey\s*=/m.test(result)) {
-    result = removeExportConstBlock(result, "cacheKey");
-    // Also handle simpler inline forms
-    result = result.replace(
-      /^export\s+const\s+cacheKey\s*=[^;]*;\s*\n?/gm,
-      "",
+    notes.push(
+      "MANUAL: `export const cacheKey` is kept and now active — verify its signature is `(props, req)`; the old `ctx` 3rd arg is no longer passed.",
     );
-    changed = true;
-    notes.push("Removed dead `export const cacheKey` (old caching system)");
   }
 
   // NOTE: `export const loader` is kept — these are server-side functions