@decocms/blocks-cli 8.0.0 → 8.1.0-next.0

package/scripts/generate-schema.ts

@@ -27,16 +27,14 @@ import { fileURLToPath } from "node:url";
  *   --skip-apps   Skip app schema generation
  *   --out         Output file        (default: ".deco/meta.gen.json")
  *   --platform    Platform name      (default: "cloudflare")
- *   --compose     Run composeMeta() before writing so the output is
- *                 SELF-CONTAINED (bakes in Page, matchers, __SECTION_REF__,
- *                 Resolvable). For consumers that read meta.gen.json straight
- *                 from disk with no runtime (FS-based Studio / Eitri stack).
- *   --framework   With --compose, the value written to the `framework` field
+ *   --framework   Value written to the composed meta's `framework` field
  *                 (default: "tanstack-start").
  *
- * If no `--out` is passed and the OLD default (src/server/admin/meta.gen.json)
- * still exists on disk, a one-line legacy warning is printed to stderr and the
- * NEW default is written anyway — see lib/legacyArtifact.ts.
+ * The output is ALWAYS run through composeMeta() before writing, so
+ * meta.gen.json is self-contained (bakes in Page, matchers, __SECTION_REF__,
+ * Resolvable). This matters for consumers that read the file straight from
+ * disk with no runtime (FS-based Studio / Eitri stack); runtime readers
+ * re-compose idempotently (see composeMeta's `framework` sentinel).
  */
 import {
   type Symbol as MorphSymbol,
@@ -47,7 +45,7 @@ import {
   type Type,
 } from "ts-morph";
 import { isExcludedCodegenFile } from "./lib/codegenExclusions";
-import { warnLegacyArtifact } from "./lib/legacyArtifact";
+import { resolvePackageDirectory } from "./lib/installedPackages";
 
 // ---------------------------------------------------------------------------
 // CLI arg parsing
@@ -56,12 +54,9 @@ import { warnLegacyArtifact } from "./lib/legacyArtifact";
 // here) so that importing this module for its pure exports
 // (definitionIdForPath, applyWidgetFormat, typeToJsonSchema — see
 // generate-schema.test.ts) never reads argv or touches the filesystem.
-// Without the guard, every import used to run an `fs.existsSync` check
-// against the *importing process's* cwd and could print a legacy-artifact
-// warning to stderr as an import-time side effect, unrelated to whatever
-// the test actually wanted to exercise. generateMeta() (below) and the
-// final write are themselves only reached inside `if (isMainModule())`, so
-// these vars only need real values in that same case.
+// generateMeta() (below) and the final write are themselves only reached
+// inside `if (isMainModule())`, so these vars only need real values in that
+// same case.
 // ---------------------------------------------------------------------------
 const argv = process.argv.slice(2);
 function arg(name: string, fallback: string): string {
@@ -70,7 +65,6 @@ function arg(name: string, fallback: string): string {
 }
 
 const NEW_DEFAULT_OUT_REL = ".deco/meta.gen.json";
-const OLD_DEFAULT_OUT_REL = "src/server/admin/meta.gen.json";
 
 let SITE_NAMESPACE = "site";
 let SITE_NAME = "storefront";
@@ -81,14 +75,12 @@ let APPS_REL = "src/apps";
 let SKIP_APPS = false;
 let OUT_REL = NEW_DEFAULT_OUT_REL;
 let PLATFORM = "cloudflare";
-// When true, run composeMeta() over the generated site meta before writing, so
-// the output file is SELF-CONTAINED — it carries the framework block types
-// (Page, matchers, __SECTION_REF__, Resolvable) that composeMeta otherwise
-// injects at runtime. Required by consumers that read meta.gen.json straight
-// from the filesystem with no runtime (e.g. the FS-based Studio / Eitri stack).
-let COMPOSE = false;
-// Value written to the composed meta's `framework` field (only used with
-// --compose). Defaults to composeMeta's historical "tanstack-start".
+// Value written to the composed meta's `framework` field. Defaults to
+// composeMeta's historical "tanstack-start". composeMeta ALWAYS runs before
+// writing (see the write block below), so the output file is SELF-CONTAINED —
+// it carries the framework block types (Page, matchers, __SECTION_REF__,
+// Resolvable). Required by consumers that read meta.gen.json straight from the
+// filesystem with no runtime (e.g. the FS-based Studio / Eitri stack).
 let FRAMEWORK = "tanstack-start";
 
 if (isMainModule()) {
@@ -99,14 +91,9 @@ if (isMainModule()) {
   LOADERS_REL = arg("loaders", LOADERS_REL);
   APPS_REL = arg("apps", APPS_REL);
   SKIP_APPS = argv.includes("--skip-apps");
-  const outFileExplicit = argv.includes("--out");
   OUT_REL = arg("out", NEW_DEFAULT_OUT_REL);
   PLATFORM = arg("platform", PLATFORM);
-  COMPOSE = argv.includes("--compose");
   FRAMEWORK = arg("framework", FRAMEWORK);
-  if (!outFileExplicit && fs.existsSync(path.resolve(process.cwd(), OLD_DEFAULT_OUT_REL))) {
-    warnLegacyArtifact(OLD_DEFAULT_OUT_REL, NEW_DEFAULT_OUT_REL);
-  }
 }
 
 // ---------------------------------------------------------------------------
@@ -319,6 +306,33 @@ const SECTION_REF_DEF_KEY = "__SECTION_REF__";
 // Well-known definition key for Resolvable (saved blocks picker)
 const RESOLVABLE_KEY = "Resolvable";
 
+/**
+ * Whether a prop annotated `Section` / `Section[]` is the framework's opaque
+ * Section type (a "pick any section" reference) rather than a user-defined type
+ * that merely happens to be named `Section`.
+ *
+ * The framework's `Section` is opaque — `export type Section = any` in the
+ * scaffolded `~/types/deco.ts` — so it resolves to `any` (or `unknown`). A
+ * component that declares its own local `type Section = { label; items }`
+ * (e.g. a footer column list) resolves to a concrete object with properties;
+ * that is user data and must render as an inline editable object, NOT a picker.
+ *
+ * Discriminates by the resolved shape after stripping `| null | undefined` and
+ * the array wrapper: only the opaque type is a section reference.
+ */
+function isOpaqueSectionType(propType: Type): boolean {
+  let type = propType;
+  if (type.isUnion()) {
+    const nonNull = type.getUnionTypes().filter((u) => !u.isNull() && !u.isUndefined());
+    if (nonNull.length === 1) type = nonNull[0];
+  }
+  if (type.isArray()) {
+    const el = type.getArrayElementType();
+    if (el) type = el;
+  }
+  return type.isAny() || type.isUnknown();
+}
+
 // Only truly React-internal props that are never user-defined.
 // Do NOT include "children", "type", "props", or "key" — those are commonly
 // used as legitimate property names in data interfaces (e.g. SelectedFacet
@@ -356,6 +370,37 @@ interface GenerationContext {
   outputTypeToLoaderKeys: Map<string, string[]>;
 }
 
+function namedLoaderType(type: Type | undefined): string | null {
+  if (!type) return null;
+  const name = type.getSymbol()?.getName();
+  if (
+    name &&
+    name !== "__type" &&
+    name !== "__object" &&
+    name !== "Array" &&
+    name !== "ReadonlyArray"
+  ) {
+    return name;
+  }
+  // Mapped/object aliases have a synthetic symbol but retain their own name.
+  // Bare Omit<T, K>/Generic<T> must not share a bucket across instantiations.
+  const alias = type.getAliasSymbol();
+  return alias && type.getAliasTypeArguments().length === 0 ? alias.getName() : null;
+}
+
+/** Same bounded name lookup for loader outputs and section props; no shape matching. */
+function loaderTypeName(type: Type): string | null {
+  if (type.isUnion()) {
+    const nonNull = type.getUnionTypes().filter((t) => !t.isNull() && !t.isUndefined());
+    if (nonNull.length === 1) type = nonNull[0];
+  }
+  if (type.isArray()) {
+    const name = namedLoaderType(type.getArrayElementType());
+    return name ? `${name}[]` : null;
+  }
+  return namedLoaderType(type);
+}
+
 /**
  * Extract the return type name of a loader's default export.
  * Unwraps Promise<T> and T | null wrappers.
@@ -370,25 +415,7 @@ function extractLoaderOutputTypeName(sourceFile: SourceFile): string | null {
     const args = ret.getTypeArguments();
     if (args.length) ret = args[0];
   }
-  if (ret.isUnion()) {
-    const nonNull = ret.getUnionTypes().filter((t) => !t.isNull() && !t.isUndefined());
-    if (nonNull.length === 1) ret = nonNull[0];
-  }
-  // Unwrap array element type — Product[] → "Product[]" (keyed as array).
-  // When the element type has no resolvable name (primitives like `string[]`,
-  // or opaque types like `VNode[]`), there is NO meaningful output-type key.
-  // Returning the generic `Array` symbol here would bucket the loader under
-  // "Array", which then collides with EVERY array-typed section prop
-  // (`Collection[]`, `Tab[]`, …) and wrongly turns them into loader pickers.
-  if (ret.isArray()) {
-    const elType = ret.getArrayElementType();
-    const elName = elType?.getSymbol()?.getName() ?? elType?.getAliasSymbol()?.getName() ?? null;
-    return elName ? `${elName}[]` : null;
-  }
-  // Reject anonymous object returns (`{ … }` → symbol name "__type"): they are
-  // not a nameable output type and would over-match anonymous-object props.
-  const name = ret.getSymbol()?.getName() ?? ret.getAliasSymbol()?.getName() ?? null;
-  return name && name !== "__type" ? name : null;
+  return loaderTypeName(ret);
 }
 
 export function typeToJsonSchema(type: Type, visited = new Set<string>(), ctx?: GenerationContext): any {
@@ -573,9 +600,16 @@ export function typeToJsonSchema(type: Type, visited = new Set<string>(), ctx?:
           if (tn) typeHint = tn.getText();
         }
 
-        // Section type → section picker reference (resolved by composeMeta)
+        // Section type → section picker reference (resolved by composeMeta).
+        // Guard on the resolved shape: the name `Section` is not reserved, so a
+        // component may declare its own local `type Section = { label; items }`
+        // (e.g. a footer column list). Only the framework's opaque Section type
+        // becomes a picker; a concretely-shaped local type falls through to the
+        // normal inline-object handling below (`isOpaqueSectionType`).
         const baseHint = typeHint.replace(/\s*\|\s*(null|undefined)/g, "").trim();
-        if (baseHint === "Section" || baseHint === "Section[]" || baseHint === "Section[] | null") {
+        const isSectionName =
+          baseHint === "Section" || baseHint === "Section[]" || baseHint === "Section[] | null";
+        if (isSectionName && isOpaqueSectionType(propType)) {
           const isArray = baseHint.includes("[]");
           const sectionSchema: any = isArray
             ? {
@@ -599,32 +633,10 @@ export function typeToJsonSchema(type: Type, visited = new Set<string>(), ctx?:
         // Loader output type → block-ref: emit anyOf [Resolvable, ...matchingLoaders]
         // baseHint strips "| null | undefined" so "ProductListingPage | null" → "ProductListingPage"
         if (ctx?.outputTypeToLoaderKeys) {
-          const typeSym = propType.getSymbol() ?? propType.getAliasSymbol();
-          // An array type's symbol name is always the generic "Array", which is
-          // never a meaningful loader output key — fall back to the AST type
-          // text (`baseHint`, e.g. "Collection[]") instead. The element-based
-          // `${elName}[]` lookup below handles arrays precisely.
-          const symName = typeSym?.getName();
-          const outputTypeName = symName && symName !== "Array" ? symName : baseHint;
-          let matchingLoaders =
-            ctx.outputTypeToLoaderKeys.get(outputTypeName) ??
+          const outputTypeName = loaderTypeName(propType);
+          const matchingLoaders =
+            (outputTypeName ? ctx.outputTypeToLoaderKeys.get(outputTypeName) : undefined) ??
             (outputTypeName !== baseHint ? ctx.outputTypeToLoaderKeys.get(baseHint) : undefined);
-          // If no match yet and the prop type is an array, try element type name + "[]"
-          if (!matchingLoaders?.length) {
-            let arrayElementType = propType.isArray() ? propType.getArrayElementType() : null;
-            if (!arrayElementType && propType.isUnion()) {
-              const nonNull = propType.getUnionTypes().filter((t) => !t.isNull() && !t.isUndefined());
-              if (nonNull.length === 1 && nonNull[0].isArray()) {
-                arrayElementType = nonNull[0].getArrayElementType();
-              }
-            }
-            if (arrayElementType) {
-              const elName = arrayElementType.getSymbol()?.getName() ?? arrayElementType.getAliasSymbol()?.getName();
-              if (elName) {
-                matchingLoaders = ctx.outputTypeToLoaderKeys.get(`${elName}[]`);
-              }
-            }
-          }
           if (matchingLoaders?.length) {
             const blockRefSchema: any = {
               anyOf: [
@@ -1051,8 +1063,8 @@ function generateMeta(): MetaResponse {
   // ---------------------------------------------------------------------------
 
   /** Absolute path to the installed @decocms/apps-<namespace> package, if present. */
-  function getAppPkgDir(namespace: string): string {
-    return path.resolve(root, `node_modules/@decocms/apps-${namespace}`);
+  function getAppPkgDir(namespace: string): string | null {
+    return resolvePackageDirectory(root, `@decocms/apps-${namespace}`);
   }
 
   /** Detect installed app namespaces from src/apps/ bridge files. */
@@ -1082,6 +1094,7 @@ function generateMeta(): MetaResponse {
 
     for (const namespace of installed) {
       const pkgDir = getAppPkgDir(namespace);
+      if (!pkgDir) continue;
       const loadersDir = path.join(pkgDir, "src", "loaders");
       if (!fs.existsSync(loadersDir)) continue;
 
@@ -1522,18 +1535,17 @@ function isMainModule(): boolean {
 }
 
 if (isMainModule()) {
-  // Wrapped in an async IIFE so --compose can dynamically import composeMeta
-  // ONLY when requested — the default path (and any test importing this
-  // module's pure exports) never pulls in the @decocms/blocks/cms barrel.
+  // Wrapped in an async IIFE so the composeMeta dynamic import happens only
+  // when this module is actually run (any test importing this module's pure
+  // exports never reaches here, so it never pulls in the @decocms/blocks/cms
+  // barrel). composeMeta always runs, making the written file self-contained.
   void (async () => {
-    let meta = generateMeta();
-    if (COMPOSE) {
-      const { composeMeta } = await import("@decocms/blocks/cms");
-      // composeMeta returns @decocms/blocks' MetaResponse (platform optional);
-      // this file's local MetaResponse requires platform. It's always present
-      // (composeMeta spreads siteMeta, which set it), so the cast is safe.
-      meta = composeMeta(meta, { framework: FRAMEWORK }) as MetaResponse;
-    }
+    const rawMeta = generateMeta();
+    const { composeMeta } = await import("@decocms/blocks/cms");
+    // composeMeta returns @decocms/blocks' MetaResponse (platform optional);
+    // this file's local MetaResponse requires platform. It's always present
+    // (composeMeta spreads siteMeta, which set it), so the cast is safe.
+    const meta = composeMeta(rawMeta, { framework: FRAMEWORK }) as MetaResponse;
     const outPath = path.resolve(process.cwd(), OUT_REL);
     fs.mkdirSync(path.dirname(outPath), { recursive: true });
     fs.writeFileSync(outPath, JSON.stringify(meta, null, 2));
@@ -1543,7 +1555,7 @@ if (isMainModule()) {
     const ldrCount = Object.keys(meta.manifest.blocks.loaders || {}).length;
     const appCount = Object.keys(meta.manifest.blocks.apps || {}).length;
     console.log(
-      `\nGenerated schema${COMPOSE ? " (self-contained)" : ""}: ${defCount} definitions, ${secCount} sections, ${ldrCount} loaders, ${appCount} apps → ${path.relative(process.cwd(), outPath)}`,
+      `\nGenerated schema (self-contained): ${defCount} definitions, ${secCount} sections, ${ldrCount} loaders, ${appCount} apps → ${path.relative(process.cwd(), outPath)}`,
     );
   })();
 }

package/scripts/generate-sections.test.ts

@@ -9,7 +9,7 @@
  *
  * Verifies the operationally important behavior: a co-located test/spec/
  * stories/gen file sitting next to a real section must never be walked into
- * sectionMeta (the fila incident this generator's `walkDir` reproduced:
+ * sectionMeta (a production-site incident this generator's `walkDir` reproduced:
  * `sections.test.ts` became a bogus section in a site's generated output).
  */
 import * as cp from "node:child_process";
@@ -72,6 +72,22 @@ describe("generate-sections walkDir exclusions", () => {
     expect(generated).not.toContain("Hero.stories.tsx");
     expect(generated).not.toContain("sections.gen.ts");
   }, 30_000);
+
+  it("extracts `export const deferred = true` into sectionMeta", () => {
+    fs.writeFileSync(
+      path.join(sectionsDir, "HeavyPLP.tsx"),
+      "export const deferred = true;\nexport default function HeavyPLP() { return null; }\n",
+    );
+
+    const { code } = runGenerator(["--sections-dir", sectionsDir, "--out-file", outFile]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+    // The per-section deferral flag must survive the regex scan → sectionMeta,
+    // or applySectionConventions can never register it as always-defer.
+    expect(generated).toMatch(/"site\/sections\/HeavyPLP\.tsx":\s*\{[^}]*deferred:\s*true/);
+    expect(generated).toContain("deferred?: boolean;");
+  }, 30_000);
 });
 
 describe("generate-sections default output path (.deco/)", () => {
@@ -99,39 +115,9 @@ describe("generate-sections default output path (.deco/)", () => {
     const newDefault = path.join(tmpDir, ".deco", "sections.gen.ts");
     expect(fs.existsSync(newDefault)).toBe(true);
     expect(fs.readFileSync(newDefault, "utf-8")).toContain("site/sections/Hero.tsx");
-    // No legacy file present, so no warning is expected.
+    // No legacy default path is written anymore, so no warning is expected.
     expect(stderr).not.toContain("Generator default output moved");
   }, 30_000);
-
-  it("warns once to stderr naming both paths when the OLD default file exists and no --out-file is passed, but still writes the NEW default", () => {
-    const oldDefaultDir = path.join(tmpDir, "src", "server", "cms");
-    fs.mkdirSync(oldDefaultDir, { recursive: true });
-    fs.writeFileSync(path.join(oldDefaultDir, "sections.gen.ts"), "// stale\n");
-
-    const { code, stderr } = runGenerator([], { cwd: tmpDir });
-    expect(code).toBe(0);
-
-    expect(stderr).toContain("src/server/cms/sections.gen.ts");
-    expect(stderr).toContain(".deco/sections.gen.ts");
-    expect(stderr).toContain("Move the file and update its importers");
-
-    const newDefault = path.join(tmpDir, ".deco", "sections.gen.ts");
-    expect(fs.existsSync(newDefault)).toBe(true);
-    expect(fs.readFileSync(newDefault, "utf-8")).toContain("site/sections/Hero.tsx");
-  }, 30_000);
-
-  it("does not warn when an explicit --out-file is passed, even if the OLD default file exists", () => {
-    const oldDefaultDir = path.join(tmpDir, "src", "server", "cms");
-    fs.mkdirSync(oldDefaultDir, { recursive: true });
-    fs.writeFileSync(path.join(oldDefaultDir, "sections.gen.ts"), "// stale\n");
-
-    const explicitOut = path.join(tmpDir, "custom", "sections.gen.ts");
-    const { code, stderr } = runGenerator(["--out-file", explicitOut], { cwd: tmpDir });
-    expect(code).toBe(0);
-
-    expect(stderr).not.toContain("Generator default output moved");
-    expect(fs.existsSync(explicitOut)).toBe(true);
-  }, 30_000);
 });
 
 describe("generate-sections --registry", () => {
@@ -287,8 +273,8 @@ describe("generate-sections neverDefer convention", () => {
   // SectionMetaEntry interface the SAME file declares omitted the field —
   // so every generated file containing a neverDefer section failed the
   // site's typecheck (TS2353 excess property), and sites hand-patched the
-  // interface only to have the next regeneration wipe the patch (miess's
-  // .deco/sections.gen.ts carried exactly that TODO). The emitted interface
+  // interface only to have the next regeneration wipe the patch (a production
+  // site's .deco/sections.gen.ts carried exactly that TODO). The emitted interface
   // must match SectionMetaEntry in @decocms/blocks/cms.
   let tmpDir: string;
   let sectionsDir: string;
@@ -306,7 +292,7 @@ describe("generate-sections neverDefer convention", () => {
   });
 
   it("declares neverDefer on the emitted SectionMetaEntry interface and the generated file typechecks + imports", () => {
-    // Mirrors miess's src/sections/Product/SearchResult.tsx.
+    // Mirrors a production site's src/sections/Product/SearchResult.tsx.
     fs.writeFileSync(
       path.join(sectionsDir, "SearchResult.tsx"),
       "export const neverDefer = true;\nexport default function SearchResult() { return null; }\n",
@@ -350,6 +336,89 @@ describe("generate-sections neverDefer convention", () => {
   }, 60_000);
 });
 
+describe("generate-sections renderJson convention", () => {
+  let tmpDir: string;
+  let sectionsDir: string;
+  let outFile: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "generate-sections-renderjson-"));
+    sectionsDir = path.join(tmpDir, "sections");
+    outFile = path.join(tmpDir, "out", "sections.gen.ts");
+    fs.mkdirSync(sectionsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("emits `renderJson: false` into sectionMeta and a `renderJsons` map for projection fns; the output typechecks + imports", () => {
+    // `= false` opt-out: web-only section dropped from ?renderJson.
+    fs.writeFileSync(
+      path.join(sectionsDir, "Theme.tsx"),
+      "export const renderJson = false;\nexport default function Theme() { return null; }\n",
+    );
+    // projection function: trims props for the mobile app.
+    fs.writeFileSync(
+      path.join(sectionsDir, "ProductDetails.tsx"),
+      [
+        "export const renderJson = (props: Record<string, unknown>) => {",
+        "  const { storeConfig: _s, ...rest } = props;",
+        "  return rest;",
+        "};",
+        "export default function ProductDetails() { return null; }",
+        "",
+      ].join("\n"),
+    );
+
+    const { code } = runGenerator(["--sections-dir", sectionsDir, "--out-file", outFile]);
+    expect(code).toBe(0);
+
+    const generated = fs.readFileSync(outFile, "utf-8");
+
+    // The `= false` section carries the literal false flag; the fn section
+    // carries hasRenderJson (its actual fn lives in the renderJsons map).
+    expect(generated).toMatch(/"site\/sections\/Theme\.tsx":\s*\{[^}]*renderJson:\s*false/);
+    expect(generated).toMatch(/"site\/sections\/ProductDetails\.tsx":\s*\{[^}]*hasRenderJson:\s*true/);
+    // The emitted interface declares both (excess-property guard, cf. neverDefer).
+    expect(generated).toContain("renderJson?: false;");
+    expect(generated).toContain("hasRenderJson?: boolean;");
+    // The fn is imported and wired into renderJsons; the `= false` one is NOT.
+    expect(generated).toContain("import { renderJson as _rj0 }");
+    expect(generated).toMatch(/export const renderJsons: Record<string, any> = \{[\s\S]*ProductDetails\.tsx": _rj0/);
+    expect(generated).not.toMatch(/renderJsons: Record<string, any> = \{[\s\S]*Theme\.tsx/);
+
+    // Typecheck the output (the real failure mode for a bad emit is TS2353, not
+    // a runtime error) and confirm it imports with a working projection fn.
+    // --jsx: the generated file imports a projection fn from a `.tsx` section,
+    // so tsc needs jsx set (a real site's tsconfig always does; the standalone
+    // invocation must too, or it fails with TS6142).
+    const tscResult = cp.spawnSync(
+      "npx",
+      ["tsc", "--noEmit", "--strict", "--skipLibCheck", "--jsx", "react-jsx", outFile],
+      { encoding: "utf8" },
+    );
+    expect(tscResult.status, tscResult.stdout + tscResult.stderr).toBe(0);
+
+    const checkerFile = path.join(tmpDir, "check-import.mjs");
+    fs.writeFileSync(
+      checkerFile,
+      [
+        `const m = await import(${JSON.stringify(pathToFileURL(outFile).href)});`,
+        `if (m.sectionMeta?.["site/sections/Theme.tsx"]?.renderJson !== false) {`,
+        `  throw new Error("Theme renderJson:false missing from sectionMeta");`,
+        `}`,
+        `const fn = m.renderJsons?.["site/sections/ProductDetails.tsx"];`,
+        `if (typeof fn !== "function") throw new Error("ProductDetails renderJson fn missing");`,
+        `const out = fn({ storeConfig: 1, page: 2 });`,
+        `if (out.storeConfig !== undefined || out.page !== 2) throw new Error("projection fn wrong");`,
+      ].join("\n"),
+    );
+    const importResult = cp.spawnSync("npx", ["tsx", checkerFile], { encoding: "utf8" });
+    expect(importResult.status, importResult.stderr).toBe(0);
+  }, 60_000);
+});
+
 describe("generate-sections output hygiene (non-registry)", () => {
   let tmpDir: string;
   let sectionsDir: string;

package/scripts/generate-sections.ts

@@ -28,15 +28,10 @@
  *                   Built from every scanned section file, not just the ones
  *                   carrying convention exports. Off by default so existing
  *                   Vite sites regenerating sections.gen.ts in CI see zero diff.
- *
- * If no `--out-file` is passed and the OLD default (src/server/cms/sections.gen.ts)
- * still exists on disk, a one-line legacy warning is printed to stderr and the
- * NEW default is written anyway — see lib/legacyArtifact.ts.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { isExcludedCodegenFile } from "./lib/codegenExclusions";
-import { warnLegacyArtifact } from "./lib/legacyArtifact";
 
 const args = process.argv.slice(2);
 function arg(name: string, fallback: string): string {
@@ -45,27 +40,33 @@ function arg(name: string, fallback: string): string {
 }
 
 const sectionsDir = path.resolve(process.cwd(), arg("sections-dir", "src/sections"));
-const OUT_FILE_EXPLICIT = args.includes("--out-file");
 const NEW_DEFAULT_OUT_FILE = ".deco/sections.gen.ts";
-const OLD_DEFAULT_OUT_FILE = "src/server/cms/sections.gen.ts";
 const outFile = path.resolve(process.cwd(), arg("out-file", NEW_DEFAULT_OUT_FILE));
-if (!OUT_FILE_EXPLICIT && fs.existsSync(path.resolve(process.cwd(), OLD_DEFAULT_OUT_FILE))) {
-  warnLegacyArtifact(OLD_DEFAULT_OUT_FILE, NEW_DEFAULT_OUT_FILE);
-}
 const EMIT_REGISTRY = args.includes("--registry");
 
 interface SectionMeta {
   eager?: boolean;
   neverDefer?: boolean;
+  deferred?: boolean;
   cache?: string;
   layout?: boolean;
   sync?: boolean;
   clientOnly?: boolean;
   seo?: boolean;
   hasLoadingFallback?: boolean;
+  renderJson?: false;
+  hasRenderJson?: boolean;
 }
 
-const EXPORT_CONST_RE = /export\s+const\s+(eager|neverDefer|cache|layout|sync|clientOnly|seo)\s*=\s*(.+?)(?:;|\n)/g;
+const EXPORT_CONST_RE = /export\s+const\s+(eager|neverDefer|deferred|cache|layout|sync|clientOnly|seo)\s*=\s*(.+?)(?:;|\n)/g;
+// renderJson (?renderJson mobile path). `= false` drops the section; a function
+// (`export const renderJson = (props) => ...` / `export function renderJson`)
+// projects its props. Kept separate from EXPORT_CONST_RE because the value is a
+// literal `false` OR a function, not the `= true` booleans that regex handles.
+const RENDER_JSON_FALSE_RE = /export\s+const\s+renderJson\s*=\s*false\b/;
+const RENDER_JSON_FN_INLINE_RE =
+  /export\s+(?:function\s+renderJson\b|const\s+renderJson\s*=\s*(?!false\b)\S)/;
+const RENDER_JSON_REEXPORT_RE = /export\s*\{[^}]*\brenderJson\b[^}]*\}/;
 // Detects `export function LoadingFallback(...)`, `export const LoadingFallback = ...`, etc.
 const LOADING_FALLBACK_INLINE_RE = /export\s+(?:function|const|let|var)\s+LoadingFallback\b/;
 // Detects re-exports like:
@@ -105,6 +106,14 @@ function extractMeta(content: string): SectionMeta | null {
     found = true;
   }
 
+  if (RENDER_JSON_FALSE_RE.test(content)) {
+    meta.renderJson = false;
+    found = true;
+  } else if (RENDER_JSON_FN_INLINE_RE.test(content) || RENDER_JSON_REEXPORT_RE.test(content)) {
+    meta.hasRenderJson = true;
+    found = true;
+  }
+
   return found ? meta : null;
 }
 
@@ -177,6 +186,8 @@ const lines: string[] = [
   "//   export const clientOnly = true  → skip SSR (client-only rendering)",
   "//   export const seo = true         → SEO section (provides page head data)",
   "//   export function LoadingFallback → skeleton shown while section loads",
+  "//   export const renderJson = false → drop section from ?renderJson (mobile)",
+  "//   export const renderJson = (p)=> → project props for ?renderJson (mobile)",
   "",
 ];
 
@@ -196,6 +207,16 @@ for (let i = 0; i < nonSyncFallbacks.length; i++) {
   lines.push(`import { LoadingFallback as _fb${i} } from "${importPath}";`);
 }
 
+// renderJson projection-function imports — sections whose renderJson is a
+// function (not `= false`) and aren't sync-imported.
+const renderJsonEntries = entries.filter((e) => e.meta.hasRenderJson);
+const nonSyncRenderJsons = renderJsonEntries.filter((e) => !e.meta.sync);
+for (let i = 0; i < nonSyncRenderJsons.length; i++) {
+  const e = nonSyncRenderJsons[i];
+  const importPath = relativeImportPath(outFile, e.filePath);
+  lines.push(`import { renderJson as _rj${i} } from "${importPath}";`);
+}
+
 lines.push("");
 
 // Metadata map
@@ -207,12 +228,15 @@ lines.push("");
 lines.push("export interface SectionMetaEntry {");
 lines.push("  eager?: boolean;");
 lines.push("  neverDefer?: boolean;");
+lines.push("  deferred?: boolean;");
 lines.push("  cache?: string;");
 lines.push("  layout?: boolean;");
 lines.push("  sync?: boolean;");
 lines.push("  clientOnly?: boolean;");
 lines.push("  seo?: boolean;");
 lines.push("  hasLoadingFallback?: boolean;");
+lines.push("  renderJson?: false;");
+lines.push("  hasRenderJson?: boolean;");
 lines.push("}");
 lines.push("");
 lines.push("export const sectionMeta: Record<string, SectionMetaEntry> = {");
@@ -256,6 +280,28 @@ if (allFallbacks.length > 0) {
 }
 lines.push("");
 
+// renderJson projection-functions map (?renderJson mobile path). `= false`
+// sections are NOT here — they carry `renderJson: false` in sectionMeta, which
+// applySectionConventions reads directly. Only projection functions need a live
+// reference. Typed `any` (like syncComponents) to avoid importing the RenderJson
+// type into the generated file.
+if (renderJsonEntries.length > 0) {
+  lines.push("export const renderJsons: Record<string, any> = {");
+  for (const e of renderJsonEntries) {
+    if (e.meta.sync) {
+      const syncIdx = syncEntries.indexOf(e);
+      lines.push(`  "${e.key}": _sync${syncIdx}.renderJson,`);
+    } else {
+      const rjIdx = nonSyncRenderJsons.indexOf(e);
+      lines.push(`  "${e.key}": _rj${rjIdx},`);
+    }
+  }
+  lines.push("};");
+} else {
+  lines.push("export const renderJsons: Record<string, any> = {};");
+}
+lines.push("");
+
 // Lazy section-import registry — opt-in via --registry, built from every
 // scanned section file (not just convention-carrying `entries`).
 if (EMIT_REGISTRY) {