@statorjs/stator 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Server-canonical web framework: business logic in composable state machines, UI as a thin renderer binding machine outputs to DOM positions. Ships TypeScript source (Vite/tsx-native by design).",
   "license": "MIT",
   "type": "module",
@@ -88,12 +88,13 @@
     "pino-pretty": "^13.1.3",
     "vite": "^6.0.0",
     "vitest": "^2.1.0",
-    "@statorjs/stator": "1.7.0"
+    "@statorjs/stator": "1.8.0"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:browser": "node browser-tests/tables.mjs",
     "build:client": "esbuild src/client/runtime.ts --bundle --format=iife --target=es2020 --outfile=dist/client.js"
   }
 }

package/src/engine/actor.ts

@@ -244,10 +244,16 @@ export function createActor<C extends object, E extends EventObject, S extends s
       // transition uniformly against the full event union (the runtime event
       // IS the narrowed type for this key, so the coercion is sound).
       type RawTransition = ((ctx: C, ev: E, h: ActionHelpers) => void) | TransitionConfig<C, E, S>
-      const entry = node?.on?.[event.type as E['type']] as
-        | RawTransition
-        | RawTransition[]
-        | undefined
+      let entry = node?.on?.[event.type as E['type']] as RawTransition | RawTransition[] | undefined
+      // Machine-level fallback: consulted ONLY when the current state does not
+      // declare this event (state-scoped handlers win — most specific). This is
+      // how a completion is handled regardless of the machine-wide state (a save
+      // completing while the machine reloads) without duplicating the handler
+      // into every state. A state that declares the event owns it, even if its
+      // guard drops — no fall-through to machine level in that case.
+      if (entry === undefined) {
+        entry = def.on?.[event.type as E['type']] as RawTransition | RawTransition[] | undefined
+      }
       if (!entry) return
 
       const h = helpers()

package/src/engine/define-machine.ts

@@ -6,6 +6,7 @@ import type {
   EventObject,
   Lifecycle,
   MachineDef,
+  OnMap,
   ReadsMap,
   SelectorMap,
   StateNode,
@@ -34,6 +35,13 @@ export interface DefineMachineConfig<
   initial: NoInfer<S>
   /** Transitions see `helpers.reads` typed as `ReadsMap<TReads>`. */
   states: Record<S, StateNode<C, E, S, ReadsMap<TReads>>>
+  /** Machine-level transitions: handlers that apply in ANY state, consulted only
+   *  when the current state does not declare the event (a state-scoped handler
+   *  always wins). The home for a completion event whose handling must not depend
+   *  on an unrelated machine-wide state — e.g. a per-record save completing while
+   *  the machine is busy reloading the collection. Without this, such a
+   *  completion is dropped wherever the current state has no handler for it. */
+  on?: OnMap<C, E, S, ReadsMap<TReads>>
   selectors?: Sel
   /** APP machines only: persist this machine's snapshot through the AppStore
    *  so its state survives restarts. Opt-in — caches and other
@@ -106,6 +114,7 @@ export function defineMachine<
     capabilities: computeCapabilities(reads),
     initial: config.initial,
     states: config.states as Record<string, StateNode<C, E, S>>,
+    on: config.on as OnMap<C, E, S> | undefined,
     context: config.context,
     __context: undefined as unknown as C,
     __event: undefined as unknown as E,

package/src/engine/types.ts

@@ -252,6 +252,9 @@ export interface MachineDef<
    *  reads typing that matters is enforced at the authoring callsite) and the
    *  initial context. */
   states: Record<string, StateNode<C, E, S>>
+  /** Machine-level transitions — handlers consulted when the current state does
+   *  not declare the event (state-scoped handlers take precedence). */
+  on?: OnMap<C, E, S>
   context: C
   /** Type-level carriers — never read at runtime. */
   readonly __context: C

package/src/server/query-route.ts

@@ -6,7 +6,12 @@ import { scopedLogger } from './logger.ts'
 import type { MachineStore } from './machine-store.ts'
 import type { DiscoveredRoute } from './route-discovery.ts'
 import { buildRouteRequest } from './route-request.ts'
-import type { QueryRouteDefinition, QueryRouteResult, RouteContext } from './routing.ts'
+import type {
+  QueryRouteDefinition,
+  QueryRouteHelpers,
+  QueryRouteResult,
+  RouteContext,
+} from './routing.ts'
 import { getOrCreateSessionId } from './session.ts'
 import { withSessionLock } from './session-lock.ts'
 import { SessionRuntime } from './session-runtime.ts'
@@ -74,7 +79,11 @@ export async function runQueryRoute(
 
     let result: QueryRouteResult
     try {
-      result = await route.handler(request, { machines })
+      // The map is built dynamically by machine name; the typed ReadsMap
+      // guarantee is for the user's handler, recovered at their call site.
+      result = await route.handler(request, {
+        machines: machines as QueryRouteHelpers['machines'],
+      })
     } catch (err) {
       queryLog.error({ err: String(err), path: c.req.path }, 'data route handler threw')
       return c.text('Internal Server Error', 500)

package/src/server/routing.ts

@@ -1,6 +1,6 @@
 import type { HtmlFragment } from '../template/types.ts'
 import type { WireEnvelope } from '../wire/index.ts'
-import type { AnyMachineDef, EventOf } from './define-machine.ts'
+import type { AnyMachineDef, EventOf, ReadsMap } from './define-machine.ts'
 
 /** Machine context passed to a route's render function. Keyed by machine name. */
 export type RouteContext = Record<string, unknown>
@@ -170,7 +170,7 @@ export interface DefineApiRouteConfig<TReads extends ReadonlyArray<AnyMachineDef
 /** `method: 'GET'` discriminates: with it, the handler is a read-only data
  *  route typed with `{ machines }`; without it, a command route typed with
  *  `{ dispatch, rotateSession }` — exactly as before. */
-export function defineApiRoute<TReads extends ReadonlyArray<AnyMachineDef>>(
+export function defineApiRoute<TReads extends ReadonlyArray<AnyMachineDef> = readonly []>(
   config: DefineQueryRouteConfig<TReads>,
 ): QueryRouteDefinition
 export function defineApiRoute<TReads extends ReadonlyArray<AnyMachineDef>>(
@@ -209,10 +209,15 @@ export function isStatorApiRoute(v: unknown): v is ApiRouteDefinition {
  *  there is no `dispatch` here, and that structural absence is what makes
  *  handler reads safe — a handler that cannot dispatch has nothing to
  *  interleave with effect completions or other sessions' commits. */
-export interface QueryRouteHelpers {
+export interface QueryRouteHelpers<
+  TReads extends ReadonlyArray<AnyMachineDef> = ReadonlyArray<AnyMachineDef>,
+> {
   /** Read proxies keyed by machine name — the same shape a page's render
-   *  context uses (selector + context reads; no send). */
-  machines: RouteContext
+   *  context uses (selector + context reads; no send). Typed off the route's
+   *  `reads:` tuple (`ReadsMap`), so `machines.SitesMachine` is a real proxy
+   *  and a mistyped name is a compile error rather than `unknown`. The default
+   *  keeps the erased runtime definition loose. */
+  machines: ReadsMap<TReads>
 }
 
 /** What a data GET handler may return: a raw `Response` (passed through
@@ -231,14 +236,14 @@ export interface QueryRouteDefinition {
   ) => Promise<QueryRouteResult> | QueryRouteResult
 }
 
-export interface DefineQueryRouteConfig<TReads extends ReadonlyArray<AnyMachineDef>> {
+export interface DefineQueryRouteConfig<TReads extends ReadonlyArray<AnyMachineDef> = readonly []> {
   /** The capability discriminant: `'GET'` declares a read-only data route.
    *  Discovery cross-checks it against the export name. */
   method: 'GET'
   reads?: TReads
   handler: (
     request: RouteRequest,
-    helpers: QueryRouteHelpers,
+    helpers: QueryRouteHelpers<TReads>,
   ) => Promise<QueryRouteResult> | QueryRouteResult
 }
 

package/src/template/conditional.ts

@@ -104,9 +104,9 @@ export function when<T>(cond: T | ReadResult<T>, fn: () => HtmlFragment): Branch
     })
   }
 
-  // `display: contents` so the wrapper span doesn't break the surrounding
-  // element's layout (grid/flex) — see each.ts for the same rationale.
-  const html = `<span data-slot="${slotId}" data-branch="true" style="display:contents">${innerHtml}</span>`
+  // Comment markers delimit the region (no injected node, valid in restricted
+  // parents) — see each.ts for the rationale.
+  const html = `<!--s:${slotId}-->${innerHtml}<!--/s:${slotId}-->`
   return { __isBranchResult: true, html, slotId }
 }
 
@@ -160,8 +160,8 @@ export function match<TKey extends string>(
     })
   }
 
-  // `display: contents` so the wrapper span doesn't break the surrounding
-  // element's layout (grid/flex) — see each.ts for the same rationale.
-  const html = `<span data-slot="${slotId}" data-branch="true" style="display:contents">${innerHtml}</span>`
+  // Comment markers delimit the region (no injected node, valid in restricted
+  // parents) — see each.ts for the rationale.
+  const html = `<!--s:${slotId}-->${innerHtml}<!--/s:${slotId}-->`
   return { __isBranchResult: true, html, slotId }
 }

package/src/template/defer.ts

@@ -32,9 +32,9 @@ export function deferSentinel(slotId: SlotId): string {
 }
 
 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>`
+  // Comment markers delimit the region (no injected node, valid in restricted
+  // parents) — same rationale as each()/when().
+  const html = `<!--s:${slotId}-->${inner}<!--/s:${slotId}-->`
   return { __isDeferResult: true, html, slotId }
 }
 

package/src/template/each.ts

@@ -136,12 +136,11 @@ export function each<T>(
     }
   }
 
-  // `display: contents` so the wrapper span is invisible to layout — its
-  // children become layout-children of the surrounding element. Without
-  // this, putting `each()` inside a CSS grid or flex container would
-  // collapse all items into a single grid/flex cell. The span itself stays
-  // in the DOM as the patch addressing target.
-  const html = `<span data-slot="${slotId}" data-list="true" style="display:contents">${innerHtml}</span>`
+  // Comment markers delimit the region instead of a wrapper element: they inject
+  // no node into the user's DOM (no layout box, no CSS sibling/child selector
+  // pollution) and are valid in restricted parents like <table>/<tbody> where a
+  // <span> is foster-parented out. The client addresses the list by its markers.
+  const html = `<!--s:${slotId}-->${innerHtml}<!--/s:${slotId}-->`
   return { __isEachResult: true, html, slotId }
 }
 

package/src/wire/apply.ts

@@ -9,6 +9,14 @@
  * path applied it.
  */
 import type { Directive, Patch } from './index.ts'
+import {
+  elementAt,
+  findRegion,
+  insertAt,
+  moveWithin,
+  removeAt,
+  replaceRegion,
+} from './region-apply.ts'
 import { isSafeNavigationUrl } from './safe-url.ts'
 
 function emit(name: string, detail: unknown): void {
@@ -22,44 +30,79 @@ export function resolveTarget(target: { kind: 'slot' | 'element'; id: string }):
   return document.querySelector(`[data-stator-id="${target.id}"]`)
 }
 
+function warnMissing(target: { kind: string; id: string }): void {
+  // A missing target means this DOM diverged from server truth (stale non-live
+  // page, or client code removed server-owned nodes). Skipping is safe — arm/
+  // key-scoped ids guarantee a patch can't land on the wrong content — but the
+  // divergence is worth surfacing.
+  console.warn(`stator: patch target ${target.kind} "${target.id}" not in DOM — skipped`)
+}
+
 export function applyPatches(patches: Patch[]): void {
+  // Resolve each region's marker pair once per batch. The markers are stable
+  // anchors — ops mutate only the nodes between them — so a pair found for one
+  // op stays valid for the rest of the batch (keyed lists emit a run of ops on
+  // the same slot). null caches a genuine miss.
+  const regions = new Map<string, { start: Comment; end: Comment } | null>()
+  const regionFor = (id: string): { start: Comment; end: Comment } | null => {
+    let r = regions.get(id)
+    if (r === undefined) {
+      r = findRegion(document, id)
+      regions.set(id, r)
+    }
+    return r
+  }
+
   for (const patch of patches) {
+    const element = applyPatch(patch, regionFor)
+    emit('stator:patch-applied', { patch, element, timestamp: Date.now() })
+  }
+}
+
+/** Apply one patch. Returns the element the inspector should flash (or null when
+ *  the target is missing or the change left no single node to highlight). */
+function applyPatch(
+  patch: Patch,
+  regionFor: (id: string) => { start: Comment; end: Comment } | null,
+): Element | null {
+  // `text`/`attr` address a single node: a text-binding `data-slot` span or a
+  // `data-stator-id` element.
+  if (patch.op === 'text' || patch.op === 'attr') {
     const element = resolveTarget(patch.target)
     if (!element) {
-      // A missing target means this DOM diverged from server truth (stale
-      // non-live page, or client code removed server-owned nodes). Skipping
-      // is safe — arm/key-scoped slot ids guarantee a patch can't land on
-      // the wrong content — but the divergence is worth surfacing.
-      console.warn(
-        `stator: patch target ${patch.target.kind} "${patch.target.id}" not in DOM — skipped`,
-      )
-      continue
+      warnMissing(patch.target)
+      return null
     }
-    if (element) {
-      if (patch.op === 'text') element.textContent = patch.value
-      else if (patch.op === 'html') element.innerHTML = patch.value
-      else if (patch.op === 'attr') {
-        if (patch.value === null) element.removeAttribute(patch.name)
-        else element.setAttribute(patch.name, patch.value)
-      }
-      // Keyed-list ops address element children by index, sequentially: each
-      // op sees the DOM as left by the previous one (see wire/index.ts).
-      else if (patch.op === 'insert') {
-        const tpl = document.createElement('template')
-        tpl.innerHTML = patch.value
-        element.insertBefore(tpl.content, element.children[patch.index] ?? null)
-      } else if (patch.op === 'remove') {
-        element.children[patch.index]?.remove()
-      } else if (patch.op === 'move') {
-        const node = element.children[patch.from]
-        if (node) {
-          node.remove()
-          element.insertBefore(node, element.children[patch.to] ?? null)
-        }
-      }
-    }
-    emit('stator:patch-applied', { patch, element, timestamp: Date.now() })
+    if (patch.op === 'text') element.textContent = patch.value
+    else if (patch.value === null) element.removeAttribute(patch.name)
+    else element.setAttribute(patch.name, patch.value)
+    return element
+  }
+
+  // `html`/`insert`/`remove`/`move` address a REGION delimited by comment
+  // markers (`<!--s:id-->…<!--/s:id-->`). Keyed-list ops address element
+  // children by index, sequentially: each op sees the DOM as left by the
+  // previous one (see wire/index.ts).
+  const region = regionFor(patch.target.id)
+  if (!region) {
+    warnMissing(patch.target)
+    return null
+  }
+  const { start, end } = region
+  if (patch.op === 'html') {
+    replaceRegion(start, end, patch.value)
+    return start.parentElement
+  }
+  if (patch.op === 'insert') {
+    insertAt(start, end, patch.index, patch.value)
+    return elementAt(start, end, patch.index)
+  }
+  if (patch.op === 'remove') {
+    removeAt(start, end, patch.index)
+    return start.parentElement
   }
+  moveWithin(start, end, patch.from, patch.to)
+  return elementAt(start, end, patch.to)
 }
 
 export function applyDirectives(directives: Directive[]): void {

package/src/wire/region-apply.ts

@@ -0,0 +1,103 @@
+/**
+ * Comment-marker region boundaries. A reactive region (`each`/`when`/`match`/
+ * `defer`) is delimited on the client by a pair of HTML comments
+ * `<!--s:ID-->…<!--/s:ID-->` instead of a wrapper element, so the framework
+ * injects no node into the user's authored DOM — comments are valid anywhere
+ * (including in `<table>`/`<tbody>` where a `<span>` is foster-parented out) and
+ * do not participate in the CSS sibling/child selector graph.
+ *
+ * A region is the run of nodes strictly between its two markers, sharing the
+ * markers' parent. Keyed-list ops (insert/remove/move) address the region's
+ * ELEMENT children by index — the same contract as the old wrapper's
+ * `element.children[i]`, just counted between markers instead of inside a span.
+ */
+
+export const startTag = (id: string): string => `s:${id}`
+export const endTag = (id: string): string => `/s:${id}`
+
+/** Parse a trusted HTML fragment through a `<template>`, whose "in template"
+ *  insertion mode preserves table-context children (`<tr>`, `<td>`, `<option>`)
+ *  that a plain element's `innerHTML` would drop. */
+export function parseFragment(html: string): DocumentFragment {
+  const tpl = document.createElement('template')
+  tpl.innerHTML = html
+  return tpl.content
+}
+
+/** Locate a region's marker pair by scanning comment nodes under `root`.
+ *  (Prototype: linear scan. Production adds a hydration-time index keyed by id.) */
+export function findRegion(root: Node, id: string): { start: Comment; end: Comment } | null {
+  const s = startTag(id)
+  const e = endTag(id)
+  let start: Comment | null = null
+  const walk = (node: Node): Comment | null => {
+    for (let n = node.firstChild; n; n = n.nextSibling) {
+      if (n.nodeType === 8 /* Comment */) {
+        const data = (n as Comment).data
+        if (data === s) start = n as Comment
+        else if (data === e && start) return n as Comment
+      }
+      const found = walk(n)
+      if (found) return found
+    }
+    return null
+  }
+  const end = walk(root)
+  return start && end ? { start, end } : null
+}
+
+/** The i-th ELEMENT between the markers (mirrors `element.children[i]`); text
+ *  and nested-region comment nodes are skipped. Null when out of range. */
+export function elementAt(start: Comment, end: Comment, index: number): Element | null {
+  let i = 0
+  for (let n = start.nextSibling; n && n !== end; n = n.nextSibling) {
+    if (n.nodeType === 1 /* Element */) {
+      if (i === index) return n as Element
+      i++
+    }
+  }
+  return null
+}
+
+/** Count element children in the region. */
+export function elementCount(start: Comment, end: Comment): number {
+  let i = 0
+  for (let n = start.nextSibling; n && n !== end; n = n.nextSibling) {
+    if (n.nodeType === 1) i++
+  }
+  return i
+}
+
+/** Insert `html` so its (single-root) element becomes element-index `index`
+ *  within the region — before the element currently there, or before the end
+ *  marker when appending. */
+export function insertAt(start: Comment, end: Comment, index: number, html: string): void {
+  const ref = elementAt(start, end, index) ?? end
+  ref.parentNode?.insertBefore(parseFragment(html), ref)
+}
+
+/** Remove the element at `index`. */
+export function removeAt(start: Comment, end: Comment, index: number): void {
+  elementAt(start, end, index)?.remove()
+}
+
+/** Move the element from `from` to `to`. `to` is the index in the list AFTER the
+ *  removal — matching the wire contract's sequential-op replay. */
+export function moveWithin(start: Comment, end: Comment, from: number, to: number): void {
+  const node = elementAt(start, end, from)
+  if (!node) return
+  node.remove()
+  const ref = elementAt(start, end, to) ?? end
+  ref.parentNode?.insertBefore(node, ref)
+}
+
+/** Replace the whole region body (the `html` op) — remove everything between the
+ *  markers, then insert the freshly-parsed content before the end marker. */
+export function replaceRegion(start: Comment, end: Comment, html: string): void {
+  for (let n = start.nextSibling; n && n !== end; ) {
+    const next = n.nextSibling
+    n.remove()
+    n = next
+  }
+  end.parentNode?.insertBefore(parseFragment(html), end)
+}