@decocms/start 0.19.0

package/.cursor/skills/deco-site-scaling-tuning/analysis-scripts.md

@@ -0,0 +1,267 @@
+# Analysis Scripts
+
+Ready-to-use Python scripts for discovering optimal scaling parameters via Prometheus.
+
+## Prerequisites
+
+```bash
+# Port-forward Prometheus
+PROM_POD=$(kubectl get pods -n monitoring -l app.kubernetes.io/name=prometheus -o jsonpath='{.items[0].metadata.name}')
+kubectl port-forward -n monitoring $PROM_POD 19090:9090 &
+```
+
+## Script 1: Full Scaling Analysis
+
+Collects all relevant metrics and produces a CPU vs latency correlation table.
+
+**Usage:** Change `SITENAME` and run. Uses 12h of data by default.
+
+```python
+#!/usr/bin/env python3
+"""Discover optimal scaling parameters for a Deco site."""
+import json, urllib.request, urllib.parse, time
+from datetime import datetime
+
+PROM = "http://127.0.0.1:19090"
+SITENAME = "CHANGE_ME"  # <-- Set this
+NS = f"sites-{SITENAME}"
+HOURS = 12
+END = int(time.time())
+START = END - HOURS * 3600
+
+def prom_qr(query, step=120):
+    params = urllib.parse.urlencode({"query": query, "start": START, "end": END, "step": step})
+    with urllib.request.urlopen(f"{PROM}/api/v1/query_range?{params}") as r:
+        return json.loads(r.read())
+
+def prom_q(query):
+    params = urllib.parse.urlencode({"query": query})
+    with urllib.request.urlopen(f"{PROM}/api/v1/query?{params}") as r:
+        return json.loads(r.read())
+
+def to_map(data):
+    m = {}
+    for r in data['data']['result']:
+        for ts, v in r['values']:
+            try:
+                f = float(v)
+                if str(v) not in ('NaN', '+Inf', '-Inf'):
+                    m[int(float(ts))] = f
+            except: pass
+    return m
+
+# --- Current config ---
+print("=" * 70)
+print(f"SCALING ANALYSIS: {SITENAME} (last {HOURS}h)")
+print("=" * 70)
+
+target = prom_q(f'autoscaler_target_concurrency_per_pod{{namespace_name="{NS}"}}')
+for r in target['data']['result']:
+    print(f"  Current target: {r['value'][1]} conc/pod")
+
+# --- Collect metrics ---
+cpu = to_map(prom_qr(f'avg(rate(container_cpu_usage_seconds_total{{namespace="{NS}", container="app"}}[2m]))', 120))
+# Fallback: try container="user-container" if "app" yields nothing
+if not cpu:
+    cpu = to_map(prom_qr(f'avg(rate(container_cpu_usage_seconds_total{{namespace="{NS}", container!="", container!="POD", container!="queue-proxy"}}[2m]))', 120))
+
+pods_m = to_map(prom_qr(f'autoscaler_actual_pods{{namespace_name="{NS}"}}', 120))
+conc_m = to_map(prom_qr(f'autoscaler_stable_request_concurrency{{namespace_name="{NS}"}}', 120))
+panic_m = to_map(prom_qr(f'autoscaler_panic_mode{{namespace_name="{NS}"}}', 120))
+
+# Try direct latency (requires queue-proxy PodMonitor)
+lat_m = to_map(prom_qr(
+    f'avg(rate(revision_app_request_latencies_sum{{namespace="{NS}"}}[2m]) / rate(revision_app_request_latencies_count{{namespace="{NS}"}}[2m]))', 120
+))
+has_latency = bool(lat_m)
+if has_latency:
+    print("  ✓ Direct latency metrics available (queue-proxy)")
+else:
+    print("  ✗ No direct latency metrics — using concurrency as proxy")
+
+# --- Build data points ---
+common = sorted(set(cpu.keys()) & set(pods_m.keys()) & set(conc_m.keys()))
+points = []
+for ts in common:
+    c = cpu[ts]; p = pods_m[ts]; tc = conc_m[ts]
+    if c > 0 and p > 0:
+        points.append({
+            'ts': ts, 'cpu_m': c * 1000, 'pods': p,
+            'total_conc': tc, 'cpod': tc / p,
+            'panic': panic_m.get(ts, 0),
+            'lat_ms': lat_m.get(ts),
+        })
+
+if not points:
+    print("  ERROR: No data points. Check namespace and metrics availability.")
+    exit(1)
+
+print(f"  Data points: {len(points)}")
+
+# --- Panic events ---
+panic_count = sum(1 for i in range(1, len(points)) if points[i]['panic'] == 1 and points[i-1]['panic'] == 0)
+print(f"  Panic events: {panic_count}")
+
+# --- Pod count stats ---
+pod_vals = [p['pods'] for p in points]
+print(f"  Pods: avg={sum(pod_vals)/len(pod_vals):.0f}, min={min(pod_vals):.0f}, max={max(pod_vals):.0f}")
+
+# --- CPU per pod bucketed analysis ---
+print(f"\n{'CPU range':>12}  {'Avg C/pod':>10}  {'P95 C/pod':>10}  {'Avg Pods':>9}  {'Points':>7}", end="")
+if has_latency:
+    print(f"  {'Avg Lat':>9}  {'P95 Lat':>9}", end="")
+print()
+
+cpu_buckets = [
+    (0, 200, '0-200m'), (200, 300, '200-300m'), (300, 400, '300-400m'),
+    (400, 500, '400-500m'), (500, 600, '500-600m'), (600, 700, '600-700m'),
+    (700, 1500, '700m+'),
+]
+
+for lo, hi, label in cpu_buckets:
+    bp = [p for p in points if lo <= p['cpu_m'] < hi]
+    if bp:
+        concs = sorted([p['cpod'] for p in bp])
+        avg_c = sum(concs) / len(concs)
+        p95_i = min(int(len(concs) * 0.95), len(concs) - 1)
+        avg_pods = sum(p['pods'] for p in bp) / len(bp)
+        line = f"  {label:>12}  {avg_c:10.1f}  {concs[p95_i]:10.1f}  {avg_pods:9.0f}  {len(bp):7}"
+        if has_latency:
+            lats = sorted([p['lat_ms'] for p in bp if p['lat_ms'] is not None])
+            if lats:
+                avg_l = sum(lats) / len(lats)
+                p95_l = lats[min(int(len(lats) * 0.95), len(lats) - 1)]
+                line += f"  {avg_l:8.1f}ms  {p95_l:8.1f}ms"
+        print(line)
+
+# --- Latency inflation factor ---
+print(f"\nLatency inflation factor (excess > 1.0 = latency degrading):")
+for threshold in [300, 350, 400, 450, 500, 550, 600]:
+    below = [p for p in points if p['cpu_m'] < threshold]
+    above = [p for p in points if p['cpu_m'] >= threshold]
+    if below and above:
+        avg_c_b = sum(p['cpod'] for p in below) / len(below)
+        avg_c_a = sum(p['cpod'] for p in above) / len(above)
+        avg_p_b = sum(p['pods'] for p in below) / len(below)
+        avg_p_a = sum(p['pods'] for p in above) / len(above)
+        conc_ratio = avg_c_a / avg_c_b if avg_c_b > 0 else 0
+        pods_ratio = avg_p_b / avg_p_a if avg_p_a > 0 else 0
+        excess = conc_ratio / pods_ratio if pods_ratio > 0 else 0
+        marker = " ★ INFLECTION" if 1.3 < excess < 1.7 else ""
+        print(f"  CPU <{threshold}m vs >={threshold}m: excess={excess:.2f}x{marker}")
+
+# --- Recommendation ---
+print(f"\n{'='*70}")
+print("RECOMMENDATION")
+print(f"{'='*70}")
+
+# Find inflection: first threshold where excess drops below 1.5
+inflection = None
+for threshold in [300, 350, 400, 450, 500, 550, 600]:
+    below = [p for p in points if p['cpu_m'] < threshold]
+    above = [p for p in points if p['cpu_m'] >= threshold]
+    if below and above:
+        avg_c_b = sum(p['cpod'] for p in below) / len(below)
+        avg_c_a = sum(p['cpod'] for p in above) / len(above)
+        avg_p_b = sum(p['pods'] for p in below) / len(below)
+        avg_p_a = sum(p['pods'] for p in above) / len(above)
+        conc_ratio = avg_c_a / avg_c_b if avg_c_b > 0 else 0
+        pods_ratio = avg_p_b / avg_p_a if avg_p_a > 0 else 0
+        excess = conc_ratio / pods_ratio if pods_ratio > 0 else 0
+        if excess < 1.5 and inflection is None:
+            inflection = threshold
+
+# Get CPU request
+cpu_req = prom_q(f'kube_pod_container_resource_requests{{namespace="{NS}", container!="queue-proxy", resource="cpu"}}')
+cpu_req_m = 0
+for r in cpu_req['data']['result']:
+    cpu_req_m = float(r['value'][1]) * 1000
+    break
+
+if inflection:
+    print(f"  Latency inflection point: ~{inflection}m CPU")
+    print(f"  CPU request: {cpu_req_m:.0f}m")
+    print(f"  Recommended: CPU scaling at target={inflection} (millicores)")
+    print(f"\n  SiteState scaling config:")
+    print(f'    .scaling.metric = {{"type": "cpu", "target": {inflection}}}')
+else:
+    print("  No clear inflection found. Consider:")
+    print("  - More data needed (run for 12-24h)")
+    print("  - App may be IO-bound (keep concurrency scaling)")
+    if panic_count > 0:
+        print(f"  - {panic_count} panic events detected — consider switching to CPU scaling anyway to break the loop")
+```
+
+## Script 2: Post-Change Monitoring
+
+Run after applying scaling changes to verify they're working.
+
+```python
+#!/usr/bin/env python3
+"""Monitor scaling behavior after parameter change."""
+import json, urllib.request, urllib.parse, time
+from datetime import datetime
+
+PROM = "http://127.0.0.1:19090"
+SITENAME = "CHANGE_ME"  # <-- Set this
+NS = f"sites-{SITENAME}"
+END = int(time.time())
+START = END - 2 * 3600  # last 2 hours
+
+def prom_qr(query, step=60):
+    params = urllib.parse.urlencode({"query": query, "start": START, "end": END, "step": step})
+    with urllib.request.urlopen(f"{PROM}/api/v1/query_range?{params}") as r:
+        return json.loads(r.read())
+
+def to_map(data):
+    m = {}
+    for r in data['data']['result']:
+        for ts, v in r['values']:
+            try:
+                f = float(v)
+                if str(v) not in ('NaN', '+Inf', '-Inf'):
+                    m[int(float(ts))] = f
+            except: pass
+    return m
+
+cpu = to_map(prom_qr(f'avg(rate(container_cpu_usage_seconds_total{{namespace="{NS}", container="app"}}[2m]))'))
+if not cpu:
+    cpu = to_map(prom_qr(f'avg(rate(container_cpu_usage_seconds_total{{namespace="{NS}", container!="", container!="POD", container!="queue-proxy"}}[2m]))'))
+pods_m = to_map(prom_qr(f'autoscaler_actual_pods{{namespace_name="{NS}"}}'))
+panic_m = to_map(prom_qr(f'autoscaler_panic_mode{{namespace_name="{NS}"}}'))
+
+common = sorted(set(cpu.keys()) & set(pods_m.keys()))
+
+print(f"POST-CHANGE MONITORING: {SITENAME} (last 2h)")
+print(f"{'Time':>6}  {'Pods':>5}  {'CPU/pod':>8}  {'Panic':>5}")
+prev_pods = None
+for ts in common:
+    p = pods_m[ts]; c = cpu[ts] * 1000; pa = panic_m.get(ts, 0)
+    t = datetime.fromtimestamp(ts).strftime('%H:%M')
+    ps = "PANIC" if pa == 1 else ""
+    change = ""
+    if prev_pods and abs(p - prev_pods) >= 2:
+        direction = "↑" if p > prev_pods else "↓"
+        change = f" {direction}{abs(p-prev_pods):.0f}"
+    print(f"  {t}  {p:5.0f}  {c:7.0f}m  {ps}{change}")
+    prev_pods = p
+
+# Summary
+if common:
+    pod_vals = [pods_m[ts] for ts in common]
+    cpu_vals = [cpu[ts] * 1000 for ts in common]
+    panics = sum(1 for i in range(1, len(common)) if panic_m.get(common[i], 0) == 1 and panic_m.get(common[i-1], 0) == 0)
+    print(f"\n  Pods: avg={sum(pod_vals)/len(pod_vals):.0f}, min={min(pod_vals):.0f}, max={max(pod_vals):.0f}")
+    print(f"  CPU/pod: avg={sum(cpu_vals)/len(cpu_vals):.0f}m, max={max(cpu_vals):.0f}m")
+    print(f"  Panic events: {panics}")
+    print(f"  Pod stability: {'STABLE' if max(pod_vals) - min(pod_vals) < 5 else 'OSCILLATING'}")
+
+# Check for HPA (if using CPU scaling)
+print(f"\nHPA status:")
+import subprocess
+try:
+    result = subprocess.run(['kubectl', 'get', 'hpa', '-n', NS], capture_output=True, text=True)
+    print(result.stdout if result.stdout else "  No HPA found (still using KPA?)")
+except:
+    print("  Could not check HPA")
+```

package/.cursor/skills/deco-start-architecture/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: deco-start-architecture
+description: Architecture reference for @decocms/start — the Deco framework for TanStack Start/React/Cloudflare Workers. Covers the three-layer architecture (@decocms/start + @decocms/apps + site), admin protocol (meta, decofile, invoke, render), CMS block resolution with generic recursive resolver, dynamic schema registries, section registry, worker entry with edge caching, SDK utilities (useDevice, useScript with minification, observability, health metrics), matchers, middleware, hooks, schema generation, and the comprehensive gap analysis vs deco-cx/deco. Includes a prioritized roadmap (Tier 0-3 complete, plus Tier 2.5 framework improvements). Use when working on deco-start, understanding the framework, adding features, debugging admin protocol issues, or planning what to port next from deco-cx/deco.
+globs:
+  - "**/workerEntry.ts"
+  - "**/cacheHeaders.ts"
+  - "**/LiveControls.tsx"
+  - "**/DecoPageRenderer.tsx"
+  - "**/resolve.ts"
+  - "**/setup.ts"
+  - "**/.decofile"
+  - "**/meta.gen.json"
+  - "**/blocks.gen.ts"
+---
+
+## Sub-documents
+
+| Document | Topic |
+|----------|-------|
+| [admin-protocol.md](./admin-protocol.md) | Admin protocol — meta, decofile, invoke, render, CORS, LiveControls |
+| [cms-resolution.md](./cms-resolution.md) | CMS block loading, page resolution, section registry, matchers |
+| [worker-entry-caching.md](./worker-entry-caching.md) | Cloudflare Worker entry, edge caching, segment keys, cache profiles |
+| [sdk-utilities.md](./sdk-utilities.md) | All SDK utilities — useScript, signal, analytics, cookies, redirects, sitemap |
+| [gap-analysis.md](./gap-analysis.md) | Feature-by-feature comparison with deco-cx/deco + prioritized roadmap |
+| [code-quality.md](./code-quality.md) | Code quality tools, scripts, recommendations |
+
+# @decocms/start Architecture
+
+Reference for `@decocms/start` — the Deco framework for TanStack Start storefronts on Cloudflare Workers.
+
+## Three-Layer Architecture
+
+```
+ Layer 1: @decocms/start (this repo)
+   Framework: CMS bridge, admin protocol, worker entry, caching, rendering
+         |
+ Layer 2: @decocms/apps (apps-start)
+   Commerce: VTEX/Shopify loaders, types, hooks, transforms
+         |
+ Layer 3: Site repo (e.g., espacosmart-storefront)
+   UI: components, routes, styles, contexts, sections
+```
+
+## Repository Structure
+
+```
+deco-start/
+|-- package.json            # v0.6.0, exports map, peer deps
+|-- tsconfig.json           # ES2022, bundler resolution, strictNullChecks
+|-- .releaserc.json         # semantic-release (Angular preset)
+|-- CLAUDE.md               # AI guidance document
+|-- GAP_ANALYSIS_V2.md      # Detailed gap analysis vs deco-cx/deco
+|
+|-- src/
+|   |-- index.ts            # Barrel: re-exports admin, cms, hooks, types, middleware
+|   |
+|   |-- admin/              # Admin protocol handlers (9 files)
+|   |   |-- setup.ts        # Client-safe config (setMetaData, setInvokeLoaders, setInvokeActions, setRenderShell, register*Schema)
+|   |   |-- meta.ts         # GET /live/_meta handler (auto-invalidates on decofile change)
+|   |   |-- schema.ts       # composeMeta(), dynamic schema registries (loaders + matchers)
+|   |   |-- decofile.ts     # GET/POST /.decofile handlers (revision tracking, cache invalidation)
+|   |   |-- invoke.ts       # POST /deco/invoke handler (form-data, select, actions, batch, nested resolve)
+|   |   |-- render.ts       # POST /live/previews/* handler
+|   |   |-- liveControls.ts # Admin-storefront bridge script
+|   |   |-- cors.ts         # CORS for admin origins
+|   |   |-- index.ts        # Barrel export
+|   |
+|   |-- cms/                # CMS block resolution (4 files)
+|   |   |-- loader.ts       # loadBlocks, findPageByPath, getAllPages, withBlocksOverride, getRevision, onChange
+|   |   |-- registry.ts     # registerSection, getSection, getSectionRegistry
+|   |   |-- resolve.ts      # resolveValue, resolveDecoPage, internalResolve, registerCommerceLoader, registerMatcher, addSkipResolveType, set*Handler
+|   |   |-- index.ts        # Barrel export
+|   |
+|   |-- hooks/              # React components/hooks (5 files)
+|   |   |-- LiveControls.tsx     # Admin bridge component
+|   |   |-- DecoPageRenderer.tsx # Renders sections with Suspense
+|   |   |-- LazySection.tsx      # IntersectionObserver lazy loading
+|   |   |-- SectionErrorFallback.tsx # Per-section error boundary
+|   |   |-- index.ts
+|   |
+|   |-- middleware/          # Request middleware (5 files)
+|   |   |-- observability.ts # configureTracer, configureMeter, withTracing, logRequest, MetricNames, recordRequestMetric, recordCacheMetric
+|   |   |-- healthMetrics.ts # trackRequest, getHealthMetrics, handleHealthCheck (/deco/_health)
+|   |   |-- liveness.ts     # /deco/_liveness health probe (integrated with /deco/_health)
+|   |   |-- decoState.ts    # buildDecoState per request
+|   |   |-- index.ts
+|   |
+|   |-- sdk/                # SDK utilities (21 files)
+|   |   |-- workerEntry.ts      # createDecoWorkerEntry (CF Worker wrapper)
+|   |   |-- cacheHeaders.ts     # detectCacheProfile, routeCacheDefaults
+|   |   |-- cachedLoader.ts     # In-memory SWR loader cache
+|   |   |-- mergeCacheControl.ts # Cache-Control merge
+|   |   |-- analytics.ts        # useSendEvent, ANALYTICS_SCRIPT, gtmScript
+|   |   |-- useScript.ts        # useScript (with minification + LRU cache), usePartialSection, useSection
+|   |   |-- useDevice.ts        # Server-side device detection (detectDevice, useDevice, checkMobile/Tablet/Desktop)
+|   |   |-- signal.ts           # Reactive signal (replaces @preact/signals)
+|   |   |-- clx.ts              # CSS class utility
+|   |   |-- cookie.ts           # Cookie get/set/delete (client + server)
+|   |   |-- invoke.ts           # createInvokeProxy, batchInvoke, invokeQueryOptions
+|   |   |-- redirects.ts        # CMS redirect loading + matching
+|   |   |-- sitemap.ts          # Sitemap XML generation
+|   |   |-- csp.ts              # CSP frame-ancestors for admin
+|   |   |-- urlUtils.ts         # UTM stripping, canonical URLs
+|   |   |-- requestContext.ts   # AsyncLocalStorage per-request context
+|   |   |-- serverTimings.ts    # Server-Timing header
+|   |   |-- instrumentedFetch.ts # Fetch with logging/tracing
+|   |   |-- useId.ts            # React useId wrapper
+|   |   |-- wrapCaughtErrors.ts # Deferred error proxy for resilient rendering
+|   |   |-- index.ts
+|   |
+|   |-- matchers/            # Feature flag matchers (2 files)
+|   |   |-- builtins.ts     # cookie, cron, host, pathname, queryString
+|   |   |-- posthog.ts      # PostHog integration
+|   |
+|   |-- types/               # Type definitions (2 files)
+|   |   |-- index.ts        # FnContext, App, Section, SectionProps, Flag, etc.
+|   |   |-- widgets.ts      # ImageWidget, HTMLWidget, VideoWidget aliases
+|
+|-- scripts/
+|   |-- generate-blocks.ts   # .deco/blocks/*.json -> blocks.gen.ts
+|   |-- generate-schema.ts   # TypeScript props -> JSON Schema (meta.gen.json)
+```
+
+## Package Exports
+
+| Import Path | File | Purpose |
+|-------------|------|---------|
+| `@decocms/start` | `src/index.ts` | Main barrel |
+| `@decocms/start/admin` | `src/admin/index.ts` | Admin protocol |
+| `@decocms/start/cms` | `src/cms/index.ts` | Block resolution |
+| `@decocms/start/hooks` | `src/hooks/index.ts` | React components |
+| `@decocms/start/middleware` | `src/middleware/index.ts` | Request middleware |
+| `@decocms/start/sdk` | `src/sdk/index.ts` | SDK utilities |
+| `@decocms/start/sdk/workerEntry` | `src/sdk/workerEntry.ts` | CF Worker entry |
+| `@decocms/start/sdk/cacheHeaders` | `src/sdk/cacheHeaders.ts` | Cache profiles |
+| `@decocms/start/sdk/invoke` | `src/sdk/invoke.ts` | Invoke proxy |
+| `@decocms/start/types` | `src/types/index.ts` | Type definitions |
+| `@decocms/start/types/widgets` | `src/types/widgets.ts` | Widget type aliases |
+| `@decocms/start/sdk/useDevice` | `src/sdk/useDevice.ts` | Server-side device detection |
+| `@decocms/start/middleware/healthMetrics` | `src/middleware/healthMetrics.ts` | Health metrics + `/deco/_health` |
+| `@decocms/start/matchers/builtins` | `src/matchers/builtins.ts` | Built-in matchers |
+
+## Key Concepts
+
+### 1. Worker Entry (Edge Layer)
+
+```
+Request -> createDecoWorkerEntry(serverEntry, options)
+  |-- tryAdminRoute()         <- /live/_meta, /.decofile, /live/previews/*
+  |-- cache purge check       <- __deco_purge_cache
+  |-- static asset bypass     <- /assets/*, favicon, sprites
+  |-- Cloudflare edge cache   <- caches.open() with profile-based TTLs
+  |-- serverEntry.fetch()     <- TanStack Start handles the rest
+```
+
+### 2. Admin Protocol
+
+| Route | Method | Handler | Purpose |
+|-------|--------|---------|---------|
+| `/live/_meta` | GET | `handleMeta` | JSON Schema + manifest |
+| `/.decofile` | GET | `handleDecofileRead` | CMS content blocks |
+| `/.decofile` | POST | `handleDecofileReload` | Hot reload blocks |
+| `/deco/invoke` | POST | `handleInvoke` | Execute loaders/actions |
+| `/live/previews/*` | POST | `handleRender` | Section preview in admin |
+| `/deco/_liveness` | GET | `handleLiveness` | Health probe |
+| `/deco/_health` | GET | `handleHealthCheck` | Detailed health metrics (uptime, memory, cache, requests) |
+
+### 3. CMS Resolution
+
+```
+[CMS decofile]                 [setup.ts]                    [resolveDecoPage]
+Section props with             Commerce loaders              Generic recursive resolver:
+__resolveType: "vtex/..."  --> registered by key       -->   1. Check commerce loaders
+                               + matchers                    2. Check decofile blocks
+                               + schema registries           3. DanglingReference fallback
+                                                             + memoization + depth protection
+                                                                   |
+                                                                   v
+                                                             [React Component]
+                                                             Receives plain data
+```
+
+### 4. Section Rendering
+
+```tsx
+<DecoPageRenderer sections={resolvedSections}>
+  {sections.map((section, i) => (
+    <SectionErrorBoundary key={i}>
+      <Suspense fallback={<div />}>
+        {isBelowFold(i) ? (
+          <LazySection><SectionComponent {...section.props} /></LazySection>
+        ) : (
+          <SectionComponent {...section.props} />
+        )}
+      </Suspense>
+    </SectionErrorBoundary>
+  ))}
+</DecoPageRenderer>
+```
+
+## Dependencies
+
+- **Peer**: `@tanstack/store` >= 0.7.0, `react` ^19, `react-dom` ^19
+- **Dev**: `ts-morph` (schema gen), `typescript` ^5.9
+
+## Implementation Status
+
+Tier 0 (production-blocking), Tier 1 (quality), Tier 2 (DX/completeness), and Tier 2.5 (framework improvements) are ALL DONE. See [gap-analysis.md](./gap-analysis.md) for details on Tier 3 items remaining.
+
+### Tier 2.5 Highlights (PR #3: feat/framework-improvements)
+- Dynamic schema registries (loaders + matchers) — replaces hardcoded `KNOWN_LOADERS`
+- Generic recursive resolver with memoization, depth protection, DanglingReference handler
+- `useDevice` server-side (User-Agent + RequestContext)
+- `/deco/_health` endpoint with uptime, memory, cache stats, request metrics
+- Enhanced observability: `MeterAdapter`, `MetricNames`, context propagation
+- Enhanced invoke: FormData/URLEncoded parsing, `?select=`, actions, nested `__resolveType`
+- Decofile revision tracking + `onChange` listeners + meta auto-invalidation
+- `useScript` minification + LRU cache

package/.cursor/skills/deco-start-architecture/admin-protocol.md

@@ -0,0 +1,156 @@
+# Admin Protocol
+
+The admin panel (`admin.deco.cx`) communicates with self-hosted storefronts via HTTP endpoints handled in the Cloudflare Worker entry, NOT inside TanStack Start's server.
+
+Important: Admin routes MUST be handled in `workerEntry.ts`, NOT inside `createServerEntry` - Vite strips custom fetch logic from server entries in production builds.
+
+## Endpoints
+
+### GET /live/_meta (`admin/meta.ts`)
+
+Returns JSON Schema + manifest for the admin form builder.
+
+```typescript
+handleMeta(request: Request): Response
+```
+
+- Schema is composed at runtime via `composeMeta()`
+- Content-hash ETag (DJB2) for caching
+- ETag included in JSON body for admin cache busting
+- Returns sections, pages, loaders, matchers, flags definitions
+- Auto-invalidates cached ETag when decofile changes (via `onChange` listener)
+
+### GET /.decofile (`admin/decofile.ts`)
+
+Returns the current CMS content blocks.
+
+```typescript
+handleDecofileRead(request: Request): Response
+```
+
+- Includes content-hash `revision` in JSON body
+- Sets `ETag` header from current revision for HTTP caching
+
+### POST /.decofile (`admin/decofile.ts`)
+
+Hot-reloads CMS blocks without redeployment.
+
+```typescript
+handleDecofileReload(request: Request): Response
+```
+
+- Calls `setBlocks(newBlocks)` which updates in-memory state, recomputes revision, and notifies `onChange` listeners
+- Explicitly calls `clearLoaderCache()` to ensure data consistency after reload
+
+### POST /deco/invoke (`admin/invoke.ts`)
+
+Executes loaders/actions by key.
+
+```typescript
+handleInvoke(request: Request): Response
+```
+
+- Loaders registered via `setInvokeLoaders(map)`
+- Actions registered via `setInvokeActions(map)`
+- Supports multiple body formats: `application/json`, `multipart/form-data`, `application/x-www-form-urlencoded`, URL search params (`?props=...`)
+- `?select=field1,field2` query parameter for partial response filtering
+- Batch invoke: send array of `{ key, props }` to execute multiple in parallel
+- Nested `__resolveType` within payload props are recursively resolved
+- Development mode includes stack traces in error responses
+
+### POST /live/previews/* (`admin/render.ts`)
+
+Renders a section for preview in the admin iframe.
+
+```typescript
+handleRender(request: Request): Response
+```
+
+- Uses `setRenderShell(config)` to wrap preview in HTML shell
+- Shell must include `data-theme="light"` for DaisyUI v4 color variables
+- Renders section component with provided props
+
+## Setup (`admin/setup.ts`)
+
+Client-safe configuration (no `node:` imports or AsyncLocalStorage):
+
+```typescript
+// Called in site's setup.ts
+setMetaData(metaJson);                    // Set schema data from meta.gen.json
+setInvokeLoaders(loaderMap);              // Register loaders for /deco/invoke
+setInvokeActions(actionMap);              // Register actions for /deco/invoke
+setRenderShell(shellConfig);              // Configure preview HTML wrapper
+registerLoaderSchema(key, schema);        // Register a single loader schema dynamically
+registerLoaderSchemas(schemas);           // Register multiple loader schemas at once
+registerMatcherSchema(key, schema);       // Register a single matcher schema dynamically
+registerMatcherSchemas(schemas);          // Register multiple matcher schemas at once
+```
+
+## Schema Composition (`admin/schema.ts`)
+
+`composeMeta()` injects framework-level schemas at runtime:
+
+```
+[generate-schema.ts]          [setup.ts]                [composeMeta()]
+Scans src/sections/    -->    Imports meta.gen.json  --> Injects page schema,
+Produces section-only         Calls setMetaData()       merges definitions,
+meta.gen.json                                           populates pages root
+```
+
+Key: `toBase64()` must produce padded output matching `btoa()` - admin uses `btoa()` for definition refs.
+
+### Dynamic Schema Registries
+
+Loader and matcher schemas are now managed via runtime registries instead of hardcoded lists:
+
+```typescript
+// Loaders — runtime registry replaces old KNOWN_LOADERS array
+registerLoaderSchema("vtex/loaders/productList.ts", {
+  inputSchema: { ... },
+  outputSchema: { ... },
+  tags: ["product-list"],  // used by wrapResolvableProperties to filter product-list loaders
+});
+
+// Matchers — same pattern
+registerMatcherSchema("website/matchers/device.ts", {
+  inputSchema: { ... },
+});
+```
+
+`buildLoaderDefinitions()` and `buildMatcherDefinitions()` now read from these registries at composition time. The `getProductListLoaderKeys()` function dynamically filters loaders tagged with `product-list`.
+
+## CORS (`admin/cors.ts`)
+
+```typescript
+isAdminOrLocalhost(origin: string): boolean  // Check if origin is admin
+corsHeaders(origin: string): Headers         // CORS headers for admin
+```
+
+Allows: `admin.deco.cx`, `localhost:*`.
+
+## LiveControls (`admin/liveControls.ts`)
+
+Inline script injected into every page when in admin context:
+
+```typescript
+LIVE_CONTROLS_SCRIPT: string  // postMessage bridge script
+```
+
+Provides:
+- `__DECO_STATE` global with decofile state
+- `postMessage` bridge to admin iframe
+- Section selection/highlighting
+- Environment info (site, deploymentId)
+
+## LiveControls Component (`hooks/LiveControls.tsx`)
+
+React component that renders the bridge script:
+
+```tsx
+<LiveControls
+  site={site}
+  siteId={siteId}
+/>
+```
+
+Injected in the site's `__root.tsx`.