@decocms/start 0.38.0 → 0.40.0

package/{.cursor/skills/deco-async-rendering-site-guide/SKILL.md → .agents/skills/deco-to-tanstack-migration/references/async-rendering.md}

@@ -1,13 +1,278 @@
+# Async Rendering: Architecture & Site Implementation
+
+## Part 1: Architecture
+
+Internal documentation for the async section rendering system in `@decocms/start`.
+
+### When to Use This Reference
+
+- 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`
+
 ---
-name: deco-async-rendering-site-guide
-description: Site-level guide for implementing Async Section Rendering in Deco storefronts on TanStack Start. Covers LoadingFallback implementation with detailed product card skeletons, setup.ts configuration using CMS Lazy.tsx wrappers (respectCmsLazy), adding Lazy wrappers to CMS page JSONs, route wiring ($.tsx, index.tsx), alwaysEager sections, NavigationProgress for SPA transitions, and diagnosing dev warnings. Use when adding async rendering to a new Deco site, creating LoadingFallback components, wrapping CMS sections in Lazy, debugging deferred sections, or optimizing page payload.
+
+### 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 |
+
 ---
 
-# Deco Async Section Rendering — Site Implementation Guide
+## Part 2: Site Implementation
 
 How to configure and use Async Section Rendering in your Deco storefront.
 
-## When to Use This Skill
+### When to Use This Reference
 
 - Setting up async section rendering on a new or existing Deco site
 - Creating `LoadingFallback` components for sections
@@ -18,9 +283,9 @@ How to configure and use Async Section Rendering in your Deco storefront.
 
 ---
 
-## Quick Start (3 steps)
+### Quick Start (3 steps)
 
-### 1. `src/setup.ts` — Enable async rendering
+#### 1. `src/setup.ts` — Enable async rendering
 
 ```ts
 import {
@@ -49,7 +314,7 @@ registerCacheableSections({
 });
 ```
 
-### 2. Wrap sections in Lazy in CMS JSONs
+#### 2. Wrap sections in Lazy in CMS JSONs
 
 In `.deco/blocks/pages-*.json`, wrap below-the-fold sections:
 
@@ -75,15 +340,15 @@ In `.deco/blocks/pages-*.json`, wrap below-the-fold sections:
 - SEO sections → **skip** (they're metadata, not visual)
 - Everything else below the fold → **wrap in Lazy**
 
-### 3. Add LoadingFallback to every lazy section
+#### 3. Add LoadingFallback to every lazy section
 
 Export `LoadingFallback` from the section file. See detailed patterns below.
 
 ---
 
-## CMS Lazy Wrapper Strategy
+### CMS Lazy Wrapper Strategy
 
-### Page audit checklist
+#### Page audit checklist
 
 For each CMS page (`pages-*.json`):
 
@@ -92,7 +357,7 @@ For each CMS page (`pages-*.json`):
 3. Wrap everything else in `website/sections/Rendering/Lazy.tsx`.
 4. Keep `alwaysEager` sections (Header, Footer, etc.) unwrapped even if they appear at the end.
 
-### Real-world example: Homepage
+#### Real-world example: Homepage
 
 | Index | Section | Status |
 |-------|---------|--------|
@@ -111,9 +376,9 @@ Result: 4 eager + 17 lazy → **52% payload reduction**.
 
 ---
 
-## Creating LoadingFallback Components
+### Creating LoadingFallback Components
 
-### Key rules
+#### Key rules
 
 1. **Match dimensions**: Same container classes, padding, and aspect ratio as the real section
 2. **CSS-only**: Use `skeleton animate-pulse` classes. No JS, no hooks, no data.
@@ -121,7 +386,7 @@ Result: 4 eager + 17 lazy → **52% payload reduction**.
 4. **One per section file**: Export from `src/sections/Foo.tsx`, not from the component file
 5. **Represent the content**: Skeletons should visually match the final layout
 
-### Product Card Skeleton (reusable pattern)
+#### Product Card Skeleton (reusable pattern)
 
 Most shelf/grid sections contain product cards. Define a shared skeleton:
 
@@ -148,7 +413,7 @@ function CardSkeleton() {
 
 This matches the real `ProductCard` layout: image → flag → name (2 lines) → price block (from/to/installment) → buy button.
 
-### Pattern: Product Shelf
+#### Pattern: Product Shelf
 
 ```tsx
 export function LoadingFallback() {
@@ -168,7 +433,7 @@ export function LoadingFallback() {
 }
 ```
 
-### Pattern: Tabbed Shelf
+#### Pattern: Tabbed Shelf
 
 ```tsx
 export function LoadingFallback() {
@@ -194,7 +459,7 @@ export function LoadingFallback() {
 }
 ```
 
-### Pattern: Search Result (PLP)
+#### Pattern: Search Result (PLP)
 
 ```tsx
 export function LoadingFallback() {
@@ -232,7 +497,7 @@ export function LoadingFallback() {
 }
 ```
 
-### Pattern: Full-width Banner/Carousel
+#### Pattern: Full-width Banner/Carousel
 
 ```tsx
 export function LoadingFallback() {
@@ -244,7 +509,7 @@ export function LoadingFallback() {
 }
 ```
 
-### Pattern: FAQ Accordion
+#### Pattern: FAQ Accordion
 
 ```tsx
 export function LoadingFallback() {
@@ -260,7 +525,7 @@ export function LoadingFallback() {
 }
 ```
 
-### Pattern: Testimonials/Cards Grid
+#### Pattern: Testimonials/Cards Grid
 
 ```tsx
 export function LoadingFallback() {
@@ -282,7 +547,7 @@ export function LoadingFallback() {
 }
 ```
 
-### Pattern: Footer
+#### Pattern: Footer
 
 ```tsx
 export function LoadingFallback() {
@@ -308,7 +573,7 @@ export function LoadingFallback() {
 
 ---
 
-## SPA Navigation: NavigationProgress
+### SPA Navigation: NavigationProgress
 
 **Do NOT use `pendingComponent`** on CMS routes — it replaces the entire page content (Header/Footer disappear, causing a "flash white").
 
@@ -338,9 +603,9 @@ Add `<NavigationProgress />` before your main layout in `RootLayout`.
 
 ---
 
-## Configuration Reference
+### Configuration Reference
 
-### `setAsyncRenderingConfig(options)`
+#### `setAsyncRenderingConfig(options)`
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
@@ -348,7 +613,7 @@ Add `<NavigationProgress />` before your main layout in `RootLayout`.
 | `foldThreshold` | `number` | `Infinity` | Fallback for non-wrapped sections (Infinity = only Lazy-wrapped defer) |
 | `alwaysEager` | `string[]` | `[]` | Section keys that are ALWAYS eager regardless |
 
-### `registerCacheableSections(configs)`
+#### `registerCacheableSections(configs)`
 
 ```ts
 registerCacheableSections({
@@ -360,9 +625,9 @@ Good candidates: Product shelves (2-3 min), FAQ/content (15-30 min). NOT for PDP
 
 ---
 
-## Debugging
+### Debugging
 
-### Section not being deferred
+#### Section not being deferred
 
 1. Is `setAsyncRenderingConfig()` called in `setup.ts`?
 2. Is the section wrapped in `website/sections/Rendering/Lazy.tsx` in the CMS JSON?
@@ -371,7 +636,7 @@ Good candidates: Product shelves (2-3 min), FAQ/content (15-30 min). NOT for PDP
 5. Is it wrapped in a multivariate flag? (always eager)
 6. Is the user-agent a bot? (bots always get full eager)
 
-### Verifying with curl
+#### Verifying with curl
 
 ```bash
 # Normal user — count deferred sections
@@ -385,13 +650,13 @@ curl -s -o /dev/null -w "Normal: %{size_download}\n" http://localhost:5173/
 curl -s -o /dev/null -w "Bot:    %{size_download}\n" -A "Googlebot/2.1" http://localhost:5173/
 ```
 
-### InvalidCharacterError with sections
+#### InvalidCharacterError with sections
 
 If you see `Failed to execute 'createElement'` with a section path as tag name, the component is using `{ Component, props }` destructuring directly as JSX. Use `SectionRenderer` or `SectionList` from `@decocms/start/hooks` instead.
 
 ---
 
-## Performance Impact
+### Performance Impact
 
 Measured on `espacosmart-storefront`:
 
@@ -403,7 +668,7 @@ Measured on `espacosmart-storefront`:
 
 ---
 
-## Checklist for New Sites
+### Checklist for New Sites
 
 - [ ] Call `setAsyncRenderingConfig()` in `setup.ts` with `alwaysEager` sections
 - [ ] Audit all CMS page JSONs — wrap below-fold sections in `Lazy.tsx`

package/.agents/skills/deco-to-tanstack-migration/references/codemod-commands.md

@@ -0,0 +1,174 @@
+# Codemod Commands
+
+All automation commands organized by phase. Run from project root.
+
+## Phase 1 — Imports & JSX
+
+### Preact → React (safe for bulk)
+
+```bash
+find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
+  -e 's|from "preact/hooks"|from "react"|g' \
+  -e 's|from "preact/compat"|from "react"|g' \
+  -e 's|from "preact"|from "react"|g'
+```
+
+### ComponentChildren → ReactNode
+
+```bash
+find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
+  -e 's/ComponentChildren/ReactNode/g'
+```
+
+### SVG attributes (safe for bulk)
+
+```bash
+find src/ -name '*.tsx' | xargs sed -i '' \
+  -e 's/stroke-width=/strokeWidth=/g' \
+  -e 's/stroke-linecap=/strokeLinecap=/g' \
+  -e 's/stroke-linejoin=/strokeLinejoin=/g' \
+  -e 's/fill-rule=/fillRule=/g' \
+  -e 's/clip-rule=/clipRule=/g' \
+  -e 's/clip-path=/clipPath=/g' \
+  -e 's/stroke-dasharray=/strokeDasharray=/g' \
+  -e 's/stroke-dashoffset=/strokeDashoffset=/g'
+```
+
+### HTML attributes
+
+```bash
+find src/ -name '*.tsx' | xargs sed -i '' \
+  -e 's/ for=/ htmlFor=/g' \
+  -e 's/ fetchpriority=/ fetchPriority=/g' \
+  -e 's/ autocomplete=/ autoComplete=/g'
+```
+
+### Remove JSX pragmas
+
+```bash
+find src/ -name '*.tsx' -o -name '*.ts' | xargs sed -i '' \
+  -e '/\/\*\* @jsxRuntime automatic \*\//d' \
+  -e '/\/\*\* @jsx h \*\//d' \
+  -e '/\/\*\* @jsxFrag Fragment \*\//d'
+```
+
+## Phase 2 — Signals
+
+### Module-level signal imports (safe for bulk)
+
+```bash
+find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
+  's|from "@preact/signals"|from "@decocms/start/sdk/signal"|g'
+```
+
+### Audit useSignal usage (manual conversion needed)
+
+```bash
+grep -rn 'useSignal\|useComputed' src/ --include='*.tsx' --include='*.ts'
+```
+
+## Phase 3 — Deco Framework
+
+### Remove $fresh imports
+
+```bash
+find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
+  -e 's|import { asset } from "\$fresh/runtime.ts";||g' \
+  -e 's|asset(\([^)]*\))|\1|g'
+```
+
+### Replace site-local import aliases
+
+```bash
+# Replace with your actual site name:
+SITE_NAME="osklenbr"
+
+find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
+  -e "s|from \"\\\$store/|from \"~/|g" \
+  -e "s|from \"deco-sites/${SITE_NAME}/|from \"~/|g" \
+  -e "s|from \"site/|from \"~/|g"
+```
+
+### IS_BROWSER replacement
+
+```bash
+find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
+  -e 's|import { IS_BROWSER } from "\$fresh/runtime.ts";||g' \
+  -e 's|IS_BROWSER|typeof window !== "undefined"|g'
+```
+
+## Phase 4 — Commerce
+
+```bash
+find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
+  -e 's|from "apps/commerce/types.ts"|from "@decocms/apps/commerce/types"|g' \
+  -e 's|from "apps/admin/widgets.ts"|from "~/types/widgets"|g' \
+  -e 's|from "apps/website/components/Image.tsx"|from "~/components/ui/Image"|g' \
+  -e 's|from "apps/website/components/Picture.tsx"|from "~/components/ui/Picture"|g' \
+  -e 's|from "apps/website/components/Video.tsx"|from "~/components/ui/Video"|g'
+```
+
+### SDK utilities
+
+```bash
+find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
+  -e 's|from "~/sdk/useOffer.ts"|from "@decocms/apps/commerce/sdk/useOffer"|g' \
+  -e 's|from "~/sdk/useOffer"|from "@decocms/apps/commerce/sdk/useOffer"|g' \
+  -e 's|from "~/sdk/format.ts"|from "@decocms/apps/commerce/sdk/formatPrice"|g'
+```
+
+## Phase 6 — Islands
+
+### Audit island types
+
+```bash
+echo "=== Wrapper islands (re-export from components) ==="
+grep -rl 'export.*from.*components' src/islands/ --include='*.tsx' 2>/dev/null
+
+echo ""
+echo "=== Standalone islands (have real logic) ==="
+find src/islands/ -name '*.tsx' ! -exec grep -l 'export.*from.*components' {} \; 2>/dev/null
+```
+
+### Repoint imports from islands/ to components/
+
+```bash
+find src/ -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \
+  's|from "~/islands/|from "~/components/|g'
+```
+
+## Verification Commands
+
+```bash
+# Zero old imports (run after all phases):
+echo "Preact: $(grep -r 'from "preact' src/ --include='*.tsx' --include='*.ts' | wc -l)"
+echo "Signals: $(grep -r '@preact/signals' src/ --include='*.tsx' --include='*.ts' | wc -l)"
+echo "@deco/deco: $(grep -r '@deco/deco' src/ --include='*.tsx' --include='*.ts' | wc -l)"
+echo "\$fresh: $(grep -r '\$fresh' src/ --include='*.tsx' --include='*.ts' | wc -l)"
+echo "apps/: $(grep -r 'from \"apps/' src/ --include='*.tsx' --include='*.ts' | wc -l)"
+echo "islands/: $(grep -r 'from \"~/islands/' src/ --include='*.tsx' --include='*.ts' | wc -l)"
+```
+
+## Pre-Flight Audit Script
+
+Run against the source site before starting migration:
+
+```bash
+echo "=== Source Site Audit ==="
+echo "Components: $(find components/ sections/ -name '*.tsx' 2>/dev/null | wc -l)"
+echo "Islands: $(find islands/ -name '*.tsx' 2>/dev/null | wc -l)"
+echo "Sections: $(find sections/ -name '*.tsx' 2>/dev/null | wc -l)"
+echo "Loaders: $(find loaders/ -name '*.ts' -o -name '*.tsx' 2>/dev/null | wc -l)"
+echo ""
+echo "=== Import Dependencies ==="
+echo "Preact: $(grep -rl 'from "preact' . --include='*.tsx' --include='*.ts' 2>/dev/null | wc -l) files"
+echo "Signals: $(grep -rl '@preact/signals' . --include='*.tsx' --include='*.ts' 2>/dev/null | wc -l) files"
+echo "@deco/deco: $(grep -rl '@deco/deco' . --include='*.tsx' --include='*.ts' 2>/dev/null | wc -l) files"
+echo "\$fresh: $(grep -rl '\$fresh/' . --include='*.tsx' --include='*.ts' 2>/dev/null | wc -l) files"
+echo "apps/: $(grep -rl 'from \"apps/' . --include='*.tsx' --include='*.ts' 2>/dev/null | wc -l) files"
+echo "useSignal: $(grep -r 'useSignal' . --include='*.tsx' --include='*.ts' -c 2>/dev/null | awk -F: '{sum+=$2} END{print sum}')"
+echo ""
+echo "=== CMS Blocks ==="
+echo "Total: $(find .deco/blocks/ -name '*.json' 2>/dev/null | wc -l)"
+echo "Pages: $(find .deco/blocks/ -name 'pages-*.json' 2>/dev/null | wc -l)"
+```