@decocms/start 0.19.0

package/.cursor/skills/deco-core-architecture/site-usage.md

@@ -0,0 +1,165 @@
+# How a Deco Site Uses the Framework
+
+Reference based on `deco-sites/osklenbr`, a production VTEX storefront using Fresh/Preact.
+
+## Site Structure
+
+```
+osklenbr/
+|-- deno.json              # Dependencies, tasks, import map
+|-- fresh.config.ts        # Fresh + Deco plugin registration
+|-- manifest.gen.ts        # Auto-generated manifest (site blocks)
+|-- fresh.gen.ts           # Auto-generated Fresh manifest (routes + islands)
+|-- runtime.ts             # Typed invoke client
+|-- main.ts                # Production entry: start(manifest, config)
+|-- dev.ts                 # Dev entry: tailwind build + dotenv + Fresh dev
+|
+|-- apps/                  # App registrations (site.ts, decohub.ts)
+|-- sections/              # 117 UI sections (Preact components)
+|-- islands/               # 99 interactive islands (Preact)
+|-- loaders/               # 13 site-specific loaders
+|-- actions/               # 4 site-specific actions
+|-- routes/                # 2 routes (_app.tsx, proxy.ts)
+|-- sdk/                   # Client-side utilities
+|-- components/            # Shared Preact components
+|-- static/                # Static assets
+```
+
+## Configuration
+
+### deno.json
+
+Key imports: `$fresh/` (Fresh 1.7.3), `@deco/deco` (1.174.2), `apps/` (deco-cx/apps 0.139.0), `$store/` and `site/` (self-reference).
+
+Tasks: `start` (production via deco.cx/run), `dev` (generate + Fresh dev), `gen` (manifest generation).
+
+JSX: `react-jsx` with `preact` import source.
+
+### fresh.config.ts
+
+```typescript
+import { defineConfig } from "$fresh/server.ts";
+import { plugins } from "deco/plugins/deco.ts";
+import manifest from "./manifest.gen.ts";
+
+export default defineConfig({
+  plugins: plugins({ manifest, htmx: false }),
+});
+```
+
+### runtime.ts
+
+```typescript
+import { proxy } from "@deco/deco/web";
+import type { Manifest } from "./manifest.gen.ts";
+import type { Manifest as VTEXManifest } from "apps/vtex/manifest.gen.ts";
+
+export const invoke = proxy<Manifest & VTEXManifest>();
+```
+
+## App Registration (`apps/`)
+
+### apps/site.ts
+
+```typescript
+import manifest, { Manifest } from "../manifest.gen.ts";
+import { type App, type AppContext as AC } from "@deco/deco";
+import commerce from "apps/commerce/mod.ts";
+import std from "apps/compat/std/mod.ts";
+
+export type AppContext = AC<ReturnType<typeof Site>>;
+
+export default function Site(state: Props): App<
+  Manifest, Props, [typeof std, ReturnType<typeof commerce>]
+> {
+  return {
+    state,
+    manifest,
+    dependencies: [std(state), commerce(state)],
+  };
+}
+```
+
+Key pattern: site app bundles manifest + commerce dependencies. `AppContext` enables typed `ctx.invoke()`.
+
+### apps/decohub.ts
+
+```typescript
+export { default, Preview } from "apps/decohub/mod.ts";
+```
+
+## Execution Flow
+
+### Production
+```
+main.ts -> fresh.gen.ts + fresh.config.ts -> start(manifest, config)
+  -> Fresh server starts
+  -> Deco plugin initializes
+  -> Loads DecofileProvider (CMS state)
+  -> Installs apps (site -> commerce -> vtex)
+  -> Registers all block resolvers
+  -> Mounts routes + middleware
+```
+
+### Dev
+```
+dev.ts -> Build Tailwind -> Load .env -> Fresh dev server -> Generate manifest -> Hot reload
+```
+
+## Manifest System
+
+### manifest.gen.ts (Deco)
+
+Contains loaders (13), sections (117), actions (4), matchers (1), apps (2). Keys formatted as `site/loaders/...`, `site/sections/...`.
+
+### fresh.gen.ts (Fresh)
+
+Contains routes (2) and islands (99). Generated by Fresh from the Deco plugin.
+
+## Loader/Action Patterns
+
+### Site Loader
+
+```typescript
+import { AppContext } from "site/apps/site.ts";
+
+export default async function loader(
+  props: Props,
+  _req: Request,
+  ctx: AppContext,
+): Promise<Store[]> {
+  // fetch data, transform, return
+}
+```
+
+### Invoking Other Apps
+
+```typescript
+export default async function loader(props: Props, _req: Request, ctx: AppContext) {
+  const products = await ctx.invoke(
+    "vtex/loaders/intelligentSearch/productListingPage.ts",
+    { query: props.query, count: 12 },
+  );
+  return products;
+}
+```
+
+## Routes
+
+`_app.tsx` is the global layout. Page routes are NOT file-based; they come from the CMS admin decofile.
+
+## Migration Patterns for TanStack
+
+| Fresh/Deco Pattern | TanStack Equivalent |
+|--------------------|---------------------|
+| `manifest.gen.ts` | Explicit exports from `@decocms/apps-start` |
+| `runtime.ts` invoke proxy | Direct function imports + React Query |
+| Islands | Regular React components |
+| Fresh `<Partial>` | TanStack Router navigation |
+| `useSection()` partial render | React state + React Query invalidation |
+| `ctx.invoke("key", props)` | Direct function call: `loaderFn(props)` |
+| `AppContext` | `configureVtex()` + env vars |
+| Deco plugin | TanStack Start entry + `@decocms/start` |
+| DecofileProvider | Admin API from `@decocms/start` |
+| `@preact/signals` | `@tanstack/react-store` or React state |
+| `Deno.env.get()` | `process.env` or `import.meta.env` |

package/.cursor/skills/deco-e2e-testing/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: deco-e2e-testing
+description: Implement end-to-end performance tests for any Deco e-commerce site with lazy section tracking, cache analysis, and observability. Use this skill when asked to set up e2e tests, create performance testing infrastructure, or test user journeys on a Deco/VTEX site.
+---
+
+# Deco E2E Performance Testing Skill
+
+This skill helps you implement comprehensive e2e performance tests for Deco e-commerce sites. It covers the full user journey: Home → PLP → PDP → Add to Cart, with **lazy section tracking**, **cache analysis**, and **device-specific reports**.
+
+## When to Use This Skill
+
+- Setting up e2e tests from scratch on a Deco site
+- Creating performance testing infrastructure
+- Testing cache performance (cold vs warm)
+- Validating TTFB, FCP, and other Core Web Vitals
+- **Debugging slow lazy sections** (`/deco/render` requests)
+- **Analyzing page cache and CDN behavior**
+- **Comparing performance across desktop/mobile**
+
+## Quick Start
+
+1. **Discover site-specific values** (read `discovery.md`)
+2. **Run scaffold script** or copy templates manually
+3. **Configure selectors** for your site
+4. **Add deno.json tasks** for easy test execution
+5. **Run tests** and verify
+
+## Workflow
+
+```
+1. Read discovery.md → Find site-specific selectors
+2. Run scaffold.sh → Create test directory structure
+3. Replace {{PLACEHOLDERS}} → Customize for site
+4. Add deno.json tasks → Enable `deno task test:e2e`
+5. npm install && deno task test:e2e → Verify tests work
+```
+
+## Directory Structure to Create
+
+```
+tests/e2e/
+├── README.md
+├── package.json
+├── playwright.config.ts
+├── tsconfig.json
+├── specs/
+│   └── ecommerce-flow.spec.ts
+├── utils/
+│   └── metrics-collector.ts
+├── scripts/
+│   └── baseline.ts
+└── reports/                    # gitignored
+    ├── report-desktop-chrome.json
+    ├── report-mobile-chrome.json
+    └── baselines/
+
+scripts/
+└── run-e2e.ts                  # Test runner with server management
+```
+
+## Test Flow
+
+| Step | Page | Metrics |
+|------|------|---------|
+| 1 | Server Warmup | Liveness check, lazy import trigger |
+| 2 | Homepage (cold cache) | TTFB, FCP, lazy sections, scroll |
+| 3 | Homepage (warm cache) | Cache improvement |
+| 4 | PLP (cold cache) | TTFB, products loaded, lazy sections |
+| 5 | PLP (warm cache) | Cache improvement |
+| 6 | PDP (cold cache) | TTFB, buy button, lazy sections |
+| 7 | PDP (warm cache) | Cache improvement |
+| 8 | Add to Cart | Response time |
+| 9 | Minicart | Verification (with retry) |
+
+## Key Features
+
+### 1. Lazy Section Tracking
+
+The test tracks all `/deco/render` requests (lazy-loaded sections) with:
+- **Section name** extracted from `x-deco-section` header
+- **Timing** with color-coded status (🟢 fast, 🟡 medium, 🔴 slow)
+- **Cache status** (💾 HIT, ❌ MISS, ⏳ STALE)
+
+```
+🔄 Lazy Sections (14):
+┌───────────────────────────────────────────────────────────
+│ 🔴 Product/ProductShelf: L...  1182ms 💾 cached
+│ 🔴 Product/ProductShelfGroup   1000ms 💾 cached
+│ 🟢 Footer/Footer                 13ms 💾 cached
+└───────────────────────────────────────────────────────────
+📊 Summary: 5 fast, 2 medium, 7 slow │ Total: 7121ms
+```
+
+### 2. Scroll-Based Lazy Loading
+
+The test scrolls the page to trigger lazy sections and waits for them:
+
+```typescript
+// Scroll until footer is visible, waiting for pending renders
+await collector.scrollPage(page, true) // full=true for homepage
+```
+
+This ensures all lazy sections are triggered and their performance is measured.
+
+### 3. Device-Specific Reports
+
+Tests run on both desktop and mobile with separate reports:
+
+```
+reports/
+├── report-desktop-chrome.json
+├── report-mobile-chrome.json
+├── report-latest-desktop.json
+└── report-latest-mobile.json
+```
+
+### 4. Enhanced Report Structure
+
+Reports include a summary for easy comparison:
+
+```json
+{
+  "project": "desktop-chrome",
+  "timestamp": "2026-01-18T...",
+  "summary": {
+    "totalPages": 7,
+    "avgTTFB": 485,
+    "avgFCP": 892,
+    "totalLazyRenders": 32,
+    "totalLoaders": 12,
+    "cacheHits": 28,
+    "cacheMisses": 4,
+    "pages": [...]
+  },
+  "metrics": [...]
+}
+```
+
+### 5. Deco Observability Headers
+
+The test captures custom Deco headers for debugging:
+- `x-deco-section` - Section component type and title
+- `x-deco-page` - Matched page block name
+- `x-deco-route` - Matched route template
+
+## Critical: Server Warmup
+
+**Deco/Fresh lazily loads imports on first request.** This causes artificially high latency for the first request after server start. The test must:
+
+1. Wait for `/deco/_liveness` endpoint to return 200
+2. Make a warmup request to trigger lazy imports
+3. Only then start measuring performance
+
+```typescript
+const LIVENESS_PATH = '/deco/_liveness'
+
+async function waitForServerReady(baseUrl: string) {
+    // Step 1: Wait for liveness
+    for (let i = 0; i < 30; i++) {
+        const res = await fetch(`${baseUrl}/deco/_liveness`)
+        if (res.ok) break
+        await new Promise(r => setTimeout(r, 1000))
+    }
+
+    // Step 2: Warmup request to trigger lazy imports
+    await fetch(`${baseUrl}/?__d`)
+}
+```
+
+## Key Configuration
+
+The `SITE_CONFIG` object centralizes all site-specific values:
+
+```typescript
+const SITE_CONFIG = {
+    // URLs
+    baseUrl: 'https://localhost--{sitename}.deco.site',
+    plpPath: '/category-path',
+    fallbackPdpPath: '/product-name-sku/p',
+    
+    // Always use ?__d for Server-Timing headers
+    debugParam: '?__d',
+
+    // Deco framework endpoints
+    livenessPath: '/deco/_liveness',
+
+    // Selectors
+    productCard: '[data-deco="view-product"]',
+    productCardFallback: 'a:has-text("R$")',
+    buyButton: 'button:has-text("Comprar agora")',
+    buyButtonFallback: 'button:has-text("Comprar")',
+    minicartText: 'Produtos Adicionados',
+
+    // Sizes (fashion) or voltages (electronics)
+    sizes: ['P', 'M', 'G', 'GG'],
+    voltages: ['110V', '127V', '220V', 'Bivolt'],
+
+    // Thresholds (ms)
+    thresholds: {
+        coldTTFB: 5000,
+        warmTTFB: 2000,
+        homeTTFB: 3000,
+        homeWarmTTFB: 1500,
+    },
+
+    // Server warmup settings
+    warmup: {
+        livenessRetries: 30,
+        livenessRetryDelay: 1000,
+        warmupTimeout: 60000,
+    },
+}
+```
+
+## deno.json Integration
+
+Add these tasks to the site's `deno.json`:
+
+```json
+{
+  "tasks": {
+    "test:e2e": "deno run -A scripts/run-e2e.ts",
+    "test:e2e:headed": "deno run -A scripts/run-e2e.ts --headed",
+    "test:e2e:install": "cd tests/e2e && npm install && npx playwright install chromium",
+    "test:e2e:baseline:save": "deno run -A tests/e2e/scripts/baseline.ts save",
+    "test:e2e:baseline:compare": "deno run -A tests/e2e/scripts/baseline.ts compare"
+  }
+}
+```
+
+## .gitignore Updates
+
+Add to `.gitignore`:
+
+```gitignore
+# E2E test reports (generated artifacts)
+tests/e2e/reports/report-*.json
+tests/e2e/reports/test-results/
+tests/e2e/reports/results.json
+```
+
+## Files in This Skill
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | This overview |
+| `discovery.md` | How to find site-specific values |
+| `templates/` | Ready-to-use test files |
+| `templates/scripts/run-e2e.ts` | Test runner with server management |
+| `templates/scripts/baseline.ts` | Baseline save/compare script |
+| `selectors.md` | Platform-specific selector patterns |
+| `troubleshooting.md` | Common issues and fixes |
+| `scripts/scaffold.sh` | Auto-create test structure |
+
+## Expected Output
+
+```
+══════════════════════════════════════════════════════════════════════
+🖥️  Desktop (desktop-chrome)
+══════════════════════════════════════════════════════════════════════
+
+══════════════════════════════════════════════════════════════════════
+🏠 HOMEPAGE (cold cache)
+══════════════════════════════════════════════════════════════════════
+   📜 Scrolling to trigger lazy renders (full)...
+      ⏳ Waiting for 1 pending render before next scroll...
+      ✅ Footer visible after 47 scrolls
+   📜 Triggered 13 lazy renders
+
+   🟢 TTFB:   414ms  🟡 FCP:  1508ms  │  🌐 369 requests (11.7 MB)
+
+   ⚡ Server Timing: 0ms total (1 loaders)
+
+   🔄 Lazy Sections (14):
+   ┌───────────────────────────────────────────────────────────
+   │ 🔴 Product/ProductShelf: L...  1182ms 💾 cached
+   │ 🔴 Product/ProductShelfGroup   1000ms 💾 cached
+   │ 🟢 Content/SimpleText            18ms 💾 cached
+   │ 🟢 Footer/Footer                 13ms 💾 cached
+   └───────────────────────────────────────────────────────────
+   📊 Summary: 5 fast, 2 medium, 7 slow │ Total: 7121ms
+
+══════════════════════════════════════════════════════════════════════
+📊 PERFORMANCE SUMMARY
+══════════════════════════════════════════════════════════════════════
+
+   ┌──────────────────┬─────────────┬─────────────┬────────┐
+   │ Page             │       TTFB  │        FCP  │  Lazy  │
+   ├──────────────────┼─────────────┼─────────────┼────────┤
+   │ Homepage Cold    │ 🟢   414ms │  🟡  1508ms │     14 │
+   │ Homepage Warm    │ 🟢   485ms │  🟢   560ms │      4 │
+   │ PLP Cold         │ 🟢   456ms │  🟢   508ms │      3 │
+   │ PDP Cold         │ 🟢   459ms │  🟢   520ms │      4 │
+   └──────────────────┴─────────────┴─────────────┴────────┘
+
+   Legend: 🟢 Good  🟡 Needs Work  🔴 Poor
+   Thresholds: TTFB <500ms good, <800ms ok | FCP <1000ms good, <1800ms ok
+```
+
+## Baseline Comparison
+
+Save performance baselines and compare future runs to detect regressions.
+
+### Save a Baseline
+
+```bash
+deno task test:e2e:baseline:save
+```
+
+### Compare Against Baseline
+
+```bash
+deno task test:e2e:baseline:compare
+```
+
+### Regression Thresholds
+
+| Metric | Threshold |
+|--------|-----------|
+| TTFB   | +10% |
+| FCP    | +10% |
+| LCP    | +15% |
+| CLS    | +50% |
+
+## Minicart Robustness
+
+The minicart verification uses multiple selectors and retry logic:
+
+```typescript
+async isMinicartOpen(): Promise<boolean> {
+    const selectors = [
+        `text=${SITE_CONFIG.minicartText}`,
+        '[data-testid="minicart"]',
+        '.minicart',
+        '[class*="minicart"]',
+        '[class*="cart-drawer"]',
+    ]
+    
+    // Retry with increasing timeout
+    for (let attempt = 0; attempt < 3; attempt++) {
+        const timeout = 2000 + (attempt * 1000)
+        for (const selector of selectors) {
+            const visible = await this.page.locator(selector).first()
+                .isVisible({ timeout }).catch(() => false)
+            if (visible) return true
+        }
+        await this.page.waitForTimeout(500)
+    }
+    return false
+}
+```
+
+## Integration with Deco Runtime
+
+For full lazy section observability, ensure your deco runtime includes:
+
+1. **x-deco-section header** in `/deco/render` responses
+2. **x-deco-page header** with matched page block name
+3. **x-deco-route header** with matched route template
+
+These are set in:
+- `deco/runtime/features/render.tsx` - Section name extraction
+- `deco/runtime/routes/render.tsx` - Header setting
+- `deco/runtime/middleware.ts` - Page/route headers
+- `apps/website/handlers/fresh.ts` - Page block state
+
+## Next Steps
+
+1. Read `discovery.md` to learn how to find the correct selectors and paths
+2. Check `selectors.md` for platform-specific patterns (VTEX, Shopify, VNDA)
+3. See `troubleshooting.md` if tests fail
+4. Use the MCP tools to search for related optimization patterns