@decocms/start 0.19.0

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

@@ -0,0 +1,220 @@
+# Resolution Engine (`engine/`)
+
+The heart of Deco — resolves configuration objects (Resolvables) into runtime values using a pipeline of resolvers.
+
+## Core Concepts
+
+### Resolvable
+
+An object with `__resolveType` that tells the engine which resolver to use:
+
+```typescript
+interface Resolvable<T = unknown> {
+  __resolveType: string;  // resolver key (e.g. "site/loaders/productList.ts")
+  [key: string]: unknown; // props passed to the resolver
+}
+```
+
+### Resolver
+
+A function that processes a Resolvable:
+
+```typescript
+type Resolver<T = unknown> = (
+  parent: T,           // resolved props from the Resolvable
+  context: ResolverContext
+) => T | Resolvable<T> | Promise<T | Resolvable<T>>;
+```
+
+### ResolverContext
+
+```typescript
+interface ResolverContext {
+  resolvables: Record<string, Resolvable>;  // decofile state
+  resolvers: Record<string, Resolver>;      // all registered resolvers
+  resolve: (resolvable: Resolvable | string) => Promise<unknown>;
+  resolveChain: FieldResolver[];            // debug: resolution path
+  memo: Map<string, Promise<unknown>>;      // memoization cache
+  runOnce: (key: string, fn: () => Promise<T>) => Promise<T>;
+  revision: string;
+}
+```
+
+## Resolution Pipeline
+
+```
+resolve(input)
+  │
+  ├─ string → resolveWithType(resolveType, {}, context)
+  │
+  └─ Resolvable → resolveAny()
+       │
+       └─ resolvePropsWithHints()
+            │
+            ├─ Extract __resolveType
+            ├─ Call onBeforeResolveProps (if defined)
+            ├─ Resolve each prop recursively (parallel)
+            └─ resolveWithType(__resolveType)
+                 │
+                 ├─ In resolvables? → resolveResolvable() [with memo]
+                 ├─ In resolvers?   → invokeResolverWithProps()
+                 └─ Else            → danglingRecover or DanglingReference error
+```
+
+### Key Functions (`engine/core/resolver.ts`)
+
+| Function | Purpose |
+|----------|---------|
+| `resolve(input, ctx)` | Main entry — handles string refs and Resolvable objects |
+| `resolveAny(obj, ctx)` | Resolves an arbitrary object, recursing into props |
+| `resolvePropsWithHints(obj, ctx)` | Uses hint nodes to efficiently resolve only resolvable props |
+| `resolveWithType(type, props, ctx)` | Resolves by looking up type in resolvables or resolvers |
+| `resolveResolvable(id, ctx)` | Resolves a named resolvable with memoization |
+| `invokeResolverWithProps(type, props, ctx)` | Calls the resolver function with resolved props |
+
+### Resolution Hints (`engine/core/hints.ts`)
+
+Optimization to avoid scanning all props. `HintNode` trees mark which properties contain resolvables:
+
+```typescript
+interface HintNode {
+  __resolveType?: boolean;  // this object is a Resolvable
+  [prop: string]: HintNode; // nested hints
+}
+```
+
+`traverseAny()` builds hints from the decofile. The resolver only recurses into hinted paths.
+
+### Memoization
+
+`resolveResolvable` memos results by `resolverIdFromResolveChain`. Same resolvable in the same resolution tree returns the cached promise.
+
+## Resolve Chain
+
+A debug/tracing mechanism. Each resolution step appends a `FieldResolver`:
+
+```typescript
+type FieldResolver =
+  | { type: "prop"; value: string }       // accessing a property
+  | { type: "resolvable"; value: string } // resolving a named resolvable
+  | { type: "resolver"; value: string }   // invoking a resolver
+  | { type: "dangling"; value: string }   // unresolved reference
+```
+
+Used for cache keys, tracing, and error reporting.
+
+## ReleaseResolver (`engine/core/mod.ts`)
+
+Top-level coordinator:
+
+```typescript
+function ReleaseResolver(
+  decofileProvider: DecofileProvider,
+  resolvers: Record<string, Resolver>,
+  options?: { danglingRecover?, overrides?, forceFresh? }
+): {
+  resolve: (resolvable | string) => Promise<unknown>;
+  state: () => ResolvableMap;
+  revision: () => string;
+}
+```
+
+- Gets `resolvables` and `revision` from the DecofileProvider
+- Combines default resolvers + block resolvers + app resolvers
+- Provides the top-level `resolve()` function used by the runtime
+
+## DecofileProvider (`engine/decofile/`)
+
+Interface for state management (the decofile is the CMS state):
+
+```typescript
+interface DecofileProvider {
+  state(): Record<string, Resolvable>;    // current state
+  revision(): string;                      // version/etag
+  onChange(cb: () => void): void;          // subscribe to changes
+  dispose?(): void;
+}
+```
+
+### Implementations
+
+| Provider | Source | Usage |
+|----------|--------|-------|
+| `newFsProvider` | Local filesystem (`.json`, `.jsonl`) | Dev mode |
+| `jsonProvider` | In-memory JSON object | Testing, static |
+| `realtimeProvider` | CMS websocket connection | Production |
+| `fsFolderProvider` | `folder://` directory with individual files | Legacy |
+
+### State Lifecycle
+
+1. `DecofileProvider.state()` returns current `ResolvableMap`
+2. Engine creates `ReleaseResolver` with this state
+3. Provider emits `onChange()` when CMS publishes
+4. Engine reinstalls apps and rebuilds resolvers
+
+## Manifest System (`engine/manifest/`)
+
+### ManifestBuilder
+
+Programmatically builds a manifest file:
+
+```typescript
+interface ManifestData {
+  namespace: string;
+  imports: Record<string, string>;     // import name → module path
+  manifest: Record<string, string[]>;  // block type → keys
+  exports: Record<string, string>;
+  statements: string[];
+}
+```
+
+Key methods:
+- `mergeWith(other)` — merge manifests from multiple apps
+- `addValuesOnManifestKey(key, values)` — add blocks by type
+- `build()` — generate the `.ts` file content
+
+### manifestGen
+
+`decoManifestBuilder()` walks directories by block type, calling `withDefinition()` for each discovered module.
+
+### Default Resolvers (`engine/manifest/defaults.ts`)
+
+Built-in resolvers available in every Deco instance:
+
+| Resolver | Purpose |
+|----------|---------|
+| `state` | Returns raw resolvable value |
+| `resolvables` | Access resolvables map |
+| `resolvers` | Access resolvers map |
+| `once` | Run-once resolver (memoized) |
+| `resolveTypeSelector` | Dynamic __resolveType selection |
+| `blockSelector` | Select block by type |
+| `selectKeys` | Pick specific keys from resolved object |
+| `mergeProps` | Deep-merge multiple resolved objects |
+| `resolved` | Mark value as already resolved |
+| `preview` | `Preview@{block}` namespace |
+| `invoke` | `Invoke@{block}` namespace |
+
+## Schema System (`engine/schema/`)
+
+Generates JSON Schema from TypeScript types at runtime:
+
+| File | Purpose |
+|------|---------|
+| `schemeable.ts` | Core schema types (`Schemeable`) |
+| `builder.ts` | Builds JSON Schema from scheemables |
+| `parser.ts` | Parses TypeScript AST into scheemables |
+| `merge.ts` | Merges schemas from multiple sources |
+| `reader.ts` | Reads and caches module schemas |
+| `transform.ts` | Schema transformations (refs, ids) |
+| `lazy.ts` | Lazy schema loading for performance |
+
+Used by the admin to generate forms for block props.
+
+## Import Map (`engine/importmap/`)
+
+Builds Deno import maps for blocks:
+
+- `buildImportMap(manifest)` — generates imports for each block
+- `FuncAddr.build()` — creates `resolve://path?export=funcName` addresses
+- Supports JSR (`jsr:`) and URL imports

package/.cursor/skills/deco-core-architecture/hooks-components.md

@@ -0,0 +1,157 @@
+# Hooks and Components
+
+Server-side hooks and shared components provided by the Deco framework.
+
+## Hooks (`hooks/`)
+
+### useSection (`useSection.ts`)
+
+Generates a URL for partial section rendering via `/deco/render`.
+
+```typescript
+function useSection<TProps>(options: {
+  props?: Partial<TProps>;   // new props for the section
+  href?: string;             // target URL
+}): string  // returns URL to POST for partial render
+```
+
+Used in section components to create interactive behavior without client-side JS:
+
+```tsx
+function ProductShelf({ products, page = 0 }: Props) {
+  const nextPageUrl = useSection({ props: { page: page + 1 } });
+
+  return (
+    <div>
+      {products.map(p => <ProductCard product={p} />)}
+      <button hx-get={nextPageUrl} hx-target="closest section">
+        Load more
+      </button>
+    </div>
+  );
+}
+```
+
+Internals:
+- Serializes `props`, `href`, `pathTemplate`, `resolveChain` into the URL
+- Strips tracking query params (BLOCKED_QS: utm_*, gclid, fbclid, etc.)
+- Supports `__cb` callback parameter
+
+### usePartialSection (`usePartialSection.ts`)
+
+Fresh-specific: returns attributes for Fresh `<Partial>` navigation.
+
+```typescript
+function usePartialSection<TProps>(options: {
+  props?: Partial<TProps>;
+  href?: string;
+}): { "f-client-nav": true; "f-partial": string }
+```
+
+Usage:
+```tsx
+<button {...usePartialSection({ props: { page: 2 } })}>
+  Next Page
+</button>
+```
+
+### useScript (`useScript.ts`)
+
+Minifies a function and returns it as a script string or data URI.
+
+```typescript
+// Returns minified script string
+function useScript<Args>(fn: (...args: Args) => void, ...args: Args): string;
+
+// Returns data:text/javascript,... URI
+function useScriptAsDataURI<Args>(fn: (...args: Args) => void, ...args: Args): string;
+```
+
+Usage:
+```tsx
+<script dangerouslySetInnerHTML={{
+  __html: useScript((count) => {
+    document.getElementById("counter").textContent = String(count);
+  }, initialCount)
+}} />
+```
+
+Uses Terser for minification.
+
+### useDevice (`useDevice.ts`)
+
+Returns the current device type from the server context.
+
+```typescript
+function useDevice(): "desktop" | "mobile" | "tablet";
+```
+
+Detection is done server-side via User-Agent header using `userAgent.ts`.
+
+### useSetEarlyHints (`useSetEarlyHints.ts`)
+
+Adds `Link` headers for HTTP 103 Early Hints (preload/preconnect).
+
+```typescript
+function useSetEarlyHints(links: Array<{
+  href: string;
+  as?: string;
+  rel?: string;
+}>): void;
+```
+
+## Components (`components/`)
+
+### Section (`section.tsx`)
+
+Core section rendering infrastructure:
+
+| Export | Purpose |
+|--------|---------|
+| `withSection(Component)` | HOC wrapping component with context + error boundary |
+| `SectionContext` | Preact context providing section ID, resolve chain |
+| `getSectionID(resolveChain)` | Extracts unique section ID from resolve chain |
+| `ErrorBoundary` | Catches render errors, shows fallback UI |
+| `Framework` | Framework-agnostic section wrapper |
+
+### StubSection (`StubSection.tsx`)
+
+Placeholder for dangling references (when a section's module is not found):
+
+```tsx
+function StubSection({ component }: { component: string }) {
+  return <div>Section not found: {component}</div>;
+}
+```
+
+Used as `defaultDanglingRecover` for section blocks.
+
+### PreviewNotAvailable (`PreviewNotAvailable.tsx`)
+
+Shown in admin when a block doesn't have a preview implementation.
+
+### LiveControls (`LiveControls.tsx`)
+
+Injected into every page in edit mode. Provides:
+
+- `__DECO_STATE` global with decofile state
+- `DomInspector` for element selection
+- Keyboard shortcuts (`Ctrl+Shift+E` for editor)
+- `postMessage` bridge to admin iframe
+- Script loads from `decoAssistantUrl`
+
+### JsonViewer (`JsonViewer.tsx`)
+
+Renders JSON data using jQuery JSONView. Used in admin previews for loaders/actions.
+
+## Exports Map (`hooks/mod.ts`)
+
+All hooks are re-exported from `@deco/deco/hooks`:
+
+```typescript
+export { useSection } from "./useSection.ts";
+export { usePartialSection } from "./usePartialSection.ts";
+export { useScript, useScriptAsDataURI } from "./useScript.ts";
+export { useDevice } from "./useDevice.ts";
+export { useSetEarlyHints } from "./useSetEarlyHints.ts";
+```

package/.cursor/skills/deco-core-architecture/plugins-clients.md

@@ -0,0 +1,136 @@
+# Plugins and Clients
+
+## Plugins (`plugins/`)
+
+### Deco Plugin (`plugins/deco.ts`)
+
+The main Fresh plugin that integrates Deco into a Fresh app.
+
+```typescript
+import { plugins } from "deco/plugins/deco.ts";
+
+export default defineConfig({
+  plugins: plugins({
+    manifest,
+    htmx: false,
+    site: "mysite",
+    ErrorFallback,
+    useServer: true,
+    middlewares: [],
+  }),
+});
+```
+
+Internally wraps `runtime/fresh/plugin.tsx`. Registers routes (`/[...catchall]`, `/index`), island (`DispatchAsyncRender.tsx`), selects framework (Fresh or HTMX), injects middleware chain.
+
+### Fresh + Tailwind Plugin (`plugins/fresh.ts`)
+
+Convenience that combines Tailwind CSS and Deco:
+
+```typescript
+import { plugins } from "deco/plugins/fresh.ts";
+
+export default defineConfig({
+  plugins: plugins({
+    manifest,
+    tailwind: { /* config */ },
+  }),
+});
+```
+
+Returns `[tailwindPlugin(config), decoPlugin(options)]`.
+
+### Styles Plugin (`plugins/styles.ts`)
+
+Injects global CSS into `<head>` via `id="__DECO_GLOBAL_STYLES__"`.
+
+## Client-side Invoke (`clients/`)
+
+### withManifest (`clients/withManifest.ts`)
+
+Creates a typed invoke client for calling server loaders/actions from the browser.
+
+```typescript
+import { proxy } from "@deco/deco/web";
+import type { Manifest } from "./manifest.gen.ts";
+
+const invoke = proxy<Manifest>();
+
+// Single invoke
+const products = await invoke["site/loaders/productList.ts"]({ query: "shoes" });
+
+// Batch invoke
+const [products, categories] = await invoke({
+  "site/loaders/productList.ts": { query: "shoes" },
+  "site/loaders/categories.ts": {},
+});
+```
+
+Internals: `fetchWithProps(key, props)` POSTs to `/live/invoke/${key}`. Supports `text/event-stream` for streaming.
+
+### InvokeAwaiter (`clients/proxy.ts`)
+
+Chainable proxy that builds invoke keys from property access:
+
+```typescript
+const invoke = proxy<Manifest>();
+
+// Equivalent calls:
+invoke["site/loaders/productList.ts"](props);
+invoke.site.loaders["productList.ts"](props);
+```
+
+Uses JavaScript `Proxy` to build the key string from nested property access.
+
+### Stream Reading
+
+```typescript
+import { readFromStream } from "@deco/deco/web";
+
+const response = await invoke.streaming["site/loaders/feed.ts"]({});
+for await (const chunk of readFromStream(response)) {
+  console.log(chunk);
+}
+```
+
+### FormData Utils (`clients/formdata.ts`)
+
+Converts between objects and FormData:
+
+```typescript
+const formData = propsToFormData({ name: "John", address: { city: "SP" } });
+// name=John, address.city=SP
+
+const props = formDataToProps(formData);
+// { name: "John", address: { city: "SP" } }
+```
+
+## Usage in Sites
+
+### runtime.ts Pattern
+
+Every Deco site has a `runtime.ts`:
+
+```typescript
+import { proxy } from "@deco/deco/web";
+import type { Manifest } from "./manifest.gen.ts";
+import type { Manifest as VTEXManifest } from "apps/vtex/manifest.gen.ts";
+
+export const invoke = proxy<Manifest & VTEXManifest>();
+```
+
+Merges site + VTEX manifests for typed invocation.
+
+### Client Usage
+
+```typescript
+import { invoke } from "../runtime.ts";
+
+const products = await invoke.vtex.loaders.intelligentSearch.productListingPage({
+  query: "shoes",
+  page: 0,
+  count: 12,
+});
+```
+
+The invoke proxy builds the key from the property chain, POSTs to `/live/invoke/{key}`, and returns parsed JSON.

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

@@ -0,0 +1,116 @@
+# Runtime (`runtime/`)
+
+The runtime handles HTTP requests, routing, rendering, and the invoke API. Built on Hono with Fresh or HTMX rendering.
+
+## Entry Point: Deco class (`runtime/mod.ts`)
+
+```typescript
+class Deco {
+  constructor(options: DecoOptions);
+  handler(): Deno.ServeHandler;
+  render(params): Promise<string>;
+  meta(): { schema, manifest };
+  styles(): string;
+  dispose(): void;
+}
+```
+
+## Request Flow (`runtime/handler.tsx`)
+
+```
+Hono App
+  |-- Middleware: bindings     (sets RENDER_FN, GLOBALS)
+  |-- Middleware: liveness     (/deco/_liveness probes)
+  |-- Middleware: statebuilder (prepareState, debug, echo)
+  |-- Middleware: observability (OpenTelemetry trace/span)
+  |-- Middleware: main         (CORS, Cache-Control, segment)
+  |
+  |-- GET /styles.css           -> tailwind CSS
+  |-- GET /live/_meta            -> schema + manifest
+  |-- GET /deco/meta             -> alias for _meta
+  |-- ALL /live/release          -> release info
+  |-- ALL /.decofile/reload      -> trigger state reload
+  |-- GET /live/inspect/:block   -> block inspector
+  |-- POST /live/invoke          -> batch invoke
+  |-- ALL /live/invoke/*         -> single invoke by key
+  |-- ALL /live/previews         -> preview index
+  |-- ALL /live/previews/*       -> block preview
+  |-- POST /deco/render          -> partial section render
+  |-- ALL /live/workflows/run    -> trigger workflow
+  |-- ALL * (catch-all)          -> page handler (entrypoint)
+```
+
+## Middleware Chain
+
+### 1. Bindings
+Sets `RENDER_FN` (framework render function) and `GLOBALS` (error handler, dev flag).
+
+### 2. Liveness (`runtime/middlewares/liveness.ts`)
+Health probe at `/deco/_liveness` returning memory, uptime, requestCount, requestInflight.
+
+### 3. State Builder
+Creates resolve/invoke functions scoped to the request. Sets `state.deco` with DecoRuntimeState.
+
+### 4. Observability
+OpenTelemetry spans per request with `http.method`, `http.url`, `http.status_code`, `deco.site` attributes.
+
+### 5. Main
+CORS headers, Cache-Control, segment cookie handling, custom response headers from flags.
+
+## Key Routes
+
+### Invoke (`/live/invoke/*`)
+Single-key invocation: `POST /live/invoke/site/loaders/productList.ts` with JSON body.
+
+### Batch Invoke (`/live/invoke`)
+Multiple invocations in one request with a multi-key JSON body.
+
+### Render (`/deco/render`)
+Partial section rendering used by `useSection` hook. Receives `props`, `href`, `pathTemplate`, `resolveChain`.
+
+### Entrypoint (`*` catch-all)
+1. Resolves `./routes/[...catchall].tsx` via `state.resolve`
+2. Handler processes request
+3. Calls `ctx.render(PageData)` for HTML output
+
+## Rendering
+
+### PageData
+Contains `page` (resolved sections), `routerInfo` (URL, params), `loadingMode`.
+
+### Section Rendering
+Each section gets: SectionContext, ErrorBoundary, `withSection` HOC, framework-specific partial support.
+
+## Frameworks
+
+| Framework | Islands | Partials | Usage |
+|-----------|---------|----------|-------|
+| Fresh | Preact islands | `<Partial>` + `f-partial` | Standard Deco sites |
+| HTMX | None (no JS) | `hx-get/hx-swap` | Lightweight alternative |
+
+### Fresh (`runtime/fresh/`)
+- `plugin.ts` / `plugin.tsx` for Fresh plugin registration
+- `Bindings.tsx` provides `<Partial>`, `<Head>`
+- `islands/DispatchAsyncRender.tsx` for lazy section loading via IntersectionObserver
+
+### HTMX (`runtime/htmx/`)
+- `Renderer.tsx` uses `renderToString(Preact)` for full server rendering
+- No islands, no client-side hydration
+- Uses `hx-get`, `hx-trigger`, `hx-target`, `hx-swap`
+
+## Caching (`runtime/caches/`)
+
+| Cache | Purpose |
+|-------|---------|
+| `lru.ts` | In-memory LRU (weak references) |
+| `redis.ts` | Redis-backed cache |
+| `tiered.ts` | LRU then Redis then origin |
+| `fileSystem.ts` | Disk-based cache |
+
+## Fetch Instrumentation (`runtime/fetch/`)
+
+| File | Purpose |
+|------|---------|
+| `mod.ts` | Main fetch wrapper with logging + caching |
+| `fetchLog.ts` | Logs fetch calls to OpenTelemetry |
+| `fetchCache.ts` | HTTP cache (respects Cache-Control) |