@statorjs/stator 1.3.0 → 1.4.1

package/src/server/recompute.ts

@@ -3,6 +3,7 @@ import { coerceKeys, renderKeyedItem, renderListBody } from '../template/each.ts
 import type { Patch } from '../wire/index.ts'
 import { isUrlAttribute, safeAttrUrl } from '../wire/safe-url.ts'
 import {
+  type ItemBinding,
   keyedScopePrefix,
   keyToken,
   type RenderState,
@@ -16,6 +17,40 @@ import type { SessionRuntime } from './session-runtime.ts'
  *  shape drops this field. */
 type PendingPatch = { patch: Patch; sourceSlot: string }
 
+/** Diff one row's item-value bindings against its current item, pushing a text-
+ *  or attr-op patch for each changed field — the row itself is never re-rendered.
+ *  Text bindings target their slot, attr bindings their element, mirroring the
+ *  machine text/attr binding patches. Only ever called for live (retained/
+ *  current) rows, so no subsumption concern. */
+function diffItemBindings(
+  pending: PendingPatch[],
+  row: ItemBinding[],
+  item: unknown,
+  index: number,
+): void {
+  for (const ib of row) {
+    const nv = ib.selector(item, index)
+    if (valuesEqual(nv, ib.lastValue)) continue
+    ib.lastValue = nv
+    if (ib.kind === 'text') {
+      pending.push({
+        patch: { target: { kind: 'slot', id: ib.slotId }, op: 'text', value: stringify(nv) },
+        sourceSlot: ib.slotId,
+      })
+    } else {
+      pending.push({
+        patch: {
+          target: { kind: 'element', id: ib.parentId },
+          op: 'attr',
+          name: ib.attrName,
+          value: sanitizeAttrWire(ib.attrName, attrWireValue(nv)),
+        },
+        sourceSlot: ib.parentId,
+      })
+    }
+  }
+}
+
 /**
  * Walk every binding tied to `machineName`, re-evaluate its selector against
  * the current machine snapshot, and produce patches for any binding whose
@@ -34,6 +69,19 @@ export function recompute(
   machineName: string,
   runtime: SessionRuntime,
 ): Patch[] {
+  // Expose the fan-out runtime to nested `read()`s so an arm/list body that
+  // re-renders this pass resolves the CURRENT proxy, not its frozen closure
+  // instance (FINDINGS #3). Restored after so nothing leaks across passes.
+  const prevRuntime = state.currentRuntime
+  state.currentRuntime = runtime
+  try {
+    return recomputeInner(state, machineName, runtime)
+  } finally {
+    state.currentRuntime = prevRuntime
+  }
+}
+
+function recomputeInner(state: RenderState, machineName: string, runtime: SessionRuntime): Patch[] {
   const proxy = runtime.proxyFor(machineName)
   if (!proxy) return []
 
@@ -78,28 +126,44 @@ export function recompute(
     } else if (binding.kind === 'list') {
       const newArray = newValue as readonly unknown[]
       const oldArray = binding.lastValue as readonly unknown[]
-      if (!arrayShallowEqual(newArray, oldArray)) {
+      const rows = binding.rows
+      // SPIKE (finding #5 / option C): a same-length list with item bindings
+      // diffs each row's item-value bindings and patches only the changed fields
+      // — the row DOM (islands, focus) is preserved, and identity churn (the VM
+      // re-deriving item objects) no longer forces a re-render, because we
+      // compare *values*, not references. Nested read() bindings inside a row
+      // are separate machine bindings and update through the main pass as usual.
+      if (rows && newArray.length === rows.length) {
+        for (let i = 0; i < newArray.length; i++) {
+          diffItemBindings(pending, rows[i]!, newArray[i], i)
+        }
+        binding.lastValue = newArray
+      } else if (!arrayShallowEqual(newArray, oldArray)) {
+        // No item bindings, or the length changed → wholesale re-render (and
+        // refresh binding.rows so a later same-length pass is granular again).
         const fn = binding.itemRenderer
-        const newInner = runInRender(state, () => renderListBody(state, slotId, newArray, fn))
+        const rendered = runInRender(state, () => renderListBody(state, slotId, newArray, fn))
         pending.push({
           patch: {
             target: { kind: 'slot', id: slotId },
             op: 'html',
-            value: newInner,
+            value: rendered.html,
           },
           sourceSlot: slotId,
         })
         binding.lastValue = newArray
+        binding.rows = rendered.rows.some((r) => r.length > 0) ? rendered.rows : undefined
       }
     } else if (binding.kind === 'list-keyed') {
       // Keyed diff: shape changes become per-item insert/remove/move ops from
       // a replay simulation (`work` mirrors what the client's DOM will look
-      // like after each emitted op — see the wire contract). Content inside
-      // retained items updates through the items' own nested bindings; the
-      // keyed path never re-renders a retained row.
+      // like after each emitted op — see the wire contract). Retained rows keep
+      // their DOM; their content updates through nested read()s and — option C —
+      // per-row itemBind item-value bindings (diffed after the shape pass).
       const newArray = newValue as readonly unknown[]
       const newKeys = coerceKeys(newArray, binding.keyFn, slotId)
       const oldKeys = binding.lastKeys
+      const rowsByKey = binding.rowsByKey
       if (!stringArraysEqual(newKeys, oldKeys)) {
         const target = { kind: 'slot', id: slotId } as const
         const newKeySet = new Set(newKeys)
@@ -112,6 +176,7 @@ export function recompute(
           const scope = keyedScopePrefix(slotId, keyToken(key))
           removedScopes.push(`${scope}:`)
           unregisterBindingsForScope(state, scope)
+          rowsByKey?.delete(key)
           work.splice(i, 1)
         }
         // Settle each position left-to-right: an existing key moves up, a new
@@ -125,11 +190,12 @@ export function recompute(
             work.splice(from, 1)
             work.splice(i, 0, key)
           } else {
-            const itemHtml = runInRender(state, () =>
+            const row = runInRender(state, () =>
               renderKeyedItem(state, slotId, newArray[i], i, key, binding.itemRenderer),
             )
+            rowsByKey?.set(key, row.bindings)
             pending.push({
-              patch: { target, op: 'insert', index: i, value: itemHtml },
+              patch: { target, op: 'insert', index: i, value: row.html },
               sourceSlot: slotId,
             })
             work.splice(i, 0, key)
@@ -137,6 +203,20 @@ export function recompute(
         }
         binding.lastKeys = newKeys
       }
+      // Option C (keyed): retained rows re-evaluate their item-value bindings, so
+      // a content change patches the changed field in place — no re-render, no
+      // reliance on the row carrying a nested read(). Rows inserted this pass are
+      // already current (rendered above); removed rows are gone.
+      if (rowsByKey) {
+        const oldKeySet = new Set(oldKeys)
+        for (let i = 0; i < newKeys.length; i++) {
+          const key = newKeys[i]!
+          if (!oldKeySet.has(key)) continue
+          const row = rowsByKey.get(key)
+          if (!row) continue
+          diffItemBindings(pending, row, newArray[i], i)
+        }
+      }
       binding.lastValue = newArray
     } else if (binding.kind === 'branch') {
       const newKey = binding.branchKeyFn(newValue)
@@ -253,12 +333,19 @@ export function initialSyncPatches(state: RenderState, runtime: SessionRuntime):
     for (const key of keys) {
       unregisterBindingsForScope(state, keyedScopePrefix(slotId, keyToken(key)))
     }
+    // Rebuild rowsByKey alongside the HTML — the re-render replaces every row's
+    // slot registrations, so the old item-bindings are stale.
+    const rebuilt: typeof binding.rowsByKey = binding.rowsByKey ? new Map() : undefined
     let rowsHtml = ''
     for (let i = 0; i < items.length; i++) {
-      rowsHtml += runInRender(state, () =>
-        renderKeyedItem(state, slotId, items[i], i, keys[i]!, binding.itemRenderer),
+      const key = keys[i]!
+      const row = runInRender(state, () =>
+        renderKeyedItem(state, slotId, items[i], i, key, binding.itemRenderer),
       )
+      rowsHtml += row.html
+      rebuilt?.set(key, row.bindings)
     }
+    if (rebuilt) binding.rowsByKey = rebuilt
     patches.push({ target: { kind: 'slot', id: slotId }, op: 'html', value: rowsHtml })
   }
 

package/src/server/render-context.ts

@@ -1,3 +1,4 @@
+import type { Resource } from '../template/resource.ts'
 import type { HtmlFragment } from '../template/types.ts'
 
 export type SlotId = string
@@ -38,8 +39,34 @@ export interface ListBinding extends BindingBase {
   kind: 'list'
   /** Re-invoked per item when the list re-renders. */
   itemRenderer: ErasedItemRenderer
+  /** SPIKE (finding #5 / option C): per-row item-value bindings, collected at
+   *  render. On recompute a *same-length* list re-evaluates these instead of
+   *  re-rendering the whole body — a content change patches the changed field
+   *  only, and the row DOM (islands, focus) is preserved. `undefined` on lists
+   *  with no itemBind() interpolations (they fall back to wholesale re-render). */
+  rows?: ItemBinding[][]
 }
 
+/** A per-row binding whose source is the each *item value*, not a machine
+ *  (`read(item, …)` → itemBind). Never registered in `state.bindings`/`byMachine`
+ *  — owned by its ListBinding and re-evaluated during the list's recompute.
+ *  Discriminated by position, mirroring text vs attr machine bindings. */
+interface ItemBindingBase {
+  /** `(item, index) => value` — evaluated against the row's current item. */
+  selector: (item: unknown, index: number) => unknown
+  lastValue: unknown
+}
+export interface TextItemBinding extends ItemBindingBase {
+  kind: 'text'
+  slotId: SlotId
+}
+export interface AttrItemBinding extends ItemBindingBase {
+  kind: 'attr'
+  attrName: string
+  parentId: ElementId
+}
+export type ItemBinding = TextItemBinding | AttrItemBinding
+
 /** A keyed list's key selector, item type erased (same variance argument as
  *  ErasedSelector). */
 // biome-ignore lint/suspicious/noExplicitAny: contravariant parameter — see ErasedSelector
@@ -53,6 +80,11 @@ export interface KeyedListBinding extends BindingBase {
   keyFn: ErasedKeyFn
   /** The previous render's keys, in order — the diff baseline. */
   lastKeys: string[]
+  /** SPIKE (option C, keyed): per-row item-value bindings keyed by identity key
+   *  — stable across moves (a row's slot ids live under its key scope). On
+   *  recompute, retained keys re-evaluate these for field-level patches instead
+   *  of relying on nested read()s. `undefined` when the rows have no itemBind(). */
+  rowsByKey?: Map<string, ItemBinding[]>
 }
 
 export interface BranchBinding extends BindingBase {
@@ -73,9 +105,37 @@ export interface BranchBinding extends BindingBase {
  *  recompute narrows on the discriminant instead of asserting optionals. */
 export type Binding = TextBinding | AttrBinding | ListBinding | KeyedListBinding | BranchBinding
 
+/**
+ * A `defer` slot recorded during the sync render pass, resolved and filled in
+ * the async resolve phase (see server/render.ts). Deliberately NOT a `Binding`
+ * — it never enters `byMachine`, so `recompute` provably never revisits it: the
+ * slot is static/one-shot, which is what keeps `defer` I/O off the session lock.
+ */
+export interface DeferRecord {
+  slotId: SlotId
+  resource: Resource
+  /** Rendered with the resolved value when the resource fulfills. */
+  ready: (value: unknown) => HtmlFragment
+  /** Rendered with the reason when the resource rejects; absent ⇒ the rejection
+   *  bubbles to route-level error handling. */
+  error?: (reason: unknown) => HtmlFragment
+}
+
 interface Scope {
   prefix: string
   counter: number
+  /** Per-scope element-id counter. Element ids are scoped by the arm/list they
+   *  render in — exactly like slot ids — so a node inside a `match`/`when`/`each`
+   *  keeps a STABLE id across a re-render. (A flat global counter shifted the id
+   *  whenever the element-id'd sibling set changed, so the live wire patched the
+   *  wrong node — FINDINGS #2.) */
+  elementCounter: number
+}
+
+/** A fresh child scope: slot and element counters both start at 0, so ids inside
+ *  are deterministic from the scope prefix regardless of surrounding renders. */
+export function makeScope(prefix: string): Scope {
+  return { prefix, counter: 0, elementCounter: 0 }
 }
 
 export interface RenderState {
@@ -84,7 +144,30 @@ export interface RenderState {
   bindings: Map<SlotId, Binding>
   byMachine: Map<MachineName, Set<SlotId>>
   scopeStack: Scope[]
-  elementIdCounter: number
+  /** `defer` slots recorded during the sync pass, drained by the resolve phase. */
+  deferred: DeferRecord[]
+  /** >0 while rendering inside a `defer` arm — machine bindings are illegal there
+   *  (a defer slot is never re-diffed), so `registerBinding` throws. */
+  deferDepth: number
+  /** Whether this render should resolve `defer` slots. True on the read paths
+   *  (GET, SSE-connect — off-lock); false for the `/__events` re-diff baseline,
+   *  which runs UNDER the session lock and must never kick a defer thunk. */
+  resolveDeferred: boolean
+  /** Set only during a recompute-driven re-render (fan-out): nested `read()`s
+   *  resolve their proxy from THIS runtime by machine name, instead of the
+   *  closure-captured instance — which fan-out `rehydrate()` froze at
+   *  connect-time, so an arm/list interior would otherwise render stale on the
+   *  first data arrival (FINDINGS #3). Null on the initial render, where the
+   *  closure instance already IS the current proxy. */
+  currentRuntime: { proxyFor(name: string): unknown } | null
+  /** SPIKE (option C): the each row currently rendering. `itemBind()` reads
+   *  `currentItem`/`currentItemIndex` to evaluate its selector, and pushes its
+   *  binding into `currentRowBindings` (the row collector the list attaches to
+   *  its ListBinding.rows). All three are ambient like the render state itself,
+   *  saved/restored around each row. */
+  currentItem?: unknown
+  currentItemIndex?: number
+  currentRowBindings?: ItemBinding[]
 }
 
 export function createRenderState(sessionId: SessionId, routeKey: string): RenderState {
@@ -93,8 +176,11 @@ export function createRenderState(sessionId: SessionId, routeKey: string): Rende
     routeKey,
     bindings: new Map(),
     byMachine: new Map(),
-    scopeStack: [{ prefix: '', counter: 0 }],
-    elementIdCounter: 0,
+    scopeStack: [makeScope('')],
+    deferred: [],
+    deferDepth: 0,
+    resolveDeferred: true,
+    currentRuntime: null,
   }
 }
 
@@ -134,11 +220,12 @@ export function allocSlotId(state: RenderState): SlotId {
 }
 
 export function allocElementId(state: RenderState): ElementId {
-  return `e${state.elementIdCounter++}`
+  const scope = topScope(state)
+  return `${scope.prefix ? `${scope.prefix}:` : ''}e${scope.elementCounter++}`
 }
 
 export function pushListScope(state: RenderState, listSlotId: SlotId, iterIndex: number): void {
-  state.scopeStack.push({ prefix: `${listSlotId}:i${iterIndex}`, counter: 0 })
+  state.scopeStack.push(makeScope(`${listSlotId}:i${iterIndex}`))
 }
 
 /**
@@ -148,7 +235,7 @@ export function pushListScope(state: RenderState, listSlotId: SlotId, iterIndex:
  * primitive keyed `each` is built on.
  */
 export function pushKeyedScope(state: RenderState, listSlotId: SlotId, token: string): void {
-  state.scopeStack.push({ prefix: `${listSlotId}:k${token}`, counter: 0 })
+  state.scopeStack.push(makeScope(`${listSlotId}:k${token}`))
 }
 
 /** Keyed scope prefix for a key token (shared by render and recompute). */
@@ -173,7 +260,37 @@ export function popListScope(state: RenderState): void {
   state.scopeStack.pop()
 }
 
+/**
+ * Enter a `defer` arm's render scope (used by the resolve phase when it renders
+ * the resolved arm). Scopes descendant slot ids under `${slotId}:d` — like a
+ * branch arm — and raises `deferDepth` so machine reads inside the arm throw.
+ */
+export function pushDeferScope(state: RenderState, slotId: SlotId): void {
+  state.scopeStack.push(makeScope(`${slotId}:d`))
+  state.deferDepth += 1
+}
+
+export function popDeferScope(state: RenderState): void {
+  if (state.scopeStack.length <= 1) {
+    throw new Error('stator: cannot pop root render scope')
+  }
+  state.scopeStack.pop()
+  state.deferDepth -= 1
+}
+
 export function registerBinding(state: RenderState, binding: Binding): void {
+  // Runtime backstop for the defer/machine boundary (the static compile check is
+  // the primary, build-time gate). A machine read — read(), or a machine-bound
+  // each/when/match — inside a defer arm would need live re-diffing, but a defer
+  // slot is one-shot and never revisited. Catch it (direct or reached through a
+  // helper) rather than silently freeze the value.
+  if (state.deferDepth > 0) {
+    throw new Error(
+      `stator: a machine read (read() / a machine-bound each/when/match) cannot appear inside a ` +
+        `defer() arm — defer is one-shot and static, so the value would never update. For a live ` +
+        `value, use a machine and place the read in a sibling slot outside the defer.`,
+    )
+  }
   state.bindings.set(binding.slotId, binding)
   let slotIds = state.byMachine.get(binding.machineName)
   if (!slotIds) {

package/src/server/render.ts

@@ -1,4 +1,13 @@
-import { createRenderState, type RenderState, runInRender } from './render-context.ts'
+import { deferSentinel } from '../template/defer.ts'
+import { isHtmlFragment } from '../template/types.ts'
+import {
+  createRenderState,
+  type DeferRecord,
+  popDeferScope,
+  pushDeferScope,
+  type RenderState,
+  runInRender,
+} from './render-context.ts'
 import type {
   RouteDefinition,
   RouteRenderContext,
@@ -81,14 +90,23 @@ function createResponseContext(): {
  * returns the rendered HTML; the HTTP layer combines the HTML with the
  * response effects to build the final Response.
  */
-export function renderRoute(
+export interface RenderRouteOptions {
+  /** Resolve `defer` slots (default true). The `/__events` re-diff baseline
+   *  passes false: it runs under the session lock and must not kick defer I/O;
+   *  its defer slots emit inert placeholders that the diff never touches. */
+  resolveDeferred?: boolean
+}
+
+export async function renderRoute(
   route: RouteDefinition,
   routeKey: string,
   sessionId: string,
   runtime: SessionRuntime,
   request: RouteRequest,
-): RenderResult {
+  opts: RenderRouteOptions = {},
+): Promise<RenderResult> {
   const state = createRenderState(sessionId, routeKey)
+  state.resolveDeferred = opts.resolveDeferred ?? true
   const { ctx: responseCtx, effects } = createResponseContext()
   const renderCtx: RouteRenderContext = {
     response: responseCtx,
@@ -107,5 +125,60 @@ export function renderRoute(
     ;(renderCtx as Record<string, unknown>)[def.name] = proxy
   }
   const fragment = runInRender(state, () => route.render(renderCtx, request))
-  return { html: fragment.html, renderState: state, response: effects }
+  let html = fragment.html
+  if (state.resolveDeferred && state.deferred.length > 0) {
+    html = await resolveDeferred(state, html)
+  }
+  return { html, renderState: state, response: effects }
+}
+
+/**
+ * The `defer` resolve phase (v1: blocking-inline, no streaming). Runs after the
+ * synchronous render, so it can `await` without losing `currentRenderState`.
+ *
+ * Drains `state.deferred` in batches: a resolve-window yield lets already-ready
+ * data settle with no added latency, then the batch's resources are awaited in
+ * parallel (bounded by the slowest, not the sum), then each slot's arm is
+ * rendered and spliced into its sentinel. A defer arm may itself contain a
+ * defer, which records during fill — so the loop drains until the page is quiet.
+ */
+async function resolveDeferred(state: RenderState, html: string): Promise<string> {
+  while (state.deferred.length > 0) {
+    const batch = state.deferred
+    state.deferred = []
+    // Macrotask yield: sync values, warm caches, already-resolved promises, and
+    // multi-hop-but-instant chains settle here; real network/disk I/O does not.
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    await Promise.all(batch.map((record) => record.resource.settled))
+    for (const record of batch) {
+      html = html.replace(deferSentinel(record.slotId), fillDeferSlot(state, record))
+    }
+  }
+  return html
+}
+
+/** Render a resolved defer slot's arm, scoped under the slot id (so nested
+ *  static constructs get stable ids and machine reads are rejected). */
+function fillDeferSlot(state: RenderState, record: DeferRecord): string {
+  return runInRender(state, () => {
+    pushDeferScope(state, record.slotId)
+    try {
+      const { resource } = record
+      let fragment: ReturnType<DeferRecord['ready']>
+      if (resource.status === 'fulfilled') {
+        fragment = record.ready(resource.value)
+      } else if (record.error) {
+        fragment = record.error(resource.reason)
+      } else {
+        // No error arm — let the rejection bubble to route-level error handling.
+        throw resource.reason
+      }
+      if (!isHtmlFragment(fragment)) {
+        throw new Error('stator: a defer() ready/error arm must return an html`...` result')
+      }
+      return fragment.html
+    } finally {
+      popDeferScope(state)
+    }
+  })
 }

package/src/template/client-shell.ts

@@ -19,9 +19,32 @@ import { isReadResult, type ReadResult } from './read.ts'
 export function clientShellAttrs(
   props: Record<string, unknown>,
   decl: Record<string, 'number' | 'string' | 'boolean'>,
+  base: Record<string, string | boolean> = {},
 ): string {
-  let out = ''
+  // The component's own root static attributes are the BASE; usage-site props
+  // (below) win on scalar conflict and `class`/`style` concatenate (FINDINGS #4).
+  // Live read() props emit separately since their value changes over the wire.
+  const staticAttrs = new Map<string, string | true>()
+  for (const key in base) {
+    const v = base[key]
+    if (v === false) continue
+    staticAttrs.set(key, v === true ? true : String(v))
+  }
+  const setMerged = (name: string, value: string | true): void => {
+    const prev = staticAttrs.get(name)
+    if (
+      (name === 'class' || name === 'style') &&
+      typeof prev === 'string' &&
+      typeof value === 'string'
+    ) {
+      staticAttrs.set(name, `${prev} ${value}`.trim())
+    } else {
+      staticAttrs.set(name, value)
+    }
+  }
+
   let elementId: string | null = null
+  let liveOut = ''
   for (const key in decl) {
     const v = props[key]
     if (v == null) continue
@@ -35,10 +58,7 @@ export function clientShellAttrs(
             `live island attrs only make sense inside a route render.`,
         )
       }
-      if (!elementId) {
-        elementId = allocElementId(state)
-        out += ` data-stator-id="${elementId}"`
-      }
+      if (!elementId) elementId = allocElementId(state)
       const r = v as ReadResult
       registerBinding(state, {
         slotId: r.slotId,
@@ -51,15 +71,21 @@ export function clientShellAttrs(
       })
       // Same value semantics as template attr bindings (boolean-aware).
       if (r.value === false || r.value === null || r.value === undefined) continue
-      out += r.value === true ? ` ${name}` : ` ${name}="${escapeAttribute(String(r.value))}"`
+      liveOut += r.value === true ? ` ${name}` : ` ${name}="${escapeAttribute(String(r.value))}"`
       continue
     }
 
     if (decl[key] === 'boolean') {
-      if (v) out += ` ${name}`
+      if (v) setMerged(name, true)
     } else {
-      out += ` ${name}="${escapeAttribute(String(v))}"`
+      setMerged(name, String(v))
     }
   }
-  return out
+
+  let out = ''
+  if (elementId) out += ` data-stator-id="${elementId}"`
+  for (const [name, value] of staticAttrs) {
+    out += value === true ? ` ${name}` : ` ${name}="${escapeAttribute(value)}"`
+  }
+  return out + liveOut
 }

package/src/template/conditional.ts

@@ -2,6 +2,7 @@ import {
   allocSlotId,
   type ErasedSelector,
   keyToken,
+  makeScope,
   popListScope,
   type RenderState,
   registerBinding,
@@ -49,7 +50,7 @@ export function renderBranchBody(
 ): string {
   unregisterBindingsForScope(state, slotId)
   if (!renderer) return ''
-  state.scopeStack.push({ prefix: `${slotId}:b${keyToken(String(armKey))}`, counter: 0 })
+  state.scopeStack.push(makeScope(`${slotId}:b${keyToken(String(armKey))}`))
   try {
     const fragment = renderer()
     if (!isHtmlFragment(fragment)) {

package/src/template/defer.ts

@@ -0,0 +1,72 @@
+import { allocSlotId, requireCurrentRenderState, type SlotId } from '../server/render-context.ts'
+import { createResource } from './resource.ts'
+import type { HtmlFragment } from './types.ts'
+
+/**
+ * A deferred async region. Same position-marker shape as `EachResult` /
+ * `BranchResult` — a `data-slot` span the resolve phase fills. Unlike those, it
+ * registers no machine binding, so it is never re-diffed (static, one-shot).
+ */
+export interface DeferResult {
+  readonly __isDeferResult: true
+  readonly html: string
+  readonly slotId: SlotId
+}
+
+export function isDeferResult(v: unknown): v is DeferResult {
+  return (
+    typeof v === 'object' && v !== null && (v as Record<string, unknown>).__isDeferResult === true
+  )
+}
+
+export interface DeferArms<T> {
+  ready: (value: Awaited<T>) => HtmlFragment
+  /** Optional. Absent ⇒ a rejection bubbles to route-level error handling. */
+  error?: (reason: unknown) => HtmlFragment
+}
+
+/** The fill phase replaces this exact token with the rendered arm. An HTML
+ *  comment: invisible if a slot somehow never fills, and uniquely keyed. */
+export function deferSentinel(slotId: SlotId): string {
+  return `<!--defer:${slotId}-->`
+}
+
+function deferPlaceholder(slotId: SlotId, inner: string): DeferResult {
+  // `display: contents` so the wrapper span doesn't disturb the surrounding
+  // element's layout — same rationale as each()/when().
+  const html = `<span data-slot="${slotId}" data-defer="true" style="display:contents">${inner}</span>`
+  return { __isDeferResult: true, html, slotId }
+}
+
+/**
+ * Render an async region without making frontmatter async. `thunk` is kicked
+ * during the synchronous render pass (closing over frontmatter locals); its
+ * result is wrapped in a peekable resource and recorded, and the resolve phase
+ * (server/render.ts) awaits it — in parallel with every other defer on the page
+ * — then renders `ready(value)` / `error(reason)` inline. A synchronous thunk
+ * result fills with no added latency and no placeholder.
+ *
+ * The thunk belongs *inside* `defer` (not a frontmatter const), so the framework
+ * owns the kick: fired once on a cold render, never re-run on the `/__events`
+ * re-diff.
+ */
+export function defer<T>(thunk: () => T | Promise<T>, arms: DeferArms<T>): DeferResult {
+  const state = requireCurrentRenderState()
+  const slotId = allocSlotId(state)
+
+  // `/__events` re-diff baseline (under the session lock): never kick the thunk —
+  // that would run I/O under the lock. The slot is static and never diffed, so an
+  // inert placeholder is correct; the client keeps the content from its first render.
+  if (!state.resolveDeferred) {
+    return deferPlaceholder(slotId, '')
+  }
+
+  const resource = createResource(thunk)
+  state.deferred.push({
+    slotId,
+    resource,
+    ready: arms.ready as (value: unknown) => HtmlFragment,
+    error: arms.error,
+  })
+  return deferPlaceholder(slotId, deferSentinel(slotId))
+}