@decocms/start 1.6.3 → 2.0.0

package/.releaserc.json

@@ -4,6 +4,7 @@
     ["@semantic-release/commit-analyzer", {
       "preset": "angular",
       "releaseRules": [
+        { "breaking": true, "release": "major" },
         { "type": "feat", "release": "minor" },
         { "type": "fix", "release": "patch" },
         { "type": "perf", "release": "patch" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "1.6.3",
+  "version": "2.0.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",

package/scripts/generate-loaders.ts

@@ -5,23 +5,31 @@
  *
  * Each loader/action file that exports a default function gets a generated
  * entry like:
- *   "site/loaders/SAP/getUser": async (props) => {
+ *   "site/loaders/SAP/getUser": async (props, request) => {
  *     const mod = await import("../../loaders/SAP/getUser");
- *     return mod.default(props);
+ *     return mod.default(props, request);
  *   },
  *
  * Both keyed with and without `.ts` suffix for CMS block compatibility.
  *
  * Files listed in --exclude are skipped (they need custom wiring in setup.ts).
  *
+ * CMS-aware filtering (`--decofile-dir`): when supplied, the script walks
+ * every JSON file in the directory and collects the set of `__resolveType`
+ * references. Only loaders whose key appears in that set are emitted —
+ * keeping the registry to what the site actually uses and avoiding the
+ * "200 dead passthroughs" pattern.
+ *
  * Usage (from site root):
  *   npx tsx node_modules/@decocms/start/scripts/generate-loaders.ts
+ *   npx tsx node_modules/@decocms/start/scripts/generate-loaders.ts --decofile-dir .deco/blocks
  *
  * CLI:
- *   --loaders-dir  override loaders input  (default: src/loaders)
- *   --actions-dir  override actions input  (default: src/actions)
- *   --out-file     override output         (default: src/server/cms/loaders.gen.ts)
- *   --exclude      comma-separated list of loader keys to skip (they have custom wiring)
+ *   --loaders-dir   override loaders input    (default: src/loaders)
+ *   --actions-dir   override actions input    (default: src/actions)
+ *   --out-file      override output           (default: src/server/cms/loaders.gen.ts)
+ *   --exclude       comma-separated list of loader keys to skip (they have custom wiring)
+ *   --decofile-dir  if provided, only emit entries whose key appears as `__resolveType` in any JSON
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -37,6 +45,8 @@ const actionsDir = path.resolve(process.cwd(), arg("actions-dir", "src/actions")
 const outFile = path.resolve(process.cwd(), arg("out-file", "src/server/cms/loaders.gen.ts"));
 const excludeRaw = arg("exclude", "");
 const excludeSet = new Set(excludeRaw.split(",").map((s) => s.trim()).filter(Boolean));
+const decofileDirRaw = arg("decofile-dir", "");
+const decofileDir = decofileDirRaw ? path.resolve(process.cwd(), decofileDirRaw) : null;
 
 function walkDir(dir: string): string[] {
   const results: string[] = [];
@@ -68,6 +78,48 @@ function hasDefaultExport(content: string): boolean {
   return /export\s+default\b/.test(content) || /export\s*\{[^}]*\bdefault\b/.test(content);
 }
 
+// ---------------------------------------------------------------------------
+// CMS-referenced loader discovery
+//
+// Walk every JSON file under decofileDir and collect the set of strings that
+// appear as `__resolveType` values. The migration script + generators emit
+// pass-throughs for every loader/action file on disk; without this filter,
+// 90%+ of those entries are dead code (the CMS never references them) and
+// they pollute the type system and bundle.
+// ---------------------------------------------------------------------------
+
+function collectResolveTypes(dir: string): Set<string> {
+  const found = new Set<string>();
+  if (!fs.existsSync(dir)) return found;
+
+  const RESOLVE_RE = /"__resolveType"\s*:\s*"([^"]+)"/g;
+
+  function visit(d: string) {
+    for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+      const fullPath = path.join(d, entry.name);
+      if (entry.isDirectory()) {
+        visit(fullPath);
+      } else if (entry.name.endsWith(".json")) {
+        const content = fs.readFileSync(fullPath, "utf-8");
+        let m: RegExpExecArray | null;
+        while ((m = RESOLVE_RE.exec(content)) !== null) {
+          found.add(m[1]);
+        }
+      }
+    }
+  }
+
+  visit(dir);
+  return found;
+}
+
+const cmsReferences = decofileDir ? collectResolveTypes(decofileDir) : null;
+
+function isReferenced(key: string): boolean {
+  if (!cmsReferences) return true;
+  return cmsReferences.has(key) || cmsReferences.has(`${key}.ts`);
+}
+
 // ---------------------------------------------------------------------------
 
 interface LoaderEntry {
@@ -76,12 +128,17 @@ interface LoaderEntry {
 }
 
 const entries: LoaderEntry[] = [];
+let prunedCount = 0;
 
 for (const filePath of walkDir(loadersDir)) {
   const content = fs.readFileSync(filePath, "utf-8");
   if (!hasDefaultExport(content)) continue;
   const key = fileToKey(filePath, loadersDir, "site/loaders");
   if (excludeSet.has(key) || excludeSet.has(`${key}.ts`)) continue;
+  if (!isReferenced(key)) {
+    prunedCount++;
+    continue;
+  }
   entries.push({
     key,
     importPath: relativeImportPath(outFile, filePath),
@@ -93,6 +150,10 @@ for (const filePath of walkDir(actionsDir)) {
   if (!hasDefaultExport(content)) continue;
   const key = fileToKey(filePath, actionsDir, "site/actions");
   if (excludeSet.has(key) || excludeSet.has(`${key}.ts`)) continue;
+  if (!isReferenced(key)) {
+    prunedCount++;
+    continue;
+  }
   entries.push({
     key,
     importPath: relativeImportPath(outFile, filePath),
@@ -108,17 +169,20 @@ const lines: string[] = [
   "// Pass-through loader/action entries for COMMERCE_LOADERS.",
   "// Custom-wired entries should be excluded via --exclude and added manually in setup.ts.",
   "",
-  "export const siteLoaders: Record<string, (props: any) => Promise<any>> = {",
+  "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) => {`);
+  lines.push(`  "${entry.key}": async (props: any, request?: Request) => {`);
   lines.push(`    const mod = await import("${entry.importPath}");`);
-  lines.push("    return mod.default(props);");
+  lines.push("    return (mod.default as any)(props, request);");
   lines.push("  },");
-  lines.push(`  "${entry.key}.ts": async (props: any) => {`);
+  lines.push(`  "${entry.key}.ts": async (props: any, request?: Request) => {`);
   lines.push(`    const mod = await import("${entry.importPath}");`);
-  lines.push("    return mod.default(props);");
+  lines.push("    return (mod.default as any)(props, request);");
   lines.push("  },");
 }
 
@@ -128,6 +192,9 @@ lines.push("");
 fs.mkdirSync(path.dirname(outFile), { recursive: true });
 fs.writeFileSync(outFile, lines.join("\n"));
 
+const filterNote = cmsReferences
+  ? ` (filtered against ${cmsReferences.size} CMS __resolveType references; pruned ${prunedCount} dead entries)`
+  : "";
 console.log(
-  `Generated ${entries.length} loader entries (${entries.length * 2} with .ts aliases) → ${path.relative(process.cwd(), outFile)}`,
+  `Generated ${entries.length} loader entries (${entries.length * 2} with .ts aliases) → ${path.relative(process.cwd(), outFile)}${filterNote}`,
 );

package/scripts/migrate/phase-analyze.ts

@@ -32,6 +32,10 @@ const PATTERN_DETECTORS: Array<[DetectedPattern, RegExp]> = [
   ["head-component", /<Head[\s>]/],
   ["define-app", /defineApp\(/],
   ["invoke-proxy", /proxy<Manifest/],
+  // Bagaggio-style HTMX dynamic-section loader. Both the source file and
+  // every call site need manual conversion to React state / createServerFn.
+  ["sections-component-loader", /sections\/Component\.tsx?$/m],
+  ["use-component", /import\s*\{[^}]*\buseComponent\b[^}]*\}\s*from\s*["'][^"']*sections\/Component(?:\.tsx?)?["']/],
 ];
 
 /** Files/dirs that should be completely skipped during scanning */
@@ -312,6 +316,25 @@ function decideAction(
     };
   }
 
+  // Bagaggio-style HTMX dynamic-section loader → delete and flag.
+  // The file uses Deno-only APIs (`toFileUrl(Deno.cwd())`, `import.meta.resolve`)
+  // and the `useComponent(component, props)` HTMX render-and-swap pattern, none
+  // of which work on TanStack Start / Cloudflare Workers. The site author must
+  // refactor every `useComponent(...)` call site to React state, `createServerFn`
+  // + `useMutation`, or a direct `~/server/invoke` call BEFORE this file is
+  // safe to remove.
+  if (
+    relPath === "sections/Component.tsx" ||
+    relPath === "sections/Component.ts"
+  ) {
+    return {
+      action: "delete",
+      notes:
+        "HTMX dynamic-section loader (useComponent) — incompatible with TanStack Start. " +
+        "Migrate every useComponent(...) call site to React state / createServerFn before deploy.",
+    };
+  }
+
   // Static code/tooling files → delete
   if (STATIC_DELETE.has(relPath)) {
     return { action: "delete", notes: "Code/tooling file, not an asset" };
@@ -637,6 +660,37 @@ export function analyze(ctx: MigrationContext): void {
   console.log(`  By category: ${JSON.stringify(byCategory)}`);
   console.log(`  By action: ${JSON.stringify(byAction)}`);
 
+  // Surface the HTMX dynamic-section loader and every `useComponent` call site
+  // up-front. These need manual conversion to React state / createServerFn before
+  // the migrated site will run on Cloudflare Workers — the analyzer cannot do
+  // it automatically, so it must be loud enough to land in the report.
+  const useComponentSites = ctx.files.filter(
+    (f) => f.patterns.includes("use-component"),
+  );
+  const componentLoaderFile = ctx.files.find(
+    (f) =>
+      f.path === "sections/Component.tsx" ||
+      f.path === "sections/Component.ts",
+  );
+  if (componentLoaderFile || useComponentSites.length > 0) {
+    console.log("\n  ⚠ HTMX dynamic-section loader detected (Bagaggio-style)");
+    if (componentLoaderFile) {
+      console.log(`    • ${componentLoaderFile.path} (will be deleted)`);
+    }
+    if (useComponentSites.length > 0) {
+      console.log(`    • ${useComponentSites.length} useComponent(...) call site(s) need manual conversion:`);
+      for (const f of useComponentSites.slice(0, 10)) {
+        console.log(`        - ${f.path}`);
+      }
+      if (useComponentSites.length > 10) {
+        console.log(`        ... and ${useComponentSites.length - 10} more`);
+      }
+    }
+    console.log(
+      "    See: deco-to-tanstack-migration skill, 'useComponent / partial sections' section",
+    );
+  }
+
   // Run analyzers
   extractSectionMetadata(ctx);
   classifyIslands(ctx);

package/scripts/migrate/phase-cleanup.ts

@@ -20,7 +20,10 @@ const ROOT_FILES_TO_DELETE = [
   "tailwind.css",
   "tailwind.config.ts",
   "runtime.ts",
-  "constants.ts",
+  // NOTE: `constants.ts` is intentionally NOT deleted here — it holds
+  //   site-specific UI constants (form/drawer IDs, header heights, etc.)
+  //   that components reference via `~/constants` or `../../constants`.
+  //   We move it to `src/constants.ts` instead — see `moveRootConstantsToSrc`.
   "fresh.gen.ts",
   "manifest.gen.ts",
   "fresh.config.ts",
@@ -1251,6 +1254,94 @@ function normalizeImportCasing(ctx: MigrationContext) {
   });
 }
 
+/**
+ * Move root-level `constants.ts` → `src/constants.ts`.
+ *
+ * Old stack: a root-level `constants.ts` exporting site-wide UI constants
+ * (MINICART_FORM_ID, SIDEMENU_DRAWER_ID, HEADER_HEIGHT, USER_ID, etc.) that
+ * components reference via `../../constants` or `~/constants`.
+ *
+ * Without this step, `phase-cleanup` deletes the file and the build fails
+ * with `Could not resolve "../../constants"` from many components. The CMS
+ * doesn't reference these IDs, so a 1:1 file move is sufficient.
+ *
+ * If `src/constants.ts` already exists (rare — usually means the migration
+ * was re-run), we leave it alone.
+ */
+function moveRootConstantsToSrc(ctx: MigrationContext) {
+  const rootPath = path.join(ctx.sourceDir, "constants.ts");
+  const srcPath = path.join(ctx.sourceDir, "src", "constants.ts");
+
+  if (!fs.existsSync(rootPath)) return;
+  if (fs.existsSync(srcPath)) {
+    log(ctx, `Skipped move: src/constants.ts already exists; deleting root constants.ts`);
+    if (!ctx.dryRun) fs.unlinkSync(rootPath);
+    ctx.deletedFiles.push("constants.ts");
+    return;
+  }
+
+  if (ctx.dryRun) {
+    log(ctx, `[DRY] Would move: constants.ts → src/constants.ts`);
+    ctx.movedFiles.push({ from: "constants.ts", to: "src/constants.ts" });
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(srcPath), { recursive: true });
+  fs.renameSync(rootPath, srcPath);
+  ctx.movedFiles.push({ from: "constants.ts", to: "src/constants.ts" });
+  log(ctx, `Moved: constants.ts → src/constants.ts`);
+}
+
+/**
+ * Rewrite the legacy multi-platform `loaders/minicart.ts` file.
+ *
+ * Old stack: `loaders/minicart.ts` runtime-dispatches on `usePlatform()` to
+ * platform-specific loaders under `sdk/cart/{vtex,vnda,wake,linx,shopify,nuvemshop}/loader.ts`.
+ * The cleanup phase already deletes `sdk/cart/` entirely, leaving the loader
+ * with broken imports.
+ *
+ * New stack: the canonical Minicart contract + VTEX transform live in
+ * `@decocms/apps/vtex/inline-loaders/minicart`. We replace the loader with a
+ * thin VTEX-only re-export. Sites on Shopify/VNDA/Wake/Linx/Nuvemshop are
+ * not currently in production on the new stack — when one is, swap this for
+ * a runtime dispatcher again or add a platform-flagged rewrite.
+ */
+function rewriteMinicartLoader(ctx: MigrationContext) {
+  const candidates = [
+    path.join(ctx.sourceDir, "src", "loaders", "minicart.ts"),
+    path.join(ctx.sourceDir, "loaders", "minicart.ts"),
+  ];
+
+  for (const filePath of candidates) {
+    if (!fs.existsSync(filePath)) continue;
+
+    const content = fs.readFileSync(filePath, "utf-8");
+    // Only rewrite if it actually imports the legacy multi-platform sdk/cart layout.
+    const isLegacyLoader = /from\s+["'](?:~|\.\.?)\/sdk\/cart\/(?:vtex|vnda|wake|linx|shopify|nuvemshop)\/loader["']/
+      .test(content);
+    if (!isLegacyLoader) continue;
+
+    const newContent = `// VTEX-only minicart loader.
+//
+// The legacy site shipped per-platform loaders behind a \`usePlatform()\`
+// switch (vnda, wake, linx, shopify, nuvemshop). The canonical minicart
+// contract now lives in \`@decocms/apps\`. Until a non-VTEX customer comes
+// online on the new stack, we re-export the framework loader directly.
+// TODO: when adding another platform, replace this with a runtime
+// dispatcher and import the matching framework loader.
+export { default } from "@decocms/apps/vtex/inline-loaders/minicart";
+export type { MinicartProps } from "@decocms/apps/vtex/inline-loaders/minicart";
+`;
+
+    if (ctx.dryRun) {
+      log(ctx, `[DRY] Would rewrite: ${path.relative(ctx.sourceDir, filePath)} (VTEX-only re-export)`);
+    } else {
+      fs.writeFileSync(filePath, newContent);
+      log(ctx, `Rewrote: ${path.relative(ctx.sourceDir, filePath)} (VTEX-only re-export of @decocms/apps/vtex/inline-loaders/minicart)`);
+    }
+  }
+}
+
 /**
  * Fix APIs that don't exist in Cloudflare Workers:
  * - window.setTimeout → setTimeout
@@ -1367,6 +1458,19 @@ export function cleanup(ctx: MigrationContext): void {
   console.log("  Rewriting VTEX utility imports → ~/lib/ wrappers...");
   rewriteVtexUtilImports(ctx);
 
+  // 11a. Preserve root-level constants.ts (site-wide UI IDs/heights) by
+  //    moving it to src/constants.ts. The cleanup phase used to delete it
+  //    unconditionally, breaking every component that imports `~/constants`.
+  console.log("  Moving root constants.ts → src/constants.ts...");
+  moveRootConstantsToSrc(ctx);
+
+  // 11b. Rewrite legacy multi-platform minicart loader → VTEX-only re-export.
+  //    `sdk/cart/` is deleted by DIRS_TO_DELETE, leaving loaders/minicart.ts
+  //    with broken imports. Replace it with a thin re-export of the
+  //    framework's @decocms/apps/vtex/inline-loaders/minicart loader.
+  console.log("  Rewriting loaders/minicart.ts → VTEX-only re-export...");
+  rewriteMinicartLoader(ctx);
+
   // 12. Fix useVariantPossiblities omit set
   console.log("  Fixing useVariantPossiblities omit set...");
   fixVariantOmitSet(ctx);

package/scripts/migrate/phase-transform.ts

@@ -126,6 +126,48 @@ export function transform(ctx: MigrationContext): void {
       });
     }
 
+    // Flag the legacy sections/Component.tsx dynamic-section loader.
+    // This file uses Deno-specific APIs (toFileUrl, import.meta.resolve)
+    // and the HTMX-driven `useComponent(component, props)` pattern, which
+    // do not run on Cloudflare Workers and have no equivalent in
+    // @decocms/start. The whole file must be deleted.
+    if (
+      /sections\/Component\.tsx?$/.test(record.path) ||
+      /sections\/Component\.tsx?$/.test(targetPath)
+    ) {
+      ctx.manualReviewItems.push({
+        file: targetPath,
+        reason:
+          "sections/Component.tsx (Deno HTMX dynamic-section loader) is incompatible with TanStack Start / Cloudflare Workers. " +
+          "DELETE this file and migrate every `useComponent(...)` call site to one of: " +
+          "(a) local React state for client-side toggles, " +
+          "(b) `createServerFn` + `useMutation` for server actions, or " +
+          "(c) a direct `invoke` call (`~/server/invoke`) for ad-hoc loaders. " +
+          "See: deco-to-tanstack-migration skill, 'useComponent / partial sections' section.",
+        severity: "error",
+      });
+    }
+
+    // Flag any import of useComponent — typically `import { useComponent } from "site/sections/Component.tsx"`.
+    // We also catch `from "../../sections/Component"` and similar relative variants.
+    if (
+      /\buseComponent\b/.test(result.content) &&
+      /from\s+["'][^"']*sections\/Component(?:\.tsx?)?["']/.test(result.content)
+    ) {
+      ctx.manualReviewItems.push({
+        file: targetPath,
+        reason:
+          "useComponent({ ... }) call site detected. This is the HTMX-style dynamic-section render pattern " +
+          "that ships HTML fragments and swaps them client-side. It does not work on TanStack Start. " +
+          "Recipes: " +
+          "(1) Self-contained UI toggles → keep state in React (`useState` + event handlers); " +
+          "(2) Form submissions / mutations → `createServerFn` + `useMutation` (see casaevideo-storefront for canonical examples); " +
+          "(3) Ad-hoc data fetches → call the loader/action via `~/server/invoke` and store results in `useState`. " +
+          "Remove the import after refactoring, then delete `src/sections/Component.tsx`.",
+        severity: "error",
+      });
+    }
+
     if (ctx.dryRun) {
       if (result.changed) {
         log(ctx, `[DRY] Would transform: ${record.path} → ${targetPath}`);

package/scripts/migrate/templates/commerce-loaders.ts

@@ -83,7 +83,7 @@ export function generateCommerceLoaders(ctx: MigrationContext): string {
     lines.push(``);
   }
 
-  lines.push(`export const COMMERCE_LOADERS: Record<string, (props: any) => Promise<any>> = {`);
+  lines.push(`export const COMMERCE_LOADERS: Record<string, (props: any, request?: Request) => Promise<any>> = {`);
 
   if (ctx.platform === "vtex") {
     lines.push(`  ...vtexLoaders,`);

package/scripts/migrate/templates/section-loaders.ts

@@ -156,7 +156,10 @@ export function generateSectionLoaders(ctx: MigrationContext): string {
       const importPath = `~/` + meta.path.replace(/\.tsx?$/, "");
       entries.push(`  "${sectionKey}": async (props: any, req: Request) => {`);
       entries.push(`    const mod = await import("${importPath}");`);
-      entries.push(`    if (typeof mod.loader === "function") return mod.loader(props, req);`);
+      // Cast to any: legacy Fresh/Deno section loaders are typed `(props, req, ctx)`.
+      // We invoke with 2 args; any ctx-dependent code path inside the loader will throw
+      // at runtime and must be refactored — the migration phase-transform flags these.
+      entries.push(`    if (typeof mod.loader === "function") return (mod.loader as any)(props, req);`);
       entries.push(`    return props;`);
       entries.push(`  },`);
     }

package/scripts/migrate/types.ts

@@ -61,7 +61,9 @@ export type DetectedPattern =
   | "asset-function"
   | "head-component"
   | "define-app"
-  | "invoke-proxy";
+  | "invoke-proxy"
+  | "use-component"
+  | "sections-component-loader";
 
 /** Metadata extracted from a section file during analysis */
 export interface SectionMeta {

package/src/cms/resolve.ts

@@ -228,7 +228,18 @@ function isBot(userAgent?: string): boolean {
   return botPatterns.some((re) => re.test(userAgent));
 }
 
-export type CommerceLoader = (props: any) => Promise<any>;
+/**
+ * A loader registered against a `__resolveType` key. The runtime invokes it
+ * through two paths:
+ *
+ * 1. CMS resolution (`commerceLoader(resolvedProps)`) — 1-arg call.
+ * 2. `/deco/invoke/...` endpoint — `(props, request)` 2-arg call.
+ *
+ * Loaders that need the `Request` (cookies, geo, headers) declare the second
+ * parameter; pure loaders ignore it. This shape lets a single registry serve
+ * both invocation paths without `as any` casts at every wrapper.
+ */
+export type CommerceLoader = (props: any, request?: Request) => Promise<any>;
 
 /**
  * Context passed through the resolution pipeline.

package/src/sdk/useScript.ts

@@ -137,13 +137,34 @@ export function inlineScript(js: string) {
 }
 
 /**
- * Stub -- Deco partial sections don't apply in TanStack Start.
- * Returns the provided props as-is.
+ * @deprecated Removed in TanStack Start.
+ *
+ * The Fresh/Deno HTMX-based partial-section pattern (`useSection` /
+ * `usePartialSection` + `sections/Component.tsx`) does not apply on
+ * Cloudflare Workers and React. Replace call-sites with one of:
+ *
+ *   1. Local React state (`useState` + event handlers) for client-side toggles.
+ *   2. `createServerFn` + `useMutation` for server actions.
+ *   3. Direct `invoke` calls (`~/server/invoke`) for ad-hoc loaders.
+ *
+ * See: deco-to-tanstack-migration skill, "useComponent / partial sections"
+ * section, for the per-pattern recipes.
+ *
+ * Both stubs throw at runtime (and at import time, if you call them at
+ * module top level) so legacy code surfaces a clear error instead of a
+ * silent no-op.
  */
-export function usePartialSection(props?: Record<string, unknown>) {
-  return props || {};
+const DEPRECATION_MESSAGE =
+  "[@decocms/start] useSection / usePartialSection were removed. " +
+  "The Fresh/Deno HTMX partial-section pattern does not apply on " +
+  "TanStack Start / Cloudflare Workers. Replace call-sites with " +
+  "createServerFn + useMutation, or local React state. See the " +
+  "deco-to-tanstack-migration skill for per-pattern recipes.";
+
+export function usePartialSection(_props?: Record<string, unknown>): never {
+  throw new Error(DEPRECATION_MESSAGE);
 }
 
-export function useSection(_props?: Record<string, unknown>) {
-  return "";
+export function useSection(_props?: Record<string, unknown>): never {
+  throw new Error(DEPRECATION_MESSAGE);
 }

package/src/sdk/workerEntry.ts

@@ -34,7 +34,7 @@ import {
 } from "./cacheHeaders";
 import { buildHtmlShell } from "./htmlShell";
 import { cleanPathForCacheKey } from "./urlUtils";
-import { isMobileUA } from "./useDevice";
+import { type Device, isMobileUA } from "./useDevice";
 import { getRenderShellConfig } from "../admin/setup";
 import { RequestContext } from "./requestContext";
 import { getAppMiddleware } from "./setupApps";
@@ -88,7 +88,16 @@ interface ServerEntry {
  * cache entry; different segments get different cached responses.
  */
 export interface SegmentKey {
-  device: "mobile" | "desktop";
+  /**
+   * Device class derived from the request User-Agent.
+   *
+   * Accepts the full `Device` union (`"mobile" | "desktop" | "tablet"`) so
+   * that callers can pass `detectDevice(...)` directly without manual
+   * narrowing. Sites that want to share cache entries between mobile and
+   * tablet can collapse the value at the call site (e.g.
+   * `device === "tablet" ? "mobile" : device`).
+   */
+  device: Device;
   /** Whether the user is logged in (e.g., has a valid auth cookie). */
   loggedIn?: boolean;
   /** Commerce sales channel / price list. */

package/src/setup.ts

@@ -96,7 +96,7 @@ export interface SiteSetupOptions {
 	 * { getCommerceLoaders: () => COMMERCE_LOADERS }
 	 * ```
 	 */
-	getCommerceLoaders?: () => Record<string, (props: any) => Promise<any>>;
+	getCommerceLoaders?: () => Record<string, (props: any, request?: Request) => Promise<any>>;
 }
 
 /**