@statorjs/stator 1.3.0 → 1.4.1

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'
 
@@ -20,6 +21,15 @@ import { type DirectiveInvocation, defineDirective, invoke } from './core.ts'
 
 type ConditionalEntry<TValue> = TValue | ReadResult<TValue>
 
+/** Resolve the machine instance a spec read evaluates against. During a
+ *  fan-out recompute this returns the CURRENT proxy — the ReadResult's captured
+ *  `.instance` was frozen at first render, and `rehydrate()` has since replaced
+ *  the connection's actor (FINDINGS #3, one composition boundary further out:
+ *  the spec object outlives the render that built it). Null runtime (initial
+ *  render, request-scoped recompute) falls back to the captured instance,
+ *  which is current there by construction. */
+type InstanceResolver = (r: ReadResult<unknown>) => unknown
+
 /** Recursive shape accepted by class:list. */
 export type ClassListSpec =
   | string
@@ -40,11 +50,25 @@ export type StyleListSpec =
   | Record<string, ConditionalEntry<string | number | null | undefined>>
   | StyleListSpec[]
 
-function evalRead<T>(value: ConditionalEntry<T>): T {
-  return isReadResult(value) ? (value.selector(value.instance) as T) : value
+function evalRead<T>(value: ConditionalEntry<T>, resolve: InstanceResolver): T {
+  return isReadResult(value) ? (value.selector(resolve(value)) 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,47 +81,48 @@ 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)
     }
   }
 }
 
-function composeClass(spec: ClassListSpec): string {
+function composeClass(spec: ClassListSpec, resolve: InstanceResolver): string {
   const parts: string[] = []
-  walkClass(spec, parts)
+  walkClass(spec, parts, resolve)
   return parts.join(' ')
 }
 
-function walkClass(spec: ClassListSpec, out: string[]): void {
+function walkClass(spec: ClassListSpec, out: string[], resolve: InstanceResolver): void {
   if (spec == null || spec === false) return
   if (typeof spec === 'string') {
     if (spec.length > 0) out.push(spec)
     return
   }
   if (isReadResult(spec)) {
-    const v = spec.selector(spec.instance)
+    const v = spec.selector(resolve(spec))
     if (typeof v === 'string' && v.length > 0) out.push(v)
     return
   }
   if (Array.isArray(spec)) {
-    for (const item of spec) walkClass(item, out)
+    for (const item of spec) walkClass(item, out, resolve)
     return
   }
   if (typeof spec === 'object') {
     for (const [name, cond] of Object.entries(spec)) {
-      const truthy = evalRead(cond)
+      const truthy = evalRead(cond, resolve)
       if (truthy) out.push(name)
     }
   }
 }
 
-function composeStyle(spec: StyleListSpec): string {
+function composeStyle(spec: StyleListSpec, resolve: InstanceResolver): string {
   const decls: string[] = []
-  walkStyle(spec, decls)
+  walkStyle(spec, decls, resolve)
   return decls.join('; ')
 }
 
-function walkStyle(spec: StyleListSpec, out: string[]): void {
+function walkStyle(spec: StyleListSpec, out: string[], resolve: InstanceResolver): void {
   if (spec == null || spec === false) return
   if (typeof spec === 'string') {
     const trimmed = spec.trim()
@@ -105,19 +130,19 @@ function walkStyle(spec: StyleListSpec, out: string[]): void {
     return
   }
   if (isReadResult(spec)) {
-    const v = spec.selector(spec.instance)
+    const v = spec.selector(resolve(spec))
     if (typeof v === 'string' && v.trim().length > 0) {
       out.push(v.trim().replace(/;\s*$/, ''))
     }
     return
   }
   if (Array.isArray(spec)) {
-    for (const item of spec) walkStyle(item, out)
+    for (const item of spec) walkStyle(item, out, resolve)
     return
   }
   if (typeof spec === 'object') {
     for (const [prop, raw] of Object.entries(spec)) {
-      const value = evalRead(raw)
+      const value = evalRead(raw, resolve)
       if (value == null || value === '') continue
       // A single property's value must not carry `;` — a `read()`-sourced value
       // like `red; position: fixed; …` would otherwise inject extra
@@ -140,26 +165,32 @@ function cssValue(v: string): string {
 /**
  * Register one attr-binding per unique machine the spec depends on. Each
  * binding's selector ignores its arg and recomputes the entire attribute
- * by re-walking the spec — every ReadResult inside re-evaluates its
- * `.selector(.instance)`, returning fresh state.
+ * by re-walking the spec — every ReadResult inside re-evaluates its selector
+ * against the RESOLVED instance (current proxy under a fan-out recompute,
+ * the captured one otherwise), returning fresh state.
  */
 function bindListAttr<TSpec>(
   state: RenderState,
   spec: TSpec,
   attrName: string,
   elementId: string,
-  compose: (spec: TSpec) => string,
+  compose: (spec: TSpec, resolve: InstanceResolver) => string,
 ): string {
   const machines = new Set<string>()
   collectMachines(spec, machines)
 
-  const initial = compose(spec)
+  // Resolution is per-evaluation, through the render state the binding was
+  // registered under — recompute sets `currentRuntime` for the fan-out pass.
+  const resolve: InstanceResolver = (r) =>
+    state.currentRuntime?.proxyFor(r.machineName) ?? r.instance
+
+  const initial = compose(spec, resolve)
   for (const machineName of machines) {
     const slotId = allocSlotId(state)
     registerBinding(state, {
       slotId,
       machineName,
-      selector: () => compose(spec),
+      selector: () => compose(spec, resolve),
       lastValue: initial,
       kind: 'attr',
       attrName,

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,
   }
 }

package/src/template/resource.ts

@@ -0,0 +1,70 @@
+export type ResourceStatus = 'pending' | 'fulfilled' | 'rejected'
+
+/**
+ * A peekable async value. You cannot synchronously read a native promise's
+ * settled state (`.then` is always a microtask), so `defer` wraps a thunk's
+ * result in a resource that records its settlement as it happens — letting the
+ * fill pass read `status` synchronously ("peek") at the moment it splices HTML.
+ *
+ * A non-promise thunk result fulfills immediately, so `defer` degrades to plain
+ * inline render for synchronous data.
+ */
+export interface Resource<T = unknown> {
+  readonly status: ResourceStatus
+  readonly value?: T
+  readonly reason?: unknown
+  /**
+   * Resolves when the resource settles (fulfilled OR rejected). Never rejects —
+   * a rejection is recorded as `status: 'rejected'` + `reason`, and `settled`
+   * still resolves, so the resolve phase can `await` a batch of resources with a
+   * plain `Promise.all` and never has to catch.
+   */
+  readonly settled: Promise<void>
+}
+
+function isPromiseLike(v: unknown): v is PromiseLike<unknown> {
+  return (
+    (typeof v === 'object' || typeof v === 'function') &&
+    v !== null &&
+    typeof (v as { then?: unknown }).then === 'function'
+  )
+}
+
+/**
+ * Wrap a thunk's result in a peekable {@link Resource}. Synchronous values (and
+ * synchronous throws) settle immediately; a promise records its settlement on a
+ * single attached continuation.
+ */
+export function createResource<T>(produce: () => T | Promise<T>): Resource<T> {
+  let result: T | Promise<T>
+  try {
+    result = produce()
+  } catch (reason) {
+    // A thunk that throws synchronously is a rejected resource, not a crash.
+    return { status: 'rejected', reason, settled: Promise.resolve() }
+  }
+
+  if (!isPromiseLike(result)) {
+    return { status: 'fulfilled', value: result, settled: Promise.resolve() }
+  }
+
+  const resource: {
+    status: ResourceStatus
+    value?: T
+    reason?: unknown
+    settled: Promise<void>
+  } = { status: 'pending', settled: Promise.resolve() }
+
+  resource.settled = Promise.resolve(result).then(
+    (value) => {
+      resource.status = 'fulfilled'
+      resource.value = value
+    },
+    (reason) => {
+      resource.status = 'rejected'
+      resource.reason = reason
+    },
+  )
+
+  return resource
+}