@decocms/start 2.28.1 → 2.29.0

package/README.md

@@ -1,124 +1,219 @@
-# @decocms/start 
+# @decocms/start
 
 [![npm version](https://img.shields.io/npm/v/@decocms/start.svg)](https://www.npmjs.com/package/@decocms/start)
 [![license](https://img.shields.io/npm/l/@decocms/start.svg)](https://github.com/decocms/deco-start/blob/main/LICENSE)
 
-Framework layer for [Deco](https://deco.cx) storefronts built on **TanStack Start + React 19 + Cloudflare Workers**.
+Framework layer for [deco.cx](https://deco.cx) storefronts on **TanStack Start + React 19 + Cloudflare Workers**.
 
-Provides CMS block resolution, admin protocol handlers, section rendering, schema generation, edge caching, and SDK utilities. This is **not** a storefront — it's the npm package that storefronts depend on.
+`@decocms/start` is the npm package that storefronts depend on. It provides the CMS bridge, admin protocol, section registry, schema generation, edge caching, the Vite plugin, and a small SDK. It is **not** itself a storefront — it is what storefronts build on top of.
 
-## Install
+📖 **[Read the full documentation →](https://docs.deco.cx/v2/en/getting-started/overview)**
+
+---
+
+## What's in the box
 
-```bash
-npm install @decocms/start
+```
+┌─────────────────────────────────────────────────┐
+│   Site repo (your storefront)                    │  ← Components, sections, routes
+├─────────────────────────────────────────────────┤
+│   @decocms/apps  (commerce integrations)         │  ← VTEX, Shopify, Resend
+├─────────────────────────────────────────────────┤
+│   @decocms/start  (framework — this package)     │  ← CMS bridge, admin, caching
+└─────────────────────────────────────────────────┘
+              ↓ runs on ↓
+   TanStack Start  +  React 19  +  Cloudflare Workers
 ```
 
-## Architecture
+`@decocms/start` exports cover four surfaces:
+
+- **Worker entry** — `createDecoWorkerEntry` wraps your Cloudflare Worker with admin routes, edge cache, and asset bypass.
+- **CMS bridge** — `loadCmsPage`, `resolveDecoPage`, `registerSectionLoaders`, `registerLayoutSections`.
+- **Admin protocol** — `handleMeta`, `handleDecofile`, `handleRender`, `handleInvoke`.
+- **SDK** — `createCachedLoader`, `createInstrumentedFetch`, `createInvoke`, `decoVitePlugin`, plus utilities (cookies, redirects, sitemap, A/B testing).
+
+Full export reference: [docs.deco.cx/v2/en/reference/package-exports](https://docs.deco.cx/v2/en/reference/package-exports).
+
+---
+
+## Hello, World
+
+A minimal v2 storefront has six files. Here they are.
+
+### `package.json`
+
+```jsonc
+{
+  "name": "my-store",
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "deploy": "wrangler deploy"
+  },
+  "dependencies": {
+    "@decocms/start": "^2.28.0",
+    "@decocms/apps": "^1.11.0",
+    "@tanstack/react-start": "^1.166.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "vite": "^6.0.0",
+    "wrangler": "^4.72.0"
+  }
+}
+```
 
+### `vite.config.ts`
+
+```ts
+import { defineConfig } from "vite";
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import react from "@vitejs/plugin-react";
+import decoVitePlugin from "@decocms/start/vite";
+
+export default defineConfig({
+  plugins: [
+    cloudflare({ viteEnvironment: { name: "ssr" } }),
+    tanstackStart({ server: { entry: "server" } }),
+    react({ babel: { plugins: ["babel-plugin-react-compiler"] } }),
+    decoVitePlugin(),
+  ],
+  resolve: {
+    alias: { "~": "/src" },
+    deduplicate: ["react", "react-dom", "@decocms/start", "@decocms/apps"],
+  },
+});
 ```
-@decocms/start        ← Framework (this package)
-  └─ @decocms/apps    ← Commerce integrations (VTEX, Shopify)
-       └─ site repo   ← UI components, routes, styles
+
+### `wrangler.jsonc`
+
+```jsonc
+{
+  "name": "my-store",
+  "main": "./src/worker-entry.ts",
+  "compatibility_date": "2026-02-14",
+  "compatibility_flags": [
+    "nodejs_compat",
+    "no_handle_cross_request_promise_resolution"
+  ],
+  "assets": { "directory": "./dist/client" }
+}
+```
+
+### `src/setup.ts`
+
+```ts
+import { createSiteSetup } from "@decocms/start/setup";
+import { applySectionConventions } from "@decocms/start/cms";
+
+import blocks from "./server/cms/blocks.gen";
+import sectionsGen from "./server/cms/sections.gen";
+import meta from "./server/cms/meta.gen.json";
+
+createSiteSetup({
+  sections: import.meta.glob("./sections/**/*.tsx", { eager: true }),
+  blocks,
+  meta: () => meta,
+  productionOrigins: ["https://my-store.com"],
+});
+
+applySectionConventions(sectionsGen);
 ```
 
-### Package Exports
-
-| Import | Purpose |
-|--------|---------|
-| `@decocms/start` | Barrel export |
-| `@decocms/start/cms` | Block loading, page resolution, section registry |
-| `@decocms/start/admin` | Admin protocol (meta, decofile, invoke, render, schema) |
-| `@decocms/start/hooks` | DecoPageRenderer, LiveControls, LazySection |
-| `@decocms/start/routes` | CMS route config, admin routes |
-| `@decocms/start/middleware` | Observability, deco state, liveness probe |
-| `@decocms/start/sdk/workerEntry` | Cloudflare Worker entry with edge caching |
-| `@decocms/start/sdk/cacheHeaders` | URL-to-profile cache detection |
-| `@decocms/start/sdk/cachedLoader` | In-flight dedup for loaders |
-| `@decocms/start/sdk/useScript` | Inline `<script>` with minification |
-| `@decocms/start/sdk/useDevice` | SSR-safe device detection |
-| `@decocms/start/sdk/analytics` | Analytics event types |
-| `@decocms/start/matchers/*` | Feature flag matchers (PostHog, built-ins) |
-| `@decocms/start/types` | Section, App, FnContext type definitions |
-| `@decocms/start/scripts/*` | Code generation (blocks, schema, invoke) |
-
-### Worker Entry Request Flow
+### `src/worker-entry.ts`
+
+```ts
+import "./setup";   // MUST be first
+
+import { createDecoWorkerEntry } from "@decocms/start/sdk/workerEntry";
+import {
+  handleMeta,
+  handleDecofile,
+  handleRender,
+  handleInvoke,
+} from "@decocms/start/admin";
+import serverEntry from "./server";
 
+export default createDecoWorkerEntry(serverEntry, {
+  admin: { handleMeta, handleDecofile, handleRender, handleInvoke },
+});
 ```
-Request → createDecoWorkerEntry()
- ├─ Admin routes (/live/_meta, /.decofile, /deco/render, /deco/invoke)
- ├─ Cache purge check
- ├─ Static asset bypass (/assets/*, favicon)
- ├─ Cloudflare edge cache (profile-based TTLs)
- └─ TanStack Start server entry
+
+### `src/routes/$.tsx`
+
+```tsx
+import { createFileRoute } from "@tanstack/react-router";
+import { cmsRouteConfig } from "@decocms/start/routes";
+
+export const Route = createFileRoute("/$")(
+  cmsRouteConfig({ siteName: "my-store" }),
+);
 ```
 
-### Edge Cache Profiles
+That is the entire skeleton. `npm install`, `npm run dev`, point `admin.deco.cx` at it, and you have a working CMS-driven site.
 
-| URL Pattern | Profile | Edge TTL |
-|-------------|---------|----------|
-| `/` | static | 1 day |
-| `*/p` | product | 5 min |
-| `/s`, `?q=` | search | 60s |
-| `/cart`, `/checkout` | private | none |
-| Everything else | listing | 2 min |
+For commerce integrations (VTEX, Shopify) see [`@decocms/apps`](https://www.npmjs.com/package/@decocms/apps).
 
-## Migrating from Fresh/Preact/Deno
+---
 
-`@decocms/start` includes an Agent Skill that handles migration for you. It works with Claude Code, Cursor, Codex, and other AI coding tools. Install the skill, open your Fresh storefront, and tell the AI to migrate:
+## Migrating from Fresh / Preact / Deno
+
+`@decocms/start` ships an Agent Skill that handles the migration for you. It works with Claude Code, Cursor, Codex, and any tool that supports skills.
 
 ```bash
 npx skills add decocms/deco-start
 ```
 
-Then open your project in any supported tool and say:
+Then, in your editor, point at your Fresh storefront and prompt:
 
 > migrate this project to TanStack Start
 
-The skill handles compatibility checking, import rewrites, config generation, section registry setup, and worker entry creation. It knows what `@decocms/start` supports and will flag anything that needs manual attention.
+The skill runs the migration script, walks you through `MIGRATION_REPORT.md`, fixes typecheck/build errors interactively, and shows the diff before committing.
 
-### Or run the script manually
+### Or run the script directly
 
 ```bash
-# From your Fresh site directory (nothing to install beforehand):
+# from inside the v1 storefront directory
 npx -p @decocms/start deco-migrate
 ```
 
-**Options:**
+The script runs seven phases (analyze → scaffold → transform → cleanup → report → verify → bootstrap), produces `MIGRATION_REPORT.md` with manual TODOs, and gets you to "compiles clean, builds clean".
+
+Full migration playbook: [docs.deco.cx/v2/en/migration/overview](https://docs.deco.cx/v2/en/migration/overview).
 
-| Flag | Description |
-|------|-------------|
-| `--source <dir>` | Source directory (default: current directory) |
-| `--dry-run` | Preview changes without writing files |
-| `--verbose` | Show detailed output |
-| `--help`, `-h` | Show help message |
+---
 
-The script runs 7 phases automatically:
+## Documentation
 
-1. **Analyze** — scan source, detect Preact/Fresh/Deco patterns
-2. **Scaffold** — generate `vite.config.ts`, `wrangler.jsonc`, routes, `setup.ts`, worker entry
-3. **Transform** — rewrite imports (70+ rules), JSX attrs, Fresh APIs, Deno-isms, Tailwind v3→v4
-4. **Cleanup** — delete `islands/`, old routes, `deno.json`, move `static/` → `public/`
-5. **Report** — generate `MIGRATION_REPORT.md` with manual review items
-6. **Verify** — 18+ smoke tests (zero old imports, scaffolded files exist)
-7. **Bootstrap** — `npm install`, generate CMS blocks, generate routes
+The full v2 docs live at **[docs.deco.cx/v2](https://docs.deco.cx/v2/en/getting-started/overview)**:
 
-Your existing `src/sections/`, `src/components/`, and `.deco/blocks/` work as-is. The script gets you to "builds clean with zero old imports" — manual work starts at platform hooks (`useCart`) and runtime tuning.
+- [Getting started](https://docs.deco.cx/v2/en/getting-started/overview) — install paths, project structure, stack overview.
+- [Concepts](https://docs.deco.cx/v2/en/concepts/sections) — sections, loaders, blocks, routes, deferred rendering.
+- [Framework reference](https://docs.deco.cx/v2/en/framework/overview) — every export of `@decocms/start`, page by page.
+- [Migration](https://docs.deco.cx/v2/en/migration/overview) — v1 → v2 playbook + script + skill.
+- [Case studies](https://docs.deco.cx/v2/en/case-studies/overview) — three production stores end-to-end.
 
-### Agent Skills
+---
 
-Skills live in [`.agents/skills/`](.agents/skills/) and provide deep context to AI coding tools:
+## Peer dependencies
 
-| Skill | What it covers |
-|-------|---------------|
-| `deco-to-tanstack-migration` | Full 12-phase migration playbook with 22 reference docs and 6 templates |
-| `deco-migrate-script` | How the automated `scripts/migrate.ts` works, how to extend it |
+```json
+{
+  "@tanstack/react-start": ">=1.0.0",
+  "@tanstack/store": ">=0.7.0",
+  "@tanstack/react-query": ">=5.0.0",
+  "react": "^19.0.0",
+  "react-dom": "^19.0.0",
+  "vite": ">=6.0.0"
+}
+```
 
-## Peer Dependencies
+OpenTelemetry is optional but recommended: `@microlabs/otel-cf-workers >=1.0.0-rc.0`, `@opentelemetry/api >=1.9.0`.
 
-- `@tanstack/react-start` >= 1.0.0
-- `@tanstack/store` >= 0.7.0
-- `react` ^19.0.0
-- `react-dom` ^19.0.0
+---
 
 ## Development
 
@@ -128,7 +223,11 @@ npm run lint        # biome check
 npm run check       # typecheck + lint + unused exports
 ```
 
-This is a library — no dev server. Consumer sites run their own `vite dev`.
+This is a library — there is no dev server here. Consumer storefronts run their own `vite dev`.
+
+Contributing? See `CLAUDE.md` for the architectural decisions, and `MIGRATION_TOOLING_PLAN.md` for the append-only history of the migration tooling.
+
+---
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decocms/start",
-  "version": "2.28.1",
+  "version": "2.29.0",
   "type": "module",
   "description": "Deco framework for TanStack Start - CMS bridge, admin protocol, hooks, schema generation",
   "main": "./src/index.ts",
@@ -35,6 +35,11 @@
     "./sdk/invoke": "./src/sdk/invoke.ts",
     "./sdk/instrumentedFetch": "./src/sdk/instrumentedFetch.ts",
     "./sdk/otel": "./src/sdk/otel.ts",
+    "./sdk/logger": "./src/sdk/logger.ts",
+    "./sdk/composite": "./src/sdk/composite.ts",
+    "./sdk/otelAdapters": "./src/sdk/otelAdapters.ts",
+    "./sdk/sampler": "./src/sdk/sampler.ts",
+    "./sdk/observability": "./src/sdk/observability.ts",
     "./sdk/workerEntry": "./src/sdk/workerEntry.ts",
     "./sdk/abTesting": "./src/sdk/abTesting.ts",
     "./sdk/redirects": "./src/sdk/redirects.ts",
@@ -99,6 +104,15 @@
   },
   "dependencies": {
     "@deco-cx/warp-node": "^0.3.16",
+    "@microlabs/otel-cf-workers": "^1.0.0-rc.52",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/api-logs": "^0.200.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.200.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.200.0",
+    "@opentelemetry/resources": "^2.6.1",
+    "@opentelemetry/sdk-logs": "^0.200.0",
+    "@opentelemetry/sdk-metrics": "^2.0.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.1",
     "clsx": "^2.1.1",
     "fast-json-patch": "^3.1.0",
     "tailwind-merge": "^3.3.1",
@@ -106,8 +120,6 @@
     "ws": "^8.18.0"
   },
   "peerDependencies": {
-    "@microlabs/otel-cf-workers": ">=1.0.0-rc.0",
-    "@opentelemetry/api": ">=1.9.0",
     "@tanstack/react-query": ">=5.0.0",
     "@tanstack/react-start": ">=1.0.0",
     "@tanstack/store": ">=0.7.0",
@@ -115,25 +127,15 @@
     "react-dom": "^19.0.0",
     "vite": ">=6.0.0 || >=7.0.0 || >=8.0.0"
   },
-  "peerDependenciesMeta": {
-    "@microlabs/otel-cf-workers": {
-      "optional": true
-    },
-    "@opentelemetry/api": {
-      "optional": true
-    }
-  },
   "devDependencies": {
     "@biomejs/biome": "^2.4.6",
-    "@microlabs/otel-cf-workers": "^1.0.0-rc.52",
-    "@opentelemetry/api": "^1.9.1",
     "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
     "@tanstack/react-query": "^5.96.0",
     "@tanstack/store": "^0.9.1",
     "@types/react": "^19.0.0",
-    "@types/ws": "^8.18.0",
     "@types/react-dom": "^19.0.0",
+    "@types/ws": "^8.18.0",
     "jsdom": "^29.0.0",
     "knip": "^5.86.0",
     "ts-morph": "^27.0.0",

package/src/cms/resolve.ts

@@ -1,9 +1,15 @@
+import {
+  type ActionConfig,
+  type LoaderConfig,
+  registerActionSchemas,
+  registerLoaderSchemas,
+} from "../admin/schema";
+import { getMeter, MetricNames, withTracing } from "../middleware/observability";
+import { djb2Hex } from "../sdk/djb2";
+import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
 import { findPageByPath, loadBlocks } from "./loader";
 import { getOnBeforeResolveProps, getSection, registerOnBeforeResolveProps } from "./registry";
 import { isLayoutSection, runSingleSectionLoader } from "./sectionLoaders";
-import { normalizeUrlsInObject } from "../sdk/normalizeUrls";
-import { djb2Hex } from "../sdk/djb2";
-import { registerLoaderSchemas, registerActionSchemas, type LoaderConfig, type ActionConfig } from "../admin/schema";
 
 // globalThis-backed: share state across Vite server function split modules
 const G = globalThis as any;
@@ -134,10 +140,7 @@ export function setAsyncRenderingConfig(config?: {
   respectCmsLazy?: boolean;
 }): void {
   const existing = getAsyncConfig();
-  const merged = new Set([
-    ...(existing?.alwaysEager ?? []),
-    ...(config?.alwaysEager ?? []),
-  ]);
+  const merged = new Set([...(existing?.alwaysEager ?? []), ...(config?.alwaysEager ?? [])]);
   G.__deco.asyncConfig = {
     respectCmsLazy: config?.respectCmsLazy ?? existing?.respectCmsLazy ?? true,
     foldThreshold: config?.foldThreshold ?? existing?.foldThreshold ?? Infinity,
@@ -321,7 +324,13 @@ export function registerCommerceLoaders(loaders: Record<string, CommerceLoader>)
     if (key.includes("/actions/")) {
       actionConfigs.push({ key, title: key, namespace, propsSchema: schema });
     } else {
-      loaderConfigs.push({ key, title: key, namespace, propsSchema: schema, tags: inferLoaderTags(key) });
+      loaderConfigs.push({
+        key,
+        title: key,
+        namespace,
+        propsSchema: schema,
+        tags: inferLoaderTags(key),
+      });
     }
   }
 
@@ -374,18 +383,24 @@ export function registerMatcher(
 if (!G.__deco._builtinMatchersRegistered) {
   G.__deco._builtinMatchersRegistered = true;
 
-  const builtinMatchers: Record<string, (rule: Record<string, unknown>, ctx: MatcherContext) => boolean> = {
+  const builtinMatchers: Record<
+    string,
+    (rule: Record<string, unknown>, ctx: MatcherContext) => boolean
+  > = {
     "website/matchers/always.ts": () => true,
     "$live/matchers/MatchAlways.ts": () => true,
     "website/matchers/never.ts": () => false,
     "website/matchers/device.ts": (rule, ctx) => {
       const ua = (ctx.userAgent || "").toLowerCase();
       const isTablet = /ipad|android(?!.*mobile)|tablet/i.test(ua);
-      const isMobile = !isTablet && /mobile|android|iphone|ipod|webos|blackberry|opera mini|iemobile/i.test(ua);
+      const isMobile =
+        !isTablet && /mobile|android|iphone|ipod|webos|blackberry|opera mini|iemobile/i.test(ua);
       const isDesktop = !isMobile && !isTablet;
       // If no flags are set, match everything (permissive default)
       if (!rule.mobile && !rule.tablet && !rule.desktop) return true;
-      return !!(rule.mobile && isMobile) || !!(rule.tablet && isTablet) || !!(rule.desktop && isDesktop);
+      return (
+        !!(rule.mobile && isMobile) || !!(rule.tablet && isTablet) || !!(rule.desktop && isDesktop)
+      );
     },
     "website/matchers/random.ts": (rule) => {
       const traffic = typeof rule.traffic === "number" ? rule.traffic : 0.5;
@@ -457,7 +472,10 @@ function ensureInitialized() {
 // Matcher evaluation
 // ---------------------------------------------------------------------------
 
-export function evaluateMatcher(rule: Record<string, unknown> | undefined, ctx: MatcherContext): boolean {
+export function evaluateMatcher(
+  rule: Record<string, unknown> | undefined,
+  ctx: MatcherContext,
+): boolean {
   if (!rule) return true;
 
   const resolveType = rule.__resolveType as string | undefined;
@@ -828,10 +846,7 @@ export async function resolvePageSeoBlock(
     }
 
     // Multivariate flag — evaluate matcher and follow matched variant
-    if (
-      rt === "website/flags/multivariate.ts" ||
-      rt === "website/flags/multivariate/section.ts"
-    ) {
+    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;
@@ -909,10 +924,7 @@ function isRawSectionLayout(section: unknown): string | null {
  * unwrapping Lazy/Deferred wrappers, and evaluating multivariate flags.
  * Returns null if not determinable.
  */
-function resolveFinalSectionKey(
-  section: unknown,
-  matcherCtx?: MatcherContext,
-): string | null {
+function resolveFinalSectionKey(section: unknown, matcherCtx?: MatcherContext): string | null {
   if (!section || typeof section !== "object") return null;
 
   const blocks = loadBlocks();
@@ -946,13 +958,8 @@ function resolveFinalSectionKey(
       continue;
     }
 
-    if (
-      rt === WELL_KNOWN_TYPES.MULTIVARIATE ||
-      rt === WELL_KNOWN_TYPES.MULTIVARIATE_SECTION
-    ) {
-      const variants = current.variants as
-        | Array<{ value: unknown; rule?: unknown }>
-        | undefined;
+    if (rt === WELL_KNOWN_TYPES.MULTIVARIATE || rt === WELL_KNOWN_TYPES.MULTIVARIATE_SECTION) {
+      const variants = current.variants as Array<{ value: unknown; rule?: unknown }> | undefined;
       if (!variants?.length) return null;
 
       let matched: unknown = null;
@@ -999,21 +1006,13 @@ function isCmsDeferralWrapped(section: unknown, matcherCtx?: MatcherContext): bo
     const rt = current.__resolveType as string | undefined;
     if (!rt) return false;
 
-    if (
-      rt === WELL_KNOWN_TYPES.LAZY ||
-      rt === WELL_KNOWN_TYPES.DEFERRED
-    ) {
+    if (rt === WELL_KNOWN_TYPES.LAZY || rt === WELL_KNOWN_TYPES.DEFERRED) {
       return true;
     }
 
     // Walk through multivariate flags to check the matched variant
-    if (
-      rt === WELL_KNOWN_TYPES.MULTIVARIATE ||
-      rt === WELL_KNOWN_TYPES.MULTIVARIATE_SECTION
-    ) {
-      const variants = current.variants as
-        | Array<{ value: unknown; rule?: unknown }>
-        | undefined;
+    if (rt === WELL_KNOWN_TYPES.MULTIVARIATE || rt === WELL_KNOWN_TYPES.MULTIVARIATE_SECTION) {
+      const variants = current.variants as Array<{ value: unknown; rule?: unknown }> | undefined;
       if (!variants?.length) return false;
 
       let matched: unknown = null;
@@ -1125,13 +1124,8 @@ function resolveSectionShallow(
     }
 
     // Multivariate flags — evaluate matchers and continue with matched variant
-    if (
-      rt === WELL_KNOWN_TYPES.MULTIVARIATE ||
-      rt === WELL_KNOWN_TYPES.MULTIVARIATE_SECTION
-    ) {
-      const variants = current.variants as
-        | Array<{ value: unknown; rule?: unknown }>
-        | undefined;
+    if (rt === WELL_KNOWN_TYPES.MULTIVARIATE || rt === WELL_KNOWN_TYPES.MULTIVARIATE_SECTION) {
+      const variants = current.variants as Array<{ value: unknown; rule?: unknown }> | undefined;
       if (!variants?.length) return null;
 
       let matched: unknown = null;
@@ -1331,6 +1325,30 @@ export interface DecoPageResult {
 export async function resolveDecoPage(
   targetPath: string,
   matcherCtx?: MatcherContext,
+): Promise<DecoPageResult | null> {
+  const startedAt = performance.now();
+  return withTracing(
+    "deco.cms.resolvePage",
+    async () => {
+      const result = await resolveDecoPageImpl(targetPath, matcherCtx);
+      try {
+        getMeter()?.histogramRecord?.(
+          MetricNames.RESOLVE_DURATION_MS,
+          performance.now() - startedAt,
+          { path: targetPath },
+        );
+      } catch {
+        /* observability never fails the request */
+      }
+      return result;
+    },
+    { "deco.route": targetPath },
+  );
+}
+
+async function resolveDecoPageImpl(
+  targetPath: string,
+  matcherCtx?: MatcherContext,
 ): Promise<DecoPageResult | null> {
   ensureInitialized();
 
@@ -1378,7 +1396,12 @@ export async function resolveDecoPage(
           // Cache rawProps server-side and strip from the deferred object
           // so they are NOT serialized into the HTML payload.
           if (deferred.rawProps) {
-            cacheDeferredRawProps(targetPath, deferred.component, currentFlatIndex, deferred.rawProps);
+            cacheDeferredRawProps(
+              targetPath,
+              deferred.component,
+              currentFlatIndex,
+              deferred.rawProps,
+            );
             delete deferred.rawProps;
           }
 
@@ -1430,10 +1453,12 @@ export async function resolveDecoPage(
       })();
 
       const idx = currentFlatIndex;
-      eagerResults.push(promise.then((sections) => {
-        for (const s of sections) s.index = idx;
-        return sections;
-      }));
+      eagerResults.push(
+        promise.then((sections) => {
+          for (const s of sections) s.index = idx;
+          return sections;
+        }),
+      );
       flatIndex++;
     }
   }
@@ -1445,10 +1470,7 @@ export async function resolveDecoPage(
   let seoSection: ResolvedSection | null = null;
   if (page.seo) {
     try {
-      seoSection = await resolvePageSeoBlock(
-        page.seo as Record<string, unknown>,
-        rctx,
-      );
+      seoSection = await resolvePageSeoBlock(page.seo as Record<string, unknown>, rctx);
     } catch (e) {
       onResolveError(e, "page.seo", "Page SEO block resolution");
     }
@@ -1588,18 +1610,14 @@ export async function resolveDeferredSectionFull(
   matcherCtx?: MatcherContext,
 ): Promise<ResolvedSection | null> {
   // rawProps may be stripped from the client payload — resolve from cache or page
-  const rawProps = ds.rawProps
-    ?? getDeferredRawProps(pagePath, ds.component, ds.index)
-    ?? await reExtractRawProps(pagePath, ds.component, ds.index, matcherCtx);
+  const rawProps =
+    ds.rawProps ??
+    getDeferredRawProps(pagePath, ds.component, ds.index) ??
+    (await reExtractRawProps(pagePath, ds.component, ds.index, matcherCtx));
 
   if (!rawProps) return null;
 
-  const section = await resolveDeferredSection(
-    ds.component,
-    rawProps,
-    pagePath,
-    matcherCtx,
-  );
+  const section = await resolveDeferredSection(ds.component, rawProps, pagePath, matcherCtx);
   if (!section) return null;
   section.index = ds.index;
   const enriched = await runSingleSectionLoader(section, request);

package/src/cms/sectionLoaders.ts

@@ -8,6 +8,8 @@
  * This runs AFTER resolveDecoPage and BEFORE React rendering,
  * inside the TanStack Start server function.
  */
+
+import { withTracing } from "../middleware/observability";
 import { getCacheProfile } from "../sdk/cacheHeaders";
 import { djb2 } from "../sdk/djb2";
 import type { ResolvedSection } from "./resolve";
@@ -326,6 +328,15 @@ function withPageContext(loader: SectionLoaderFn): SectionLoaderFn {
 export async function runSingleSectionLoader(
   section: ResolvedSection,
   request: Request,
+): Promise<ResolvedSection> {
+  return withTracing("deco.section.loader", () => runSingleSectionLoaderImpl(section, request), {
+    "deco.section": section.component,
+  });
+}
+
+async function runSingleSectionLoaderImpl(
+  section: ResolvedSection,
+  request: Request,
 ): Promise<ResolvedSection> {
   const loader = loaderRegistry.get(section.component);