@decocms/start 0.19.0

package/.cursor/skills/deco-full-analysis/checklists/asset-optimization.md

@@ -0,0 +1,251 @@
+# Asset Optimization Checklist
+
+17 learnings from real Deco sites. Check these during analysis.
+
+## Third-Party Scripts
+
+### 1. On-Demand Script Loading
+**Check**: Are heavy scripts loaded on page load?
+
+```typescript
+// Bad: Loads immediately
+<script src="https://chat-widget.com/bundle.js" />
+
+// Good: Load on interaction
+function ChatButton() {
+  const [loaded, setLoaded] = useState(false);
+  
+  const loadChat = () => {
+    if (!loaded) {
+      const script = document.createElement('script');
+      script.src = "https://chat-widget.com/bundle.js";
+      document.body.appendChild(script);
+      setLoaded(true);
+    }
+  };
+  
+  return <button onClick={loadChat}>Chat</button>;
+}
+```
+
+### 2. Route-Specific Script Injection
+**Check**: Do scripts load on pages where they're not used?
+
+```typescript
+// Good: Only load on relevant pages
+const isCheckout = ctx.url.pathname.startsWith('/checkout');
+const isPDP = ctx.url.pathname.includes('/p');
+
+return (
+  <>
+    {isCheckout && <PaymentScript />}
+    {isPDP && <ReviewScript />}
+  </>
+);
+```
+
+### 3. Script Localization
+**Check**: Are external scripts hosted locally?
+- Localize frequently used scripts to `/static`
+- Improves reliability and performance
+- Works offline
+
+```typescript
+// Before: External
+<script src="https://unpkg.com/htmx.org@1.9.10" />
+
+// After: Local
+<script src="/static/htmx-1.9.10.js" />
+```
+
+### 4. GTM Implementation
+**Check**: Does GTM have noscript fallback?
+
+```html
+<!-- Head -->
+<script>(function(w,d,s,l,i){...})(window,document,'script','dataLayer','GTM-XXX');</script>
+
+<!-- Body (required) -->
+<noscript>
+  <iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXX" />
+</noscript>
+```
+
+### 5. Third-Party Widget Removal
+**Check**: Are there unused third-party widgets?
+- Audit PDP for review widgets that can be lazy-loaded
+- Remove chat widgets from pages where not needed
+- Defer non-critical analytics
+
+## Section Optimization
+
+### 6. Lazy Section Loading
+**Check**: Are heavy below-fold sections lazy?
+
+```json
+{
+  "__resolveType": "website/sections/Rendering/Lazy.tsx",
+  "section": { "__resolveType": "site/sections/Product/Reviews.tsx" }
+}
+```
+
+Best candidates for lazy loading:
+- Product shelves
+- Reviews
+- Similar products
+- FAQ sections
+- Instagram feeds
+
+### 7. Skeleton/Fallback Pattern
+**Check**: Do async sections have loading states?
+
+```typescript
+export function LoadingFallback() {
+  return (
+    <div class="animate-pulse">
+      <div class="h-8 bg-gray-200 rounded w-1/3 mb-4" />
+      <div class="grid grid-cols-4 gap-4">
+        {[...Array(4)].map(() => (
+          <div class="h-64 bg-gray-200 rounded" />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+### 8. Video Section Handling
+**Check**: Are video sections wrapped in Lazy/Deferred?
+- Native video or iframes should NOT be lazy wrapped
+- Causes interaction breakage
+- Only lazy wrap if explicitly needed
+
+## Block Architecture
+
+### 9. Block Flattening
+**Check**: Are there unnecessary PageInclude wrappers?
+
+```json
+// Bad: Extra resolution overhead
+{
+  "__resolveType": "website/sections/PageInclude.tsx",
+  "page": { "__resolveType": "Header-Block" }
+}
+
+// Good: Direct reference
+{
+  "__resolveType": "$Header-Block"
+}
+```
+
+## Migration
+
+### 10. Standard Library Migration
+**Check**: Are there `deco-sites/std` imports?
+
+```typescript
+// Bad: Legacy
+import { Image } from "deco-sites/std/components/Image.tsx";
+
+// Good: Modern
+import { Image } from "apps/website/components/Image.tsx";
+```
+
+Audit all imports and replace:
+- `deco-sites/std` → `apps/`
+
+## Layout Stability
+
+### 11. Aspect Ratio Reservation
+**Check**: Do images/videos cause CLS?
+
+```tsx
+// Good: Reserve space
+<div class="aspect-video relative">
+  <Image class="absolute inset-0 w-full h-full object-cover" />
+</div>
+```
+
+## Security
+
+### 12. CSP Hardening
+**Check**: Are CSP headers configured?
+
+```typescript
+// In _middleware.ts
+const cspHeader = [
+  "default-src 'self'",
+  "script-src 'self' 'unsafe-inline' https://www.googletagmanager.com",
+  "worker-src 'self'",
+  "frame-ancestors 'self'",
+].join("; ");
+
+response.headers.set("Content-Security-Policy", cspHeader);
+```
+
+### 13. Service Worker Strategy
+**Check**: Is Service Worker strategy optimal?
+
+```typescript
+// Avoid: NetworkOnly as default (negates caching)
+defaultStrategy: "NetworkOnly"
+
+// Better: CacheFirst or StaleWhileRevalidate
+defaultStrategy: "CacheFirst"
+```
+
+## Deno Configuration
+
+### 14. Deno Native Optimization
+**Check**: Is `nodeModulesDir` enabled unnecessarily?
+
+```json
+// deno.json - disable if not needed
+{
+  "nodeModulesDir": false  // Faster startup, less disk
+}
+```
+
+### 15. Relative Path Invocation
+**Check**: Are loaders using absolute URLs?
+
+```typescript
+// Bad: Cross-domain overhead
+fetch("https://mysite.com/live/invoke/...");
+
+// Good: Relative path
+fetch("/live/invoke/...");
+```
+
+## Quick Audit Commands
+
+```bash
+# Find deco-sites/std imports
+grep -r "deco-sites/std" sections/ loaders/ components/
+
+# Find third-party scripts
+grep -r '<script src="http' sections/ components/
+
+# Find sections without LoadingFallback
+for f in sections/**/*.tsx; do
+  grep -q "LoadingFallback" "$f" || echo "Missing fallback: $f"
+done
+
+# Check CSP headers
+grep -r "Content-Security-Policy" routes/ _middleware.ts
+```
+
+## Asset Audit Table
+
+Add this to AGENTS.md:
+
+```markdown
+## Third-Party Scripts
+
+| Script | Pages | Load Strategy | Action |
+|--------|-------|---------------|--------|
+| GTM | All | Head | ✅ OK |
+| Chat Widget | All | Eager | 🔴 Make lazy |
+| Reviews | PDP | Eager | 🟡 Consider lazy |
+| Payment | Checkout | Conditional | ✅ OK |
+```

package/.cursor/skills/deco-full-analysis/checklists/bug-fix.md

@@ -0,0 +1,189 @@
+# Bug Fix Checklist
+
+8 learnings from real Deco sites. Check these during analysis.
+
+## Defensive Coding
+
+### 1. Defensive Prop Handling
+**Check**: Are CMS-configurable props accessed safely?
+
+```typescript
+// Bad: Crashes on undefined
+const title = props.title.toUpperCase();
+const items = props.items.map(i => i.name);
+
+// Good: Optional chaining
+const title = props.title?.toUpperCase() ?? "";
+const items = props.items?.map(i => i?.name) ?? [];
+```
+
+CMS props can be:
+- Undefined (not configured)
+- Null (explicitly cleared)
+- Empty arrays/strings
+
+### 2. Safe Request Parsing
+**Check**: Are API routes handling malformed requests?
+
+```typescript
+// Bad: Crashes on empty/malformed body
+export async function handler(req: Request) {
+  const body = await req.json();
+  return Response.json({ ok: true });
+}
+
+// Good: Try-catch wrapper
+export async function handler(req: Request) {
+  try {
+    const body = await req.json();
+    // ... process
+  } catch (e) {
+    return new Response("Bad Request", { status: 400 });
+  }
+}
+```
+
+### 3. Current Product Exclusion
+**Check**: Do "Related Products" shelves include current product?
+
+```typescript
+// Good: Filter out current product
+const relatedProducts = allProducts.filter(p => p.id !== currentProductId);
+```
+
+## Content Sanitization
+
+### 4. Protocol Upgrade Filter
+**Check**: Does external content have `http://` links?
+
+```typescript
+// Good: Upgrade to HTTPS
+function sanitizeContent(html: string): string {
+  return html.replace(/http:\/\//g, 'https://');
+}
+
+// Apply to product descriptions, CMS content, etc.
+<div dangerouslySetInnerHTML={{ 
+  __html: sanitizeContent(product.description) 
+}} />
+```
+
+Mixed content blocks images, scripts, and iframes.
+
+### 5. UTM Injection Prevention
+**Check**: Are empty links being processed?
+
+```typescript
+// Bad: Crashes on empty href
+document.querySelectorAll('a').forEach(link => {
+  const url = new URL(link.href); // Crashes if href is ""
+  url.searchParams.set('utm_source', 'site');
+  link.href = url.toString();
+});
+
+// Good: Validate first
+document.querySelectorAll('a[href]').forEach(link => {
+  if (!link.href || link.href === '#') return;
+  try {
+    const url = new URL(link.href);
+    url.searchParams.set('utm_source', 'site');
+    link.href = url.toString();
+  } catch {}
+});
+```
+
+## SEO & Indexing
+
+### 6. Soft Out-of-Stock Handling
+**Check**: Do out-of-stock pages return 404?
+
+```typescript
+// Bad: 404 for out-of-stock (loses SEO)
+if (!product.available) {
+  return new Response("Not Found", { status: 404 });
+}
+
+// Good: 200 with unavailable state
+if (!product.available) {
+  return renderUnavailablePage(product); // Status 200
+}
+```
+
+Out-of-stock products should:
+- Return 200 status
+- Show "unavailable" UI
+- Keep structured data
+- Maintain SEO value
+
+## UI Stability
+
+### 7. Smooth Image Transitions
+**Check**: Do hover effects cause flickering?
+
+```css
+/* Bad: Flicker on hover */
+.product-card:hover .secondary-image {
+  display: block; /* Hidden class uses display:none */
+}
+
+/* Good: Opacity transition */
+.product-card .secondary-image {
+  opacity: 0;
+  transition: opacity 0.3s;
+}
+.product-card:hover .secondary-image {
+  opacity: 1;
+}
+```
+
+Never combine `display: none` with opacity transitions.
+
+### 8. Pricing Consistency
+**Check**: Is promotional logic duplicated?
+
+```typescript
+// Bad: Different calculations in different places
+// ProductCard.tsx
+const price = product.price * 0.9;
+
+// ProductDetails.tsx
+const price = product.price - 10;
+
+// Good: Centralized utility
+// utils/pricing.ts
+export function calculateFinalPrice(product: Product): number {
+  const promotion = getActivePromotion(product);
+  return applyPromotion(product.price, promotion);
+}
+```
+
+Centralize:
+- Discount calculations
+- Promotion logic
+- Price formatting
+
+## Quick Audit Commands
+
+```bash
+# Find unsafe prop access (no optional chaining)
+grep -rn "props\.\w\+\." sections/ | grep -v "props\.\w\+?\."
+
+# Find direct URL construction without try-catch
+grep -rn "new URL" islands/ | grep -v "try"
+
+# Find http:// in content
+grep -r "http://" .deco/blocks/*.json | grep -v "https://"
+
+# Find 404 responses
+grep -r "status: 404" loaders/ sections/
+```
+
+## Common Bug Patterns
+
+| Bug | Symptom | Fix |
+|-----|---------|-----|
+| Null prop access | White screen, error in console | Add optional chaining |
+| Mixed content | Images not loading | Upgrade http to https |
+| OOS 404 | SEO drops for seasonal items | Return 200 with unavailable UI |
+| Duplicate pricing | Different prices across site | Centralize price logic |
+| Flickering images | Visual glitch on hover | Use opacity not display |

package/.cursor/skills/deco-full-analysis/checklists/cache-strategy.md

@@ -0,0 +1,144 @@
+# Cache Strategy Checklist
+
+7 learnings from real Deco sites. Check these during analysis.
+
+## Loader Caching
+
+### 1. Stale-While-Revalidate Pattern
+**Check**: Do custom loaders have cache configuration?
+
+```typescript
+// Good: Has caching
+export const cache = "stale-while-revalidate";
+
+export const cacheKey = (props: Props) =>
+  `${props.productId}-${props.locale}`;
+
+export default async function loader(props: Props) {
+  // ...
+}
+```
+
+### 2. Deterministic Cache Keys
+**Check**: Are cache keys based on unique identifiers?
+
+```typescript
+// Bad: Uses full URL (includes tracking params)
+export const cacheKey = (props: Props, req: Request) => req.url;
+
+// Good: Uses only relevant data
+export const cacheKey = (props: Props) => {
+  const facets = [...(props.facets || [])].sort();
+  return `${props.query}-${facets.join(",")}`;
+};
+```
+
+**Common mistakes**:
+- Including UTM parameters in cache key
+- Including session/user-specific data
+- Using unsorted arrays (order changes = cache miss)
+
+### 3. Loader Deduplication via Shared Blocks
+**Check**: Are the same loaders configured inline in multiple places?
+
+```json
+// Bad: Same loader inline in multiple pages
+// pages-Home.json, pages-PLP.json, pages-PDP.json all have:
+{ "loader": { "productId": "..." } }
+
+// Good: Reference shared block
+{ "__resolveType": "$live/loaders/Loader.tsx", "loader": "PDP-Main-Loader" }
+```
+
+Benefits:
+- Single cache entry for same data
+- Easier to update
+- Better hit rate
+
+## Rate Limiting
+
+### 4. Bot-Specific Rate Limiting
+**Check**: Do bots and users share rate limits?
+
+```typescript
+// In _middleware.ts
+const isBot = req.headers.get("user-agent")?.includes("bot");
+
+if (isBot) {
+  // Apply stricter rate limiting for bots
+  const botRateLimit = await checkBotRateLimit(ip);
+  if (botRateLimit.exceeded) {
+    return new Response("Too Many Requests", { status: 429 });
+  }
+}
+```
+
+### 5. Granular Rate Limit Tracking
+**Check**: Is rate limiting per-endpoint or global?
+- Track rate limits per endpoint for critical paths
+- Allow more requests to cached endpoints
+
+## SSR Caching
+
+### 6. SSR Promotion Fetching
+**Check**: Is promotion data fetched client-side causing CLS?
+- Fetch discount/promotion rules on server
+- Prevents price flickering
+
+```typescript
+// Good: Fetch on server
+export default async function ProductCard({ product }: Props) {
+  const promotion = await fetchPromotion(product.id);
+  const finalPrice = applyPromotion(product.price, promotion);
+  return <Card price={finalPrice} />;
+}
+```
+
+### 7. Related Products Caching
+**Check**: Do related product loaders have cache?
+- Often high-volume, low-change-rate
+- Good candidate for aggressive caching
+
+```typescript
+export const cache = "stale-while-revalidate";
+export const cacheKey = (props: Props) => `related-${props.productId}`;
+```
+
+## Cache Audit Table
+
+Add this to AGENTS.md:
+
+```markdown
+## Caching Inventory
+
+| Loader | Cache | Cache Key | Priority |
+|--------|-------|-----------|----------|
+| `loaders/search/intelligentSearch.ts` | ❌ None | - | 🔴 High |
+| `loaders/product/buyTogether.ts` | ✅ SWR | productId | - |
+| `loaders/getUserGeolocation.ts` | ❌ None | - | 🟡 Medium |
+| `vtex/loaders/categories/tree.ts` | ❌ None | - | 🔴 High |
+```
+
+## Quick Audit Commands
+
+```bash
+# Find loaders without cache
+grep -L "export const cache" loaders/**/*.ts
+
+# Find loaders with cache but no cacheKey
+grep -l "export const cache" loaders/**/*.ts | xargs grep -L "cacheKey"
+
+# Find inline loaders in page blocks (should be shared)
+grep -r '"loader":' .deco/blocks/pages-*.json | grep -v "__resolveType"
+```
+
+## Common Cache Durations
+
+| Content Type | Strategy | TTL |
+|--------------|----------|-----|
+| Product details | SWR | 5 min |
+| Category tree | SWR | 1 hour |
+| Search results | SWR | 1 min |
+| Reviews | SWR | 15 min |
+| Static content | SWR | 1 day |
+| User-specific | None | - |