@decocms/start 0.38.0 → 0.40.0

package/src/sdk/setupApps.ts

@@ -0,0 +1,211 @@
+/**
+ * App system integration pipeline.
+ *
+ * Consumes AppDefinition objects from @decocms/apps and automates:
+ * 1. Invoke handler registration (from manifest + explicit handlers)
+ * 2. Section registration (when manifest.sections is available)
+ * 3. App middleware registration (with state injection into RequestContext)
+ *
+ * @example
+ * ```ts
+ * import { setupApps } from "@decocms/start/sdk/setupApps";
+ * import * as vtexApp from "@decocms/apps/vtex/mod";
+ * import * as resendApp from "@decocms/apps/resend/mod";
+ *
+ * const vtex = await vtexApp.configure(blocks["deco-vtex"], resolveSecret);
+ * const resend = await resendApp.configure(blocks["deco-resend"], resolveSecret);
+ *
+ * await setupApps([vtex, resend].filter(Boolean));
+ * ```
+ */
+
+import { clearInvokeHandlers, registerInvokeHandlers } from "../admin/invoke";
+import { registerSections } from "../cms/registry";
+import { RequestContext } from "./requestContext";
+
+// ---------------------------------------------------------------------------
+// Types — mirrors @decocms/apps/commerce/app-types without importing it
+// ---------------------------------------------------------------------------
+
+export interface AppManifest {
+  name: string;
+  loaders: Record<string, Record<string, unknown>>;
+  actions: Record<string, Record<string, unknown>>;
+  sections?: Record<string, () => Promise<any>>;
+}
+
+export interface AppMiddleware {
+  (request: Request, next: () => Promise<Response>): Promise<Response>;
+}
+
+export interface AppDefinition<TState = unknown> {
+  name: string;
+  manifest: AppManifest;
+  state: TState;
+  middleware?: AppMiddleware;
+  dependencies?: AppDefinition[];
+}
+
+/**
+ * Extended definition with optional explicit handlers.
+ * autoconfigApps() attaches mod.handlers here before calling setupApps().
+ */
+export interface AppDefinitionWithHandlers<TState = unknown>
+  extends AppDefinition<TState> {
+  /** Pre-wrapped handlers from the app's mod.ts (e.g. unwrapped VTEX actions). */
+  handlers?: Record<string, (props: any, request: Request) => Promise<any>>;
+}
+
+// ---------------------------------------------------------------------------
+// App middleware registry
+// ---------------------------------------------------------------------------
+
+/** Per-app state entries — injected into RequestContext.bag on every request. */
+const appStates: Array<{ name: string; state: unknown }> = [];
+
+const appMiddlewares: Array<{
+  name: string;
+  middleware: AppMiddleware;
+}> = [];
+
+function registerAppState(name: string, state: unknown) {
+  appStates.push({ name, state });
+}
+
+export function registerAppMiddleware(
+  name: string,
+  mw: AppMiddleware,
+) {
+  appMiddlewares.push({ name, middleware: mw });
+}
+
+/**
+ * Clear all registrations. Called before re-running setupApps()
+ * on admin hot-reload to prevent duplicate middleware/state entries.
+ */
+function clearRegistrations() {
+  appStates.length = 0;
+  appMiddlewares.length = 0;
+}
+
+/**
+ * Returns a chained middleware that runs all registered app middlewares.
+ * The site wires this into its own createMiddleware() chain.
+ *
+ * Before running app middlewares, all app states are injected into
+ * RequestContext.bag so loaders can access them via getAppState().
+ *
+ * Returns undefined if no app states or middlewares were registered.
+ */
+export function getAppMiddleware(): AppMiddleware | undefined {
+  if (appStates.length === 0 && appMiddlewares.length === 0) return undefined;
+
+  return async (request, next) => {
+    // Inject all app states into RequestContext bag
+    for (const { name, state } of appStates) {
+      RequestContext.setBag(`app:${name}:state`, state);
+    }
+
+    // Chain app middlewares (first registered runs outermost)
+    if (appMiddlewares.length === 0) return next();
+    const run = async (i: number): Promise<Response> => {
+      if (i >= appMiddlewares.length) return next();
+      return appMiddlewares[i].middleware(request, () => run(i + 1));
+    };
+    return run(0);
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Dependency flattening
+// ---------------------------------------------------------------------------
+
+/**
+ * Topological sort: dependencies before parents.
+ * Combined with first-wins registration in registerInvokeHandlers,
+ * this means parent apps can override handlers from their dependencies
+ * by providing explicit `handlers` (registered before manifest flatten).
+ */
+function flattenDependencies(apps: AppDefinition[]): AppDefinition[] {
+  const seen = new Set<string>();
+  const result: AppDefinition[] = [];
+
+  function visit(app: AppDefinition) {
+    if (seen.has(app.name)) return;
+    seen.add(app.name);
+    if (app.dependencies) {
+      for (const dep of app.dependencies) visit(dep);
+    }
+    result.push(app);
+  }
+
+  for (const app of apps) visit(app);
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Main pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * Initialize apps from their AppDefinitions.
+ *
+ * Call once in setup.ts after configuring apps via their mod.configure().
+ * Handles: invoke handler registration, section registration, middleware setup.
+ */
+export async function setupApps(
+  apps: Array<AppDefinitionWithHandlers | AppDefinition>,
+): Promise<void> {
+  if (typeof document !== "undefined") return; // server-only
+
+  // Clear previous registrations (safe for hot-reload via onChange)
+  clearRegistrations();
+  clearInvokeHandlers();
+
+  for (const app of flattenDependencies(apps as AppDefinition[])) {
+    const appWithHandlers = app as AppDefinitionWithHandlers;
+
+    // 1. Register explicit handlers (pre-unwrapped by the app, e.g. resend)
+    if (appWithHandlers.handlers) {
+      registerInvokeHandlers(appWithHandlers.handlers);
+    }
+
+    // 2. Flatten manifest modules → individual invoke handlers
+    // manifest.actions["vtex/actions/checkout"] = { getOrCreateCart, addItemsToCart, ... }
+    // → register "vtex/actions/checkout/getOrCreateCart" as handler
+    for (const category of ["loaders", "actions"] as const) {
+      const modules = app.manifest[category];
+      if (!modules) continue;
+
+      for (const [moduleKey, moduleExports] of Object.entries(modules)) {
+        for (const [fnName, fn] of Object.entries(
+          moduleExports as Record<string, unknown>,
+        )) {
+          if (typeof fn !== "function") continue;
+          const key = `${moduleKey}/${fnName}`;
+          const handler = (props: any, req: Request) =>
+            (fn as Function)(props, req);
+          registerInvokeHandlers({
+            [key]: handler,
+            [`${key}.ts`]: handler,
+          });
+        }
+      }
+    }
+
+    // 3. Register sections from manifest (future — when apps export sections)
+    if (app.manifest.sections) {
+      registerSections(
+        app.manifest.sections as Record<string, () => Promise<any>>,
+      );
+    }
+
+    // 4. Always register app state (so getAppState() works for all apps)
+    registerAppState(app.name, app.state);
+
+    // 5. Register middleware (optional — not all apps have middleware)
+    if (app.middleware) {
+      registerAppMiddleware(app.name, app.middleware);
+    }
+  }
+}

package/src/sdk/workerEntry.ts

@@ -36,6 +36,7 @@ import { buildHtmlShell } from "./htmlShell";
 import { cleanPathForCacheKey } from "./urlUtils";
 import { isMobileUA } from "./useDevice";
 import { getRenderShellConfig } from "../admin/setup";
+import { RequestContext } from "./requestContext";
 
 /**
  * Append Link preload headers for CSS and fonts so the browser starts
@@ -653,6 +654,10 @@ export function createDecoWorkerEntry(
       env: Record<string, unknown>,
       ctx: WorkerExecutionContext,
     ): Promise<Response> {
+      // Wrap the entire request in a RequestContext so that all code
+      // in the call stack (loaders, invoke handlers, vtexFetchWithCookies)
+      // can access the request and write response headers.
+      return RequestContext.run(request, async () => {
       const url = new URL(request.url);
 
       // Admin routes (/_meta, /.decofile, /live/previews) — always handled first
@@ -879,6 +884,7 @@ export function createDecoWorkerEntry(
       // the stream in Workers runtime, causing Error 1101.
       storeInCache(origin);
       return dressResponse(origin, "MISS");
+      }); // end RequestContext.run()
     },
   };
 }

package/.cursor/skills/deco-async-rendering-architecture/SKILL.md

@@ -1,270 +0,0 @@
----
-name: deco-async-rendering-architecture
-description: Architecture and internals of Async Section Rendering in @decocms/start. Documents the server-side eager/deferred split (resolve.ts) using CMS Lazy.tsx wrappers as source of truth, client-side IntersectionObserver loading (DecoPageRenderer.tsx), per-section SWR caching (sectionLoaders.ts), bot detection for SEO, the loadDeferredSection server function, and the full request flow from CMS page resolution to on-scroll hydration. Use when debugging async rendering, extending the framework, understanding how deferred sections are resolved, or troubleshooting why a section is/isn't being deferred.
----
-
-# Deco Async Section Rendering — Framework Architecture
-
-Internal documentation for the async section rendering system in `@decocms/start`.
-
-## When to Use This Skill
-
-- Debugging why a section is or isn't being deferred
-- Understanding the full request flow from CMS resolution to on-scroll loading
-- Extending the async rendering system (new cache tiers, new deferral strategies)
-- Fixing issues with deferred section data resolution
-- Understanding how bot detection and SEO safety work
-- Working on `@decocms/start` framework code
-
----
-
-## Problem Solved
-
-TanStack Start serializes all `loaderData` as JSON in a `<script>` tag for client-side hydration. When a CMS page has 20+ sections with commerce data, the HTML payload becomes enormous (8+ MB on some pages). The root cause: `resolveDecoPage` fully resolves ALL sections, and TanStack Start embeds everything.
-
-## Architecture Overview
-
-```
-Request → resolveDecoPage()
-  ├─ resolveSectionsList()     → unwrap flags/blocks to get raw section array
-  ├─ shouldDeferSection()      → classify each section as eager or deferred
-  │   ├─ Eager: resolveRawSection() → full CMS + commerce resolution
-  │   └─ Deferred: resolveSectionShallow() → component key + raw CMS props only
-  ├─ runSectionLoaders()       → enrich eager sections (server loaders)
-  └─ Return { resolvedSections, deferredSections }
-
-Client render → DecoPageRenderer
-  ├─ mergeSections()           → interleave eager + deferred by original index
-  ├─ Eager: <Suspense><LazyComponent .../></Suspense>
-  └─ Deferred: <DeferredSectionWrapper>
-       ├─ preloadSectionModule() → get LoadingFallback early
-       ├─ Render skeleton (custom LoadingFallback or generic)
-       ├─ IntersectionObserver(rootMargin: 300px)
-       └─ On intersect: loadDeferredSection serverFn
-            ├─ resolveDeferredSection() → resolve __resolveType refs in rawProps
-            ├─ runSingleSectionLoader() → enrich with server loader
-            └─ Return ResolvedSection → render real component with fade-in
-```
-
----
-
-## Deferral Strategy: CMS Lazy.tsx as Source of Truth
-
-### How it works now (respectCmsLazy)
-
-The deferral decision is driven by **CMS editor choices**, not a global index threshold:
-
-1. **`respectCmsLazy: true`** (default) — a section is deferred if and only if it's wrapped in `website/sections/Rendering/Lazy.tsx` in the CMS page JSON
-2. **`foldThreshold`** (default `Infinity`) — fallback for sections NOT wrapped in Lazy; with default `Infinity`, non-wrapped sections are always eager
-3. **`alwaysEager`** — section keys that override all deferral (Header, Footer, Theme, etc.)
-
-### Why this approach
-
-The previous `foldThreshold` approach deferred sections by index position, ignoring editor intent. This caused:
-- Sections that editors wanted eager getting deferred
-- No control per-page (threshold was global)
-- Homepage with 12 sections marked Lazy in CMS showing 0 deferred
-
-Now editors control deferral by wrapping sections in `Lazy.tsx` in the CMS admin, and the framework respects that.
-
-### `isCmsLazyWrapped(section)` in `resolve.ts`
-
-Detects whether a section is wrapped in `website/sections/Rendering/Lazy.tsx`, either:
-- Directly: `section.__resolveType === "website/sections/Rendering/Lazy.tsx"`
-- Via named block: `section.__resolveType` references a block whose `__resolveType` is `"website/sections/Rendering/Lazy.tsx"`
-
-### `shouldDeferSection(section, flatIndex, cfg, isBotReq)`
-
-Updated decision logic:
-
-```
-1. Bot request? → EAGER (SEO safety)
-2. No __resolveType? → EAGER (can't classify)
-3. Is multivariate flag? → EAGER (requires runtime evaluation)
-4. resolveFinalSectionKey() → walk block refs + Lazy wrappers to find final component
-5. In alwaysEager set? → EAGER
-6. isLayoutSection()? → EAGER
-7. respectCmsLazy && isCmsLazyWrapped(section)? → DEFER
-8. flatIndex >= foldThreshold? → DEFER (fallback, only if not wrapped)
-9. Otherwise → EAGER
-```
-
----
-
-## Files and Their Roles
-
-| File | Layer | Role |
-|------|-------|------|
-| `src/cms/resolve.ts` | Server | Types, config, eager/deferred split, CMS Lazy detection, shallow resolution, full deferred resolution |
-| `src/cms/sectionLoaders.ts` | Server | Section loader registry, layout cache, SWR cacheable sections, `runSingleSectionLoader` |
-| `src/cms/registry.ts` | Shared | Section component registry, `preloadSectionModule` for early LoadingFallback |
-| `src/routes/cmsRoute.ts` | Server | `loadCmsPage`, `loadCmsHomePage`, `loadDeferredSection` server functions |
-| `src/hooks/DecoPageRenderer.tsx` | Client | Merge, render eager/deferred, `DeferredSectionWrapper`, dev warnings |
-| `src/cms/index.ts` | Barrel | Re-exports all public types and functions |
-| `src/routes/index.ts` | Barrel | Re-exports route helpers including `loadDeferredSection` |
-
----
-
-## Server-Side: Eager/Deferred Split
-
-### Entry point: `resolveDecoPage()` in `resolve.ts`
-
-```
-resolveDecoPage(targetPath, matcherCtx)
-  1. findPageByPath(targetPath) → { page, params }
-  2. Get raw sections array:
-     - If page.sections is Array → use directly
-     - If page.sections is wrapped (multivariate flag, block ref) → resolveSectionsList()
-  3. For each raw section:
-     - If shouldDeferSection() → resolveSectionShallow() → DeferredSection
-     - Else → resolveRawSection() (full resolution) → ResolvedSection[]
-  4. Return { resolvedSections, deferredSections }
-```
-
-### `resolveSectionsList(value, rctx, depth)`
-
-Resolves **only the outer wrapper** around the sections array. Handles multivariate flags, named block references, and `resolved` type wrappers. Extracts the raw section array WITHOUT resolving individual section commerce loaders.
-
-### `resolveFinalSectionKey(section)`
-
-Walks block reference chain and unwraps `Lazy` wrappers to find the final registered section component key:
-
-```
-"Header - 01" (named block)
-  → { __resolveType: "website/sections/Rendering/Lazy.tsx", section: {...} }
-    → { __resolveType: "site/sections/Header/Header.tsx", ...props }
-```
-
-Returns `"site/sections/Header/Header.tsx"`, checked against `alwaysEager` and `isLayoutSection`.
-
-### `resolveSectionShallow(section)`
-
-Synchronously follows block refs and unwraps Lazy to extract `component` (final key) and `rawProps` (CMS props as-is). No API calls, no async.
-
-### `resolveDeferredSection(component, rawProps, pagePath, matcherCtx)`
-
-Called when client requests a deferred section. Runs full resolution:
-1. `resolveProps(rawProps, rctx)` — resolves all nested `__resolveType` references
-2. `normalizeNestedSections(resolvedProps)` — converts nested sections to `{ Component, props }`
-3. Returns `ResolvedSection` ready for `runSingleSectionLoader`
-
----
-
-## Server-Side: Section Caching
-
-### Three cache tiers in `sectionLoaders.ts`
-
-**Tier 1: Layout sections** (Header, Footer, Theme)
-- 5-minute TTL, in-flight dedup, registered via `registerLayoutSections`
-
-**Tier 2: Cacheable sections** (ProductShelf, FAQ)
-- Configurable TTL via `registerCacheableSections`, SWR semantics, LRU eviction at 200 entries
-- Cache key: `component::djb2Hash(JSON.stringify(props))`
-
-**Tier 3: Regular sections** — No caching, always fresh.
-
----
-
-## Client-Side: DeferredSectionWrapper
-
-### Lifecycle
-
-```
-1. Mount (stableKey = pagePath + component + index)
-   ├─ preloadSectionModule(component) → extract LoadingFallback
-   └─ Render skeleton (custom or generic DefaultSectionFallback)
-
-2. IntersectionObserver (rootMargin: "300px")
-   └─ On intersect (once):
-       ├─ loadDeferredSection serverFn
-       ├─ On success: render <LazyComponent .../> with fade-in
-       └─ On error: render ErrorFallback or null
-
-3. SPA navigation: stableKey changes → reset state (triggered, section, error)
-```
-
-### Key: stableKey for SPA navigation
-
-`DeferredSectionWrapper` uses `pagePath + component + index` as a stable key. When the route changes, this key changes, forcing React to remount the wrapper and reset all internal state. This prevents deferred sections from a previous page being "stuck" in a triggered state.
-
----
-
-## Bot Detection (SEO Safety)
-
-`isBot(userAgent)` regex detects search engine crawlers. When detected, ALL sections are resolved eagerly — `deferredSections` is empty.
-
----
-
-## Types
-
-### `AsyncRenderingConfig`
-
-```ts
-interface AsyncRenderingConfig {
-  respectCmsLazy: boolean;     // Default true — use Lazy.tsx wrappers as deferral source
-  foldThreshold: number;       // Default Infinity — fallback for non-wrapped sections
-  alwaysEager: Set<string>;    // Section keys that must always be eager
-}
-```
-
-### `DeferredSection`
-
-```ts
-interface DeferredSection {
-  component: string;
-  key: string;
-  index: number;
-  rawProps: Record<string, unknown>;
-}
-```
-
----
-
-## Edge Cases and Gotchas
-
-### 1. CMS Lazy.tsx is the source of truth
-Editors wrap sections in `website/sections/Rendering/Lazy.tsx` in the CMS admin. The framework detects this via `isCmsLazyWrapped()` and defers those sections. Sections NOT wrapped are eager (with `foldThreshold: Infinity`).
-
-### 2. Block references to Lazy
-A section may reference a named block (e.g., `"Footer - 01"`) whose underlying definition is `Lazy.tsx`. `isCmsLazyWrapped` resolves one level of block reference to detect this.
-
-### 3. alwaysEager overrides Lazy wrapping
-If `Footer.tsx` is in `alwaysEager` but wrapped in Lazy in the CMS, it stays eager. This is intentional — layout sections must always be in the initial HTML.
-
-### 4. Multivariate flags are always eager
-Individual sections wrapped in `website/flags/multivariate.ts` require runtime matcher evaluation and can't be safely deferred.
-
-### 5. InvalidCharacterError with section rendering
-In TanStack Start, resolved sections have `Component` as a string key (not a React component). Use `SectionRenderer` or `SectionList` from `@decocms/start/hooks` to render sections — never destructure `{ Component, props }` and use as JSX directly.
-
-### 6. Navigation flash prevention
-Don't use `pendingComponent` on CMS routes — it replaces the entire page content (including Header/Footer) during transitions. Instead, use a root-level `NavigationProgress` bar that keeps previous page visible while loading.
-
----
-
-## Public API Summary
-
-### From `@decocms/start/cms`
-
-| Export | Type | Description |
-|--------|------|-------------|
-| `setAsyncRenderingConfig` | Function | Enable/configure async rendering |
-| `getAsyncRenderingConfig` | Function | Read current config |
-| `registerCacheableSections` | Function | Register sections for SWR loader caching |
-| `runSingleSectionLoader` | Function | Run a single section's loader |
-| `resolveDeferredSection` | Function | Fully resolve a deferred section's raw props |
-| `preloadSectionModule` | Function | Eagerly import a section to extract LoadingFallback |
-
-### From `@decocms/start/routes`
-
-| Export | Type | Description |
-|--------|------|-------------|
-| `loadDeferredSection` | ServerFn | Server function to resolve + enrich deferred section on demand |
-
-### From `@decocms/start/hooks`
-
-| Export | Type | Description |
-|--------|------|-------------|
-| `DecoPageRenderer` | Component | Renders page with eager + deferred section support |
-| `SectionRenderer` | Component | Renders a single section by registry key |
-| `SectionList` | Component | Renders an array of sections |