@statorjs/stator 1.2.2 → 1.4.0

package/src/server/create-app.ts

@@ -52,8 +52,10 @@ export async function createApp(config: CreateAppConfig): Promise<StatorApp> {
     sessionTtlSeconds: config.sessionTtlSeconds,
     appStore: config.appStore,
   })
-  await store.bootAppMachines()
+  // Wire the effect scheduler BEFORE booting: a fresh app machine fires its
+  // initial-state entry effect during boot, and that must have somewhere to go.
   wireAppEffects(store)
+  await store.bootAppMachines()
 
   const routes = await discoverRoutes(routesDir)
   const app = await buildHonoApp({

package/src/server/dev.ts

@@ -135,8 +135,10 @@ export async function createDevApp(config: DevAppConfig): Promise<DevApp> {
       sessionTtlSeconds: config.sessionTtlSeconds,
       appStore: config.appStore,
     })
-    await store.bootAppMachines()
+    // Wire the effect scheduler before booting — a fresh app machine's
+    // initial-state entry effect fires during boot and needs a live scheduler.
     runtime.wireAppEffects(store)
+    await store.bootAppMachines()
   }
   const rebuildRoutes = async (): Promise<void> => {
     routes = await runtime.discoverRoutes(routesDir, loader)

package/src/server/effects.ts

@@ -1,4 +1,4 @@
-import type { AnyMachineDef, EffectInvocation } from '../engine/index.ts'
+import type { AnyMachineDef, EffectInvocation, EventObject } from '../engine/index.ts'
 import { dispatchToApp } from './app-dispatch.ts'
 import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
@@ -95,22 +95,7 @@ async function runSessionEffect(
   if (!completion) return
 
   try {
-    await withSessionLock(sessionId, async () => {
-      const runtime = new SessionRuntime(sessionId, store)
-      try {
-        const def = store.getDef(machineName)
-        if (!def) return // machine graph changed under us (dev reload) — drop
-        // loadGraph pulls reads + subscribers transitively, so completion
-        // emits reach cross-machine listeners like any other event.
-        await runtime.loadGraph([def])
-        runtime.wireSubscriptions()
-        const touched = runtime.processEvent(machineName, completion)
-        await runtime.persistTouched(touched)
-        await fanOut(touched, { sessionId })
-      } finally {
-        runtime.dispose()
-      }
-    })
+    await reenterSessionEvent(store, sessionId, machineName, completion)
   } catch (err) {
     effectLog.error(
       { machine: machineName, effectId, err: String(err) },
@@ -118,3 +103,37 @@ async function runSessionEffect(
     )
   }
 }
+
+/**
+ * Re-enter an out-of-band event (an effect completion, or an `after` timeout)
+ * through the full session event path: fresh lock, hydrate the machine (the
+ * triggering runtime is long gone — the transient-actor model working for us),
+ * process, persist (including a machine that fired an entry effect on the
+ * resulting transition), fan out to live connections, and schedule any effect
+ * the event chained. Shared by effect completions and state timeouts.
+ */
+export async function reenterSessionEvent(
+  store: MachineStore,
+  sessionId: string,
+  machineName: string,
+  event: EventObject,
+): Promise<void> {
+  await withSessionLock(sessionId, async () => {
+    const runtime = new SessionRuntime(sessionId, store)
+    try {
+      const def = store.getDef(machineName)
+      if (!def) return // machine graph changed under us (dev reload) — drop
+      // loadGraph pulls reads + subscribers transitively, so emits reach
+      // cross-machine listeners like any other event.
+      await runtime.loadGraph([def])
+      runtime.wireSubscriptions()
+      const touched = runtime.processEvent(machineName, event)
+      await runtime.persistTouched(new Set([...touched, ...runtime.entryFiredMachines()]))
+      await fanOut(touched, { sessionId })
+      // A transition or entry effect chained off this event surfaces here.
+      scheduleSessionEffects(runtime, store, sessionId)
+    } finally {
+      runtime.dispose()
+    }
+  })
+}

package/src/server/http.ts

@@ -222,7 +222,7 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
     return streamSSE(c, async (stream) => {
       const runtime = new SessionRuntime(sessionId, config.store)
       await runtime.loadGraph(route.reads)
-      const { renderState } = renderRoute(route, routeKey, sessionId, runtime, request)
+      const { renderState } = await renderRoute(route, routeKey, sessionId, runtime, request)
       const conn = registerConnection({
         sessionId,
         clientId: c.req.query('client'),
@@ -320,7 +320,11 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
         await runtime.loadGraph([...route.reads, originDef])
         runtime.wireSubscriptions()
 
-        const { renderState } = renderRoute(route, routeKey, sessionId, runtime, request)
+        // Baseline render for the diff runs UNDER the session lock — never
+        // resolve defer slots here (that would kick their I/O under the lock).
+        const { renderState } = await renderRoute(route, routeKey, sessionId, runtime, request, {
+          resolveDeferred: false,
+        })
 
         const touched = runtime.processEvent(body.machine, body.event)
 
@@ -333,7 +337,10 @@ export async function buildHonoApp(config: HttpConfig): Promise<Hono> {
           patches.push(...recompute(renderState, name, runtime))
         }
 
-        await runtime.persistTouched(touched)
+        // Persist committed machines plus any fresh machine that fired its
+        // initial entry effect (an entry commits no transition, so it's not in
+        // `touched`) — so it isn't re-created and re-fired next request.
+        await runtime.persistTouched(new Set([...touched, ...runtime.entryFiredMachines()]))
 
         await fanOut(touched, {
           sessionId,
@@ -414,6 +421,9 @@ async function bundleInspector(): Promise<string> {
     target: 'es2020',
     write: false,
     minify: false,
+    // The inspector imports its CSS as a text string (bundled inline, no
+    // separate stylesheet request).
+    loader: { '.css': 'text' },
     logLevel: 'silent',
   })
   cachedInspectorJs = result.outputFiles[0]!.text
@@ -454,7 +464,7 @@ async function handleGet(
     const runtime = new SessionRuntime(sessionId, store)
     try {
       await runtime.loadGraph(route.reads)
-      const result = renderRoute(route, routeKey, sessionId, runtime, request)
+      const result = await renderRoute(route, routeKey, sessionId, runtime, request)
       let html = result.html
 
       const headHtml: string[] = []
@@ -479,6 +489,17 @@ async function handleGet(
         bodyEnd: bodyHtml.join(''),
       })
       applyRenderedEffects(c, result.response)
+
+      // A fresh machine that fired its initial entry effect on load must be
+      // persisted (so the next request hydrates instead of re-firing) and its
+      // effect scheduled off-lock, after the response. The common GET (no entry
+      // effect) skips both and stays a pure read.
+      const entryFired = runtime.entryFiredMachines()
+      if (entryFired.size > 0) {
+        await runtime.persistTouched(entryFired)
+        scheduleSessionEffects(runtime, store, sessionId)
+      }
+
       return c.html(html)
     } finally {
       runtime.dispose()

package/src/server/machine-store.ts

@@ -6,6 +6,7 @@ import { createInstanceProxy, type InstanceHandle } from './instance-proxy.ts'
 import { scopedLogger } from './logger.ts'
 import { serverReadsResolver } from './reads-helpers.ts'
 import type { Store } from './store.ts'
+import { APP_SCOPE, armAfterTimers, cancelAfterTimers } from './timers.ts'
 
 const storeLog = scopedLogger('machine-store')
 
@@ -259,6 +260,12 @@ export class MachineStore {
                 'app-machine effect dropped — no scheduler wired (call wireAppEffects(store))',
               )
           },
+          // `after` state timeouts, at app scope: arm on entry, cancel on exit.
+          // Timers live in the process-wide registry (server/timers.ts) and fire
+          // through dispatchToApp — no session, wall-clock only (revalidation,
+          // circuit breakers). See armAfterTimers.
+          onStateEnter: (stateKey, ctx) => armAfterTimers(this, APP_SCOPE, def, stateKey, ctx),
+          onStateExit: (stateKey) => cancelAfterTimers(APP_SCOPE, def.name, stateKey),
         }).start()
         this.appInstances.set(
           def.name,

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)
+    }
+  })
 }