npm - @decocms/start - Versions diffs - 0.24.0 → 0.25.0 - Mend

@decocms/start 0.24.0 → 0.25.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/.cursor/skills/deco-cms-route-config/SKILL.md +181 -50
package/.cursor/skills/deco-start-architecture/cms-resolution.md +76 -0
package/.cursor/skills/deco-tanstack-storefront-patterns/SKILL.md +115 -0
package/.cursor/skills/deco-to-tanstack-migration/SKILL.md +9 -5
package/package.json +1 -1
package/src/admin/invoke.ts +14 -1
package/src/cms/index.ts +6 -0
package/src/cms/resolve.ts +195 -0
package/src/routes/cmsRoute.ts +179 -21
package/src/routes/index.ts +2 -0

package/.cursor/skills/deco-cms-route-config/SKILL.md CHANGED Viewed

@@ -45,44 +45,24 @@ import { createFileRoute } from "@tanstack/react-router";
 import { cmsRouteConfig, loadDeferredSection } from "@decocms/start/routes";
 import { DecoPageRenderer } from "@decocms/start/hooks";
 import type { ResolvedSection, DeferredSection } from "@decocms/start/cms";
-import type { CacheProfile } from "@decocms/start/sdk/cacheHeaders";
-import { cacheHeaders, routeCacheDefaults } from "@decocms/start/sdk/cacheHeaders";
 const routeConfig = cmsRouteConfig({
   siteName: "My Store",
   defaultTitle: "My Store - Default Title",
+  defaultDescription: "My Store — best products with the best prices.",
   ignoreSearchParams: ["skuId"],
 });
 type PageData = {
   resolvedSections: ResolvedSection[];
   deferredSections: DeferredSection[];
-  cacheProfile: CacheProfile;
   name: string;
   path: string;
   params: Record<string, string>;
 } | null;
 export const Route = createFileRoute("/$")({
-  ...routeCacheDefaults("listing"),
-  loaderDeps: routeConfig.loaderDeps,
-  loader: routeConfig.loader as any,
-  headers: ({ loaderData }) => {
-    const data = loaderData as PageData;
-    return cacheHeaders(data?.cacheProfile ?? "listing");
-  },
-  head: ({ loaderData }) => {
-    const data = loaderData as PageData;
-    return {
-      meta: [
-        {
-          title: data?.name
-            ? `${data.name} | My Store`
-            : "My Store - Default Title",
-        },
-      ],
-    };
-  },
+  ...routeConfig,
   component: CmsPage,
   notFoundComponent: NotFoundPage,
 });
@@ -105,15 +85,17 @@ function CmsPage() {
 }
 ```
-**CRITICAL**: The `...routeCacheDefaults("listing")` spread is essential. Without it, every SPA navigation triggers a full server re-fetch even when the data was just loaded seconds ago. This is the most common cause of perceived slow navigation.
+**CRITICAL**: `cmsRouteConfig` already includes `routeCacheDefaults("product")`, cache headers, and full SEO head metadata. Spread the entire config — do NOT cherry-pick individual fields.
 ### `cmsRouteConfig` Options
 ```typescript
 interface CmsRouteOptions {
-  siteName: string;        // Used in page title: "Page Name | siteName"
-  defaultTitle: string;    // Fallback title when CMS page has no name
-  ignoreSearchParams?: string[];  // Search params excluded from loaderDeps
+  siteName: string;              // Used in page title: "Page Name | siteName"
+  defaultTitle: string;          // Fallback title when CMS page has no name
+  defaultDescription?: string;   // Fallback description when no SEO section contributes one
+  ignoreSearchParams?: string[]; // Search params excluded from loaderDeps (default: ["skuId"])
+  pendingComponent?: () => any;  // Skeleton shown during SPA navigation
 }
 ```
@@ -160,17 +142,23 @@ The `cacheProfile` is determined by `detectCacheProfile(basePath)` inside `loadC
 | `/cart`, `/checkout` | private | none |
 | Everything else | listing | 2 min |
-### Head/SEO
+### Head/SEO — Automatic from CMS `page.seo` + Section Registry
-```typescript
-head: ({ loaderData }) => ({
-  meta: [
-    { title: loaderData?.pageName
-        ? `${loaderData.pageName} | ${siteName}`
-        : defaultTitle },
-  ],
-}),
-```
+The framework's `buildHead()` function generates full `<head>` metadata from two sources:
+**Primary: `page.seo` field** — The top-level `seo` block in CMS page JSONs is resolved eagerly by `resolvePageSeoBlock()`. Lazy/Deferred wrappers are always unwrapped (SEO must never be deferred for crawlers). Commerce loaders within the seo block are resolved (e.g., PDP product data). Section loaders transform the resolved props into standard SEO fields.
+**Secondary: Registered SEO sections** — Sections in `page.sections` registered via `registerSeoSections()` contribute SEO as a fallback. Page-level `page.seo` always takes precedence.
+Generated tags:
+- `<title>` from page.seo → section SEO → page name + siteName → defaultTitle
+- `<meta name="description">` from page.seo → section SEO → defaultDescription
+- `<link rel="canonical">` from page.seo canonical
+- `<meta property="og:*">` Open Graph tags (title, description, image, type, url)
+- `<meta name="twitter:*">` Twitter Card tags
+- `<meta name="robots">` noindex/nofollow when `noIndexing: true`
+Title/description templates from the CMS (e.g., `"%s | STORE NAME"`) are applied automatically. The `head()` function is built into `cmsRouteConfig` — sites do NOT need to implement their own.
 ---
@@ -187,22 +175,20 @@ import { cmsHomeRouteConfig, loadDeferredSection } from "@decocms/start/routes";
 import { DecoPageRenderer } from "@decocms/start/hooks";
 import type { ResolvedSection, DeferredSection } from "@decocms/start/cms";
-const homeConfig = cmsHomeRouteConfig({
-  defaultTitle: "My Store - Homepage",
-});
-type HomeData = {
-  resolvedSections: ResolvedSection[];
-  deferredSections: DeferredSection[];
-} | null;
 export const Route = createFileRoute("/")({
-  ...homeConfig,
+  ...cmsHomeRouteConfig({
+    defaultTitle: "My Store - Homepage",
+    defaultDescription: "My Store — best products with the best prices.",
+    siteName: "My Store",
+  }),
   component: HomePage,
 });
 function HomePage() {
-  const data = Route.useLoaderData() as HomeData;
+  const data = Route.useLoaderData() as {
+    resolvedSections: ResolvedSection[];
+    deferredSections: DeferredSection[];
+  } | null;
   if (!data) return null;
   return (
@@ -216,13 +202,16 @@ function HomePage() {
 }
 ```
-`cmsHomeRouteConfig` already includes `routeCacheDefaults("static")` and `cacheHeaders("static")`, giving the homepage a 5-min client staleTime and 24h edge TTL. Do NOT add additional cache config.
+`cmsHomeRouteConfig` already includes `routeCacheDefaults("static")`, `cacheHeaders("static")`, and full SEO head metadata. Do NOT add additional cache or head config.
 ### `cmsHomeRouteConfig` Options
 ```typescript
 interface CmsHomeRouteOptions {
   defaultTitle: string;
+  defaultDescription?: string;   // Fallback description
+  siteName?: string;             // For OG title composition (defaults to defaultTitle)
+  pendingComponent?: () => any;
 }
 ```
@@ -289,17 +278,30 @@ TanStack Router injects internal properties (`id`, `path`) that conflict if the
 ```typescript
 // @decocms/start/routes
 export {
-  cmsRouteConfig,        // Catch-all CMS route config factory
-  cmsHomeRouteConfig,    // Homepage route config factory
+  cmsRouteConfig,        // Catch-all CMS route config factory (includes full SEO head)
+  cmsHomeRouteConfig,    // Homepage route config factory (includes full SEO head)
   loadCmsPage,           // Server function for CMS page resolution
   loadCmsHomePage,       // Server function for homepage resolution
+  loadDeferredSection,   // Server function for on-scroll section loading
   type CmsRouteOptions,
+  type PageSeo,          // SEO data type extracted from sections
+  type Device,           // Device type: "mobile" | "tablet" | "desktop"
   CmsPage,              // Generic CMS page component
   NotFoundPage,         // Generic 404 component
   decoMetaRoute,        // Admin meta route config
   decoRenderRoute,      // Admin render route config
   decoInvokeRoute,      // Admin invoke route config
 };
+// @decocms/start/cms
+export {
+  registerSeoSections,    // Register section keys that contribute page SEO (secondary source)
+  extractSeoFromProps,    // Extract SEO fields from any section's props
+  extractSeoFromSections, // Extract SEO from registered sections (used internally)
+  resolvePageSeoBlock,    // Resolve page.seo CMS block eagerly (used internally)
+  type PageSeo,           // { title, description, canonical, image, noIndexing, jsonLDs, type }
+  // ... all existing exports
+};
 ```
 Add to `package.json` exports:
@@ -346,6 +348,135 @@ The root route contains site-specific elements that should NOT be in the framewo
 - Font loading
 - Theme configuration
 - QueryClient setup
+- **Default description and OG site_name/locale** — root-level `head()` should include fallback `<meta name="description">`, `og:site_name`, and `og:locale`. Child routes (from `cmsRouteConfig`) override these when section SEO provides better values.
+```typescript
+// src/routes/__root.tsx
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      { title: "My Store - Default Title" },
+      { name: "description", content: "My Store — default description for all pages." },
+      { property: "og:site_name", content: "My Store" },
+      { property: "og:locale", content: "pt_BR" },
+    ],
+    links: [
+      { rel: "stylesheet", href: appCss },
+      { rel: "icon", href: "/favicon.ico" },
+    ],
+  }),
+  component: RootLayout,
+});
+```
+**Do NOT include a `Device.Provider` with hardcoded values.** For client-side device detection, use `useSyncExternalStore` + `window.matchMedia`. For server-side, use section loaders via `registerSectionLoaders` (they receive the request and can detect UA).
+---
+## SEO Architecture
+SEO in @decocms/start works across four layers:
+### 1. CMS `page.seo` Block (primary source)
+CMS page JSONs have a top-level `seo` field separate from `sections`. This is the **primary** SEO data source, processed by `resolvePageSeoBlock()` in `resolve.ts`.
+**Key behavior: Lazy/Deferred wrappers are always unwrapped.** SEO metadata must be in the initial SSR HTML for crawlers. The original Fresh/Deno framework did NOT do this, causing PDP pages to have zero SSR SEO when `page.seo` was wrapped in `Lazy.tsx`. We fix this by design.
+Resolution pipeline:
+1. Unwrap Lazy/Deferred (unlimited depth)
+2. Follow named block references
+3. Evaluate multivariate flags
+4. Resolve all nested `__resolveType` (commerce loaders for product data)
+5. Return `ResolvedSection` in `DecoPageResult.seoSection`
+In `cmsRoute.ts`, the seoSection is enriched by its section loader, then:
+- `extractSeoFromProps()` picks title/description/canonical/image/noIndexing/jsonLDs/type
+- `titleTemplate` / `descriptionTemplate` from the CMS block are applied (e.g., `"%s | STORE NAME"`)
+### 2. Page-Level Meta (framework `head()`)
+`cmsRouteConfig` and `cmsHomeRouteConfig` generate `<head>` metadata automatically from the merged `PageSeo` object (page.seo primary + sections secondary). Includes title, description, canonical, OG (title, description, image, type, url), Twitter Card, and robots.
+### 3. Section-Contributed SEO (secondary source, `registerSeoSections`)
+Sections in `page.sections` that also contribute SEO metadata register themselves in `setup.ts`:
+```typescript
+import { registerSeoSections } from "@decocms/start/cms";
+registerSeoSections([
+  "site/sections/SEOPDP.tsx",     // Product structured data + meta
+  "site/sections/SEOPLP.tsx",     // Category/search meta
+]);
+```
+These sections must have a **section loader** that returns props with SEO fields:
+```typescript
+interface PageSeo {
+  title?: string;
+  description?: string;
+  canonical?: string;
+  image?: string;
+  noIndexing?: boolean;
+  jsonLDs?: Record<string, any>[];
+  type?: string;    // og:type: "website", "product", etc.
+}
+```
+After `runSectionLoaders`, the framework scans registered SEO sections and extracts these fields. Page.seo fields take precedence when both sources provide the same field.
+### 4. Structured Data (section component)
+JSON-LD (`<script type="application/ld+json">`) is rendered by the section component itself — NOT in `<head>`. The section receives `jsonLDs` in its props and renders them:
+```typescript
+// src/components/ui/Seo.tsx
+export default function Seo({ jsonLDs }: Props) {
+  if (!jsonLDs?.length) return null;
+  return (
+    <>
+      {jsonLDs.map((jsonLD, i) => (
+        <script
+          key={i}
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLD) }}
+        />
+      ))}
+    </>
+  );
+}
+```
+### SEO Data Flow
+```
+CMS Page JSON
+  ├─ page.sections[] → resolveDecoPage → runSectionLoaders
+  │    → extractSeoFromSections() (secondary SEO source)
+  │
+  └─ page.seo → resolvePageSeoBlock (unwrap Lazy, resolve commerce loaders)
+       → runSingleSectionLoader (SEOPDP transforms jsonLD → title/desc/etc.)
+       → extractSeoFromProps() → apply titleTemplate/descriptionTemplate
+       → PRIMARY PageSeo
+  Merged PageSeo = { ...sectionSeo, ...pageSeo }
+  → cmsRouteConfig head() → emits <title>, <meta>, <link>, OG, Twitter, robots
+  → Section component renders JSON-LD in page body
+```
+### Checklist for New Sites
+1. **`__root.tsx`**: Include fallback `description`, `og:site_name`, `og:locale`
+2. **`$.tsx` / `index.tsx`**: Pass `siteName`, `defaultTitle`, `defaultDescription` to `cmsRouteConfig` / `cmsHomeRouteConfig`
+3. **`setup.ts`**: Register section loaders for any site SEO sections (e.g., SEOPDP) that appear in `page.seo` CMS blocks
+4. **`setup.ts`**: Optionally call `registerSeoSections([...])` for sections in `page.sections` that contribute SEO
+5. **`Seo.tsx`**: Component renders JSON-LD (NOT meta tags — framework handles those)
+6. **Device**: Use `matchMedia` for client-side, section loaders for server-side — NO hardcoded `Device.Provider`
+7. **CMS audit**: Verify PDP `page.seo` blocks are NOT wrapped in `Lazy.tsx` with no inner section — the framework unwraps Lazy, but the inner section must exist
 ---

package/.cursor/skills/deco-start-architecture/cms-resolution.md CHANGED Viewed

@@ -190,6 +190,82 @@ import { addSkipResolveType } from "@decocms/start/cms";
 addSkipResolveType("custom/loaders/myCustomLoader.ts");
 ```
+### Page-Level SEO Resolution (`page.seo`)
+CMS page JSONs have a top-level `seo` field separate from `sections`:
+```json
+{
+  "name": "Home",
+  "path": "/",
+  "sections": [ ... ],
+  "seo": {
+    "__resolveType": "website/sections/Seo/SeoV2.tsx",
+    "title": "My Store",
+    "description": "Best prices",
+    "canonical": "https://example.com/",
+    "jsonLDs": [{ "@type": "Organization", ... }],
+    "titleTemplate": "%s",
+    "descriptionTemplate": "%s",
+    "type": "website"
+  }
+}
+```
+For PDP pages, `page.seo` is often wrapped in `Lazy.tsx` with a commerce loader:
+```json
+{
+  "seo": {
+    "__resolveType": "website/sections/Rendering/Lazy.tsx",
+    "section": {
+      "__resolveType": "site/sections/SEOPDP.tsx",
+      "jsonLD": { "__resolveType": "Intelligent Search PDP Loader" },
+      "titleTemplate": "%s | STORE NAME",
+      "descriptionTemplate": "%s | STORE NAME"
+    }
+  }
+}
+```
+`resolvePageSeoBlock()` handles this by:
+1. **Always unwrapping Lazy/Deferred** — SEO must never be deferred for crawlers
+2. Following named block references and multivariate flags
+3. Resolving all nested `__resolveType` props (commerce loaders for PDP product data)
+4. Returning a `ResolvedSection` with the component key and resolved props
+The result is stored in `DecoPageResult.seoSection` and processed in `cmsRoute.ts`:
+1. Run the registered section loader (e.g., SEOPDP transforms `{jsonLD: ProductDetailsPage}` → `{title, description, canonical, image, jsonLDs}`)
+2. Extract `PageSeo` fields via `extractSeoFromProps()`
+3. Apply `titleTemplate`/`descriptionTemplate` from the CMS config (e.g., `"%s | STORE NAME"`)
+4. Merge with section-contributed SEO (page.seo is primary, sections are secondary)
+```typescript
+interface PageSeo {
+  title?: string;
+  description?: string;
+  canonical?: string;
+  image?: string;
+  noIndexing?: boolean;
+  jsonLDs?: Record<string, any>[];
+  type?: string;  // og:type: "website", "product", etc.
+}
+```
+`buildHead()` in `cmsRouteConfig` generates full `<head>` metadata from `PageSeo`: `<title>`, `<meta name="description">`, `<link rel="canonical">`, Open Graph (including `og:url`, `og:type`), Twitter Card, and robots directives.
+### SEO Section Registry (secondary source)
+Sections in `page.sections` that also contribute SEO metadata are registered via `registerSeoSections()`:
+```typescript
+registerSeoSections(["site/sections/SEOPDP.tsx"]);
+```
+`extractSeoFromSections()` scans registered sections and extracts SEO fields. This is the **secondary** source — `page.seo` always takes precedence when both are present.
+Note: PLP and search pages typically lack a `page.seo` field. For these, `cmsRouteConfig` falls back to composing a title from the page name and `siteName` option.
 ### PostHog Matchers (`matchers/posthog.ts`)
 Server-side PostHog feature flag evaluation:

package/.cursor/skills/deco-tanstack-storefront-patterns/SKILL.md CHANGED Viewed

@@ -997,11 +997,126 @@ export default defineConfig({
 ---
+## 25. SEO Architecture — Three Layers
+### Problem
+Sites migrated from Fresh/Deno often have broken SEO:
+- `Seo.tsx` component returns `null` (dead stub from migration)
+- Route `head()` functions only set `<title>`, missing description/canonical/OG
+- No JSON-LD structured data on PDPs
+- No Open Graph tags for social sharing
+### Solution — Framework + Section + Component
+**Layer 1: Framework head()** (`cmsRouteConfig` / `cmsHomeRouteConfig`)
+Automatically emits title, description, canonical, OG, Twitter Card, robots from `DecoPageResult.seo`. Requires `defaultDescription` option and `registerSeoSections()` in setup.
+**Layer 2: Section SEO** (`registerSeoSections` + `registerSectionLoaders`)
+Sections like SEOPDP register as SEO contributors. Their section loader computes title/description/canonical from commerce data (product name, product description, breadcrumb canonical). The framework extracts these into `PageSeo`.
+**Layer 3: Structured data** (section component renders JSON-LD)
+The `Seo.tsx` component renders `<script type="application/ld+json">` for Product, WebSite, BreadcrumbList schemas. Meta tags are NOT rendered here — the framework handles those via `head()`.
+### Setup Checklist
+```typescript
+// setup.ts
+import { registerSeoSections } from "@decocms/start/cms";
+registerSeoSections(["site/sections/SEOPDP.tsx"]);
+// Also register the SEOPDP section loader:
+registerSectionLoaders({
+  "site/sections/SEOPDP.tsx": async (props, req) => {
+    const mod = await import("./sections/SEOPDP");
+    return mod.loader(props, req, { seo: {} } as any) ?? props;
+  },
+});
+```
+```typescript
+// routes/$.tsx — spread full config, framework handles SEO
+const routeConfig = cmsRouteConfig({
+  siteName: "My Store",
+  defaultTitle: "My Store - Default Title",
+  defaultDescription: "My Store — best products...",
+  ignoreSearchParams: ["skuId"],
+});
+export const Route = createFileRoute("/$")({ ...routeConfig, component: CmsPage });
+```
+```typescript
+// __root.tsx — fallback description and OG globals
+head: () => ({
+  meta: [
+    { charSet: "utf-8" },
+    { name: "viewport", content: "width=device-width, initial-scale=1" },
+    { title: "My Store - Default Title" },
+    { name: "description", content: "My Store — default description." },
+    { property: "og:site_name", content: "My Store" },
+    { property: "og:locale", content: "pt_BR" },
+  ],
+}),
+```
+### Anti-Patterns
+- `Seo.tsx` returning `null` — must render JSON-LD at minimum
+- Custom `head()` in routes that only sets title — use `cmsRouteConfig` which handles full SEO
+- Hardcoded Device.Provider — use matchMedia for client, section loaders for server
+---
+## 26. Device Detection — No Hardcoded Provider
+### Problem
+Sites often have `<Device.Provider value={{ isMobile: false }}>` in `__root.tsx`, making ALL client-side components think they're on desktop regardless of actual viewport.
+### Solution — Two-Layer Detection
+**Server-side**: Section loaders via `registerSectionLoaders()` detect device from UA and inject `isMobile` / `device` as props. The page result also includes `device` for client use.
+**Client-side**: Use `useSyncExternalStore` + `window.matchMedia` instead of React context:
+```typescript
+// contexts/device.tsx
+import { useSyncExternalStore } from "react";
+const MOBILE_QUERY = "(max-width: 767px)";
+function subscribe(cb: () => void) {
+  if (typeof window === "undefined") return () => {};
+  const mql = window.matchMedia(MOBILE_QUERY);
+  mql.addEventListener("change", cb);
+  return () => mql.removeEventListener("change", cb);
+}
+function getSnapshot() { return window.matchMedia(MOBILE_QUERY).matches; }
+function getServerSnapshot() { return false; }
+export const useDevice = () => {
+  const isMobile = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  return { isMobile };
+};
+```
+### Why matchMedia > UA context
+- Reflects actual viewport, not a server guess
+- Reactive — updates if user resizes browser
+- No Provider needed — works anywhere in the component tree
+- SSR defaults to desktop (false), hydrates to real value
+---
 ## Related Skills
 | Skill | Purpose |
 |-------|---------|
 | `deco-to-tanstack-migration` | Initial migration playbook (imports, signals, architecture) |
+| `deco-cms-route-config` | Route config, SEO architecture, device detection |
 | `deco-tanstack-navigation` | SPA navigation patterns (`<Link>`, `useNavigate`, `loaderDeps`) |
 | `deco-islands-migration` | Eliminating the `src/islands/` directory |
 | `deco-edge-caching` | Edge caching with `createDecoWorkerEntry` |

package/.cursor/skills/deco-to-tanstack-migration/SKILL.md CHANGED Viewed

@@ -235,6 +235,7 @@ See: skill `deco-islands-migration`
 6. Wire `onBeforeResolve()` → `initVtexFromBlocks()` for VTEX config
 7. Configure `setAsyncRenderingConfig()` with `alwaysEager` for critical sections
 8. Configure admin: `setMetaData()`, `setRenderShell()`, `setInvokeLoaders()`
+9. **Register SEO sections via `registerSeoSections()`** — identify sections that produce title/description/canonical (typically SEOPDP, SEOPLP). Register their loaders in `registerSectionLoaders` too.
 **Template**: `templates/setup-ts.md`
@@ -250,15 +251,17 @@ See: skill `deco-async-rendering-site-guide`
 **Actions**:
 1. Create `src/router.tsx` with scroll restoration
-2. Create `src/routes/__root.tsx` with QueryClient, LiveControls, NavigationProgress, analytics
-3. Create `src/routes/index.tsx` using `cmsHomeRouteConfig()`
-4. Create `src/routes/$.tsx` using `cmsRouteConfig()`
+2. Create `src/routes/__root.tsx` with QueryClient, LiveControls, NavigationProgress, analytics. **Include fallback `description`, `og:site_name`, `og:locale` in root `head()`.** Do NOT include a hardcoded `Device.Provider`.
+3. Create `src/routes/index.tsx` using `cmsHomeRouteConfig({ defaultTitle, defaultDescription, siteName })`
+4. Create `src/routes/$.tsx` using `cmsRouteConfig({ siteName, defaultTitle, defaultDescription })` — spread the full config, do NOT cherry-pick fields. The framework handles SEO head, cache headers, and staleTime/gcTime.
+5. **Create/port `Seo.tsx` component** — must render JSON-LD structured data (NOT return null). Meta tags are handled by the framework's `head()`.
+6. **Port device detection** — use `useSyncExternalStore` + `matchMedia` for client-side. Use `registerSectionLoaders` for server-side UA detection. Do NOT use a hardcoded `Device.Provider`.
 **Templates**: `templates/root-route.md`, `templates/router.md`
-**Exit**: Routes compile, CMS pages resolve
+**Exit**: Routes compile, CMS pages resolve, PDPs have JSON-LD + meta description in `<head>`
-See: skill `deco-tanstack-navigation`
+See: skills `deco-tanstack-navigation`, `deco-cms-route-config`
 ---
@@ -566,6 +569,7 @@ The conductor approach that worked (836 errors → 0 across 213 files) treated e
 | deco-apps-vtex-porting | Understanding VTEX loader internals (Phase 4-5) |
 | deco-islands-migration | Eliminating islands/ (Phase 6) |
 | deco-async-rendering-site-guide | Lazy wrappers, LoadingFallback (Phase 7, 10) |
+| deco-cms-route-config | Route config, SEO architecture, device detection (Phase 7-8) |
 | deco-tanstack-navigation | Link, prefetch, scroll issues (Phase 8) |
 | deco-edge-caching | Worker caching, cache profiles (Phase 9) |
 | deco-tanstack-hydration-fixes | Hydration mismatches post-migration |

package/package.json CHANGED Viewed

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

package/src/admin/invoke.ts CHANGED Viewed

@@ -126,6 +126,13 @@ export async function handleInvoke(request: Request): Promise<Response> {
     try {
       const result = await found.handler(body, request);
+      // Response passthrough: if the loader/action returns a Response object,
+      // forward it as-is (preserving headers like Set-Cookie). This matches
+      // deco-cx/deco's invokeToHttpResponse behavior where auth loaders return
+      // Response objects with Set-Cookie headers for HttpOnly cookies.
+      if (result instanceof Response) {
+        return result;
+      }
       const filtered = selectFields(result, select);
       return new Response(JSON.stringify(filtered), { status: 200, headers: JSON_HEADERS });
     } catch (error) {
@@ -145,7 +152,13 @@ export async function handleInvoke(request: Request): Promise<Response> {
         if (found) {
           try {
-            const result = await found.handler(payload, request);
+            let result = await found.handler(payload, request);
+            // If a loader returns a Response, extract its JSON body for batching.
+            // Set-Cookie headers from batch items are not forwarded individually
+            // (use single invoke for auth loaders that need cookie passthrough).
+            if (result instanceof Response) {
+              try { result = await result.json(); } catch { result = null; }
+            }
             results[key] = selectFields(result, select);
           } catch (error) {
             results[key] = { error: (error as Error).message };

package/src/cms/index.ts CHANGED Viewed

@@ -30,19 +30,25 @@ export type {
   DecoPageResult,
   DeferredSection,
   MatcherContext,
+  PageSeo,
   ResolvedSection,
   ResolveErrorHandler,
 } from "./resolve";
 export {
   addSkipResolveType,
   evaluateMatcher,
+  extractSeoFromProps,
+  extractSeoFromSections,
   getAsyncRenderingConfig,
+  isSeoSection,
   onBeforeResolve,
   registerBotPattern,
   registerCommerceLoader,
   registerCommerceLoaders,
   registerMatcher,
+  registerSeoSections,
   resolveDecoPage,
+  resolvePageSeoBlock,
   resolveDeferredSection,
   resolveValue,
   setAsyncRenderingConfig,

package/src/cms/resolve.ts CHANGED Viewed

@@ -615,6 +615,104 @@ async function resolveRawSection(
   return results;
 }
+// ---------------------------------------------------------------------------
+// Page-level SEO block resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the page-level `seo` field from the CMS page JSON.
+ *
+ * The CMS stores SEO config in `page.seo` as a separate field from
+ * `page.sections`. This field is typically a SeoV2.tsx block (homepage)
+ * or a site SEO section like SEOPDP.tsx wrapped in Lazy (PDP).
+ *
+ * This function always resolves eagerly — SEO metadata must never be
+ * deferred because search engine crawlers need it in the initial HTML.
+ * Lazy/Deferred wrappers are unwrapped, block references are followed,
+ * and commerce loader refs (e.g. PDP jsonLD) are resolved.
+ *
+ * Returns a ResolvedSection with the final component key and resolved props,
+ * or null if the seo field is absent/unresolvable.
+ */
+export async function resolvePageSeoBlock(
+  seoBlock: Record<string, unknown> | undefined,
+  rctx: ResolveContext,
+): Promise<ResolvedSection | null> {
+  if (!seoBlock || typeof seoBlock !== "object") return null;
+  const blocks = loadBlocks();
+  let current = seoBlock;
+  for (let depth = 0; depth < 10; depth++) {
+    const rt = current.__resolveType as string | undefined;
+    if (!rt) return null;
+    // Lazy wrapper — always unwrap for SEO (never defer)
+    if (rt === "website/sections/Rendering/Lazy.tsx") {
+      const inner = current.section;
+      if (!inner || typeof inner !== "object") return null;
+      current = inner as Record<string, unknown>;
+      continue;
+    }
+    // Deferred wrapper — unwrap
+    if (rt === "website/sections/Rendering/Deferred.tsx") {
+      const inner = current.sections;
+      if (!inner || typeof inner !== "object") return null;
+      if (Array.isArray(inner) && inner.length === 1 && inner[0] && typeof inner[0] === "object") {
+        current = inner[0] as Record<string, unknown>;
+        continue;
+      }
+      return null;
+    }
+    // Multivariate flag — evaluate matcher and follow matched variant
+    if (
+      rt === "website/flags/multivariate.ts" ||
+      rt === "website/flags/multivariate/section.ts"
+    ) {
+      const variants = current.variants as Array<{ value: unknown; rule?: unknown }> | undefined;
+      if (!variants?.length) return null;
+      let matched: unknown = null;
+      for (const variant of variants) {
+        const rule = variant.rule as Record<string, unknown> | undefined;
+        if (evaluateMatcher(rule, rctx.matcherCtx)) {
+          matched = variant.value;
+          break;
+        }
+      }
+      if (!matched || typeof matched !== "object") return null;
+      current = matched as Record<string, unknown>;
+      continue;
+    }
+    // Named block reference — follow the chain
+    const block = blocks[rt] as Record<string, unknown> | undefined;
+    if (block) {
+      const { __resolveType: _, ...overrides } = current;
+      current = { ...block, ...overrides };
+      continue;
+    }
+    // Terminal section (site section or framework SEO type).
+    // Resolve all nested prop __resolveType refs (commerce loaders, etc.).
+    const { __resolveType: _, ...rawProps } = current;
+    try {
+      const resolvedProps = await resolveProps(rawProps, rctx);
+      return {
+        component: rt,
+        props: resolvedProps as Record<string, unknown>,
+        key: `seo:${rt}`,
+      };
+    } catch (e) {
+      onResolveError(e, rt, "Page SEO resolution");
+      return null;
+    }
+  }
+  return null;
+}
 /**
  * Check if a raw CMS section block will produce a layout section.
  * Walks the block reference chain (up to 5 levels) to find the final
@@ -960,12 +1058,94 @@ async function resolveSectionsList(
   return [];
 }
+// ---------------------------------------------------------------------------
+// Page-level SEO — extracted from registered SEO sections after resolution
+// ---------------------------------------------------------------------------
+export interface PageSeo {
+  title?: string;
+  description?: string;
+  canonical?: string;
+  image?: string;
+  noIndexing?: boolean;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  jsonLDs?: Record<string, any>[];
+  /** Open Graph type — "website" (default), "product", etc. */
+  type?: string;
+}
+const seoSectionKeys: Set<string> = G.__deco.seoSections ?? (G.__deco.seoSections = new Set());
+/**
+ * Register section component keys whose resolved props contribute page-level
+ * SEO metadata (title, description, canonical, image, jsonLDs, noIndexing).
+ *
+ * After section loaders run, the framework scans these sections and extracts
+ * their SEO fields into `DecoPageResult.seo`, which `cmsRouteConfig` uses
+ * to generate `<head>` metadata (meta tags, OG, canonical, robots).
+ *
+ * JSON-LD structured data stays in the section props for the section
+ * component to render as `<script type="application/ld+json">`.
+ */
+export function registerSeoSections(keys: string[]): void {
+  for (const k of keys) seoSectionKeys.add(k);
+}
+/** Check if a section key is registered as an SEO section. */
+export function isSeoSection(key: string): boolean {
+  return seoSectionKeys.has(key);
+}
+/**
+ * Pick standard SEO fields from a props object.
+ * Works for both framework SEO types (SeoV2) and site SEO sections (SEOPDP).
+ */
+export function extractSeoFromProps(props: Record<string, unknown>): PageSeo {
+  const seo: PageSeo = {};
+  if (props.title) seo.title = props.title as string;
+  if (props.description) seo.description = props.description as string;
+  if (props.canonical) seo.canonical = props.canonical as string;
+  if (props.image) seo.image = props.image as string;
+  if (props.noIndexing !== undefined) seo.noIndexing = props.noIndexing as boolean;
+  if (props.type) seo.type = props.type as string;
+  if (Array.isArray(props.jsonLDs) && props.jsonLDs.length) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    seo.jsonLDs = props.jsonLDs as Record<string, any>[];
+  }
+  return seo;
+}
+/**
+ * Extract SEO metadata from resolved sections registered via
+ * `registerSeoSections`. Later sections override earlier ones
+ * (e.g., a PDP SEO section overrides a generic page SEO).
+ */
+export function extractSeoFromSections(sections: ResolvedSection[]): PageSeo {
+  const seo: PageSeo = {};
+  for (const section of sections) {
+    if (!seoSectionKeys.has(section.component)) continue;
+    const extracted = extractSeoFromProps(section.props);
+    if (extracted.jsonLDs) {
+      extracted.jsonLDs = [...(seo.jsonLDs ?? []), ...extracted.jsonLDs];
+    }
+    Object.assign(seo, extracted);
+  }
+  return seo;
+}
 export interface DecoPageResult {
   name: string;
   path: string;
   params: Record<string, string>;
   resolvedSections: ResolvedSection[];
   deferredSections: DeferredSection[];
+  /**
+   * Resolved SEO block from the page-level `seo` field in the CMS JSON.
+   * Contains the section component key and resolved props (with commerce
+   * loader data already fetched). Needs section loader enrichment in
+   * cmsRoute before SEO fields can be extracted.
+   */
+  seoSection?: ResolvedSection | null;
 }
 export async function resolveDecoPage(
@@ -1072,12 +1252,27 @@ export async function resolveDecoPage(
   const allResults = await Promise.all(eagerResults);
+  // Resolve page-level SEO block (page.seo field) — always eager.
+  // Runs after sections to benefit from memoized commerce loader results.
+  let seoSection: ResolvedSection | null = null;
+  if (page.seo) {
+    try {
+      seoSection = await resolvePageSeoBlock(
+        page.seo as Record<string, unknown>,
+        rctx,
+      );
+    } catch (e) {
+      onResolveError(e, "page.seo", "Page SEO block resolution");
+    }
+  }
   return {
     name: page.name,
     path: page.path || targetPath,
     params,
     resolvedSections: allResults.flat(),
     deferredSections,
+    seoSection,
   };
 }

package/src/routes/cmsRoute.ts CHANGED Viewed

@@ -30,8 +30,13 @@ import {
 } from "@tanstack/react-start/server";
 import { createElement } from "react";
 import { preloadSectionComponents } from "../cms/registry";
-import type { DeferredSection, MatcherContext, ResolvedSection } from "../cms/resolve";
-import { resolveDecoPage, resolveDeferredSection } from "../cms/resolve";
+import type { DeferredSection, MatcherContext, PageSeo, ResolvedSection } from "../cms/resolve";
+import {
+  extractSeoFromProps,
+  extractSeoFromSections,
+  resolveDecoPage,
+  resolveDeferredSection,
+} from "../cms/resolve";
 import { runSectionLoaders, runSingleSectionLoader } from "../cms/sectionLoaders";
 import {
   type CacheProfile,
@@ -40,6 +45,7 @@ import {
   routeCacheDefaults,
 } from "../sdk/cacheHeaders";
 import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
+import { type Device, detectDevice } from "../sdk/useDevice";
 const isServer = typeof document === "undefined";
@@ -87,12 +93,23 @@ async function loadCmsPageInternal(fullPath: string) {
   await preloadSectionComponents(eagerKeys);
   const cacheProfile = detectCacheProfile(basePath);
+  const ua = getRequestHeader("user-agent") ?? "";
+  const device = detectDevice(ua);
+  // Build SEO: merge page-level seo block (primary) with section-contributed SEO (secondary)
+  const seo = await buildPageSeo(page.seoSection, enrichedSections, request);
+  // Destructure seoSection out — it's an internal artifact, not serialized to client
+  const { seoSection: _seo, ...pageData } = page;
   return {
-    ...page,
+    ...pageData,
     resolvedSections: normalizeUrlsInObject(enrichedSections),
     deferredSections: normalizeUrlsInObject(page.deferredSections),
     cacheProfile,
     pageUrl: urlWithSearch,
+    seo,
+    device,
   };
 }
@@ -116,8 +133,9 @@ export const loadCmsPage = createServerFn({ method: "GET" })
  */
 export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async () => {
   const request = getRequest();
+  const ua = getRequestHeader("user-agent") ?? "";
   const matcherCtx: MatcherContext = {
-    userAgent: getRequestHeader("user-agent") ?? "",
+    userAgent: ua,
     url: getRequestUrl().toString(),
     path: "/",
     cookies: getCookies(),
@@ -130,10 +148,17 @@ export const loadCmsHomePage = createServerFn({ method: "GET" }).handler(async (
   const eagerKeys = enrichedSections.map((s) => s.component);
   await preloadSectionComponents(eagerKeys);
+  const device = detectDevice(ua);
+  const seo = await buildPageSeo(page.seoSection, enrichedSections, request);
+  const { seoSection: _seo, ...pageData } = page;
   return {
-    ...page,
+    ...pageData,
     resolvedSections: normalizeUrlsInObject(enrichedSections),
     deferredSections: normalizeUrlsInObject(page.deferredSections),
+    seo,
+    device,
   };
 });
@@ -208,6 +233,8 @@ export interface CmsRouteOptions {
   siteName: string;
   /** Default page title when CMS page has no name. */
   defaultTitle: string;
+  /** Default description for pages without section-contributed SEO. */
+  defaultDescription?: string;
   /**
    * Search params to exclude from loader deps.
    * These params won't trigger a server re-fetch when they change.
@@ -218,15 +245,148 @@ export interface CmsRouteOptions {
   pendingComponent?: () => any;
 }
+type CmsPageLoaderData = {
+  name?: string;
+  cacheProfile?: CacheProfile;
+  seo?: PageSeo;
+  device?: Device;
+} | null;
+// ---------------------------------------------------------------------------
+// Page SEO assembly — merges page.seo block with section-contributed SEO
+// ---------------------------------------------------------------------------
+/**
+ * Process the resolved SEO section from page.seo, run its section loader
+ * if registered, apply title/description templates, and merge with
+ * section-contributed SEO.
+ */
+async function buildPageSeo(
+  seoSection: ResolvedSection | null | undefined,
+  enrichedSections: ResolvedSection[],
+  request: Request,
+): Promise<PageSeo> {
+  // Secondary source: SEO sections embedded in the sections array
+  const sectionSeo = extractSeoFromSections(enrichedSections);
+  if (!seoSection) return sectionSeo;
+  // Run the section loader on the seo section if one is registered
+  // (e.g., SEOPDP loader transforms {jsonLD: ProductDetailsPage} → {title, description, ...})
+  let enrichedProps = seoSection.props;
+  try {
+    const enriched = await runSingleSectionLoader(seoSection, request);
+    if (enriched) enrichedProps = enriched.props;
+  } catch {
+    // Section loader failed — use the raw resolved props
+  }
+  const pageSeo = extractSeoFromProps(enrichedProps);
+  // Apply title/description templates from the SEO block config.
+  // SeoV2 blocks carry templates like "%s | CASA & VIDEO" that wrap
+  // the computed title. Template "%s" is a no-op.
+  const rawProps = seoSection.props;
+  const titleTemplate = rawProps.titleTemplate as string | undefined;
+  const descTemplate = rawProps.descriptionTemplate as string | undefined;
+  if (titleTemplate && titleTemplate !== "%s" && pageSeo.title) {
+    pageSeo.title = titleTemplate.replace("%s", pageSeo.title);
+  }
+  if (descTemplate && descTemplate !== "%s" && pageSeo.description) {
+    pageSeo.description = descTemplate.replace("%s", pageSeo.description);
+  }
+  // Primary source (page.seo) overrides secondary (section-contributed).
+  // Only truthy fields in pageSeo override — undefined keys don't clear sectionSeo.
+  return { ...sectionSeo, ...pageSeo };
+}
+// ---------------------------------------------------------------------------
+// Head metadata builder
+// ---------------------------------------------------------------------------
+/**
+ * Build TanStack Router `head()` metadata from page-level and section-contributed SEO.
+ * Emits: title, description, canonical, OG tags, Twitter Card, robots directive.
+ */
+function buildHead(
+  loaderData: CmsPageLoaderData | undefined,
+  siteName: string,
+  defaultTitle: string,
+  defaultDescription?: string,
+) {
+  const seo = loaderData?.seo;
+  const title = seo?.title
+    ? seo.title
+    : loaderData?.name
+      ? `${loaderData.name} | ${siteName}`
+      : defaultTitle;
+  const description = seo?.description || defaultDescription;
+  const image = seo?.image;
+  const canonical = seo?.canonical;
+  const noIndex = seo?.noIndexing;
+  const meta: Record<string, string>[] = [{ title }];
+  if (description) {
+    meta.push({ name: "description", content: description });
+  }
+  // Robots
+  if (noIndex) {
+    meta.push({ name: "robots", content: "noindex, nofollow" });
+  }
+  // Open Graph
+  meta.push({ property: "og:title", content: title });
+  if (description) meta.push({ property: "og:description", content: description });
+  if (image) meta.push({ property: "og:image", content: image });
+  meta.push({ property: "og:type", content: seo?.type || "website" });
+  if (canonical) meta.push({ property: "og:url", content: canonical });
+  // Twitter Card
+  meta.push({ name: "twitter:card", content: image ? "summary_large_image" : "summary" });
+  meta.push({ name: "twitter:title", content: title });
+  if (description) meta.push({ name: "twitter:description", content: description });
+  if (image) meta.push({ name: "twitter:image", content: image });
+  const links: Record<string, string>[] = [];
+  if (canonical) {
+    links.push({ rel: "canonical", href: canonical });
+  }
+  // JSON-LD structured data — rendered as <script type="application/ld+json"> in <head>
+  const scripts: Array<{ type: string; children: string }> = [];
+  if (seo?.jsonLDs?.length) {
+    for (const jsonLD of seo.jsonLDs) {
+      scripts.push({
+        type: "application/ld+json",
+        children: JSON.stringify(jsonLD),
+      });
+    }
+  }
+  return { meta, links, scripts };
+}
 /**
  * Returns a TanStack Router route config object for a CMS catch-all route.
  * Spread the result into your `createFileRoute("/$")({...})` call.
  *
- * Includes: loaderDeps, loader, headers, head, staleTime/gcTime.
+ * Includes: loaderDeps, loader, headers, head (with full SEO), staleTime/gcTime.
  * Does NOT include: component, notFoundComponent (site provides these).
+ *
+ * SEO metadata is extracted from sections registered via `registerSeoSections()`.
+ * The `head()` function emits title, description, canonical, OG tags, and robots.
  */
 export function cmsRouteConfig(options: CmsRouteOptions) {
-  const { siteName, defaultTitle, ignoreSearchParams = ["skuId"], pendingComponent } = options;
+  const {
+    siteName,
+    defaultTitle,
+    defaultDescription,
+    ignoreSearchParams = ["skuId"],
+    pendingComponent,
+  } = options;
   const ignoreSet = new Set(ignoreSearchParams);
@@ -253,9 +413,6 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
         : "";
       const page = await loadCmsPage({ data: basePath + searchStr });
-      // On the client (SPA navigation or initial hydration), pre-import
-      // eager section modules BEFORE React renders. This ensures
-      // getResolvedComponent() returns a value and we skip React.lazy.
       if (!isServer && page?.resolvedSections) {
         const keys = page.resolvedSections.map((s: ResolvedSection) => s.component);
         await preloadSectionComponents(keys);
@@ -267,29 +424,31 @@ export function cmsRouteConfig(options: CmsRouteOptions) {
     ...routeCacheDefaults("product"),
-    headers: ({ loaderData }: { loaderData?: { cacheProfile?: CacheProfile } }) => {
+    headers: ({ loaderData }: { loaderData?: CmsPageLoaderData }) => {
       const profile = loaderData?.cacheProfile ?? "listing";
       return cacheHeaders(profile);
     },
-    head: ({ loaderData }: { loaderData?: { name?: string } }) => ({
-      meta: [
-        {
-          title: loaderData?.name ? `${loaderData.name} | ${siteName}` : defaultTitle,
-        },
-      ],
-    }),
+    head: ({ loaderData }: { loaderData?: CmsPageLoaderData }) =>
+      buildHead(loaderData, siteName, defaultTitle, defaultDescription),
   };
 }
 /**
  * Returns a TanStack Router route config for the CMS homepage route.
  * Spread into `createFileRoute("/")({...})`.
+ *
+ * Like `cmsRouteConfig`, emits full SEO head metadata from section-contributed data.
  */
 export function cmsHomeRouteConfig(options: {
   defaultTitle: string;
+  defaultDescription?: string;
+  /** Site name for OG title composition. Defaults to defaultTitle. */
+  siteName?: string;
   pendingComponent?: () => any;
 }) {
+  const { defaultTitle, defaultDescription, siteName } = options;
   return {
     loader: async () => {
       const page = await loadCmsHomePage();
@@ -302,8 +461,7 @@ export function cmsHomeRouteConfig(options: {
     ...(options.pendingComponent ? { pendingComponent: options.pendingComponent } : {}),
     ...routeCacheDefaults("static"),
     headers: () => cacheHeaders("static"),
-    head: () => ({
-      meta: [{ title: options.defaultTitle }],
-    }),
+    head: ({ loaderData }: { loaderData?: CmsPageLoaderData }) =>
+      buildHead(loaderData, siteName ?? defaultTitle, defaultTitle, defaultDescription),
   };
 }

package/src/routes/index.ts CHANGED Viewed

@@ -13,3 +13,5 @@ export {
   loadDeferredSection,
 } from "./cmsRoute";
 export { CmsPage, NotFoundPage } from "./components";
+export type { PageSeo } from "../cms/resolve";
+export type { Device } from "../sdk/useDevice";