@statorjs/stator 1.7.1 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@statorjs/stator",
-  "version": "1.7.1",
+  "version": "1.9.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.1"
+    "@statorjs/stator": "1.9.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/client/bind.ts

@@ -33,6 +33,40 @@ export function bind(
   }
 }
 
+/**
+ * Text-slot binding for a client-machine `read()` in text position. The
+ * compiler renders an `<!--sN-->` comment where the expression sat; this finds
+ * every occurrence of the marker under `root` (a marker inside a `.map()`
+ * repeats per row), materializes one text node after each, and binds them all
+ * to the thunk through the normal `bind()` diff loop. Returns a disposer.
+ */
+export function bindSlot(
+  root: Node,
+  marker: string,
+  deps: ClientInstanceBase[],
+  compute: () => unknown,
+): () => void {
+  // Manual walk, not TreeWalker: happy-dom's walker prunes descent at
+  // non-matching nodes, so a SHOW_COMMENT filter never reaches nested comments
+  // — and the manual loop is as small as the workaround discussion.
+  const texts: Text[] = []
+  const stack: Node[] = [root]
+  while (stack.length > 0) {
+    const n = stack.pop() as Node
+    if (n.nodeType === 8 /* COMMENT_NODE */ && (n as Comment).data === marker) {
+      const t = document.createTextNode('')
+      n.parentNode?.insertBefore(t, n.nextSibling)
+      texts.push(t)
+    } else {
+      for (let c = n.firstChild; c; c = c.nextSibling) stack.push(c)
+    }
+  }
+  return bind(deps, compute, (v) => {
+    const s = v == null ? '' : String(v)
+    for (const t of texts) if (t.data !== s) t.data = s
+  })
+}
+
 /**
  * Imperative reactivity escape hatch: run `fn` now and again whenever any
  * dependency changes (no diffing — `fn` owns its own DOM writes). The lower-

package/src/client/client-id.ts

@@ -4,10 +4,25 @@
  * diff baseline WITHOUT re-sending patches the POST response already
  * delivered (text/attr dupes are invisible; keyed inserts are not).
  */
-export const clientId: string =
-  typeof crypto !== 'undefined' && 'randomUUID' in crypto
+function freshId(): string {
+  return typeof crypto !== 'undefined' && 'randomUUID' in crypto
     ? crypto.randomUUID()
     : `c${Math.random().toString(36).slice(2)}`
+}
+
+/** One identity per PAGE, not per bundle. The page runtime (a classic-script
+ *  bundle) and island modules (the Vite/asset graph) each carry their own copy
+ *  of this module — a plain module-scoped id would mint one per copy, the SSE
+ *  connection and an island's dispatch would disagree, and fan-out's
+ *  originator skip would never fire (double-applying keyed inserts on the
+ *  dispatching page). The window slot is the page-load singleton both copies
+ *  converge on. */
+export const clientId: string = (() => {
+  if (typeof window === 'undefined') return freshId()
+  const w = window as { __statorClientId?: string }
+  w.__statorClientId ??= freshId()
+  return w.__statorClientId
+})()
 
 /** Per-dispatch idempotency key: the server replays a duplicate POST's cached
  *  response instead of re-applying it, which is what makes retrying a lost

package/src/client/index.ts

@@ -4,7 +4,7 @@
  * island needs; these are also the symbols an author references directly.
  */
 
-export { bind, effect } from './bind.ts'
+export { bind, bindSlot, effect } from './bind.ts'
 export type { DispatchResult } from './dispatch.ts'
 export { dispatch } from './dispatch.ts'
 export { defineElement, StatorElement } from './element.ts'

package/src/client/machine.ts

@@ -22,9 +22,30 @@ import { defineMachine, type MachineDef } from '../engine/index.ts'
  * is just a label and need not be unique.
  */
 
-/** Client events are structurally loose — the terse form declares no union. */
+/** The loose client event shape — the fallback when a machine declares no
+ *  union and has no `on` map to derive one from. */
 export type ClientEvent = { type: string; [k: string]: unknown }
 
+/** Event-name union derived from an `on` map: the NAMES are typed (a `send`
+ *  typo is a compile error), payloads stay structurally open. The
+ *  zero-ceremony tier of client event typing. */
+export type DerivedEvents<O> = {
+  [K in keyof O & string]: { type: K } & Record<string, unknown>
+}[keyof O & string]
+
+/** The `on` map for a machine with a DECLARED event union: keys are the
+ *  declared event names, and each handler sees its event narrowed — no
+ *  annotations needed. Mirrors the server `defineMachine` experience. */
+export type TypedClientOnMap<C, E extends { type: string }> = {
+  [K in E['type']]?:
+    | ((ctx: C, ev: Extract<E, { type: K }>) => void)
+    | {
+        when?: (ctx: C, ev: Extract<E, { type: K }>) => boolean
+        do?: (ctx: C, ev: Extract<E, { type: K }>) => void
+        emit?: string | string[]
+      }
+}
+
 interface ClientTransitionObject<C> {
   when?: (ctx: C, ev: ClientEvent) => boolean
   do?: (ctx: C, ev: ClientEvent) => void
@@ -57,17 +78,41 @@ export interface LegacyMachineConfig {
 
 const RESERVED = new Set(['name', 'on', 'select'])
 
-// Data-only: no behavior, no selectors.
+// Data-only: no behavior. Events stay structurally LOOSE (ClientEvent) on
+// purpose: data-only machines are the `bind:value` / hand-written `@set`
+// carriers until 2.0 removes `@set` — tightening them now would break that
+// still-supported surface. Tighten to `never` when `@set` goes.
 export function machine<C extends Record<string, unknown>>(
-  context: C & { on?: never; select?: never; name?: never },
+  context: C & { on?: never; select?: never; name?: never; events?: never },
 ): MachineDef<C, ClientEvent, 'active', Record<string, never>>
-// Data + behavior: handlers and selectors typed against the context.
+// Derived union — no `events:` declared: event NAMES come from the `on` keys
+// (typo-safe send), payloads stay open. Zero authoring change. Ordered BEFORE
+// the declared overload: `events?: never` keeps declared calls falling through.
+export function machine<
+  C extends Record<string, unknown>,
+  O extends Record<string, ClientTransition<C>>,
+  S extends Record<string, (ctx: C) => unknown>,
+>(
+  context: C & { on?: never; select?: never; name?: never; events?: never },
+  behavior: { name?: string; events?: never; on: O; select?: S },
+): MachineDef<C, DerivedEvents<O>, 'active', S>
+// Declared union (`events: {} as E`) — mirrors defineMachine: full payload
+// typing on send, handlers narrowed per key, undeclared handler keys error.
+export function machine<
+  C extends Record<string, unknown>,
+  E extends { type: string },
+  S extends Record<string, (ctx: C) => unknown>,
+>(
+  context: C & { on?: never; select?: never; name?: never; events?: never },
+  behavior: { name?: string; events: E; on?: TypedClientOnMap<C, E>; select?: S },
+): MachineDef<C, E, 'active', S>
+// Behavior without `on` (selectors only): loose, as data-only.
 export function machine<
   C extends Record<string, unknown>,
   S extends Record<string, (ctx: C) => unknown>,
 >(
-  context: C & { on?: never; select?: never; name?: never },
-  behavior: ClientBehavior<C> & { select?: S },
+  context: C & { on?: never; select?: never; name?: never; events?: never },
+  behavior: { name?: string; events?: never; on?: never; select?: S },
 ): MachineDef<C, ClientEvent, 'active', S>
 /** @deprecated see LegacyMachineConfig */
 export function machine(
@@ -76,8 +121,11 @@ export function machine(
 ): MachineDef<Record<string, any>, ClientEvent, 'active', Record<string, (ctx: any) => any>>
 export function machine(
   first: Record<string, unknown>,
-  behavior?: ClientBehavior<never>,
+  // Loose impl signature: the overloads above are the contract. `events` is a
+  // type-only phantom (`{} as E`) — the runtime never reads it.
+  rawBehavior?: unknown,
 ): MachineDef {
+  const behavior = rawBehavior as (ClientBehavior<never> & { events?: unknown }) | undefined
   let context: Record<string, unknown>
   let name: string | undefined
   let on: Record<string, unknown>

package/src/client/use.ts

@@ -2,6 +2,7 @@ import {
   type AnyActor,
   type AnyMachineDef,
   createActor,
+  type EventOf,
   type MachineDef,
   type Snapshot,
 } from '../engine/index.ts'
@@ -17,17 +18,30 @@ const CLIENT_HELPERS = {
   ),
 } as never
 
+/** Event names sendable as a bare string: only members whose shape is
+ *  satisfied by `{ type }` alone — an event with a required payload must be
+ *  sent as an object. (For the loose ClientEvent this admits any string,
+ *  preserving the untyped tier's behavior.) */
+export type BareEventTypes<E extends { type: string }> = E extends { type: infer T extends string }
+  ? { type: T } extends E
+    ? T
+    : never
+  : never
+
 /**
  * The client-side reactive handle for a machine. Returned by `use()`, held as a
  * class field (`qty = use(Qty)`). Exposes:
  *   - each selector / context key as a live property (read through the actor's
  *     current snapshot on every access — the client mirror of the server
  *     instance proxy). This is what `bind:text={qty.count}` reads.
- *   - `send(event)` to drive transitions.
+ *   - `send(event)` to drive transitions, typed to the machine's event union
+ *     (declared `events:`, derived from `on` keys, or loose for data-only).
  *   - the underlying actor (non-enumerable) for the binding loop to subscribe.
  */
-export interface ClientInstanceBase {
-  send(event: { type: string; [k: string]: unknown } | string): void
+export interface ClientInstanceBase<
+  E extends { type: string } = { type: string; [k: string]: unknown },
+> {
+  send(event: E | BareEventTypes<E>): void
   /** @internal — the actor a binding subscribes to. */
   readonly __actor: AnyActor
 }
@@ -41,7 +55,8 @@ type ClientView<D> =
       }
     : unknown
 
-export type ClientInstance<D extends MachineDef = MachineDef> = ClientInstanceBase & ClientView<D>
+export type ClientInstance<D extends MachineDef = MachineDef> = ClientInstanceBase<EventOf<D>> &
+  ClientView<D>
 
 /** An actor plus an optional deferred seed thunk — evaluated at the element's
  *  connect (when attributes are available), not at construction. */

package/src/compiler/client-emit.ts

@@ -14,7 +14,7 @@ import { CompileError } from './diagnostics.ts'
  */
 
 const PRIMITIVES =
-  "import { StatorElement, defineElement, use, machine, bind, effect, dispatch } from '@statorjs/stator/client'"
+  "import { StatorElement, defineElement, use, machine, bind, bindSlot, effect, dispatch } from '@statorjs/stator/client'"
 
 export interface EmitClientInput {
   /** The author's `<script>` source. */
@@ -40,9 +40,20 @@ export function emitClientModule(input: EmitClientInput): string {
   const lines: string[] = []
   let i = 0
   for (const [marker, group] of byMarker) {
+    if (group[0]?.kind === 'slot') {
+      // Text slot: the runtime finds every `<!--sN-->` comment, materializes a
+      // text node per occurrence, and binds them all to the one thunk.
+      for (const d of group) {
+        const thunk = `() => (${rewriteMembers(d.expr, members)})`
+        const deps = `[${d.deps.map((dep) => `this.${dep}`).join(', ')}]`
+        lines.push(`    this.track(bindSlot(this, ${JSON.stringify(marker)}, ${deps}, ${thunk}))`)
+      }
+      continue
+    }
+    // Element wiring: every occurrence of the marker is wired — a marked
+    // element inside a `.map()` repeats per row.
     const node = `n${i++}`
-    lines.push(`    const ${node} = this.querySelector('[data-b="${marker}"]')`)
-    lines.push(`    if (${node}) {`)
+    lines.push(`    for (const ${node} of this.querySelectorAll('[data-b="${marker}"]')) {`)
     for (const d of group) lines.push(`      ${wireDirective(node, d, members)}`)
     lines.push('    }')
   }

package/src/compiler/client-script.ts

@@ -216,9 +216,13 @@ function loc(file?: string): DiagnosticLocation | undefined {
  * emits the wiring from this.
  */
 export interface ClientDirective {
-  /** Unique node marker, e.g. `b0`. The element gets `data-b="b0"`. */
+  /** Node marker. Element wiring (`on`/`bind`): `b<N>`, rendered as
+   *  `data-b="b<N>"` and resolved via querySelectorAll (every occurrence is
+   *  wired — a marker inside a `.map()` repeats). Text slots (`slot`): `s<N>`,
+   *  rendered as an `<!--s<N>-->` comment the client materializes a text node
+   *  after. */
   marker: string
-  kind: 'on' | 'bind'
+  kind: 'on' | 'bind' | 'slot'
   /** on: the DOM event name (`click`). */
   event?: string
   /** bind: the target (`text` / `html` / `value` / `checked` / `disabled` / attr). */

package/src/compiler/compile.ts

@@ -48,7 +48,7 @@ export interface CompileResult {
 }
 
 const PRIMITIVES_IMPORT =
-  "import { html, read, each, itemBind, when, match, defer, on, classList, styleList } from '@statorjs/stator/template'"
+  "import { html, read, each, itemBind, when, match, defer, on, classList, styleList, spreadAttrs } from '@statorjs/stator/template'"
 
 export interface CompileOptions {
   /** Stable id for the component (file path). Used for the scope hash so the
@@ -186,7 +186,7 @@ function compileClient(
   const attrDecl = `{ ${[...cls.staticAttrs].map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(', ')} }`
   const rootScope = ctx.scopeAttr ? ` data-s-${ctx.hash}` : ''
   const serverCode = [
-    "import { html, read, each, when, match, defer, on, classList, styleList, createHtmlFragment, clientShellAttrs } from '@statorjs/stator/template'",
+    "import { html, read, each, when, match, defer, on, classList, styleList, spreadAttrs, createHtmlFragment, clientShellAttrs } from '@statorjs/stator/template'",
     '',
     `export default function (props = {}) {`,
     `  const __inner = ${innerExpr}`,
@@ -373,6 +373,26 @@ function processFrontmatter(
         repls.push([n.getStart(sf), n.getEnd(), bound])
         return
       }
+      if (ts.isCallExpression(n) && isStatorCall(n, 'forwarded')) {
+        if (kind === 'route') {
+          throw new CompileError(
+            'stator: Stator.forwarded() is only available in a component — it reads a directive ' +
+              'forwarded from a parent (`<Child on:click={h}/>`), and a route has no parent.',
+            locInFm(n),
+          )
+        }
+        const arg = n.arguments[0]
+        if (!arg) {
+          throw new CompileError(
+            "stator: Stator.forwarded(name) takes a directive name, e.g. Stator.forwarded('on:click')",
+            locInFm(n),
+          )
+        }
+        // The parent packs component-level directives into a reserved `$directives`
+        // prop; this reads one back so the author can re-attach it where they like.
+        repls.push([n.getStart(sf), n.getEnd(), `props.$directives?.[${arg.getText(sf)}]`])
+        return
+      }
       if (ts.isPropertyAccessExpression(n) && isStatorMember(n, 'request')) {
         requireRoute('Stator.request', kind, locInFm(n))
         repls.push([n.getStart(sf), n.getEnd(), '__req'])

package/src/compiler/dts.ts

@@ -43,6 +43,11 @@ export function generateDts(
       // props an island's SERVER-rendered markup may consume (they never
       // cross the attr wire, so `static attrs` can't know about them).
       propsT = `{ ${fields} } & { [prop: string]: unknown }`
+    } else {
+      // No declared attrs, but the hydrate contract still holds: an island's
+      // server shell may consume any props its markup references. A closed
+      // `Record<string, never>` here would reject every use site.
+      propsT = '{ [prop: string]: unknown }'
     }
   }
 

package/src/compiler/virtual-code.ts

@@ -92,7 +92,8 @@ function injectImports(globals: string[], modulePath: string, userCode: string):
 // `Stator.reads` binding unassignable to component props.
 const AMBIENT_TYPE_IMPORTS =
   "import type { AnyMachineDef as __SMachineDef } from '@statorjs/stator/machine';\n" +
-  "import type { InstanceOf as __SInstanceOf } from '@statorjs/stator/template';\n"
+  "import type { InstanceOf as __SInstanceOf } from '@statorjs/stator/template';\n" +
+  "import type { StatorIntrinsicElements as __SIntrinsics } from '@statorjs/stator/template';\n"
 
 /**
  * Per-file ambient scaffold prepended to every virtual TSX. `Stator` (the macro
@@ -108,12 +109,13 @@ const AMBIENT_TYPE_IMPORTS =
 const STATOR_AMBIENT = `declare const Stator: {
   props<P>(): P;
   reads<const T extends readonly __SMachineDef[]>(defs: T): { -readonly [K in keyof T]: __SInstanceOf<T[K]> };
+  forwarded(name: \`on:\${string}\`): (() => unknown) | undefined;
   request: any;
   response: { status: number; headers: Record<string, string>; cookies: any };
 };
 declare global {
   namespace JSX {
-    interface IntrinsicElements extends Record<string, any> {}
+    interface IntrinsicElements extends __SIntrinsics {}
   }
 }
 `

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/index.ts

@@ -31,6 +31,7 @@ export type {
   ReadsMap,
   SelectorMap,
   Snapshot,
+  StateNameOf,
   StateNode,
   SubscribeEntry,
   Transition,

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
@@ -285,6 +288,13 @@ export type ReadsMap<TReads extends readonly AnyMachineDef[]> = {
 export type EventOf<D extends AnyMachineDef> =
   D extends MachineDef<any, infer E, any, any, any> ? E : never
 
+/** The state-name union a machine declares (the keys of its `states`). Threads
+ *  the literal names into `instance.state` so a template comparison
+ *  (`read(m, s => s.state === 'ready')`) autocompletes and a typo is a compile
+ *  error, instead of `state: string` swallowing it. */
+export type StateNameOf<D extends AnyMachineDef> =
+  D extends MachineDef<any, any, infer S, any, any> ? S : string
+
 export function isStatorMachine(v: unknown): v is AnyMachineDef {
   return (
     typeof v === 'object' && v !== null && (v as Record<string, unknown>).__isStatorMachine === true

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/directives/on.ts

@@ -3,9 +3,13 @@ import { type DirectiveInvocation, defineDirective, invoke } from './core.ts'
 
 type Handler = () => EventDescriptor | undefined
 
-const onDirective = defineDirective<Handler>({
+const onDirective = defineDirective<Handler | null | undefined>({
   name: 'on',
   apply({ modifier, arg, addAttribute }) {
+    // A forwarded/optional handler may be absent — `on:click={onClick}` where the
+    // caller passed no handler (Stator.forwarded returns undefined). Emit no
+    // binding rather than crash on `arg()`.
+    if (arg == null) return
     const result = arg()
     if (!isEventDescriptor(result)) {
       throw new Error(
@@ -17,6 +21,9 @@ const onDirective = defineDirective<Handler>({
   },
 })
 
-export function on(modifier: string, handler: Handler): DirectiveInvocation<Handler> {
+export function on(
+  modifier: string,
+  handler: Handler | null | undefined,
+): DirectiveInvocation<Handler | null | undefined> {
   return invoke(onDirective, modifier, handler)
 }

package/src/template/directives/spread.ts

@@ -0,0 +1,88 @@
+import { registerBinding, requireCurrentRenderState } from '../../server/render-context.ts'
+import { isUrlAttribute, safeAttrUrl } from '../../wire/safe-url.ts'
+import { isItemReadResult } from '../each.ts'
+import { isReadResult } from '../read.ts'
+import { type DirectiveInvocation, defineDirective, invoke, isDirectiveInvocation } from './core.ts'
+
+/**
+ * `{...spread}` on an element — forward a bag of attributes onto it. This is what
+ * makes the `HTMLAttributes<Tag>` component pattern practical: a `<Button>` can
+ * `<button {...rest} />` instead of hand-forwarding every native attribute.
+ *
+ * A spread value may be a literal OR a live machine `read(...)` — each read
+ * registers the same attribute binding the normal `attr={read(...)}` path does,
+ * so it patches on machine events (there is no separate reactive-spread wire).
+ * Two value kinds are rejected LOUDLY rather than silently mishandled:
+ *   - `read(item, …)` (an item binding) — it's owned by its each() row and can't
+ *     ride through a spread; bind it directly on the element. Mirrors the
+ *     class:list / style:list item-read rule (deferred util, see spread.test).
+ *   - a directive invocation (a `classList()` / `on()` result) — a directive owns
+ *     a whole attribute and isn't a plain value.
+ *
+ * Boolean/url semantics match the literal attr path (see html.ts handleRead):
+ * false / null / undefined ⇒ the attribute is ABSENT, true ⇒ present-and-empty,
+ * anything else stringifies; url-bearing names (href/src/…) get the scheme guard.
+ */
+export type SpreadAttrs = Record<string, unknown>
+
+const spreadDirective = defineDirective<SpreadAttrs>({
+  name: 'spread',
+  apply({ elementId, arg, addAttribute }) {
+    if (arg == null) return
+    const state = requireCurrentRenderState()
+    for (const [name, value] of Object.entries(arg)) {
+      if (isItemReadResult(value)) {
+        throw new Error(
+          `stator: read(item, …) can't be forwarded through {...spread} (attribute "${name}") — ` +
+            `an item read is owned by its each() row. Bind it directly on the element ` +
+            `(<el ${name}={read(item, …)} />). Only machine reads and static values can be spread.`,
+        )
+      }
+      if (isDirectiveInvocation(value)) {
+        throw new Error(
+          `stator: a directive (class:list / style:list / on:) can't be a {...spread} value ` +
+            `(attribute "${name}") — a directive owns a whole attribute. Apply it on the element directly.`,
+        )
+      }
+      if (isReadResult(value)) {
+        // A live machine read: register the same attr binding the normal
+        // `attr={read(...)}` path registers, keyed to this element + name, so a
+        // machine event patches it. No new wire — same shape recompute expects.
+        registerBinding(state, {
+          slotId: value.slotId,
+          machineName: value.machineName,
+          selector: value.selector,
+          lastValue: value.value,
+          kind: 'attr',
+          attrName: name,
+          parentId: elementId,
+        })
+        emitAttribute(name, value.value, addAttribute)
+        continue
+      }
+      emitAttribute(name, value, addAttribute)
+    }
+  },
+})
+
+/** Emit one attribute with the shared boolean/url semantics. false/null/undefined
+ *  ⇒ absent (no `addAttribute` call at all); true ⇒ present-and-empty; otherwise
+ *  stringified, url-guarded on url-bearing names. `addAttribute` HTML-escapes. */
+function emitAttribute(
+  name: string,
+  value: unknown,
+  addAttribute: (name: string, value: string) => void,
+): void {
+  if (value === false || value === null || value === undefined) return
+  if (value === true) {
+    addAttribute(name, '')
+    return
+  }
+  const str = typeof value === 'string' ? value : String(value)
+  addAttribute(name, isUrlAttribute(name) ? safeAttrUrl(str) : str)
+}
+
+/** Wrap an attribute bag as the directive the compiler emits for `{...spread}`. */
+export function spreadAttrs(attrs: SpreadAttrs): DirectiveInvocation<SpreadAttrs> {
+  return invoke(spreadDirective, '', attrs)
+}

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/template/html-attributes.ts

@@ -0,0 +1,213 @@
+/**
+ * Type-only HTML attribute surface for authoring components that extend a native
+ * element — the Astro/Svelte `HTMLAttributes<'button'>` pattern. So a component
+ * can be `Stator.props<HTMLAttributes<'button'> & { variant: 'primary' }>()` and
+ * get every native button attribute typed + validated, plus its own props.
+ *
+ * Hand-authored and intentionally LEAN: a useful subset, not the whole DOM. It
+ * mirrors `svelte/elements`' shape — a shared base (global attrs + ARIA + the
+ * Stator directives) plus a per-element attribute map, combined by tag. Grow the
+ * per-element map on demand; there is no compiler machinery behind this.
+ *
+ * STATOR REACTIVITY: a template attribute value can be a literal OR a live
+ * `read(...)` binding (`ReadResult<T>`), so every non-directive attribute value
+ * is `Reactive<T>`. This is the adaptation that makes typed intrinsics coexist
+ * with Stator templates — the load-bearing difference from Astro/Svelte, where
+ * attributes are plain values.
+ */
+
+import type { ReadResult } from './read.ts'
+
+/** A template attribute value: a literal, or a live `read(...)` binding. */
+export type Reactive<T> = T | ReadResult<T>
+
+/** Wrap every property value in `Reactive` (bindings allowed on any attribute).
+ *  Homomorphic, so it preserves the `data-*`/`aria-*` index signatures. */
+type Reactivize<A> = { [K in keyof A]: Reactive<A[K]> }
+
+/** Stator template directives — colon-namespaced, valid on any element and on any
+ *  component that forwards them. Not reactivized: their values are handlers/specs,
+ *  not bindings. Values are `unknown` for now — a later pass gives `on:`/`bind:`/
+ *  `ref:` their Stator-specific types. */
+export interface StatorDirectiveAttributes {
+  'class:list'?: unknown
+  'style:list'?: unknown
+  [key: `on:${string}`]: unknown
+  [key: `bind:${string}`]: unknown
+  [key: `ref:${string}`]: unknown
+  [key: `class:${string}`]: unknown
+  [key: `style:${string}`]: unknown
+}
+
+/** ARIA — `role` plus the open-ended `aria-*` family. */
+export interface AriaAttributes {
+  role?: string
+  [key: `aria-${string}`]: unknown
+}
+
+/** Global attributes present on every HTML element (a lean subset). Numeric
+ *  attributes accept `string` too, since templates write them as strings. */
+export interface GlobalHTMLAttributes {
+  class?: string
+  id?: string
+  style?: string
+  title?: string
+  hidden?: boolean
+  tabindex?: number | string
+  lang?: string
+  dir?: 'ltr' | 'rtl' | 'auto'
+  draggable?: boolean | 'true' | 'false'
+  popover?: boolean | string
+  /** Stator named-slot target — `child="header"` fills `<children name="header"/>`. */
+  child?: string
+  [key: `data-${string}`]: unknown
+}
+
+/** Per-element extra attributes. Extend as components need them. */
+export interface ElementSpecificAttributes {
+  a: { href?: string; target?: string; rel?: string; download?: string | boolean }
+  button: {
+    type?: 'submit' | 'reset' | 'button'
+    disabled?: boolean
+    name?: string
+    value?: string
+    form?: string
+    autofocus?: boolean
+    popovertarget?: string
+    popovertargetaction?: 'show' | 'hide' | 'toggle'
+  }
+  input: {
+    type?: string
+    name?: string
+    value?: string | number
+    placeholder?: string
+    disabled?: boolean
+    required?: boolean
+    readonly?: boolean
+    checked?: boolean
+    min?: string | number
+    max?: string | number
+    step?: string | number
+    minlength?: number | string
+    maxlength?: number | string
+    pattern?: string
+    autocomplete?: string
+    inputmode?: string
+    autofocus?: boolean
+  }
+  label: { for?: string }
+  form: {
+    action?: string
+    method?: 'get' | 'post' | 'GET' | 'POST' | 'dialog'
+    novalidate?: boolean
+  }
+  select: {
+    name?: string
+    disabled?: boolean
+    required?: boolean
+    multiple?: boolean
+    value?: string | number
+  }
+  option: { value?: string | number; selected?: boolean; disabled?: boolean }
+  textarea: {
+    name?: string
+    placeholder?: string
+    rows?: number | string
+    cols?: number | string
+    disabled?: boolean
+    required?: boolean
+    readonly?: boolean
+    minlength?: number | string
+    maxlength?: number | string
+  }
+  img: {
+    src?: string
+    alt?: string
+    width?: number | string
+    height?: number | string
+    loading?: 'eager' | 'lazy'
+  }
+}
+
+/**
+ * The attribute type for a native element `Tag`. Intersect it in a component's
+ * props to forward native attributes:
+ *
+ *   const { variant, ...rest } =
+ *     Stator.props<HTMLAttributes<'button'> & { variant: 'primary' | 'danger' }>()
+ *
+ * `Tag` defaults to the shared base (global + ARIA + directives) for elements not
+ * in the per-element map. HTML attribute values are `Reactive` (literal or live
+ * binding); directives keep their own value types.
+ */
+export type HTMLAttributes<Tag extends string = string> = Reactivize<
+  GlobalHTMLAttributes &
+    AriaAttributes &
+    (Tag extends keyof ElementSpecificAttributes
+      ? ElementSpecificAttributes[Tag]
+      : Record<never, never>)
+> &
+  StatorDirectiveAttributes
+
+/**
+ * The per-element intrinsic map wired into `JSX.IntrinsicElements`, so a typo on
+ * a plain `<button typ=>` is a real error. Common HTML tags are typed;
+ * the `[tag: string]: any` fallback keeps custom elements (client-island tags
+ * like `<live-sky>`) and everything not listed (SVG, rare tags) permissive — the
+ * escape valve that stops the typing from flooding real templates. Every explicit
+ * entry is assignable to `any`, so the index signature is satisfied.
+ */
+export interface StatorIntrinsicElements {
+  a: HTMLAttributes<'a'>
+  button: HTMLAttributes<'button'>
+  input: HTMLAttributes<'input'>
+  select: HTMLAttributes<'select'>
+  option: HTMLAttributes<'option'>
+  textarea: HTMLAttributes<'textarea'>
+  label: HTMLAttributes<'label'>
+  form: HTMLAttributes<'form'>
+  img: HTMLAttributes<'img'>
+  div: HTMLAttributes<'div'>
+  span: HTMLAttributes<'span'>
+  p: HTMLAttributes<'p'>
+  h1: HTMLAttributes<'h1'>
+  h2: HTMLAttributes<'h2'>
+  h3: HTMLAttributes<'h3'>
+  h4: HTMLAttributes<'h4'>
+  h5: HTMLAttributes<'h5'>
+  h6: HTMLAttributes<'h6'>
+  ul: HTMLAttributes<'ul'>
+  ol: HTMLAttributes<'ol'>
+  li: HTMLAttributes<'li'>
+  nav: HTMLAttributes<'nav'>
+  header: HTMLAttributes<'header'>
+  footer: HTMLAttributes<'footer'>
+  section: HTMLAttributes<'section'>
+  main: HTMLAttributes<'main'>
+  article: HTMLAttributes<'article'>
+  aside: HTMLAttributes<'aside'>
+  strong: HTMLAttributes<'strong'>
+  em: HTMLAttributes<'em'>
+  small: HTMLAttributes<'small'>
+  code: HTMLAttributes<'code'>
+  pre: HTMLAttributes<'pre'>
+  time: HTMLAttributes<'time'>
+  cite: HTMLAttributes<'cite'>
+  hr: HTMLAttributes<'hr'>
+  br: HTMLAttributes<'br'>
+  figure: HTMLAttributes<'figure'>
+  figcaption: HTMLAttributes<'figcaption'>
+  details: HTMLAttributes<'details'>
+  summary: HTMLAttributes<'summary'>
+  dialog: HTMLAttributes<'dialog'>
+  table: HTMLAttributes<'table'>
+  thead: HTMLAttributes<'thead'>
+  tbody: HTMLAttributes<'tbody'>
+  tr: HTMLAttributes<'tr'>
+  td: HTMLAttributes<'td'>
+  th: HTMLAttributes<'th'>
+  fieldset: HTMLAttributes<'fieldset'>
+  legend: HTMLAttributes<'legend'>
+  // biome-ignore lint/suspicious/noExplicitAny: escape valve — custom-element islands, SVG, and unlisted tags stay fully permissive; every explicit entry above is assignable to this index signature.
+  [tag: string]: any
+}

package/src/template/html.ts

@@ -127,7 +127,17 @@ function processValue(builder: HtmlBuilder, state: RenderState, value: unknown):
     return
   }
   if (pos.kind === 'attr-value') {
-    builder.pushRaw(escapeAttribute(sanitizeAttrValue(pos.attrName, stringifyValue(value))))
+    // Same boolean semantics as the read-binding and item-read paths:
+    // false/null/undefined → attribute ABSENT (`checked={expr}` must be able
+    // to render unchecked; a static render must agree with what a live patch
+    // of the same attribute would do), true → present-and-empty. Previously
+    // this path stringified — `checked={false}` rendered `checked="false"`,
+    // a PRESENT (thus truthy) boolean attribute.
+    if (value === false || value === null || value === undefined) {
+      builder.omitCurrentAttribute()
+    } else if (value !== true) {
+      builder.pushRaw(escapeAttribute(sanitizeAttrValue(pos.attrName, stringifyValue(value))))
+    }
     return
   }
   throw new Error(`stator: cannot interpolate a plain value at ${pos.kind} position`)

package/src/template/index.ts

@@ -22,9 +22,20 @@ export {
 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 { SpreadAttrs } from './directives/spread.ts'
+export { spreadAttrs } from './directives/spread.ts'
 export type { EachResult } from './each.ts'
 export { each, isEachResult, itemBind, renderListBody } from './each.ts'
 export { html, raw } from './html.ts'
+export type {
+  AriaAttributes,
+  ElementSpecificAttributes,
+  GlobalHTMLAttributes,
+  HTMLAttributes,
+  Reactive,
+  StatorDirectiveAttributes,
+  StatorIntrinsicElements,
+} from './html-attributes.ts'
 export type { ReadResult } from './read.ts'
 export { isReadResult, read } from './read.ts'
 export type { HtmlFragment, InstanceOf } from './types.ts'

package/src/template/types.ts

@@ -1,15 +1,27 @@
-import type { AnyMachineDef, InstanceOf as SelectorsOf } from '../engine/index.ts'
+import type {
+  AnyMachineDef,
+  EventOf,
+  InstanceOf as SelectorsOf,
+  StateNameOf,
+} from '../engine/index.ts'
 import type { EventDescriptor } from '../server/render-context.ts'
 
 /**
  * The template-facing shape of a machine instance: the engine's selector view
  * (each selector as a property carrying its return type, callable if it returns
- * a function) plus the framework-provided `send` / `state` / `snapshot`.
+ * a function) plus the framework-provided `send` / `state` / `snapshot`. Both
+ * `state` (the state-name union) and `send` (the event union) are typed to the
+ * machine's own def, so `s.state === 'ready'` and `m.send({ type: 'SAVE', … })`
+ * autocomplete and a typo — in the name or the payload — is a compile error.
  */
-export type InstanceOf<TDef extends AnyMachineDef> = SelectorsOf<TDef> & InstanceCommon
+export type InstanceOf<TDef extends AnyMachineDef> = SelectorsOf<TDef> &
+  InstanceCommon<StateNameOf<TDef>, EventOf<TDef>>
 
-export interface InstanceCommon<TStateKey extends string = string> {
-  send(event: { type: string; [k: string]: unknown }): EventDescriptor | undefined
+export interface InstanceCommon<
+  TStateKey extends string = string,
+  TEvent = { type: string; [k: string]: unknown },
+> {
+  send(event: TEvent): EventDescriptor | undefined
   readonly state: TStateKey
   readonly snapshot: unknown
 }

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