@decocms/start 0.19.0

package/.cursor/skills/deco-full-analysis/checklists/dependency-update.md

@@ -0,0 +1,150 @@
+# Dependency Update Checklist
+
+3 learnings from real Deco sites. Check these during analysis.
+
+## Framework Updates
+
+### 1. Deco Platform Upgrade
+**Check**: Is the site on latest Deco version?
+
+```json
+// deno.json - check versions
+{
+  "imports": {
+    "@deco/deco": "jsr:@deco/deco@1.x.x",  // Check for latest
+    "@deco/dev": "jsr:@deco/dev@x.x.x"
+  }
+}
+```
+
+**How to check latest**:
+- Visit https://jsr.io/@deco/deco
+- Compare with current version in deno.json
+
+**Benefits of updating**:
+- Performance patches
+- Bug fixes for image handling
+- New features
+- Security updates
+
+### 2. Apps Version Alignment
+**Check**: Are deco and apps versions synchronized?
+
+```json
+// deno.json
+{
+  "imports": {
+    "@deco/deco": "jsr:@deco/deco@1.100.0",
+    "apps/": "https://cdn.jsdelivr.net/gh/deco-cx/apps@0.60.0/"
+  }
+}
+```
+
+**Alignment matters because**:
+- Breaking changes may affect compatibility
+- Feature parity between framework and apps
+- Image optimization improvements
+
+**Check release notes**:
+- https://github.com/deco-cx/deco/releases
+- https://github.com/deco-cx/apps/releases
+
+### 3. Deco 2.0 Migration
+**Check**: Is the site on Deco 2.0?
+
+**Deco 2.0 benefits**:
+- Partytown integration
+- Optimized Apps architecture
+- Better performance defaults
+- Improved developer experience
+
+**Signs of old architecture**:
+- Using `deco-sites/std` imports
+- Old loader patterns
+- Missing Fresh 1.7+ features
+
+## Update Process
+
+### Pre-Update Checklist
+
+1. **Backup**: Commit current state
+2. **Test**: Run e2e tests before update
+3. **Review**: Check release notes for breaking changes
+4. **Staging**: Test update in staging environment
+
+### Update Commands
+
+```bash
+# Check current versions
+grep -E "@deco/deco|apps/" deno.json
+
+# Update deno.json imports manually
+# Then run:
+deno cache --reload main.ts
+
+# Test the update
+deno task dev
+deno task test:e2e
+```
+
+### Post-Update Checklist
+
+- [ ] Site builds successfully
+- [ ] Dev server starts
+- [ ] Key pages load (Home, PDP, PLP)
+- [ ] E2E tests pass
+- [ ] No console errors
+- [ ] Images loading correctly
+
+## Version Compatibility Matrix
+
+| Deco Version | Apps Version | Fresh | Notes |
+|--------------|--------------|-------|-------|
+| 1.100+ | 0.60+ | 1.7+ | Current stable |
+| 1.90-1.99 | 0.55-0.59 | 1.6+ | Stable |
+| <1.90 | <0.55 | 1.5 | Consider upgrade |
+
+## Quick Audit Commands
+
+```bash
+# Show current versions
+grep -E '"@deco|"apps/' deno.json
+
+# Check for deco-sites/std (legacy)
+grep -r "deco-sites/std" sections/ loaders/ components/
+
+# Check Fresh version
+grep '\$fresh' deno.json
+```
+
+## Dependency Audit Table
+
+Add this to AGENTS.md:
+
+```markdown
+## Dependencies
+
+| Package | Current | Latest | Action |
+|---------|---------|--------|--------|
+| @deco/deco | 1.95.0 | 1.102.0 | 🟡 Consider update |
+| apps/ | 0.58.0 | 0.62.0 | 🟡 Consider update |
+| Fresh | 1.7.3 | 1.7.3 | ✅ Up to date |
+| Preact | 10.23.1 | 10.23.1 | ✅ Up to date |
+```
+
+## When to Update
+
+**Update immediately**:
+- Security vulnerabilities
+- Critical bug fixes affecting your site
+- Required for new features you need
+
+**Update with planning**:
+- Major version bumps
+- Architecture changes
+- When you have time to test thoroughly
+
+**Delay if**:
+- In the middle of a sprint
+- Before major sales events
+- No clear benefit

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

@@ -0,0 +1,191 @@
+# Hydration Fix Checklist
+
+9 learnings from real Deco sites. Check these during analysis.
+
+## SDK & Script Race Conditions
+
+### 1. SDK Initialization Guard
+**Check**: Do components assume SDK is ready?
+
+```typescript
+// Bad: Race condition
+const { cart } = useCart(); // May be undefined
+
+// Good: Wait for SDK
+async function waitForSDK() {
+  while (!window.__STOREFRONT_SDK__) {
+    await new Promise(r => setTimeout(r, 50));
+  }
+  return window.__STOREFRONT_SDK__;
+}
+
+const sdk = await waitForSDK();
+const cart = sdk.cart;
+```
+
+### 2. Script Dependency Synchronization
+**Check**: Do components wait for external scripts?
+
+```typescript
+// Good: Wait for HTMX
+function waitFor(check: () => boolean, timeout = 5000): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (check()) return resolve();
+    const start = Date.now();
+    const interval = setInterval(() => {
+      if (check()) { clearInterval(interval); resolve(); }
+      if (Date.now() - start > timeout) { clearInterval(interval); reject(); }
+    }, 50);
+  });
+}
+
+await waitFor(() => window.htmx !== undefined);
+```
+
+### 3. Safe Browser API Access
+**Check**: Are `window`/`document` accessed during SSR?
+
+```typescript
+// Bad: Crashes on SSR
+const width = window.innerWidth;
+
+// Good: Check for browser
+import { IS_BROWSER } from "$fresh/runtime.ts";
+
+const width = IS_BROWSER ? window.innerWidth : 1024;
+```
+
+## Unique IDs
+
+### 4. Deterministic useId
+**Check**: Are there hydration mismatches with IDs?
+
+```typescript
+// Bad: Random IDs cause mismatch
+const id = Math.random().toString(36);
+
+// Good: Deterministic based on props
+function useStableId(prefix: string, index: number) {
+  return `${prefix}-${index}`;
+}
+```
+
+Or use a custom deterministic ID generator if `useId()` causes issues.
+
+## External Widgets
+
+### 5. Onload Script Guard
+**Check**: Are external widgets manipulated before load?
+
+```typescript
+// Bad: Widget may not exist
+document.querySelector('.hubspot-form').style.display = 'block';
+
+// Good: Wait for load
+script.onload = () => {
+  const widget = document.querySelector('.hubspot-form');
+  if (widget) widget.style.display = 'block';
+};
+```
+
+### 6. MutationObserver for Third-Party Widgets
+**Check**: Do third-party widgets need conditional styling?
+
+```typescript
+// Good: Watch for widget insertion
+const observer = new MutationObserver((mutations) => {
+  const widget = document.querySelector('.review-widget');
+  if (widget) {
+    widget.classList.add('loaded');
+    observer.disconnect();
+  }
+});
+
+observer.observe(document.body, { childList: true, subtree: true });
+```
+
+## HTML Content
+
+### 7. HTML Repair Utility
+**Check**: Is `dangerouslySetInnerHTML` used with external content?
+
+```typescript
+// Bad: Broken HTML causes hydration errors
+<div dangerouslySetInnerHTML={{ __html: product.description }} />
+
+// Good: Sanitize and repair
+import DOMPurify from "dompurify";
+
+function repairHtml(html: string): string {
+  // Close unclosed tags, fix nesting
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  return DOMPurify.sanitize(doc.body.innerHTML);
+}
+
+<div dangerouslySetInnerHTML={{ __html: repairHtml(product.description) }} />
+```
+
+## Lazy Loading
+
+### 8. Deferred Portal Rendering
+**Check**: Are heavy drawers rendered on mount?
+
+```typescript
+// Good: Lazy render minicart/menu
+import { createPortal } from "preact/compat";
+
+function Minicart() {
+  const [show, setShow] = useState(false);
+  
+  return (
+    <>
+      <button onClick={() => setShow(true)}>Cart</button>
+      {show && createPortal(<MinicartContent />, document.body)}
+    </>
+  );
+}
+```
+
+### 9. Interaction-based Lazy Hydration
+**Check**: Are heavy navigation menus loaded eagerly?
+
+```typescript
+// Good: Load drawer content on first interaction
+function Header() {
+  const [menuLoaded, setMenuLoaded] = useState(false);
+  
+  return (
+    <button 
+      onMouseEnter={() => setMenuLoaded(true)}
+      onClick={() => setMenuLoaded(true)}
+    >
+      Menu
+    </button>
+    {menuLoaded && <MegaMenu />}
+  );
+}
+```
+
+## Quick Audit Commands
+
+```bash
+# Find direct window/document access
+grep -rn "window\." islands/ | grep -v "IS_BROWSER"
+grep -rn "document\." islands/ | grep -v "IS_BROWSER"
+
+# Find dangerouslySetInnerHTML usage
+grep -r "dangerouslySetInnerHTML" sections/ islands/
+
+# Find Math.random in components (ID generation)
+grep -r "Math.random" sections/ islands/ components/
+```
+
+## Common Hydration Issues
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| "Text content mismatch" | Date/time formatting | Use consistent timezone |
+| "Expected server HTML" | `useDevice()` for layout | Use CSS media queries |
+| "Hydration failed" | Random IDs | Use deterministic IDs |
+| White flash | Script race condition | Add SDK initialization guard |
+| Missing styles | CSS-in-JS during SSR | Use Tailwind or static CSS |

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

@@ -0,0 +1,180 @@
+# Image Optimization Checklist
+
+18 learnings from real Deco sites. Check these during analysis.
+
+## LCP (Largest Contentful Paint)
+
+### 1. LCP Image Prioritization
+**Check**: Does the LCP image have correct attributes?
+
+```tsx
+// Good: LCP image
+<Image
+  src={bannerUrl}
+  loading="eager"           // NOT "lazy"
+  fetchPriority="high"      // Prioritize network fetch
+  decoding="sync"           // Don't defer decoding
+  preload                   // Add link preload header
+/>
+```
+
+### 2. Banner Carousel First Item
+**Check**: Is the first carousel item prioritized?
+- First banner: `loading="eager"`, `fetchPriority="high"`
+- Other banners: `loading="lazy"`
+
+### 3. PLP First Products
+**Check**: Are the first 4-6 product images prioritized?
+```tsx
+{products.map((p, i) => (
+  <Image
+    loading={i < 6 ? "eager" : "lazy"}
+    fetchPriority={i < 4 ? "high" : "auto"}
+  />
+))}
+```
+
+### 4. Full-width Hero Optimization
+**Check**: Do LCP banners have restrictive styles?
+- Use `w-full` without max-width constraints
+- Avoid padding that causes layout shift
+
+### 5. Preload Background Images
+**Check**: Are CSS background images preloaded?
+```tsx
+// In section, add preload header
+ctx.response.headers.append(
+  "Link",
+  `<${imageUrl}>; rel="preload"; as="image"; fetchpriority="high"`
+);
+```
+
+## Image Component
+
+### 6. Use Deco Image Component
+**Check**: Are all images using `<Image />`?
+- Enables automatic CDN optimization
+- Requires explicit `width` and `height`
+
+```tsx
+// Good
+import { Image } from "apps/website/components/Image.tsx";
+<Image src={url} width={300} height={200} />
+
+// Bad
+<img src={url} />
+```
+
+### 7. Platform Standard Optimization
+**Check**: Are custom URL parsers used instead of standard?
+- Use `getOptimizedMediaUrl` from apps/website
+- Don't parse VTEX image URLs manually
+
+### 8. URL Sanitization
+**Check**: Do image URLs contain special characters?
+- Sanitize URLs from external APIs
+- Remove characters like `§` that break optimization
+
+## Special Cases
+
+### 9. SVG Handling
+**Check**: Are SVGs going through image optimization?
+- SVGs don't need raster optimization
+- Use wrapper to bypass proxy for SVGs
+
+```tsx
+// Skip optimization for SVG
+if (src.endsWith('.svg')) {
+  return <img src={src} {...props} />;
+}
+return <Image src={src} {...props} />;
+```
+
+### 10. Animated WebP/GIF
+**Check**: Are animated images becoming static?
+- Disable optimization for animated WebP/GIF
+- Check `animate` flag in VTEX URLs
+
+### 11. VTEX Image Resizing
+**Check**: Are VTEX images using correct dimensions?
+```typescript
+// Transform VTEX image URL
+function getVtexImageUrl(url: string, width: number, height: number) {
+  return url.replace(/\-\d+\-\d+/, `-${width}-${height}`);
+}
+```
+
+## Responsive Images
+
+### 12. CSS-based Responsiveness
+**Check**: Is `useDevice()` used for responsive images?
+- Prefer `<picture>` and CSS media queries
+- Avoids hydration mismatches
+
+```tsx
+// Good: CSS-based
+<picture>
+  <source media="(max-width: 768px)" srcSet={mobileUrl} />
+  <Image src={desktopUrl} />
+</picture>
+
+// Avoid: JS-based
+const device = useDevice();
+return device === "mobile" ? <MobileImg /> : <DesktopImg />;
+```
+
+### 13. Breakpoint Precision
+**Check**: Do responsive breakpoints overlap?
+- Use non-overlapping breakpoints
+- Prevent loading wrong image size
+
+### 14. Sizes Attribute
+**Check**: Do images have `sizes` attribute?
+```tsx
+<Image
+  sizes="(max-width: 768px) 100vw, 50vw"
+/>
+```
+
+## Layout Stability
+
+### 15. Aspect Ratio Reservation
+**Check**: Do images cause CLS?
+- Wrap in containers with `aspect-ratio`
+- Or use fixed dimensions
+
+```tsx
+<div class="aspect-video">
+  <Image class="object-cover w-full h-full" />
+</div>
+```
+
+### 16. Object-Fit for Banners
+**Check**: Do banners crop marketing text?
+- Use `object-fit: contain` for text-heavy banners
+- Use `object-fit: cover` for full-bleed images
+
+## UI Patterns
+
+### 17. CSS-Based Peek Animation
+**Check**: Are scroll animations JS-based?
+- Prefer CSS keyframes for "product peeking" hints
+- Reduces TBT
+
+### 18. LCP Isolation
+**Check**: Is LCP element in a complex section?
+- Isolate LCP into standalone section
+- Reduces render blocking
+
+## Quick Audit Commands
+
+```bash
+# Find images without width/height
+grep -r "<img" sections/ components/ | grep -v "width"
+
+# Find images using native img instead of Image component
+grep -rn "<img src" sections/ islands/
+
+# Find useDevice in image components
+grep -r "useDevice" sections/ | grep -i image
+```

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

@@ -0,0 +1,165 @@
+# Loader Optimization Checklist
+
+33 learnings from real Deco sites. Check these during analysis.
+
+## Critical Patterns
+
+### 1. Lazy Section Wrapping
+**Check**: Are below-fold sections with heavy loaders wrapped in `Lazy`?
+- BuyTogether, ProductShelf, Reviews, SimilarProducts
+- Any section that fetches data and isn't above the fold
+
+```json
+// Good: Wrapped in Lazy
+{
+  "__resolveType": "website/sections/Rendering/Lazy.tsx",
+  "section": { "__resolveType": "site/sections/Product/BuyTogether.tsx" }
+}
+```
+
+### 2. AbortController Timeout
+**Check**: Do external API calls have timeout protection?
+- Reviews APIs, recommendation APIs, third-party services
+- Add `AbortController` with reasonable timeout (5-10s)
+
+```typescript
+// Good: Has timeout
+const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), 5000);
+const response = await fetch(url, { signal: controller.signal });
+```
+
+### 3. Client-Side Data Fetching for Below-Fold
+**Check**: Are PDP loaders blocking on below-fold content?
+- Move `fetchSimilars`, `fetchReviews`, `fetchRelated` to client-side islands
+- Don't block SSR on non-critical data
+
+### 4. Remove Sync Product Loaders from Header
+**Check**: Does Header have product loaders that block render?
+- Headers should be fast and static
+- Move product data to islands or separate sections
+
+## VTEX-Specific
+
+### 5. Simulation Behavior
+**Check**: Is VTEX simulation set correctly?
+
+| Setting | Use Case |
+|---------|----------|
+| `skip` | Maximum performance, no real-time pricing |
+| `only1P` | Balanced - first-party simulation only |
+| `default` | Full simulation (slower) |
+
+```typescript
+// In VTEX loader config
+simulationBehavior: "only1P" // or "skip" for PLPs
+```
+
+### 6. Intelligent Search Migration
+**Check**: Are you using legacy loaders?
+- Replace `deco-sites/std` loaders with `vtex/loaders/intelligentSearch`
+- Replace legacy cross-selling with Intelligent Search
+
+### 7. Legacy Loader Fallback
+**Check**: Do category paths fail to resolve?
+- If Intelligent Search fails, try Legacy VTEX loader as fallback
+
+## Loader Architecture
+
+### 8. Loader Deduplication via Blocks
+**Check**: Are common loaders duplicated across pages?
+- Use shared loader blocks instead of inline configurations
+- Centralizes PDP/PLP loaders for cache deduplication
+
+```json
+// Good: Reference shared block
+{ "__resolveType": "$live/loaders/Loader.tsx", "loader": "PDP-Main-Loader" }
+```
+
+### 9. Loader Simplification
+**Check**: Are there redundant loaders?
+- Remove loaders that only pass through data already available
+- Avoid manual `fetch` calls when standard loaders exist
+
+### 10. Cascading Fallback Search
+**Check**: Do recommendation loaders return empty?
+- Implement fallback: Subcategory → Category → Global
+- Prevents empty shelves
+
+## Performance Patterns
+
+### 11. Batch and Debounce
+**Check**: Are there high-frequency small API calls?
+- Batch review/stock/rating calls into single loader
+- Use client-side debouncing
+
+### 12. API Result Limiting
+**Check**: Do loaders fetch too much data?
+- Always apply limits to review/comment loaders
+- Use pagination for large datasets
+
+### 13. Concurrent Batch Fetching
+**Check**: Are multi-item lookups sequential?
+```typescript
+// Bad: Sequential
+for (const id of ids) { await fetch(id); }
+
+// Good: Parallel
+await Promise.all(ids.map(id => fetch(id)));
+```
+
+### 14. Cursor Pagination
+**Check**: Do infinite scroll lists use offset pagination?
+- Use cursor-based pagination for better scaling
+
+## Custom Loaders
+
+### 15. Global Signal Caching
+**Check**: Do multiple components make the same API call?
+- Use global signals or shared cache
+- Prevents duplicate cashback/loyalty requests
+
+### 16. Retail API Integration
+**Check**: Are personalization APIs using correct session IDs?
+- Extract visitor/session ID from cookies correctly
+
+### 17. External API Loaders
+**Check**: Do loaders have proper error handling?
+- Use `ctx.invoke` instead of raw `fetch` where possible
+- Add timeout and retry logic
+
+### 18. Slug Normalization
+**Check**: Do collection URLs work consistently?
+- Normalize slugs and database keys using same logic
+
+## Section Optimization
+
+### 19. Section Deferral
+**Check**: Are heavy non-LCP sections deferred?
+- Complex headers/footers can use Lazy rendering
+- Balance against UX
+
+### 20. Skeleton Fallbacks
+**Check**: Do async sections have loading states?
+```typescript
+export function LoadingFallback() {
+  return <div class="skeleton h-64 w-full" />;
+}
+```
+
+### 21. Deferred Tab Loading
+**Check**: Do tabbed components load all tabs on server?
+- Use `isDeferred` and `asResolved` to load only active tab
+
+## Quick Audit Commands
+
+```bash
+# Find loaders without cache
+grep -L "export const cache" loaders/**/*.ts
+
+# Find sections not wrapped in Lazy
+grep -r "__resolveType.*sections" .deco/blocks/pages-*.json | grep -v "Lazy"
+
+# Find fetch calls in loaders (should use ctx.invoke)
+grep -r "await fetch" loaders/
+```