@decocms/start 0.19.0

package/.cursor/skills/deco-variant-selection-perf/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: deco-variant-selection-perf
+description: Optimize product variant selection in Deco TanStack storefronts. Eliminates server re-fetches when switching SKU variants of the same product using replaceState, adds loading states for cross-product variant navigation, and removes preload="intent" from variant links to prevent double-fetch. Use when variant changes are slow, HAR analysis shows duplicate loadCmsPage calls, or when implementing variant selectors in a PDP.
+---
+
+# Product Variant Selection Performance
+
+Patterns for making variant selection instant in Deco storefronts on TanStack Start. Discovered while optimizing `espacosmart-storefront` where clicking a variant triggered 2 full `loadCmsPage` server calls (1300ms+ each).
+
+## When to Use This Skill
+
+- Variant changes on PDP are slow (>500ms)
+- HAR analysis shows duplicate `loadCmsPage` calls with/without `?skuId`
+- `preload="intent"` on variant `<Link>` causes double-fetch
+- Need to add loading feedback for cross-product variant navigation
+- Implementing a new variant selector component
+
+---
+
+## Key Insight: Two Types of "Variant" Navigation
+
+| Type | Example | Data needed | Approach |
+|------|---------|-------------|----------|
+| **Same product, different SKU** | Size 90x0.8 → 90x0.95 | Already loaded in `isVariantOf.hasVariant` | `replaceState` — zero fetch |
+| **Different product** | Product A → Product B (visual variation) | New product data | `navigate()` — single fetch |
+
+The CMS block "PDP Loader" does NOT pass `skuId` to the server loader. All SKU data comes in the first load via `isVariantOf.hasVariant`. The `?skuId` in the URL is purely for bookmarking/sharing.
+
+---
+
+## Problem: Double-Fetch on Variant Click
+
+### Root Cause
+
+When using `<Link to="/slug/p?skuId=160" preload="intent">`:
+
+1. **Hover** → TanStack Router fires a prefetch. The `loaderDeps` filters `skuId`, so it sends `loadCmsPage({ data: "/slug/p" })`.
+2. **Click** → Router fires the real navigation. Depending on timing and staleTime, it may fire `loadCmsPage({ data: "/slug/p?skuId=160" })`.
+
+Result: **2 server calls** for one variant click, each taking 1-2 seconds (full CMS resolution + section loaders + VTEX API calls).
+
+### How to Diagnose
+
+Export a HAR from Chrome DevTools (Network tab → Export HAR). Analyze:
+
+```python
+# Find all loadCmsPage calls
+import json, urllib.parse, base64
+with open('localhost.har') as f:
+    har = json.load(f)
+for e in har['log']['entries']:
+    url = e['request']['url']
+    if '/_serverFn/' not in url:
+        continue
+    qs = url.split('?')[1] if '?' in url else ''
+    params = urllib.parse.parse_qs(qs)
+    if 'payload' in params:
+        payload = json.loads(urllib.parse.unquote(params['payload'][0]))
+        # Extract the "data" (path) from TanStack's serialized payload
+        print(f"{e.get('time',0):.0f}ms  skuId={'skuId' in str(payload)}")
+```
+
+If you see two calls for the same slug (one with `skuId`, one without), this is the double-fetch.
+
+---
+
+## Fix 1: Same-Product Variants — `replaceState` (Zero Fetch)
+
+Replace `<Link>` with `<a>` + `window.history.replaceState`. This changes the URL for bookmarking without triggering any TanStack Router navigation or loader.
+
+### Before (slow)
+
+```typescript
+import { Link } from "@tanstack/react-router";
+
+function VariantSelector({ product }: { product: Product }) {
+  const possibilities = useVariantPossibilities(hasVariant, product);
+  return (
+    // ...
+    <Link to={relativeLink} preload="intent">
+      <Avatar variant={relativeLink === relative(url) ? "active" : "default"} />
+    </Link>
+  );
+}
+```
+
+### After (instant)
+
+```typescript
+import { useState, useCallback } from "react";
+
+function VariantSelector({ product }: { product: Product }) {
+  const possibilities = useVariantPossibilities(hasVariant, product);
+  const [currentUrl, setCurrentUrl] = useState(() => relative(product.url));
+
+  const handleVariantClick = useCallback(
+    (e: React.MouseEvent<HTMLAnchorElement>, link: string) => {
+      e.preventDefault();
+      setCurrentUrl(link);
+      window.history.replaceState(null, "", link);
+    },
+    [],
+  );
+
+  return (
+    // ...
+    <a
+      href={relativeLink ?? "#"}
+      onClick={(e) => relativeLink && handleVariantClick(e, relativeLink)}
+    >
+      <Avatar
+        variant={relativeLink === currentUrl ? "active" : relativeLink ? "default" : "disabled"}
+      />
+    </a>
+  );
+}
+```
+
+### Why This Works
+
+1. `replaceState` changes browser URL without notifying TanStack Router → **zero loader execution**
+2. `useState(currentUrl)` tracks the active variant for UI highlighting → **instant re-render**
+3. `<a href>` preserves accessibility (right-click, ctrl+click open in new tab)
+4. The CMS PDP Loader does NOT use `skuId` from the URL — all variant data is in `isVariantOf.hasVariant`
+
+### When NOT to Use replaceState
+
+- The variant changes the **product** (different `productGroupID`) — use `navigate()` instead
+- The server loader actually reads `skuId` from the request URL to fetch different data
+- SEO requires each variant to be a separate indexable page with unique server-rendered content
+
+---
+
+## Fix 2: Cross-Product Variants — `navigate()` with Loading
+
+For `SkuVariation` (different products shown as visual variations), use `navigate()` but WITHOUT `preload="intent"` and WITH a loading state.
+
+```typescript
+import { useNavigate } from "@tanstack/react-router";
+import { useState, useCallback, useEffect, useRef } from "react";
+
+export default function SkuVariation({ products }: { products: Product[] | null }) {
+  const [loadingIdx, setLoadingIdx] = useState<number | null>(null);
+  const navigate = useNavigate();
+  const prevProducts = useRef(products);
+
+  // Reset loading when products change (navigation completed, component reused)
+  useEffect(() => {
+    if (prevProducts.current !== products) {
+      setLoadingIdx(null);
+      prevProducts.current = products;
+    }
+  }, [products]);
+
+  const handleClick = useCallback(
+    (e: React.MouseEvent<HTMLAnchorElement>, link: string, idx: number) => {
+      e.preventDefault();
+      setLoadingIdx(idx);
+      navigate({ to: link });
+    },
+    [navigate],
+  );
+
+  if (!products?.length) return null;
+
+  return (
+    <ul>
+      {products.map((product, index) => {
+        const link = relative(product.url) ?? "#";
+        const isLoading = loadingIdx === index;
+        return (
+          <li key={index}>
+            <a href={link} onClick={(e) => handleClick(e, link, index)} className="relative">
+              <div className={`transition-opacity ${isLoading ? "opacity-30" : ""}`}>
+                <img src={product.image?.[0]?.url} width={35} height={35} />
+              </div>
+              {isLoading && (
+                <span className="loading loading-spinner loading-xs absolute top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2" />
+              )}
+            </a>
+          </li>
+        );
+      })}
+    </ul>
+  );
+}
+```
+
+### Key Details
+
+| Aspect | Why |
+|--------|-----|
+| `preload={false}` / no preload | Prevents duplicate fetch (hover + click) |
+| `useRef(prevProducts)` + `useEffect` | Resets loading when component reuses with new props |
+| No `await navigate()` | `navigate` resolves when route renders — component may already be unmounted |
+| `<a href>` not `<Link>` | Avoids TanStack Router's built-in prefetch behavior |
+
+---
+
+## Fix 3: Remove `preload="intent"` from All Variant Links
+
+Any `<Link>` with `preload="intent"` in variant selectors causes prefetch on hover, leading to:
+- Extra server calls
+- Race conditions with the click navigation
+- Wasted bandwidth
+
+Replace with `preload={false}` or use `<a>` elements:
+
+```bash
+# Find all variant links with preload="intent"
+rg 'preload="intent"' src/components/product/ --glob '*.tsx' -l
+```
+
+Files to check:
+- `ProductVariantSelector.tsx`
+- `SkuVariation.tsx`
+- `ProductCardCategory.tsx` (variant selector in PLP cards)
+
+---
+
+## Verification
+
+After applying fixes, export a new HAR and verify:
+
+1. **Same-product variant click**: Zero `loadCmsPage` calls (only image requests)
+2. **Cross-product variant click**: Exactly 1 `loadCmsPage` call per product
+3. **No duplicate calls**: Each unique slug appears at most once
+
+```python
+# Quick HAR verification
+server_calls = [e for e in har['log']['entries'] if '/_serverFn/' in e['request']['url']]
+print(f"Server calls: {len(server_calls)}")
+# Should be 0 for same-product variants, N for N different products
+```
+
+---
+
+## Related Configuration
+
+### `ignoreSearchParams` in Route Config
+
+The CMS catch-all route should filter `skuId` from `loaderDeps`:
+
+```typescript
+const config = cmsRouteConfig({
+  siteName: "My Store",
+  defaultTitle: "My Store",
+  ignoreSearchParams: ["skuId"],
+});
+```
+
+This prevents `skuId` changes from being treated as dependency changes by TanStack Router.
+
+### `staleTime` in Dev Mode
+
+With `staleTime: 0` (default in dev), even identical `loaderDeps` trigger re-fetch. Set a minimum staleTime in dev:
+
+```typescript
+// In routeCacheDefaults()
+if (isDev) return { staleTime: 5_000, gcTime: 30_000 };
+```
+
+---
+
+## Related Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `deco-cms-layout-caching` | Cache layout sections (Header/Footer) to avoid redundant API calls |
+| `deco-api-call-dedup` | In-flight deduplication for VTEX API calls |
+| `deco-cms-route-config` | CMS route configuration in `@decocms/start` |
+| `deco-tanstack-storefront-patterns` | General patterns for deco-start storefronts |

package/.cursor/skills/deco-vtex-fetch-cache/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: deco-vtex-fetch-cache
+description: SWR in-memory fetch cache for VTEX API responses in @decocms/apps. Ported from deco-cx/deco runtime/fetch/fetchCache.ts. Provides in-flight deduplication + stale-while-revalidate for all VTEX GET requests. Covers fetchWithCache utility, vtexCachedFetch client function, LRU eviction, TTL by HTTP status, integration with intelligentSearch and cross-selling calls. Use when adding caching to VTEX API calls, debugging stale responses, or understanding how the fetch cache layer works.
+---
+
+# VTEX Fetch Cache (SWR In-Memory)
+
+Server-side SWR cache for all VTEX GET API responses. Ported from `deco-cx/deco` `runtime/fetch/fetchCache.ts` and adapted for `@decocms/apps` on TanStack Start.
+
+## When to Use This Skill
+
+- Adding SWR caching to new VTEX API calls
+- Understanding why a VTEX response is served stale
+- Debugging cache hit/miss behavior
+- Tuning TTL for specific endpoints
+- Understanding the relationship between `fetchWithCache`, `vtexCachedFetch`, and `createCachedLoader`
+
+---
+
+## Architecture
+
+```
+Site Setup
+  └→ createCachedLoader (loader-level SWR, 30-120s TTL)
+       └→ vtexCachedFetch (HTTP-level SWR, 3min TTL)
+            └→ fetchWithCache (core cache engine)
+                 └→ _fetch (instrumented fetch)
+```
+
+| Layer | File | Scope | TTL |
+|-------|------|-------|-----|
+| `createCachedLoader` | `deco-start/src/sdk/cachedLoader.ts` | Loader result (parsed + transformed) | 30-120s per loader |
+| `vtexCachedFetch` | `apps-start/vtex/client.ts` | Raw HTTP JSON response | 3 min (200), 10s (404) |
+| `fetchWithCache` | `apps-start/vtex/utils/fetchCache.ts` | Core SWR + dedup engine | Status-based |
+
+---
+
+## Core: `fetchWithCache` (`vtex/utils/fetchCache.ts`)
+
+### Features
+
+- **LRU eviction**: Max 500 entries, oldest evicted first
+- **TTL by HTTP status**: 200-299 → 3 min, 404 → 10s, 500+ → never cached
+- **In-flight deduplication**: Concurrent calls for the same URL share one Promise
+- **Stale-while-revalidate**: Stale entries served immediately, refreshed in background
+- **Custom TTL**: Override per-call via `opts.ttl`
+
+### API
+
+```typescript
+import { fetchWithCache, FetchCacheOptions } from "@decocms/apps/vtex/utils/fetchCache";
+
+// Basic usage
+const data = await fetchWithCache<ProductType>(
+  fullUrl,                    // Cache key (typically the full URL)
+  () => fetch(fullUrl, init), // Fetch callback (returns Response)
+  { ttl: 60_000 },           // Optional: override TTL (1 min)
+);
+```
+
+### How SWR Works
+
+```
+Call fetchWithCache(key, doFetch)
+  ├→ Entry exists & fresh? → return cached body
+  ├→ Entry exists & stale? → return stale, fire background refresh
+  ├→ Entry missing, inflight exists? → await inflight Promise
+  └→ Entry missing, no inflight → execute doFetch(), cache result
+```
+
+### TTL Configuration
+
+```typescript
+const TTL_BY_STATUS: Record<string, number> = {
+  "2xx": 180_000,  // 3 min — success responses
+  "404": 10_000,   // 10s — not found (may become available)
+  "5xx": 0,        // never cache server errors
+};
+```
+
+### Error Handling
+
+Non-ok responses (status >= 400) throw an error. They are NOT cached. The error propagates to the caller, who should `.catch()` gracefully:
+
+```typescript
+const data = await fetchWithCache<T>(url, doFetch).catch(() => fallback);
+```
+
+---
+
+## Client Integration: `vtexCachedFetch` (`vtex/client.ts`)
+
+Convenience wrapper that routes GET requests through `fetchWithCache`:
+
+```typescript
+import { vtexCachedFetch } from "@decocms/apps/vtex";
+
+// Automatically uses SWR cache for GET
+const products = await vtexCachedFetch<Product[]>(
+  `/api/catalog_system/pub/products/search/${slug}/p`,
+);
+
+// Non-GET falls through to regular vtexFetch
+const result = await vtexCachedFetch<OrderForm>(
+  `/api/checkout/pub/orderForms/simulation`,
+  { method: "POST", body: JSON.stringify(items) },
+);
+```
+
+### Custom TTL per call
+
+```typescript
+const pageType = await vtexCachedFetch<PageType>(
+  `/api/catalog_system/pub/portal/pagetype/${term}`,
+  undefined,
+  { cacheTTL: 300_000 }, // 5 min for page types
+);
+```
+
+---
+
+## What Uses `vtexCachedFetch` (Current)
+
+| Module | Endpoint | Before | After |
+|--------|----------|--------|-------|
+| `slugCache.ts` | `search/{slug}/p` | Manual inflight Map + 5s timeout | `vtexCachedFetch` SWR 3min |
+| `relatedProducts.ts` | `crossselling/{type}/{id}` | Manual `crossSellingInflight` Map | `vtexCachedFetch` SWR 3min |
+| `productDetailsPage.ts` | Kit items search | Plain `vtexFetch` | `vtexCachedFetch` SWR 3min |
+| `client.ts` `cachedPageType` | `pagetype/{term}` | Manual inflight Map | `vtexCachedFetch` SWR 3min |
+
+## What Uses `fetchWithCache` Directly
+
+| Module | Endpoint | Notes |
+|--------|----------|-------|
+| `client.ts` `intelligentSearch` | IS `product_search`, `facets` | Wrapped inline, uses default TTL |
+
+---
+
+## Comparison with `deco-cx/deco` `fetchCache.ts`
+
+| Feature | deco-cx/deco | @decocms/apps |
+|---------|-------------|---------------|
+| Storage | `CacheStorage` (Web Cache API) | In-memory `Map` (LRU) |
+| Persistence | Disk-backed (Deno CacheStorage) | Process-lifetime only |
+| Max entries | Unlimited (disk) | 500 (memory) |
+| TTL source | HTTP `Cache-Control` headers | Status-based defaults |
+| SWR | `stale-while-revalidate` header parsing | Manual background refresh |
+| Dedup | Separate `singleFlight` wrapper | Built into `fetchWithCache` |
+| Redis/FS tiers | Yes (`tiered.ts`: LRU → FS → Redis) | No — single in-memory tier |
+
+### Why In-Memory Only?
+
+Cloudflare Workers don't have persistent storage APIs accessible during SSR. The Cache API (`caches.default`) is for edge HTTP responses, not arbitrary data. In-memory with LRU is the practical choice for Workers.
+
+---
+
+## Diagnostics
+
+### Check Cache Stats
+
+```typescript
+import { getFetchCacheStats, clearFetchCache } from "@decocms/apps/vtex/utils/fetchCache";
+
+console.log(getFetchCacheStats());
+// { entries: 42, inflight: 0 }
+```
+
+### Clear Cache
+
+```typescript
+clearFetchCache(); // Useful after decofile hot-reload
+```
+
+### Verify Cache Hits in Logs
+
+With instrumented fetch (`createInstrumentedFetch("vtex")`), look for timing:
+- **Cache HIT**: No `[vtex] GET ...` log appears (response served from cache)
+- **Cache MISS**: `[vtex] GET ...` followed by `[vtex] 200 GET ... Xms`
+- **SWR refresh**: `[vtex] GET ...` appears AFTER the response was already served
+
+### Common Issues
+
+**Stale data after CMS update**: Wait 3 min for TTL to expire, or restart the dev server to clear in-memory cache.
+
+**Cache not working in dev**: `fetchWithCache` works in both dev and prod. Unlike `createCachedLoader` which skips SWR in dev (only dedup), `fetchWithCache` always caches.
+
+**POST requests not cached**: By design — `vtexCachedFetch` only caches GET. Use `usePriceSimulationBatch` for simulation POST optimization.
+
+---
+
+## Adding Cache to a New VTEX Endpoint
+
+```typescript
+// Before — no cache
+const data = await vtexFetch<MyType>(`/api/my-endpoint/${id}`);
+
+// After — with SWR cache
+const data = await vtexCachedFetch<MyType>(`/api/my-endpoint/${id}`);
+
+// With custom TTL
+const data = await vtexCachedFetch<MyType>(
+  `/api/my-endpoint/${id}`,
+  undefined,
+  { cacheTTL: 60_000 }, // 1 min
+);
+```
+
+For non-VTEX APIs, use `fetchWithCache` directly:
+
+```typescript
+import { fetchWithCache } from "@decocms/apps/vtex/utils/fetchCache";
+
+const data = await fetchWithCache<MyType>(url, () => fetch(url, init));
+```
+
+---
+
+## Related Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `deco-api-call-dedup` | Higher-level dedup patterns (slugCache, batching, PLP filtering) |
+| `deco-cms-layout-caching` | Layout section caching (works on top of fetch cache) |
+| `deco-edge-caching` | Cloudflare edge caching (HTTP level, outside the Worker) |
+| `deco-tanstack-storefront-patterns` | General storefront patterns + `createCachedLoader` |

package/.cursor/skills/find-skills/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```