@statorjs/stator 1.2.2 → 1.4.0

package/src/server/session-runtime.ts

@@ -4,6 +4,7 @@ import { type DispatchContext, recordTouch, withDispatchContext } from './dispat
 import { createInstanceProxy, type InstanceHandle } from './instance-proxy.ts'
 import { buildDispatchEvent, MAX_CASCADE_DEPTH, type MachineStore } from './machine-store.ts'
 import { serverReadsResolver } from './reads-helpers.ts'
+import { armAfterTimers, cancelAfterTimers } from './timers.ts'
 
 /**
  * Per-request scope for session-lifecycle machine actors. Created at the
@@ -67,6 +68,11 @@ export class SessionRuntime {
       // Server plane: never run effects inline — queue them for the entry
       // point to schedule after persist + lock release.
       onEffect: (invocation) => this.pendingEffects.push(invocation),
+      // `after` state timeouts: arm on entry, cancel on exit. Timers live in the
+      // process-wide registry (server/timers.ts), not this transient runtime.
+      onStateEnter: (stateKey, ctx) =>
+        armAfterTimers(this.store, this.sessionId, def, stateKey, ctx),
+      onStateExit: (stateKey) => cancelAfterTimers(this.sessionId, def.name, stateKey),
     }).start()
     this.actors.set(
       def.name,
@@ -104,6 +110,14 @@ export class SessionRuntime {
     return this.store.getDef(name)?.lifecycle
   }
 
+  /** Machines whose entry effect fired on a fresh `start()` — queued in
+   *  `pendingEffects` but distinct from `touched` (an entry commits no
+   *  transition). Entry points persist this set so a freshly-entered state
+   *  isn't re-created and re-fired next request. Read before draining. */
+  entryFiredMachines(): Set<string> {
+    return new Set(this.pendingEffects.map((e) => e.machineName))
+  }
+
   /** Hand queued effect invocations to the scheduler, clearing the queue. */
   drainPendingEffects(): EffectInvocation[] {
     const drained = this.pendingEffects

package/src/server/timers.ts

@@ -0,0 +1,77 @@
+import type { AnyMachineDef } from '../engine/index.ts'
+import { dispatchToApp } from './app-dispatch.ts'
+import { reenterSessionEvent } from './effects.ts'
+import { scopedLogger } from './logger.ts'
+import type { MachineStore } from './machine-store.ts'
+
+const timerLog = scopedLogger('timers')
+
+/** Timer scope for app machines. They're process singletons (one instance per
+ *  name), so they share one scope and the machine name disambiguates the key —
+ *  unlike session machines, which scope by session id. */
+export const APP_SCOPE = '@app'
+
+/**
+ * Process-wide, in-memory, NON-DURABLE registry for `after` state timeouts.
+ * Session runtimes are transient (per request) and app instances live for the
+ * process, so a timer can't live on either — it lives here, keyed by the state
+ * it's counting down for, and fires across (or between) requests. A process
+ * restart drops armed timers (the 1.0 non-durable contract, same as effects).
+ */
+const timers = new Map<string, ReturnType<typeof setTimeout>[]>()
+
+const key = (scope: string, machineName: string, stateKey: string): string =>
+  `${scope} ${machineName} ${stateKey}`
+
+/** Cancel every `after` timer armed for a (scope, machine, state). `scope` is
+ *  the session id for session machines, `APP_SCOPE` for app machines. */
+export function cancelAfterTimers(scope: string, machineName: string, stateKey: string): void {
+  const k = key(scope, machineName, stateKey)
+  const handles = timers.get(k)
+  if (!handles) return
+  for (const h of handles) clearTimeout(h)
+  timers.delete(k)
+}
+
+/**
+ * Arm the `after` timers declared on `stateKey` (a no-op if it declares none).
+ * The host calls this when a machine ENTERS the state. Each timer, on elapse,
+ * dispatches its `send` event back through the machine's normal event path —
+ * a session machine through the session re-entry (fresh lock + hydrate), an app
+ * machine through `dispatchToApp` (no lock; the long-lived instance is sent
+ * directly). Either way it's guard-dropped if the state has since moved on (the
+ * cancel-on-exit is the fast path; the guard-drop is the correctness backstop).
+ * Re-arming clears any stale timers for the key first.
+ */
+export function armAfterTimers(
+  store: MachineStore,
+  scope: string,
+  def: AnyMachineDef,
+  stateKey: string,
+  ctx: object,
+): void {
+  const after = def.states[stateKey]?.after
+  if (!after || after.length === 0) return
+  cancelAfterTimers(scope, def.name, stateKey)
+  const k = key(scope, def.name, stateKey)
+  const handles = after.map((entry) => {
+    const delay = typeof entry.delay === 'function' ? entry.delay(ctx as never) : entry.delay
+    const h = setTimeout(() => {
+      timers.delete(k) // a state has one arm-set; drop the whole key on fire
+      const fire =
+        def.lifecycle === 'app'
+          ? dispatchToApp(store, def, entry.send as never).then(() => {})
+          : reenterSessionEvent(store, scope, def.name, entry.send)
+      void fire.catch((err) => {
+        timerLog.error(
+          { scope, machine: def.name, state: stateKey, err: String(err) },
+          'after-timer dispatch failed',
+        )
+      })
+    }, delay)
+    // Don't keep the process alive for a pending timer.
+    ;(h as unknown as { unref?: () => void }).unref?.()
+    return h
+  })
+  timers.set(k, handles)
+}

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

package/src/template/directives/list-attr.ts

@@ -4,6 +4,7 @@ import {
   registerBinding,
   requireCurrentRenderState,
 } from '../../server/render-context.ts'
+import { isItemReadResult } from '../each.ts'
 import { isReadResult, type ReadResult } from '../read.ts'
 import { type DirectiveInvocation, defineDirective, invoke } from './core.ts'
 
@@ -44,7 +45,21 @@ function evalRead<T>(value: ConditionalEntry<T>): T {
   return isReadResult(value) ? (value.selector(value.instance) as T) : value
 }
 
+/** Backstop for hand-written templates (the compiler rejects this at build
+ *  time): an item read inside a `:list` spec would stringify as garbage AND
+ *  never re-diff — the compound directive recomposes per machine, not per row. */
+function rejectItemRead(v: unknown): void {
+  if (isItemReadResult(v)) {
+    throw new Error(
+      'stator: read(item, …) is not supported inside a class:list/style:list spec — the ' +
+        'compound directive recomposes per machine, not per row. Give the whole attribute ' +
+        'a single item read, or use a machine read inside the spec.',
+    )
+  }
+}
+
 function collectMachines(spec: unknown, out: Set<string>): void {
+  rejectItemRead(spec)
   if (spec == null || spec === false) return
   if (typeof spec === 'string') return
   if (isReadResult(spec)) {
@@ -57,6 +72,7 @@ function collectMachines(spec: unknown, out: Set<string>): void {
   }
   if (typeof spec === 'object') {
     for (const v of Object.values(spec)) {
+      rejectItemRead(v)
       if (isReadResult(v)) out.add(v.machineName)
     }
   }

package/src/template/each.ts

@@ -3,6 +3,7 @@ import {
   type ErasedItemRenderer,
   type ErasedKeyFn,
   type ErasedSelector,
+  type ItemBinding,
   keyedScopePrefix,
   keyToken,
   popListScope,
@@ -37,6 +38,42 @@ export function isEachResult(v: unknown): v is EachResult {
   )
 }
 
+/**
+ * SPIKE (finding #5 / option C): the value of an item-dependent interpolation
+ * inside an `each` row — what the compiler will lower `{item.field}` to. It
+ * evaluates the selector against the *current* row's item now, and registers a
+ * per-row binding so a later content change patches this one slot in place
+ * (rather than re-rendering the row, so islands/focus survive).
+ */
+export interface ItemReadResult {
+  readonly __isItemRead: true
+  readonly selector: (item: unknown, index: number) => unknown
+  readonly value: unknown
+}
+
+export function isItemReadResult(v: unknown): v is ItemReadResult {
+  return typeof v === 'object' && v !== null && (v as Record<string, unknown>).__isItemRead === true
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: erased item selector — the item type is the each callback's, recovered at the call site
+export function itemBind(selector: (item: any, index: number) => unknown): ItemReadResult {
+  const state = requireCurrentRenderState()
+  if (!state.currentRowBindings) {
+    throw new Error(
+      'stator: read(item, …) (itemBind) called outside an each() row render — an item ' +
+        'binding is owned by its row, which supplies the item and re-diffs the binding. ' +
+        'This happens when an item read sits inside a when()/match()/defer() arm (an arm ' +
+        're-renders on its own schedule, without the row) or outside each() entirely. ' +
+        'Use a machine read there instead.',
+    )
+  }
+  // Compute the value now (for initial render); the per-row binding is registered
+  // by html.ts, which knows the position (text span vs attribute) — same split as
+  // read() → handleRead.
+  const value = selector(state.currentItem, state.currentItemIndex ?? 0)
+  return { __isItemRead: true, selector, value }
+}
+
 export function each<T>(
   items: readonly T[] | ReadResult<readonly T[]>,
   fn: (item: T, index: number) => HtmlFragment,
@@ -63,8 +100,10 @@ export function each<T>(
   let innerHtml: string
   if (keyFn) {
     const keys = coerceKeys(array, keyFn as ErasedKeyFn, slotId)
-    innerHtml = renderKeyedListBody(state, slotId, array, keys, fn)
+    const body = renderKeyedListBody(state, slotId, array, keys, fn)
+    innerHtml = body.html
     if (machineName && selector) {
+      const hasItemBindings = [...body.rowsByKey.values()].some((b) => b.length > 0)
       registerBinding(state, {
         slotId,
         machineName,
@@ -74,10 +113,13 @@ export function each<T>(
         itemRenderer: fn as ErasedItemRenderer,
         keyFn: keyFn as ErasedKeyFn,
         lastKeys: keys,
+        // Same opt-in as non-keyed: only track rows when there ARE item bindings.
+        rowsByKey: hasItemBindings ? body.rowsByKey : undefined,
       })
     }
   } else {
-    innerHtml = renderListBody(state, slotId, array, fn)
+    const body = renderListBody(state, slotId, array, fn)
+    innerHtml = body.html
     if (machineName && selector) {
       registerBinding(state, {
         slotId,
@@ -86,6 +128,10 @@ export function each<T>(
         lastValue: array,
         kind: 'list',
         itemRenderer: fn as ErasedItemRenderer,
+        // Only opt into the granular path when there ARE item bindings —
+        // otherwise (static-capture rows) leave it undefined so recompute
+        // wholesale-re-renders as before, keeping content fresh.
+        rows: body.rows.some((r) => r.length > 0) ? body.rows : undefined,
       })
     }
   }
@@ -111,23 +157,39 @@ export function renderListBody<T>(
   listSlotId: SlotId,
   items: readonly T[],
   fn: (item: T, index: number) => HtmlFragment,
-): string {
+): { html: string; rows: ItemBinding[][] } {
   unregisterBindingsForScope(state, listSlotId)
 
+  // Save/restore the ambient row context around the whole body so a nested
+  // each() (a row rendering its own list) doesn't clobber this list's row.
+  const prevItem = state.currentItem
+  const prevIndex = state.currentItemIndex
+  const prevRow = state.currentRowBindings
+
   const chunks: string[] = []
+  const rows: ItemBinding[][] = []
   for (let i = 0; i < items.length; i++) {
     pushListScope(state, listSlotId, i)
+    const rowBindings: ItemBinding[] = []
+    state.currentItem = items[i]
+    state.currentItemIndex = i
+    state.currentRowBindings = rowBindings
     try {
       const fragment = fn(items[i]!, i)
       if (!isHtmlFragment(fragment)) {
         throw new Error('stator: each() callback must return an html`...` result')
       }
       chunks.push(fragment.html)
+      rows.push(rowBindings)
     } finally {
       popListScope(state)
     }
   }
-  return chunks.join('')
+
+  state.currentItem = prevItem
+  state.currentItemIndex = prevIndex
+  state.currentRowBindings = prevRow
+  return { html: chunks.join(''), rows }
 }
 
 /**
@@ -173,13 +235,17 @@ export function renderKeyedListBody<T>(
   items: readonly T[],
   keys: readonly string[],
   fn: (item: T, index: number) => HtmlFragment,
-): string {
+): { html: string; rowsByKey: Map<string, ItemBinding[]> } {
   unregisterBindingsForScope(state, listSlotId)
   const chunks: string[] = []
+  const rowsByKey = new Map<string, ItemBinding[]>()
   for (let i = 0; i < items.length; i++) {
-    chunks.push(renderKeyedItem(state, listSlotId, items[i] as T, i, keys[i]!, fn))
+    const key = keys[i]!
+    const row = renderKeyedItem(state, listSlotId, items[i] as T, i, key, fn)
+    chunks.push(row.html)
+    rowsByKey.set(key, row.bindings)
   }
-  return chunks.join('')
+  return { html: chunks.join(''), rowsByKey }
 }
 
 /**
@@ -195,10 +261,21 @@ export function renderKeyedItem<T>(
   index: number,
   key: string,
   fn: (item: T, index: number) => HtmlFragment,
-): string {
+): { html: string; bindings: ItemBinding[] } {
   const token = keyToken(key)
   unregisterBindingsForScope(state, keyedScopePrefix(listSlotId, token))
   pushKeyedScope(state, listSlotId, token)
+
+  // Item-value binding context for this row (option C, keyed), save/restore
+  // around the body so a nested each() doesn't clobber it.
+  const prevItem = state.currentItem
+  const prevIndex = state.currentItemIndex
+  const prevRow = state.currentRowBindings
+  const bindings: ItemBinding[] = []
+  state.currentItem = item
+  state.currentItemIndex = index
+  state.currentRowBindings = bindings
+
   let html: string
   try {
     const fragment = fn(item, index)
@@ -207,6 +284,9 @@ export function renderKeyedItem<T>(
     }
     html = fragment.html
   } finally {
+    state.currentItem = prevItem
+    state.currentItemIndex = prevIndex
+    state.currentRowBindings = prevRow
     popListScope(state)
   }
   if (!isSingleRootElement(html)) {
@@ -216,7 +296,7 @@ export function renderKeyedItem<T>(
         `items would corrupt sibling indices`,
     )
   }
-  return html
+  return { html, bindings }
 }
 
 const VOID_TAGS = new Set([

package/src/template/html.ts

@@ -1,4 +1,5 @@
 import {
+  allocSlotId,
   type RenderState,
   registerBinding,
   requireCurrentRenderState,
@@ -22,12 +23,13 @@ export function raw(html: string): HtmlFragment {
 }
 
 import { isBranchResult } from './conditional.ts'
+import { isDeferResult } from './defer.ts'
 import {
   type DirectiveContext,
   type DirectiveInvocation,
   isDirectiveInvocation,
 } from './directives/core.ts'
-import { isEachResult } from './each.ts'
+import { type ItemReadResult, isEachResult, isItemReadResult } from './each.ts'
 import { isReadResult, type ReadResult } from './read.ts'
 
 export function html(strings: TemplateStringsArray, ...values: unknown[]): HtmlFragment {
@@ -100,11 +102,26 @@ function processValue(builder: HtmlBuilder, state: RenderState, value: unknown):
     return
   }
 
+  if (isDeferResult(value)) {
+    if (pos.kind !== 'text') {
+      throw new Error('stator: cannot inline a defer() result outside text position')
+    }
+    builder.pushRaw(value.html)
+    return
+  }
+
   if (isReadResult(value)) {
     handleRead(builder, state, value, pos)
     return
   }
 
+  // read(item, …) → itemBind: register the per-row binding by position (text span
+  // or attribute), the item analog of handleRead.
+  if (isItemReadResult(value)) {
+    handleItemRead(builder, state, value, pos)
+    return
+  }
+
   if (pos.kind === 'text') {
     builder.pushRaw(escapeText(stringifyValue(value)))
     return
@@ -180,6 +197,53 @@ function handleRead(
   throw new Error(`stator: read() result cannot be interpolated at ${pos.kind} position`)
 }
 
+/** Register a `read(item, …)` per-row binding by position — the item analog of
+ *  handleRead. Pushes onto the row's binding list (owned by the ListBinding), not
+ *  state.bindings; recompute diffs it per row and emits text- or attr-op patches. */
+function handleItemRead(
+  builder: HtmlBuilder,
+  state: RenderState,
+  r: ItemReadResult,
+  pos: ValuePosition,
+): void {
+  const row = state.currentRowBindings
+  if (!row) {
+    throw new Error(
+      'stator: read(item, …) interpolated outside an each() row render — an item binding ' +
+        'is owned by its row (see the itemBind ownership rule). Use a machine read here.',
+    )
+  }
+  if (pos.kind === 'text') {
+    const slotId = allocSlotId(state)
+    row.push({ kind: 'text', slotId, selector: r.selector, lastValue: r.value })
+    builder.pushRaw(`<span data-slot="${slotId}">${escapeText(stringifyValue(r.value))}</span>`)
+    return
+  }
+  if (pos.kind === 'attr-value') {
+    if (pos.hasLiteralText) {
+      throw new Error(
+        `stator: attribute "${pos.attrName}" mixes literal text with a read(item, …). ` +
+          `An attribute value must come from a single source.`,
+      )
+    }
+    row.push({
+      kind: 'attr',
+      attrName: pos.attrName,
+      parentId: pos.elementId,
+      selector: r.selector,
+      lastValue: r.value,
+    })
+    // Same boolean semantics as a machine attr read (see handleRead).
+    if (r.value === false || r.value === null || r.value === undefined) {
+      builder.omitCurrentAttribute()
+    } else if (r.value !== true) {
+      builder.pushRaw(escapeAttribute(sanitizeAttrValue(pos.attrName, stringifyValue(r.value))))
+    }
+    return
+  }
+  throw new Error(`stator: read(item, …) cannot be interpolated at ${pos.kind} position`)
+}
+
 function stringifyValue(v: unknown): string {
   if (v == null) return ''
   if (typeof v === 'string') return v

package/src/template/index.ts

@@ -6,6 +6,8 @@ export {
   renderBranchBody,
   when,
 } from './conditional.ts'
+export type { DeferArms, DeferResult } from './defer.ts'
+export { defer, isDeferResult } from './defer.ts'
 export type {
   Directive,
   DirectiveContext,
@@ -21,7 +23,7 @@ export type { ClassListSpec, StyleListSpec } from './directives/list-attr.ts'
 export { classList, styleList } from './directives/list-attr.ts'
 export { on } from './directives/on.ts'
 export type { EachResult } from './each.ts'
-export { each, isEachResult, renderListBody } from './each.ts'
+export { each, isEachResult, itemBind, renderListBody } from './each.ts'
 export { html, raw } from './html.ts'
 export type { ReadResult } from './read.ts'
 export { isReadResult, read } from './read.ts'

package/src/template/read.ts

@@ -29,22 +29,46 @@ export function isReadResult(v: unknown): v is ReadResult {
 export function read<TDef extends AnyMachineDef, TResult>(
   instance: InstanceOf<TDef>,
   selector: (instance: InstanceOf<TDef>) => TResult,
-): ReadResult<TResult> {
+): ReadResult<TResult>
+/**
+ * Live field of an `each` row — `read(item, (i) => i.field)`. `read()` is the
+ * one marker for live data, so an item field that changes over time is read the
+ * same way a machine value is. The compiler lowers this form to a per-row
+ * `itemBind`; it is valid only where `item` is the each callback's item param.
+ */
+export function read<TItem, TResult>(
+  item: TItem,
+  selector: (item: TItem) => TResult,
+): ReadResult<TResult>
+export function read(
+  // biome-ignore lint/suspicious/noExplicitAny: overload implementation — the typed surface is the two signatures above
+  instance: any,
+  // biome-ignore lint/suspicious/noExplicitAny: overload implementation — see above
+  selector: (instance: any) => unknown,
+): ReadResult {
   const state = requireCurrentRenderState()
   const def = defForProxy(instance as unknown as object)
   if (!def) {
+    // The item-read overload exists only for typing — the compiler rewrites
+    // read(item, …) to itemBind before runtime, so a non-machine here is a bug.
     throw new Error(
       'stator: read() must be called with a machine instance produced by the framework',
     )
   }
   const slotId = allocSlotId(state)
-  const value = selector(instance)
+  // During a recompute-driven re-render (fan-out), resolve the CURRENT proxy for
+  // this machine so arm/list interiors see fresh state — the closure `instance`
+  // was frozen at connect-time by `rehydrate()` (FINDINGS #3). On the initial
+  // render `currentRuntime` is null and `instance` already IS the current proxy.
+  const live = state.currentRuntime?.proxyFor(def.name)
+  const source = live ?? instance
+  const value = selector(source)
   return {
     __isReadResult: true,
     slotId,
     machineName: def.name,
     selector: selector as ErasedSelector,
-    instance,
-    value: value as TResult,
+    instance: source,
+    value,
   }
 }