@decocms/start 0.19.0

package/.cursor/skills/deco-islands-migration/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: deco-islands-migration
+description: Eliminate the src/islands/ directory when migrating Deco storefronts from Fresh/Preact to TanStack Start/React. Explains why islands don't make sense in the new stack, the problems they cause, how to systematically repoint or move them, and how to fix vanilla-JS DOM patterns that break React hydration. Use when auditing or removing islands from a migrated storefront.
+---
+
+# Deco Islands Migration — From Fresh Islands to React Components
+
+## Why Islands Don't Make Sense in TanStack Start
+
+In **Fresh/Preact**, islands were a core architecture concept: the server rendered static HTML and only specific `islands/` components shipped JavaScript to the browser for hydration. Everything outside `islands/` was server-only.
+
+In **TanStack Start/React**, there is no islands boundary. React performs **full hydration** of the entire component tree. Every component — whether it lives in `src/components/` or `src/islands/` — is sent to the client and hydrated. The `src/islands/` directory is a **dead artifact** that:
+
+1. **Adds a useless indirection layer** — each island is typically a 3-line wrapper that re-exports a component
+2. **Confuses the mental model** — developers think islands have special client-side powers
+3. **Doubles the module graph** — Vite must resolve and bundle both the island wrapper AND the real component
+4. **Hides the real component path** — makes searching, refactoring, and debugging harder
+5. **Breaks tree-shaking assumptions** — bundler can't optimize through the extra re-export layer
+
+## What an Island Wrapper Looks Like
+
+```typescript
+// src/islands/AddToCartButton/vtex.tsx  (TYPICAL WRAPPER — DELETE THIS)
+import Component from "~/components/product/AddToCartButton/vtex.tsx";
+import type { Props } from "~/components/product/AddToCartButton/vtex.tsx";
+
+function Island(props: Props) {
+  return <Component {...props} />;
+}
+export default Island;
+```
+
+This does literally nothing. The `<Component {...props} />` call is a pass-through.
+
+## What a Standalone Island Looks Like
+
+Some islands are NOT wrappers — they contain real logic and have no equivalent in `src/components/`:
+
+```typescript
+// src/islands/ForgeViewer/ForgeViewer.tsx  (STANDALONE — MUST BE MOVED)
+import { useEffect } from "react";
+
+export default function ForgeViewerIsland({ urn }) {
+  useEffect(() => {
+    // Real Autodesk Forge 3D viewer initialization
+    getAccessToken().then(({ token }) => {
+      Autodesk.Viewing.Initializer(options, () => { /* ... */ });
+    });
+  }, []);
+  return <div id="forgeViewer" />;
+}
+```
+
+These must be **moved** to `src/components/`, not just repointed.
+
+## Migration Strategy
+
+### Phase 1 — Discover and Classify
+
+```bash
+# List all island files
+find src/islands -name '*.tsx' -o -name '*.ts' | sort
+
+# Find all imports referencing islands/
+rg 'from ["'"'"'].*islands/' src/ --glob '*.{tsx,ts}' -l
+
+# Classify each island:
+# For each file in src/islands/X.tsx, check if it's a wrapper or standalone:
+rg 'import.*from.*components' src/islands/X.tsx
+# If it imports from components/ and re-exports → WRAPPER (repoint)
+# If it has real logic → STANDALONE (move to components/)
+```
+
+### Phase 2 — Repoint Wrappers
+
+For each wrapper island, find every file that imports it and change the import to point directly at the real component.
+
+**Pattern:**
+```
+~/islands/SliderJS.tsx           → ~/components/ui/SliderJS.tsx
+~/islands/AddToCartButton/vtex   → ~/components/product/AddToCartButton/vtex.tsx
+~/islands/WishlistButton/vtex    → ~/components/wishlist/WishlistButton/vtex.tsx
+~/islands/Header/CartDrawer      → ~/components/header/Drawers.tsx (named export)
+~/islands/Newsletter             → ~/components/footer/Newsletter.tsx
+```
+
+**How to find the target:**
+1. Read the island file
+2. Look at its `import Component from "~/components/..."` line
+3. That's your target path
+
+**How to find consumers:**
+```bash
+rg 'from ["'"'"'].*islands/SliderJS' src/ --glob '*.{tsx,ts}'
+```
+
+**Apply with StrReplace** on each consumer file.
+
+### Phase 3 — Move Standalone Islands
+
+For islands with real logic:
+
+1. Create the target directory: `mkdir -p src/components/ForgeViewer/`
+2. Copy the file: `cp src/islands/ForgeViewer/ForgeViewer.tsx src/components/ForgeViewer/ForgeViewer.tsx`
+3. Update all imports that referenced the old path
+4. Verify no references remain
+
+### Phase 4 — Delete src/islands/
+
+```bash
+# Final verification — MUST return zero results
+rg 'from ["'"'"'].*islands/' src/ --glob '*.{tsx,ts}'
+
+# Delete
+rm -rf src/islands/
+```
+
+## Common Problems Islands Cause (and Fixes)
+
+### 1. Vanilla JS DOM Manipulation Conflicts with React
+
+Many island components were written for Fresh where they needed vanilla JS to add interactivity. In React, this creates **hydration mismatches** and **broken event handlers**.
+
+**Problem: `document.querySelector` to control UI state**
+```typescript
+// BAD — bypasses React's state management
+const cartCheckbox = document.querySelector('.drawer-end .drawer-toggle') as HTMLInputElement;
+if (cartCheckbox) cartCheckbox.checked = true;
+```
+
+**Fix: Use React state/signals**
+```typescript
+// GOOD — let React manage the DOM
+const { displayCart } = useUI();
+displayCart.value = true;
+```
+
+### 2. `addEventListener` Without `window.` Prefix
+
+In Fresh/Deno, bare `addEventListener` works at module scope. In React components rendered via SSR, it can fail or attach to the wrong scope.
+
+**Problem:**
+```typescript
+addEventListener("keydown", handler);    // ambiguous scope
+removeEventListener("keydown", handler); // might not match
+```
+
+**Fix:**
+```typescript
+window.addEventListener("keydown", handler);
+// cleanup in useEffect return:
+return () => window.removeEventListener("keydown", handler);
+```
+
+### 3. `removeEventListener` With New Function References
+
+**Problem: Memory leak — listener never removed**
+```typescript
+// BAD — anonymous function creates new reference each time
+dots?.item(i).addEventListener("click", () => goToItem(i));
+// Later...
+dots?.item(i).removeEventListener("click", () => goToItem(i)); // DIFFERENT function!
+```
+
+**Fix: Store handler references**
+```typescript
+const dotHandlers: Array<() => void> = [];
+for (let i = 0; i < (dots?.length ?? 0); i++) {
+  const handler = () => goToItem(i);
+  dotHandlers.push(handler);
+  dots?.item(i).addEventListener("click", handler);
+}
+
+// Cleanup
+return () => {
+  for (let i = 0; i < dotHandlers.length; i++) {
+    dots?.item(i).removeEventListener("click", dotHandlers[i]);
+  }
+};
+```
+
+### 4. Inline Scripts Without Cleanup
+
+Components using `useScriptAsDataURI` or `dangerouslySetInnerHTML` to inject scripts won't have React lifecycle cleanup. For analytics/tracking this is acceptable (fire-and-forget). For interactive UI, convert to React hooks:
+
+**Before (inline script):**
+```typescript
+<script dangerouslySetInnerHTML={{
+  __html: `document.getElementById('${id}').addEventListener('click', ...)`
+}} />
+```
+
+**After (React hook):**
+```typescript
+useEffect(() => {
+  const el = document.getElementById(id);
+  const handler = () => { /* ... */ };
+  el?.addEventListener('click', handler);
+  return () => el?.removeEventListener('click', handler);
+}, [id]);
+```
+
+### 5. SVG Attributes Not Camel-Cased
+
+Fresh/Preact accepted HTML-style SVG attributes. React requires camelCase:
+
+| Fresh/Preact | React |
+|-------------|-------|
+| `stroke-linecap` | `strokeLinecap` |
+| `stroke-linejoin` | `strokeLinejoin` |
+| `stroke-width` | `strokeWidth` |
+| `fill-rule` | `fillRule` |
+| `clip-path` | `clipPath` |
+
+### 6. `class` vs `className`
+
+Preact accepts both `class` and `className`. React only accepts `className`. Some components accept a `class` prop — rename to `className` or support both:
+
+```typescript
+interface Props {
+  class?: string;
+  className?: string;
+}
+function Drawer({ class: classProp = "", className = "" }: Props) {
+  const cls = classProp || className;
+  return <div className={cls}>...</div>;
+}
+```
+
+## Checklist for Complete Removal
+
+- [ ] Zero results from `rg 'from.*islands/' src/ --glob '*.{tsx,ts}'`
+- [ ] `src/islands/` directory deleted
+- [ ] All `addEventListener` calls use explicit `window.` prefix
+- [ ] All `removeEventListener` calls use stored function references
+- [ ] No `document.querySelector` for state that React should manage
+- [ ] SVG attributes are camelCased
+- [ ] No `class` prop on native DOM elements (use `className`)
+- [ ] Build succeeds (`npm run build` / `bun run build`)
+- [ ] Dev server starts without errors
+- [ ] Interactive elements work: add to cart, sliders, drawers, modals
+
+## Related Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `deco-to-tanstack-migration` | Full migration playbook (imports, signals, architecture) |
+| `deco-tanstack-navigation` | SPA navigation patterns (`<a>` → `<Link>`, `useNavigate`, `loaderDeps`, forms) |
+| `deco-tanstack-storefront-patterns` | Runtime fixes post-migration (nested sections, caching, SliderJS, async_hooks, cart, server functions) |
+| `deco-storefront-test-checklist` | Context-aware QA checklist generation |
+| `deco-typescript-fixes` | TypeScript error patterns and fixes |

package/.cursor/skills/deco-loader-n-plus-1-detector/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: deco-loader-n-plus-1-detector
+description: Detect and fix N+1 API call patterns in Deco storefront section loaders. Finds loops calling individual VTEX/Shopify APIs per product instead of batching or using already-available data. Use when investigating slow page loads, high API latency, rate limiting (429s), or when optimizing SSR performance on Deco sites (Fresh or TanStack Start).
+---
+
+# Deco Loader N+1 Detector
+
+Finds N+1 API call anti-patterns in Deco storefront section loaders — the #1 cause of slow SSR on e-commerce sites.
+
+## When to Use
+
+- Page loads are slow (SSR > 3s)
+- Terminal logs show many sequential/parallel API calls for the same endpoint
+- VTEX returns 429 (Too Many Requests) errors
+- User reports "a troca de pagina ta demorando"
+- After migrating loaders or adding new shelf/search sections
+
+## What It Finds
+
+| Pattern | Severity | Example |
+|---------|----------|---------|
+| **API call inside `.map()`** | Critical | `products.map(p => getSpec(p.id))` |
+| **Missing batch alternative** | High | Individual calls where batch API exists |
+| **Redundant data fetch** | High | Fetching data already in the Product object |
+| **Sequential awaits in loop** | Medium | `for (p of products) { await fetch(p) }` |
+| **Unbounded parallel calls** | Medium | `Promise.all(100items.map(fetch))` |
+
+## Workflow
+
+```
+1. Scan loaders → Find .map() + await + API call patterns
+2. Identify the API → Catalog, IS, simulation, masterdata
+3. Check if data is already available → Product.additionalProperty, offers, etc.
+4. If redundant → Remove the call, read from existing data
+5. If needed → Create batch endpoint or add caching
+6. Verify → Check terminal logs for eliminated calls
+```
+
+## Step 1: Scan for N+1 Patterns
+
+Search for the telltale pattern: an API call inside a `.map()` or `forEach()` within a loader.
+
+### Search Commands
+
+```bash
+# Find all loaders that call external APIs inside map/forEach
+grep -rn "\.map(.*async" src/components/ src/sections/ --include="*.tsx" --include="*.ts" | grep -i "loader\|export const loader"
+
+# Find getProductSpecification calls (most common N+1)
+grep -rn "getProductSpecification" src/
+
+# Find any VTEX API call inside a map
+grep -rn "vtexFetch\|vtex.*fetch\|catalog_system\|intelligent-search" src/ --include="*.tsx" --include="*.ts"
+
+# Find simulation calls per product
+grep -rn "cartSimulation\|usePriceSimulation" src/ --include="*.tsx" --include="*.ts"
+```
+
+### Red Flag Patterns
+
+```typescript
+// RED FLAG: API call per product in a map
+export const loader = async (props: Props, _req: Request) => {
+  const results = props.products?.map(async (product) => {
+    const extra = await someApiCall(product.id);  // N+1!
+    return { ...product, extra };
+  });
+  return { ...props, results: await Promise.all(results) };
+};
+```
+
+## Step 2: Classify the API Call
+
+| API Endpoint | What It Returns | Already in Product? |
+|--------------|-----------------|---------------------|
+| `/api/catalog_system/pvt/products/{id}/Specification` | Product specs by numeric ID | Yes — `product.isVariantOf.additionalProperty` |
+| `/api/catalog_system/pub/products/crossselling/{id}/*` | Related products | No — but should be 1 call per page, not per product |
+| `/api/checkout/pub/orderForms/simulation` | Price simulation | No — needs CEP, legitimate per-product call |
+| `/api/catalog_system/pub/products/variations/{id}` | SKU variations | Yes — `product.isVariantOf.hasVariant` |
+| `/api/dataentities/{entity}/search` | MasterData docs | No — check if can be batched with `_where=id=1 OR id=2` |
+
+## Step 3: Check If Data Already Exists
+
+### Product Specifications (Most Common N+1)
+
+The VTEX Intelligent Search API returns `specificationGroups` which the `@decocms/apps` transform converts to `product.isVariantOf.additionalProperty`.
+
+**Catalog API format** (what `getProductSpecification` returns):
+```json
+[{ "Id": 208, "Name": "Rendimento", "Value": ["4.5"] }]
+```
+
+**Schema.org format** (already in `product.isVariantOf.additionalProperty`):
+```json
+[{ "name": "Rendimento", "value": "4.5", "propertyID": "groupName", "valueReference": "PROPERTY" }]
+```
+
+To use the existing data, create a bridge helper:
+
+```typescript
+// src/sdk/productSpecs.ts
+import type { Product } from "@decocms/apps/commerce/types";
+
+const SPEC_NAME_TO_ID: Record<string, number> = {
+  // Map exact IS spec names → legacy numeric IDs used by components
+  // IMPORTANT: verify exact names via IS API, some have double spaces
+};
+
+export function getSpecsFromProduct(product: Product) {
+  const props = product.isVariantOf?.additionalProperty ?? [];
+  const specs: Array<{ Id: number; Value: string[] }> = [];
+  for (const p of props) {
+    if (p.valueReference !== "PROPERTY") continue;
+    const id = SPEC_NAME_TO_ID[p.name];
+    if (id == null) continue;
+    const existing = specs.find((s) => s.Id === id);
+    if (existing) existing.Value.push(p.value);
+    else specs.push({ Id: id, Value: [p.value] });
+  }
+  return specs;
+}
+```
+
+### How to Discover Spec Names
+
+```bash
+# Hit the IS API directly and inspect specificationGroups
+curl -s "https://{account}.vtexcommercestable.com.br/api/io/_v/api/intelligent-search/product_search/?count=3&query={product-type}&sc=1" \
+  | python3 -c "
+import json, sys
+for p in json.load(sys.stdin).get('products', []):
+    print(p['productId'], '-', p['productName'][:60])
+    for g in p.get('specificationGroups', []):
+        if g['name'] == 'allSpecifications':
+            for s in g['specifications']:
+                print(f'  \"{s[\"name\"]}\": {[v[:40] for v in s[\"values\"]]}')
+    print('---')
+"
+```
+
+### SKU Variations
+
+If calling `/api/catalog_system/pub/products/variations/{id}`:
+- Already available in `product.isVariantOf.hasVariant`
+- Each variant has `additionalProperty` with variation attributes
+
+### Product Reviews/Ratings
+
+If calling an external review API per product in shelves:
+- Consider lazy-loading reviews only on PDP
+- Or batch the API if it supports multiple product IDs
+
+## Step 4: Fix Strategies
+
+### Strategy A: Use Existing Data (Best)
+
+Replace the API call with a synchronous read from the Product object.
+
+**Before** (N HTTP calls):
+```typescript
+const productAdditional = await getProductSpecification(element.inProductGroupWithID);
+```
+
+**After** (0 HTTP calls):
+```typescript
+const productAdditional = getSpecsFromProduct(element);
+```
+
+### Strategy B: Create Batch Endpoint
+
+When the data genuinely doesn't exist in the Product:
+
+```typescript
+// apps-start/vtex/loaders/catalog.ts
+export async function getProductSpecifications(productIds: string[]) {
+  return Promise.all(
+    productIds.map(id => vtexFetch(`/api/catalog_system/pvt/products/${id}/Specification`))
+  );
+}
+```
+
+Even `Promise.all` with N calls is better than sequential awaits, but a true batch API is ideal.
+
+### Strategy C: Cache + Deduplicate
+
+For data that changes infrequently:
+
+```typescript
+const specCache = new Map<string, any>();
+
+export async function getCachedSpec(productId: string) {
+  if (specCache.has(productId)) return specCache.get(productId)!;
+  const result = await getProductSpecification(productId);
+  specCache.set(productId, result);
+  return result;
+}
+```
+
+### Strategy D: Lazy Load on Client
+
+Move enrichment to client-side for non-critical data:
+
+```typescript
+// Component fetches specs only when visible
+const [specs, setSpecs] = useState(null);
+useEffect(() => {
+  if (inView) fetchSpecs(productId).then(setSpecs);
+}, [inView]);
+```
+
+## Step 5: Verify the Fix
+
+### Check Terminal Logs
+
+After fixing, the terminal should show **zero** calls to the eliminated endpoint:
+
+```bash
+# Before: dozens of these per page load
+[vtex] GET .../api/catalog_system/pvt/products/123/Specification
+[vtex] GET .../api/catalog_system/pvt/products/456/Specification
+# ... 20+ more
+
+# After: none of these, only intelligent-search calls
+[vtex] GET .../api/io/_v/api/intelligent-search/product_search/...
+```
+
+### Measure Response Time
+
+```bash
+# Cold start
+curl -s -o /dev/null -w "%{http_code} %{time_total}s" http://localhost:5173/
+
+# Warm request
+curl -s -o /dev/null -w "%{http_code} %{time_total}s" http://localhost:5173/
+```
+
+Expected improvement: 2-15 seconds faster on pages with multiple shelves.
+
+## Common N+1 Locations in Deco Sites
+
+| Component | File Pattern | Typical N+1 |
+|-----------|-------------|-------------|
+| ProductShelf | `components/product/ProductShelf.tsx` | `getProductSpecification` per product |
+| SearchResult | `components/search/SearchResult.tsx` | `getProductSpecification` per product |
+| ProductTabbedShelf | `components/product/ProductTabbedShelf/` | Specs per product per tab |
+| BuyTogether | `components/product/BuyTogether/` | Cross-selling + specs per suggestion |
+| HouseCatalog | `components/search/HouseCatalog/` | Specs + simulation per product |
+| ProductShelfDinamica | `components/product/ProductShelfDinamica.tsx` | Specs per product in dynamic shelf |
+
+## Quick Audit Checklist
+
+- [ ] Search for `getProductSpecification` — replace with `getSpecsFromProduct` in shelf loaders
+- [ ] Search for `.map(async` inside `export const loader` — each is a potential N+1
+- [ ] Check for `usePriceSimulation` in loops — legitimate but verify it's parallelized
+- [ ] Check for `getCrossSelling` in loops — should only be on PDP, not shelves
+- [ ] Verify `Promise.all` wraps parallel calls — not sequential `await` in `for` loop
+- [ ] Check terminal logs for repeated API patterns during page load
+- [ ] Measure SSR time before and after changes
+
+## Impact Reference
+
+| Products on Page | N+1 Calls | Latency per Call | Total Added Latency |
+|------------------|-----------|------------------|---------------------|
+| 12 (1 shelf) | 12 | ~370ms | ~4.4s |
+| 24 (PLP) | 24 | ~370ms | ~8.9s |
+| 48 (PLP + 2 shelves) | 48 | ~370ms | ~17.8s |
+| 100 (homepage) | 100 | ~370ms | ~37s |
+
+Even with parallelism, VTEX rate limits kick in after ~20 concurrent calls, serializing the rest.
+
+## Related Skills
+
+- [deco-performance-audit](../deco-performance-audit/SKILL.md) — CDN-level metrics and cache analysis
+- [deco-full-analysis](../deco-full-analysis/SKILL.md) — Full site architecture analysis
+- [deco-edge-caching](../deco-edge-caching/SKILL.md) — Cache headers and edge configuration