@decocms/start 0.19.0

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

@@ -0,0 +1,185 @@
+---
+name: deco-core-architecture
+description: Architecture reference for deco-cx/deco — the core Deco framework for Fresh/Deno. Covers the resolution engine (Resolvable → Resolver pipeline), block system (sections, loaders, actions, flags, matchers, handlers, apps, workflows), runtime request flow (Hono + Fresh/HTMX), DecofileProvider (state management), manifest generation, plugin system, hooks (useSection, useScript, useDevice), client-side invoke proxy, and the relationship between deco-cx/deco (Fresh/Deno) and @decocms/start (TanStack/Node). Use when exploring the deco repo, understanding how the framework works, building new block types, debugging resolution issues, or porting deco internals to TanStack Start.
+globs:
+  - "**/deco.ts"
+  - "**/manifest.gen.ts"
+  - "**/mod.ts"
+  - "**/runtime.ts"
+  - "**/fresh.config.ts"
+---
+
+## Sub-documents
+
+| Document | Topic |
+|----------|-------|
+| [engine.md](./engine.md) | Resolution engine — Resolvable, Resolver, DecofileProvider, resolve pipeline |
+| [blocks.md](./blocks.md) | Block system — all block types, adapt/decorate, manifest registration |
+| [runtime.md](./runtime.md) | Runtime request flow — Hono, middleware chain, routes, rendering |
+| [hooks-components.md](./hooks-components.md) | Hooks, components, and client-side code |
+| [plugins-clients.md](./plugins-clients.md) | Fresh plugins, client-side invoke proxy, formdata utils |
+| [site-usage.md](./site-usage.md) | How a Deco site uses the framework — osklenbr as reference |
+| [deco-vs-deco-start.md](./deco-vs-deco-start.md) | Mapping deco-cx/deco (Fresh) → @decocms/start (TanStack) |
+
+# deco-cx/deco Core Architecture
+
+Reference for the `deco-cx/deco` repository — the core Deco framework powering Fresh/Deno storefronts.
+
+## Repository Overview
+
+```
+deco/
+├── mod.ts               # Main entry — re-exports engine, runtime, blocks, context
+├── mod.web.ts           # Web/client entry — invoke proxy, stream reader
+├── deco.ts              # DecoContext, RequestContext, AsyncLocalStorage bindings
+├── live.ts              # Re-export of deco.ts (legacy alias)
+├── types.ts             # DecoManifest, DecoState, block type constants
+├── deps.ts              # External deps (OpenTelemetry, std, durable, inspect)
+├── deno.json            # v1.177.5 — imports, exports, tasks
+│
+├── engine/              # Resolution engine (45 files)
+│   ├── core/            # Resolver, Resolvable, resolve pipeline
+│   ├── manifest/        # Manifest builder, generation, defaults
+│   ├── decofile/        # State providers (filesystem, JSON, realtime)
+│   ├── schema/          # JSON Schema generation and introspection
+│   └── importmap/       # Import map builder for blocks
+│
+├── blocks/              # Block definitions (15 files)
+│   ├── section.ts       # UI components with optional loader/action
+│   ├── loader.ts        # Data fetching blocks (cached, single-flight)
+│   ├── action.ts        # Mutation blocks
+│   ├── handler.ts       # HTTP request handlers
+│   ├── flag.ts          # Feature flags
+│   ├── matcher.ts       # Audience targeting predicates
+│   ├── page.tsx         # Page-level sections
+│   ├── app.ts           # App containers with manifest + state
+│   ├── workflow.ts      # Durable workflows
+│   └── function.ts      # Legacy loader format
+│
+├── runtime/             # Request handling (51 files)
+│   ├── mod.ts           # Deco class — main runtime entry
+│   ├── handler.tsx      # Hono app setup, route registration
+│   ├── middleware.ts     # Middleware chain (liveness, state, o11y, response)
+│   ├── routes/          # Built-in routes (/live/invoke, /deco/render, etc.)
+│   ├── features/        # Invoke, render, meta, preview, styles
+│   ├── fresh/           # Fresh framework plugin + Bindings
+│   ├── htmx/            # HTMX framework (alternative renderer)
+│   ├── fetch/           # Instrumented fetch (logging, caching)
+│   └── caches/          # LRU, Redis, tiered, filesystem caches
+│
+├── hooks/               # Server-side hooks (6 files)
+├── components/          # Framework components (5 files)
+├── plugins/             # Fresh plugins (3 files)
+├── clients/             # Client-side invoke proxy (3 files)
+├── commons/             # JWT, workflows
+├── utils/               # HTTP, cookies, timings, invoke helpers
+├── observability/       # OpenTelemetry instrumentation
+├── daemon/              # Sidecar/embedded daemon for dev
+├── dev/                 # Dev server utilities
+├── hypervisor/          # Multi-site orchestration
+└── scripts/             # Release, dev, bundle scripts
+```
+
+## Core Concepts
+
+### 1. Everything is a Resolvable
+
+The fundamental unit in Deco is a **Resolvable** — an object with a `__resolveType` field pointing to a resolver:
+
+```typescript
+// A resolvable stored in the decofile (CMS state)
+{
+  "__resolveType": "site/loaders/productList.ts",
+  "query": "shoes",
+  "count": 12
+}
+```
+
+The engine recursively resolves all props, then invokes the matching resolver function.
+
+### 2. Blocks define the type system
+
+Each block type (section, loader, action, etc.) defines how modules are adapted into resolvers:
+
+- **section** → wraps a Preact component, adding SSR + optional data loading
+- **loader** → wraps a function with caching, single-flight dedup, and tracing
+- **action** → wraps a mutation function with tracing
+- **handler** → produces an HTTP handler from config
+- **matcher** → evaluates a predicate against request context
+- **flag** → combines matchers with variants for feature flags
+- **app** → bundles manifest + state + dependencies
+
+### 3. DecofileProvider manages state
+
+The decofile is the CMS state — a `Record<string, Resolvable>`. Providers can be:
+- **Filesystem** (`newFsProvider`) — reads from local `.json`/`.jsonl` files
+- **Realtime** — connects to CMS websocket for live updates
+- **JSON** — static in-memory state
+
+### 4. Request flow
+
+```
+Request → Hono
+  → bindings middleware (RENDER_FN, GLOBALS)
+  → liveness probe (/deco/_liveness)
+  → state builder (prepareState, debug, echo)
+  → observability (OpenTelemetry trace/span)
+  → main middleware (CORS, headers, cache, segment)
+  → route matching:
+      /styles.css        → tailwind CSS
+      /live/_meta         → schema + manifest
+      /live/invoke/*      → single/batch invoke
+      /deco/render        → partial section render
+      * (catch-all)       → page handler → resolve → render
+```
+
+### 5. Two rendering frameworks
+
+| Framework | Islands | Partials | Usage |
+|-----------|---------|----------|-------|
+| **Fresh** | Preact islands | `<Partial>` + `f-partial` | Standard Deco sites |
+| **HTMX** | None (no JS) | `hx-get/hx-swap` | Lightweight alternative |
+
+### 6. Invoke system
+
+Client-side code calls server loaders/actions via the invoke API:
+
+```typescript
+// Client-side (runtime.ts in a site)
+import { proxy } from "@deco/deco/web";
+const invoke = proxy<Manifest>();
+
+// Calls POST /live/invoke/site/loaders/productList.ts
+const products = await invoke["site/loaders/productList.ts"]({ query: "shoes" });
+```
+
+## Key Exports
+
+### `mod.ts` (main)
+- `Context` — AsyncLocalStorage-based context
+- `$live`, `initContext`, `newContext` — engine initialization
+- `Deco`, `PageData` — runtime class and page data type
+- `Block`, `BlockFunc`, `Resolvable`, `Resolved` — type system
+- `asResolved`, `isDeferred`, `isResolvable` — resolution utilities
+- `allowCorsFor` — CORS utility
+- `JsonViewer`, `Framework` — components
+
+### `mod.web.ts` (client)
+- `proxy`, `withManifest`, `forApp` — invoke proxy builders
+- `readFromStream` — SSE stream reader
+- `InvokeAwaiter` — chainable invoke proxy
+
+### `deco.ts` (context)
+- `DecoContext` — site, siteId, deploymentId, platform, release, runtime
+- `RequestContext` — signal, framework
+- `Context.active()` — current context
+- `Context.bind(ctx, fn)` — run fn with context
+
+## Dependencies
+
+- **Runtime**: Deno, Fresh 1.6.8, Preact 10.23.1
+- **Observability**: OpenTelemetry (api, sdk-trace, sdk-metrics, sdk-logs)
+- **Framework**: Hono (HTTP router)
+- **Deco ecosystem**: `@deco/durable`, `@deco/inspect-vscode`, `@deco/warp`
+- **Std**: `@std/assert`, `@std/async`, `@std/crypto`, `@std/encoding`, `@std/http`
+- **Compiler**: `jsx: "react-jsx"`, `jsxImportSource: "preact"`

package/.cursor/skills/deco-core-architecture/blocks.md

@@ -0,0 +1,196 @@
+# Block System (`blocks/`)
+
+Blocks are the type system of Deco. Each block type defines how a module is adapted into a resolver, previewed, and invoked.
+
+## Block Interface
+
+```typescript
+interface Block<TBlockModule> {
+  type: string;                    // manifest key: "sections", "loaders", etc.
+  introspect?: {
+    funcNames?: string[];
+    includeReturn?: boolean;
+  };
+  adapt?: (mod: TBlockModule, key: string) => Resolver | Resolver[];
+  decorate?: (mod: TBlockModule, key: string) => TBlockModule;
+  defaultDanglingRecover?: Resolver;
+  defaultPreview?: Resolver;
+  defaultInvoke?: Resolver;
+}
+```
+
+## BlockModule Convention
+
+Every block module can export:
+
+| Export | Purpose |
+|--------|---------|
+| `default` | Main function (loader, action, component, handler factory) |
+| `invoke` | Custom invocation handler (for `/live/invoke`) |
+| `preview` / `Preview` | Admin preview component |
+| `onBeforeResolveProps` | Transform props before resolution |
+
+## Block Types
+
+### Section (`section.ts`)
+
+UI components that render on the page. The most common block type.
+
+```typescript
+// type: "sections"
+export default function MySection(props: Props) {
+  return <div>{props.title}</div>;
+}
+
+// With server-side data loading:
+export const loader = async (props: Props, req: Request, ctx: AppContext) => {
+  const data = await fetchData(props);
+  return { ...props, data };
+};
+
+export default function MySection({ data, title }: LoaderReturn) {
+  return <div>{title}: {data}</div>;
+}
+```
+
+Features: wraps Preact component as resolver returning `PreactComponent`, supports `loader` for SSR, `action` for forms, ErrorBoundary + SectionContext wrapper.
+
+### Loader (`loader.ts`)
+
+Data fetching functions with caching and single-flight dedup.
+
+```typescript
+// type: "loaders"
+export default async function myLoader(
+  props: Props,
+  req: Request,
+  ctx: AppContext
+): Promise<Product[]> {
+  return await ctx.invoke("vtex/loaders/productList.ts", props);
+}
+```
+
+Features: cached (single-flight), OpenTelemetry tracing, invocable via `/live/invoke`.
+
+### Action (`action.ts`)
+
+Mutation functions (not cached).
+
+```typescript
+// type: "actions"
+export default async function addToCart(
+  props: { sku: string; quantity: number },
+  req: Request,
+  ctx: AppContext
+): Promise<Cart> {
+  return await ctx.invoke("vtex/actions/cart/addItems.ts", {
+    orderItems: [{ id: props.sku, quantity: props.quantity, seller: "1" }]
+  });
+}
+```
+
+### Handler (`handler.ts`)
+
+HTTP request handlers using a factory pattern.
+
+```typescript
+// type: "handlers"
+export default function proxy(config: { url: string }) {
+  return async (req: Request, ctx: ConnInfo): Promise<Response> => {
+    return await fetch(new URL(req.url).pathname, { ...config });
+  };
+}
+```
+
+Used for proxies, redirects, sitemaps, and custom routes.
+
+### Flag (`flag.ts`)
+
+Feature flags with variant selection.
+
+```typescript
+// type: "flags"
+// Simple boolean flag:
+export default function myFlag(config: { percentage: number }) {
+  return { name: "my-experiment", value: Math.random() < config.percentage };
+}
+
+// Multivariate:
+export default function mvFlag(config: Config) {
+  return {
+    name: "checkout-v2",
+    variants: [
+      { value: "control", rule: { traffic: 0.5 } },
+      { value: "experiment", rule: { traffic: 0.5 } },
+    ],
+  };
+}
+```
+
+### Matcher (`matcher.ts`)
+
+Predicates for audience segmentation.
+
+```typescript
+// type: "matchers"
+export default function device(config: { mobile: boolean }) {
+  return (ctx: MatchContext): boolean => {
+    return ctx.device === "mobile" === config.mobile;
+  };
+}
+```
+
+Built-in matchers: MatchDevice, MatchCookie, MatchDate, MatchLocation, MatchHost, MatchRandom, MatchUserAgent, MatchSite, MatchMulti.
+
+### App (`app.ts`)
+
+Container that bundles manifest + state + dependencies.
+
+```typescript
+// type: "apps"
+export default function MyApp(props: Props): App<Manifest, State> {
+  return {
+    manifest,
+    state: { /* clients, config */ },
+    dependencies: [otherApp(props)],
+  };
+}
+```
+
+`buildRuntime` processes the manifest, creating resolvers for each block module.
+
+### Page (`page.tsx`)
+
+Like section but page-level. Same mechanism.
+
+### Workflow (`workflow.ts`)
+
+Durable workflows using `@deco/durable`. Type: "workflows".
+
+### Function (`function.ts`)
+
+Legacy loader format. Deprecated in favor of `loader.ts`.
+
+### Account (`account.ts`)
+
+Platform configuration blocks. Returns account/config object.
+
+## Block Registration Flow
+
+1. `decoManifestBuilder()` scans directories matching block types
+2. `manifest.gen.ts` is generated with imports and block keys
+3. At startup, `buildRuntime()` processes each block:
+   - `block.adapt(mod, key)` for each module
+   - `block.decorate(mod, key)` applied before adapt
+   - Resolvers registered: `key`, `Preview@key`, `Invoke@key`
+   - `defaultDanglingRecover` registered per block type
+4. All resolvers passed to `ReleaseResolver`
+
+## Block Resolution Priority
+
+When resolving `__resolveType`:
+1. Check `resolvables[type]` (decofile state) then recurse
+2. Check `resolvers[type]` (block resolvers) then invoke
+3. Check `overrides[type]` then redirect
+4. Fall back to `DanglingRecover@{blockType}` (StubSection)
+5. Throw `DanglingReference` error

package/.cursor/skills/deco-core-architecture/deco-vs-deco-start.md

@@ -0,0 +1,191 @@
+# deco-cx/deco vs @decocms/start
+
+Mapping between the original Deco framework (Fresh/Deno) and its TanStack/Node counterpart.
+
+## Architecture Comparison
+
+```
+deco-cx/deco (Fresh/Deno)              @decocms/start (TanStack/Node)
+─────────────────────────              ──────────────────────────────
+Deno runtime                           Node.js / Cloudflare Workers
+Fresh 1.6.8 framework                  TanStack Start + Vite
+Preact 10.23.1                         React 18/19
+Hono (internal router)                 TanStack Router (file-based)
+manifest.gen.ts                        Explicit imports + admin protocol
+DecofileProvider                       Admin SDK (CMS state fetching)
+Resolution engine (Resolvable)         Direct function calls
+Block system (adapt/resolve)           Pure async functions
+@preact/signals                        @tanstack/react-store / React state
+deno.json (import map)                 package.json + npm
+```
+
+## Module Mapping
+
+### Entry Points
+
+| deco-cx/deco | @decocms/start | Notes |
+|-------------|----------------|-------|
+| `mod.ts` | `src/index.ts` | Main exports |
+| `mod.web.ts` | Not needed | Client invoke is direct imports |
+| `deco.ts` (Context) | Admin context/config | No AsyncLocalStorage pattern |
+| `live.ts` | N/A (legacy) | — |
+| `types.ts` | TypeScript types from packages | — |
+
+### Engine → Generic Resolver
+
+Both frameworks now have a resolution engine, but `@decocms/start`'s is simpler and purpose-built:
+
+```typescript
+// deco-cx/deco: full resolution engine with hints, single-flight, monitoring
+// decofile state:
+{ "__resolveType": "vtex/loaders/productList.ts", "query": "shoes", "count": 12 }
+// → engine.resolve() → find resolver → invoke with resolved props → hints → monitoring
+
+// @decocms/start: generic recursive resolver (internalResolve)
+// Same __resolveType decofile format, resolved via:
+// 1. Check commerce loaders registry
+// 2. Check decofile blocks
+// 3. DanglingReference fallback (configurable)
+// + Per-request memoization + depth protection (max 10)
+```
+
+Key differences:
+- `deco-cx/deco` has full-featured single-flight, hints, monitoring
+- `@decocms/start` has simpler memoization + configurable error handlers (`setResolveErrorHandler`, `setDanglingReferenceHandler`)
+- `@decocms/start` supports `select` field filtering on resolved values
+- `@decocms/start` allows dynamically adding skip types via `addSkipResolveType()`
+
+### Blocks → Functions/Components
+
+| deco Block | TanStack Equivalent |
+|-----------|---------------------|
+| Section block | React component (direct import) |
+| Loader block (cached, single-flight) | Server function + React Query (with staleTime) |
+| Action block | Server function + React Query mutation |
+| Handler block | TanStack Router route handler |
+| Flag block | Feature flag config (edge-level) |
+| Matcher block | Middleware or route guard |
+| App block | `configure*()` function (e.g., `configureVtex()`) |
+| Workflow block | Background task (platform-specific) |
+
+### Runtime → TanStack Start
+
+| deco Runtime | TanStack Start |
+|-------------|---------------|
+| Hono router | TanStack Router |
+| Fresh middleware chain | TanStack Start middleware |
+| `/live/invoke/*` | API routes or server functions |
+| `/deco/render` | React Server Components or loader revalidation |
+| `entrypoint.tsx` catch-all | `__root.tsx` + route tree |
+| `Deco` class | Vite plugin + start config |
+
+### Hooks → React Equivalents
+
+| deco Hook | TanStack Equivalent |
+|-----------|---------------------|
+| `useSection()` | React Query revalidation + state updates (stub in `@decocms/start`) |
+| `usePartialSection()` | TanStack Router Link / navigate (stub in `@decocms/start`) |
+| `useScript()` | `@decocms/start/sdk/useScript` — with lightweight minification + LRU cache |
+| `useScriptAsDataURI()` | `@decocms/start/sdk/useScript` — same, data URI variant |
+| `useDevice()` | `@decocms/start/sdk/useDevice` — server-side via User-Agent + RequestContext, also `detectDevice`, `checkMobile/Tablet/Desktop` |
+| `useSetEarlyHints()` | Response headers in server middleware |
+
+### Plugins → Config
+
+| deco Plugin | TanStack Equivalent |
+|------------|---------------------|
+| `plugins/deco.ts` (Fresh plugin) | `@decocms/start` Vite plugin + entry |
+| `plugins/fresh.ts` (Tailwind + Deco) | Tailwind via Vite plugin |
+| `plugins/styles.ts` (global CSS) | CSS in `__root.tsx` or global stylesheet |
+
+### Clients → Direct Imports
+
+| deco Client | TanStack Equivalent |
+|------------|---------------------|
+| `proxy<Manifest>()` | Direct function imports |
+| `invoke["key"](props)` | `await loaderFn(props)` or `/deco/invoke` with FormData/URLEncoded/JSON |
+| `readFromStream()` | `fetch()` + ReadableStream |
+| `formDataToProps()` | Built into invoke handler (auto-parses multipart/form-data and URL-encoded) |
+
+### Components → React Components
+
+| deco Component | TanStack Equivalent |
+|---------------|---------------------|
+| `LiveControls.tsx` | `LiveControls.tsx` in `@decocms/start` (adapted) |
+| `SectionContext` | React context per section |
+| `ErrorBoundary` | React Error Boundary |
+| `StubSection` | Fallback component |
+| `JsonViewer` | JSON display component |
+
+## State Management Comparison
+
+### deco-cx/deco
+
+```
+CMS Admin → publish → DecofileProvider.onChange()
+  → ReleaseResolver rebuilds
+  → New resolvables available
+  → Next request uses new state
+```
+
+### @decocms/start
+
+```
+CMS Admin → publish → POST /.decofile (hot-reload)
+  → setBlocks() updates in-memory state
+  → Revision recomputed (content-hash)
+  → onChange listeners notified (meta cache invalidated)
+  → clearLoaderCache() ensures fresh data
+  → Edge cache purge (Cloudflare)
+  → Next request uses new state + fresh schema
+```
+
+## Rendering Comparison
+
+### deco-cx/deco (SSR + Islands)
+
+```
+Request → Fresh handler
+  → Resolve page sections (engine)
+  → Preact renderToString (server)
+  → Hydrate islands only (client)
+  → Partial updates via useSection + /deco/render
+```
+
+### @decocms/start (SSR + Full Hydration)
+
+```
+Request → TanStack Start handler
+  → Route loader runs (server function)
+  → React renderToString (server)
+  → Full hydration (client)
+  → Client-side navigation via TanStack Router
+  → Data updates via React Query revalidation
+```
+
+## Caching Comparison
+
+| Aspect | deco-cx/deco | @decocms/start |
+|--------|-------------|---------------|
+| Loader cache | In-process single-flight + LRU | React Query staleTime + Cloudflare cache |
+| Page cache | CDN + Deco edge | Cloudflare Workers cache API |
+| Static assets | Fresh static serving | Vite build + CDN |
+| Cache invalidation | DecofileProvider onChange | `setBlocks` → onChange listeners + `clearLoaderCache()` + edge purge |
+
+## Key Takeaways for Porting
+
+1. **Simpler resolution engine**: `@decocms/start` now has a generic recursive resolver (`internalResolve`) for `__resolveType`, but it's simpler than `deco-cx/deco`'s full engine (no hints, no single-flight). It resolves commerce loaders, decofile blocks, and has configurable fallback for dangling references.
+
+2. **No manifest**: Instead of auto-generated manifests with lazy imports, `@decocms/apps-start` uses explicit exports that sites import directly.
+
+3. **No islands architecture**: React hydrates everything. Optimize with React.lazy, Suspense, and code splitting instead.
+
+4. **Enhanced invoke**: The `/deco/invoke` endpoint now supports FormData, URL-encoded bodies, `?select=` filtering, batch execution, actions registration, and nested `__resolveType` resolution.
+
+5. **CMS integration**: `@decocms/start` provides the admin protocol (LiveControls, section editing) through its own SDK. Schema registries are dynamic (loaders + matchers registered at runtime).
+
+6. **Edge-first**: `@decocms/start` is designed for Cloudflare Workers, with caching handled at the edge rather than in-process.
+
+7. **Observability parity**: `@decocms/start` now has pluggable `TracerAdapter` + `MeterAdapter`, standardized `MetricNames`, and a `/deco/_health` endpoint with uptime, memory, cache stats, and request metrics.
+
+8. **Server-side device detection**: `useDevice()` works server-side via `RequestContext` + User-Agent parsing, matching `deco-cx/deco`'s functionality.