@playfast/reform-remote 0.0.2 → 0.0.4

package/src/server.test.ts

@@ -0,0 +1,331 @@
+import { createElement, Fragment, type ReactNode } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { expect, test } from 'vitest'
+import { Option } from 'effect'
+import { Ui, Wire } from '@playfast/reform'
+import type { WireNode, WirePatch, WireProp, WireTree } from '@playfast/reform'
+import { makeRemoteServer } from './server'
+import { remoteViews, renderWireTree } from './client'
+import {
+  bumpedBy,
+  CounterUi,
+  counterScene,
+  listScene,
+  OptionalUi,
+  optionScene,
+  slottedScene,
+  structureCounterScene,
+} from './fixtures'
+
+// The client renders views as React components, so a test runs them by RENDERING
+// `renderWireTree`'s output (node, no DOM needed) — the views capture as they render.
+const draw = (node: ReactNode): void => void renderToStaticMarkup(createElement(Fragment, null, node))
+
+const dataOf = (node: WireNode, name: string): WireProp | undefined =>
+  node.props.find((prop) => prop._tag === 'Data' && prop.name === name)
+
+const eventOf = (node: WireNode, name: string): Extract<WireProp, { _tag: 'Event' }> | undefined =>
+  node.props.find((prop): prop is Extract<WireProp, { _tag: 'Event' }> => prop._tag === 'Event' && prop.name === name)
+
+const byId = (tree: WireTree, id: string): WireNode | undefined => tree.find((node) => node.id === id)
+
+const upsertIds = (patches: ReadonlyArray<WirePatch>): ReadonlyArray<string> =>
+  patches.flatMap((patch) => (patch._tag === 'Upsert' ? [patch.node.id] : []))
+
+const deleteIds = (patches: ReadonlyArray<WirePatch>): ReadonlyArray<string> =>
+  patches.flatMap((patch) => (patch._tag === 'Delete' ? [patch.id] : []))
+
+// ── flat counter ──────────────────────────────────────────────────────────────
+
+test('a scene renders to a wire tree with schema-encoded props and a trigger handle', async () => {
+  const server = makeRemoteServer(counterScene())
+  try {
+    const tree = await server.render()
+    expect(tree).toHaveLength(1)
+    const root = tree[0]!
+    expect(root.id).toBe('0')
+    expect(root.name).toBe('Counter')
+    expect(root.parentId).toBeNull()
+    expect(dataOf(root, 'count')).toEqual({ _tag: 'Data', name: 'count', value: 0 })
+    expect(eventOf(root, 'bump')).toEqual({ _tag: 'Event', name: 'bump', handle: '0:bump' })
+  } finally {
+    await server.dispose()
+  }
+})
+
+test('invoking a trigger handle dispatches into the runtime and the next render reflects it', async () => {
+  const server = makeRemoteServer(counterScene())
+  try {
+    await server.render()
+    await server.invoke('0:bump', { by: 5 })
+    await server.invoke('0:bump', { by: 2 })
+    const tree = await server.render()
+    expect(dataOf(tree[0]!, 'count')).toEqual({ _tag: 'Data', name: 'count', value: 7 })
+  } finally {
+    await server.dispose()
+  }
+})
+
+// ── structure-path counter: events ride ON the structure (plan 03b) ─────────────
+
+test('a mount(...)-returning body registers its event from structure.events and invoking it dispatches', async () => {
+  const server = makeRemoteServer(structureCounterScene())
+  try {
+    const tree = await server.render()
+    const root = tree[0]!
+    expect(root.name).toBe('Counter')
+    // Props come from the structure value; the `bump` trigger rode on
+    // `structure.events` and was registered behind the standard handle.
+    expect(dataOf(root, 'count')).toEqual({ _tag: 'Data', name: 'count', value: 0 })
+    expect(eventOf(root, 'bump')).toEqual({ _tag: 'Event', name: 'bump', handle: '0:bump' })
+
+    await server.invoke('0:bump', { by: 4 })
+    const next = await server.render()
+    expect(dataOf(next[0]!, 'count')).toEqual({ _tag: 'Data', name: 'count', value: 4 })
+  } finally {
+    await server.dispose()
+  }
+})
+
+test('the wire payload is validated at the seam — a bad payload rejects', async () => {
+  const server = makeRemoteServer(counterScene())
+  try {
+    await server.render()
+    await expect(server.invoke('0:bump', { by: 'nope' })).rejects.toBeDefined()
+  } finally {
+    await server.dispose()
+  }
+})
+
+test('renderDiff streams patches a client folds back to the current tree', async () => {
+  const server = makeRemoteServer(counterScene())
+  try {
+    const first = await server.renderDiff()
+    const afterFirst = Wire.apply([], first)
+    expect(dataOf(afterFirst[0]!, 'count')).toEqual({ _tag: 'Data', name: 'count', value: 0 })
+
+    await server.invoke('0:bump', { by: 3 })
+    const second = await server.renderDiff()
+    expect(second).toHaveLength(1)
+    expect(second[0]?._tag).toBe('Upsert')
+    const afterSecond = Wire.apply(afterFirst, second)
+    expect(dataOf(afterSecond[0]!, 'count')).toEqual({ _tag: 'Data', name: 'count', value: 3 })
+  } finally {
+    await server.dispose()
+  }
+})
+
+test('end to end: client reconstructs props + event callbacks that drive the server', async () => {
+  const server = makeRemoteServer(counterScene())
+  const captured: { props?: Record<string, unknown>; events?: Record<string, (p: { by: number }) => void> } = {}
+  const sent: Array<[string, unknown]> = []
+  try {
+    const tree = await server.render()
+    draw(
+      renderWireTree(tree, {
+        views: remoteViews<{ Counter: typeof CounterUi }>({
+          Counter: Ui.make(CounterUi, (props, _slots, events) => {
+            captured.props = props
+            captured.events = events
+            return null
+          }),
+        }),
+        invoke: (handle, payload) => void sent.push([handle, payload]),
+      }),
+    )
+
+    expect(captured.props).toEqual({ count: 0 })
+    captured.events?.['bump']?.({ by: 4 })
+    expect(sent).toEqual([['0:bump', { by: 4 }]])
+
+    await server.invoke(sent[0]![0], sent[0]![1])
+    const next = await server.render()
+    expect(dataOf(next[0]!, 'count')).toEqual({ _tag: 'Data', name: 'count', value: 4 })
+  } finally {
+    await server.dispose()
+  }
+})
+
+test('boot events are applied before the first render', async () => {
+  const server = makeRemoteServer(counterScene([bumpedBy(10), bumpedBy(5)]))
+  try {
+    const tree = await server.render()
+    expect(dataOf(tree[0]!, 'count')).toEqual({ _tag: 'Data', name: 'count', value: 15 })
+  } finally {
+    await server.dispose()
+  }
+})
+
+// ── nested slot: a child with its own state, two events ─────────────────────────
+
+test('a slotted child renders nested with its own encoded props and handle', async () => {
+  const server = makeRemoteServer(slottedScene())
+  try {
+    const tree = await server.render()
+    expect(tree).toHaveLength(2)
+
+    const shell = byId(tree, '0')!
+    expect(shell.name).toBe('Shell')
+    expect(shell.parentId).toBeNull()
+
+    const panel = byId(tree, '0.Main.0')!
+    expect(panel.name).toBe('Panel')
+    expect(panel.parentId).toBe('0')
+    expect(panel.slot).toBe('Main')
+    expect(panel.childIndex).toBe(0)
+    expect(dataOf(panel, 'greeting')).toEqual({ _tag: 'Data', name: 'greeting', value: 'hi' })
+    expect(eventOf(panel, 'greet')?.handle).toBe('0.Main.0:greet')
+  } finally {
+    await server.dispose()
+  }
+})
+
+test("invoking a nested child's trigger updates the child's own state", async () => {
+  const server = makeRemoteServer(slottedScene())
+  try {
+    await server.render()
+    await server.invoke('0.Main.0:greet', { text: 'yo' })
+    const tree = await server.render()
+    expect(dataOf(byId(tree, '0.Main.0')!, 'greeting')).toEqual({
+      _tag: 'Data',
+      name: 'greeting',
+      value: 'yo',
+    })
+  } finally {
+    await server.dispose()
+  }
+})
+
+test('two events on one node register distinct handles and each fires independently', async () => {
+  const server = makeRemoteServer(slottedScene())
+  try {
+    await server.render()
+    const before = byId(await server.render(), '0.Main.0')!
+    expect(eventOf(before, 'greet')?.handle).toBe('0.Main.0:greet')
+    expect(eventOf(before, 'clear')?.handle).toBe('0.Main.0:clear')
+
+    await server.invoke('0.Main.0:greet', { text: 'hello' })
+    expect(dataOf(byId(await server.render(), '0.Main.0')!, 'greeting')).toMatchObject({ value: 'hello' })
+
+    await server.invoke('0.Main.0:clear', {})
+    expect(dataOf(byId(await server.render(), '0.Main.0')!, 'greeting')).toMatchObject({ value: '' })
+  } finally {
+    await server.dispose()
+  }
+})
+
+// ── dynamic list: add (upsert), remove (delete + handle revocation) ─────────────
+
+test('a list renders one child per item under a single slot, in order', async () => {
+  const server = makeRemoteServer(listScene())
+  try {
+    const tree = await server.render()
+    // List + Bar + two items.
+    expect(tree).toHaveLength(4)
+    expect(byId(tree, '0')!.name).toBe('List')
+    expect(byId(tree, '0.Bar.0')!.slot).toBe('Bar')
+
+    const items = Wire.childrenOf(tree, '0').filter((node) => node.slot === 'Item')
+    expect(items.map((node) => node.id)).toEqual(['0.Item.0', '0.Item.1'])
+    expect(items.map((node) => node.childIndex)).toEqual([0, 1])
+    expect(dataOf(items[0]!, 'label')).toMatchObject({ value: 'A' })
+    expect(dataOf(items[1]!, 'label')).toMatchObject({ value: 'B' })
+  } finally {
+    await server.dispose()
+  }
+})
+
+test('adding an item emits an Upsert for the new node; removing emits a Delete', async () => {
+  const server = makeRemoteServer(listScene())
+  try {
+    await server.renderDiff() // first frame (snapshot baseline)
+
+    await server.invoke('0.Bar.0:add', { id: 'c', label: 'C' })
+    const added = await server.renderDiff()
+    expect(deleteIds(added)).toEqual([])
+    expect(upsertIds(added)).toContain('0.Item.2')
+
+    // Remove the last item — exactly its node leaves the tree.
+    await server.invoke('0.Item.2:remove', {})
+    const removed = await server.renderDiff()
+    expect(deleteIds(removed)).toEqual(['0.Item.2'])
+  } finally {
+    await server.dispose()
+  }
+})
+
+test("a removed node's handle is revoked — a stale client invocation rejects", async () => {
+  const server = makeRemoteServer(listScene())
+  try {
+    await server.renderDiff()
+    // The handle works while the item is mounted…
+    await server.invoke('0.Item.1:remove', {})
+    await server.renderDiff() // item 'b' gone → its handle revoked
+    // …and fails cleanly once the node has been unmounted.
+    await expect(server.invoke('0.Item.1:remove', {})).rejects.toBeDefined()
+  } finally {
+    await server.dispose()
+  }
+})
+
+// ── Option props: Effect-native values survive the wire as real instances ───────
+
+test('an Option prop round-trips through JSON as a real Option (symmetric schema decode)', async () => {
+  const server = makeRemoteServer(optionScene(Option.some('hi')))
+  const captured: { label?: unknown } = {}
+  try {
+    const tree = await server.render()
+    // Round-trip the tree through JSON exactly as the real WebSocket transport does —
+    // the Option's `toJSON` flattens it to a plain `{_tag,value}` shape on the way out.
+    const wire: WireTree = JSON.parse(JSON.stringify(tree))
+    draw(
+      renderWireTree(wire, {
+        views: remoteViews<{ Optional: typeof OptionalUi }>({
+          Optional: Ui.make(OptionalUi, (props) => {
+            captured.label = props.label
+            return null
+          }),
+        }),
+        invoke: () => undefined,
+      }),
+    )
+    // The client decoded it back through the contract schema → a REAL Option instance.
+    expect(Option.isOption(captured.label)).toBe(true)
+    expect(captured.label).toStrictEqual(Option.some('hi'))
+  } finally {
+    await server.dispose()
+  }
+})
+
+test('an Option.none prop round-trips through JSON as Option.none()', async () => {
+  const server = makeRemoteServer(optionScene(Option.none()))
+  const captured: { label?: unknown } = {}
+  try {
+    const wire: WireTree = JSON.parse(JSON.stringify(await server.render()))
+    draw(
+      renderWireTree(wire, {
+        views: remoteViews<{ Optional: typeof OptionalUi }>({
+          Optional: Ui.make(OptionalUi, (props) => ((captured.label = props.label), null)),
+        }),
+        invoke: () => undefined,
+      }),
+    )
+    expect(captured.label).toStrictEqual(Option.none())
+  } finally {
+    await server.dispose()
+  }
+})
+
+test('a data-only change upserts only the changed node, leaving siblings untouched', async () => {
+  const server = makeRemoteServer(slottedScene())
+  try {
+    await server.renderDiff()
+    await server.invoke('0.Main.0:greet', { text: 'changed' })
+    const patches = await server.renderDiff()
+    // Only the panel changed; the shell is unchanged, so no patch for it.
+    expect(upsertIds(patches)).toEqual(['0.Main.0'])
+    expect(deleteIds(patches)).toEqual([])
+  } finally {
+    await server.dispose()
+  }
+})

package/src/server.ts

@@ -0,0 +1,343 @@
+import { Effect, Layer, Match, ManagedRuntime, type ParseResult, PubSub, Queue, Schema } from 'effect'
+import {
+  Bus,
+  Composition,
+  type CompositionClass,
+  type CompositionService,
+  forceSync,
+  isFeatureBinding,
+  isStructure,
+  publish,
+  type RenderEnv,
+  type Scene,
+  type SlotChild,
+  type SlotClass,
+  type SlotFill,
+  type Structure,
+  Triggers,
+  type Trigger,
+  type TriggerRegistryApi,
+  type UiContract,
+  type UiManifest,
+  Wire,
+  type WireNode,
+  type WirePatch,
+  type WireProp,
+  type WireTree,
+} from '@playfast/reform'
+
+/**
+ * The server side of the remote transport (REMOTE_UI.md §5): render a closed
+ * `Scene` to a serializable `WireTree`, registering each trigger behind a handle.
+ * Reads each composition's returned `Structure` value directly — props, per-slot
+ * fills, and event triggers are all DATA — so the server imports no React and never
+ * evaluates a view. The render walk is breadth-first over the structure tree,
+ * assigning stable ids and encoding props via each contract's own wire schema
+ * (`WiredUiManifest`, Phase 1).
+ */
+
+// The runtime services a closed scene exposes (mirrors proof's erasure boundary:
+// the scene's `provide` is typed to `MountedServices`, but slot tags resolve
+// `SlotChild` from the same closed layer).
+type RuntimeServices = CompositionService | SlotChild | Bus
+
+const SETTLE_DRAIN = 30
+const settleDrain = Effect.yieldNow().pipe(Effect.repeatN(SETTLE_DRAIN))
+
+// The event triggers a `Structure` frame carries (plan 03b). A composition's logic
+// returns its acquired triggers ON the structure value (it never evaluates a view),
+// so the server reads them straight from there. At the erased `UiContract` boundary the contract's event map
+// is `Record<never, never>`, so each value is `never` — assignable to
+// `Trigger<unknown>` without a cast — and an omitted `events` defaults to empty.
+const eventsOf = (structure: Structure<UiContract>): Record<string, Trigger<unknown>> =>
+  Object.fromEntries(Object.entries(structure.events ?? {}))
+
+const closedSceneLayer = (scene: Scene): Layer.Layer<RuntimeServices, never, never> =>
+  scene.provide.reduce((a, b) => Layer.merge(a, b)) as unknown as Layer.Layer<
+    RuntimeServices,
+    never,
+    never
+  >
+
+/** A composition queued to render, with the props its parent handed it and its place in the tree. */
+interface Mounted {
+  readonly comp: CompositionClass<unknown>
+  readonly props: unknown
+  readonly id: string
+  readonly parentId: string | null
+  readonly slot: string | null
+  readonly childIndex: number
+  /** The React `key` the parent gave this slot child, or `null` — the keyed-slot selector. */
+  readonly key: string | null
+}
+
+const childComposition = (child: SlotChild): CompositionClass<unknown> =>
+  isFeatureBinding(child) ? child.composition : child
+
+const handlesOf = (node: WireNode): ReadonlyArray<string> =>
+  node.props.flatMap((prop) => (prop._tag === 'Event' ? [prop.handle] : []))
+
+export interface RemoteServer {
+  /** Render the current frame to a full wire tree; triggers are (re-)registered behind stable handles. */
+  readonly render: () => Promise<WireTree>
+  /**
+   * Render and return only the patches since the previous frame (the streaming
+   * form). Handles of deleted nodes are revoked, so a stale client invocation
+   * fails cleanly rather than firing a dangling trigger.
+   */
+  readonly renderDiff: () => Promise<ReadonlyArray<WirePatch>>
+  /** Fire a trigger the client referenced by handle, then settle the runtime. */
+  readonly invoke: (handle: string, encodedPayload: unknown) => Promise<void>
+  /**
+   * Observe SERVER-INITIATED state changes. The listener fires (after the drain
+   * settles) whenever an event flows on the engine bus — i.e. when an async procedure
+   * resolves, a boot loader completes, or a scheduler ticks — NOT just in response to a
+   * client invoke. `serve` registers a `renderDiff`-and-push listener here so the client
+   * sees background updates (a repo list that finishes loading, a reconcile sweep) that
+   * no user interaction triggered. Returns an unsubscribe handle.
+   */
+  readonly subscribe: (listener: () => void) => () => void
+  /** Tear down the runtime and its forked fibers. */
+  readonly dispose: () => Promise<void>
+}
+
+export const makeRemoteServer = (scene: Scene): RemoteServer => {
+  const runtime = ManagedRuntime.make(closedSceneLayer(scene))
+  const registry: TriggerRegistryApi = forceSync(() => runtime.runSync(Triggers.make))
+
+  const collect = (
+    root: CompositionClass<unknown>,
+  ): Effect.Effect<Map<SlotClass, CompositionClass<unknown>>, never, SlotChild> =>
+    Effect.gen(function* () {
+      const bindings = new Map<SlotClass, CompositionClass<unknown>>()
+      const walk = (comp: CompositionClass<unknown>): Effect.Effect<void, never, SlotChild> =>
+        Effect.gen(function* () {
+          for (const slotClass of Object.values(comp.manifest.slots ?? {})) {
+            if (bindings.has(slotClass)) continue
+            const child = childComposition(yield* slotClass.tag)
+            bindings.set(slotClass, child)
+            yield* walk(child)
+          }
+        })
+      yield* walk(root)
+      return bindings
+    })
+
+  // Structure → wire encoding (plan 02 + 03b). Props come straight from the
+  // `Structure` value (data, never a view render). Event triggers ride ON the
+  // structure (`structure.events`) and are registered from there. Produces the wire
+  // shape the transport and `Wire.diff` consume.
+  const toWireNodeFromStructure = (
+    m: Mounted,
+    structure: Structure<UiContract>,
+  ): Effect.Effect<WireNode, ParseResult.ParseError> =>
+    Effect.gen(function* () {
+      const manifest = m.comp.manifest.ui.manifest as UiManifest
+      const name = manifest.name
+
+      const dataProps: WireProp[] = []
+      if (manifest.props !== undefined) {
+        const encoded = yield* Schema.encodeUnknown(manifest.props)(structure.props)
+        for (const [propName, value] of Object.entries(encoded as Record<string, unknown>)) {
+          dataProps.push({ _tag: 'Data', name: propName, value })
+        }
+      }
+
+      const eventSchemas = manifest.events ?? {}
+      const eventProps: WireProp[] = []
+      const events = eventsOf(structure)
+      for (const [eventName, trigger] of Object.entries(events)) {
+        const schema = eventSchemas[eventName]
+        if (schema === undefined) continue
+        const handle = `${m.id}:${eventName}`
+        yield* registry.register(handle, trigger, schema)
+        eventProps.push({ _tag: 'Event', name: eventName, handle })
+      }
+
+      return {
+        id: m.id,
+        name,
+        parentId: m.parentId,
+        childIndex: m.childIndex,
+        slot: m.slot,
+        key: m.key,
+        props: [...dataProps, ...eventProps],
+      }
+    })
+
+  // Narrow an erased slot value to a `SlotFill` by its discriminant. `Structure<
+  // UiContract>` erases its per-slot fill types at this boundary (the strict typing
+  // lives on the concrete contract), so the runtime fills arrive as `unknown` and
+  // are recovered structurally — no `as`.
+  const isSlotFill = (u: unknown): u is SlotFill<unknown> =>
+    typeof u === 'object' &&
+    u !== null &&
+    '_tag' in u &&
+    (u._tag === 'Each' || u._tag === 'One' || u._tag === 'Absent')
+
+  // Read a structure's fills by slot name, recovering each erased value via the
+  // discriminant guard. Returns a plain record keyed by declared slot name.
+  const structureFills = (structure: Structure<UiContract>): Record<string, SlotFill<unknown>> =>
+    Object.fromEntries(
+      Object.entries(structure.slots).flatMap(([name, value]) =>
+        isSlotFill(value) ? [[name, value] as const] : [],
+      ),
+    )
+
+  // Enqueue the children a single declared slot is filled with, reading the fill
+  // (Each / One / Absent) from the returned `Structure`. Multiplicity, per-item
+  // `key`, and props are carried as data — no view walk, no reconstruction.
+  const enqueueStructureSlot = (
+    parent: Mounted,
+    slotName: string,
+    child: CompositionClass<unknown>,
+    fill: SlotFill<unknown>,
+    next: Mounted[],
+  ): void =>
+    Match.value(fill).pipe(
+      Match.tag('Each', (each) => {
+        each.items.forEach((item, index) => {
+          next.push({
+            comp: child,
+            props: item.props,
+            id: `${parent.id}.${slotName}.${index}`,
+            parentId: parent.id,
+            slot: slotName,
+            childIndex: index,
+            key: item.key,
+          })
+        })
+      }),
+      Match.tag('One', (single) => {
+        next.push({
+          comp: child,
+          props: single.props,
+          id: `${parent.id}.${slotName}.0`,
+          parentId: parent.id,
+          slot: slotName,
+          childIndex: 0,
+          key: null,
+        })
+      }),
+      Match.tag('Absent', () => {}),
+      Match.exhaustive,
+    )
+
+  const renderLevel = (
+    frontier: ReadonlyArray<Mounted>,
+    bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
+  ): Effect.Effect<ReadonlyArray<WireNode>, ParseResult.ParseError, CompositionService> =>
+    Effect.gen(function* () {
+      if (frontier.length === 0) return []
+      const next: Mounted[] = []
+      const nodes: WireNode[] = []
+      for (const mounted of frontier) {
+        const service = yield* mounted.comp.tag
+        const env: RenderEnv = { props: mounted.props, tracker: { add: () => {} } }
+        const frame = yield* Composition.render(service, env)
+        // Every composition returns a `Structure` (the Node render path is gone): its
+        // wire node's props come from `frame.props`, event triggers from `frame.events`,
+        // and children are enqueued by reading each declared slot's fill — no view eval.
+        if (!isStructure(frame)) {
+          return yield* Effect.dieMessage(
+            `reform-remote server: composition ${mounted.comp.manifest.name} did not return a Structure`,
+          )
+        }
+        nodes.push(yield* toWireNodeFromStructure(mounted, frame))
+        const fills = structureFills(frame)
+        for (const [slotName, slotClass] of Object.entries(mounted.comp.manifest.slots ?? {})) {
+          const child = bindings.get(slotClass)
+          if (child === undefined) continue
+          const fill = fills[slotName]
+          if (fill === undefined) continue
+          enqueueStructureSlot(mounted, slotName, child, fill, next)
+        }
+      }
+      const rest = yield* renderLevel(next, bindings)
+      return [...nodes, ...rest]
+    })
+
+  const renderEffect = Effect.gen(function* () {
+    yield* settleDrain
+    const bindings = yield* collect(scene.composition)
+    const root: Mounted = {
+      comp: scene.composition,
+      props: {},
+      id: '0',
+      parentId: null,
+      slot: null,
+      childIndex: 0,
+      key: null,
+    }
+    return yield* renderLevel([root], bindings)
+  })
+
+  // Server-initiated change notification: a forked daemon subscribes to the engine bus
+  // and, after each batch settles, fans out to registered listeners. This is what lets a
+  // streaming binding push frames the client never asked for — a background load resolving
+  // long after connect. Forked BEFORE the boot publish below so nothing is missed (the
+  // listener set is empty until `subscribe` runs, so early ticks are harmless no-ops; the
+  // binding's opening snapshot captures all state up to `start`).
+  const changeListeners = new Set<() => void>()
+  const notifyChange = (): void => {
+    for (const listener of changeListeners) listener()
+  }
+  runtime.runFork(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const bus = yield* Bus
+        const subscription = yield* PubSub.subscribe(bus)
+        // Notify on each event; the consumer (`serve`) debounces, so the render it triggers
+        // runs a tick later — after the drain has folded this event into state. No settle
+        // here: it would only perturb the drain's own scheduling for no benefit.
+        yield* Queue.take(subscription).pipe(
+          Effect.zipRight(Effect.sync(notifyChange)),
+          Effect.forever,
+        )
+      }),
+    ),
+  )
+
+  runtime.runSync(Effect.forEach(scene.boot ?? [], (event) => publish('High', event)))
+
+  // The last emitted frame, to diff against. A const holder whose field we swap
+  // (no reassigned binding — house rule), not a `let`.
+  const frame: { tree: WireTree } = { tree: [] }
+
+  const render = (): Promise<WireTree> =>
+    runtime.runPromise(renderEffect).then((tree) => {
+      frame.tree = tree
+      return tree
+    })
+
+  const renderDiff = (): Promise<ReadonlyArray<WirePatch>> =>
+    runtime.runPromise(renderEffect).then((next) => {
+      const previous = frame.tree
+      const patches = Wire.diff(previous, next)
+      frame.tree = next
+      const nextIds = new Set(next.map((node) => node.id))
+      const staleHandles = previous
+        .filter((node) => !nextIds.has(node.id))
+        .flatMap(handlesOf)
+      return runtime
+        .runPromise(Effect.forEach(staleHandles, (handle) => registry.revoke(handle)))
+        .then(() => patches)
+    })
+
+  return {
+    render,
+    renderDiff,
+    invoke: (handle, encodedPayload) =>
+      runtime.runPromise(
+        Effect.gen(function* () {
+          yield* registry.invoke(handle, encodedPayload)
+          yield* settleDrain
+        }),
+      ),
+    subscribe: (listener) => {
+      changeListeners.add(listener)
+      return () => void changeListeners.delete(listener)
+    },
+    dispose: () => runtime.dispose(),
+  }
+}