@playfast/reform-remote 1.0.1 → 1.1.0

package/src/transport.test.ts

@@ -9,18 +9,11 @@ import { inMemoryTransportPair } from './memory'
 import { remoteViews } from './client'
 import { asyncCounterScene, CounterUi, counterScene } from './fixtures'
 
-// The client renders views as React components (so view-body hooks work), so a test
-// must actually RENDER `client.node()` to run the views — `draw` forces that pass
-// (node, no DOM needed) and the probe captures what each view received.
-const draw = (node: ReactNode): void => void renderToStaticMarkup(createElement(Fragment, null, node))
-
-// A presentation that records the props/events handed to it, so a test can read
-// what the client reconstructed and fire the callbacks back at the server. It is a
-// regular `Ui.make` view (the only client authoring form), bound to the contract.
+const draw = (node: ReactNode): void =>
+  void renderToStaticMarkup(createElement(Fragment, null, node))
+
 interface Probe {
   props?: Record<string, unknown>
-  // The counter contract's only event, `bump`, takes `{ by: number }`; typing the
-  // record to that payload lets the strongly-typed `Ui.make` events assign in.
   events?: Record<string, (payload: { by: number }) => void>
 }
 const probeView = (probe: Probe) =>
@@ -64,8 +57,6 @@ test('server-initiated state change streams to the client with NO invoke (backgr
     InvokeMessage
   >()
 
-  // Count outbound client→server messages: the whole point is that the new frame arrives
-  // without the client invoking anything. A non-zero count would mean the test cheated.
   const invokes = { count: 0 }
   const countingClientTransport = {
     ...clientTransport,
@@ -80,8 +71,6 @@ test('server-initiated state change streams to the client with NO invoke (backgr
     transport: countingClientTransport,
     views: remoteViews<{ Counter: typeof CounterUi }>({ Counter: probeView(probe) }),
   })
-  // The scene's procedure sleeps, THEN bumps to 7 — so the snapshot is count:0 and the
-  // change can only reach the client via a server-pushed diff.
   const server = serve({ scene: asyncCounterScene('30 millis'), transport: serverTransport })
   try {
     await server.start()
@@ -92,7 +81,6 @@ test('server-initiated state change streams to the client with NO invoke (backgr
       draw(client.node())
       expect(probe.props).toEqual({ count: 7 })
     })
-    // The client never sent a single Invoke — the frame was entirely server-initiated.
     expect(invokes.count).toBe(0)
   } finally {
     client.dispose()
@@ -127,12 +115,10 @@ test('a fresh Snapshot replaces the client tree — stale nodes are dropped (rec
     props: [],
   })
 
-  // First session: two roots.
   serverTransport.send({ _tag: 'Snapshot', tree: [node('a', 'A'), node('b', 'B')] })
   draw(client.node())
   expect(rendered).toEqual(['A', 'B'])
 
-  // Reconnect: a fresh snapshot with only one root must drop the stale 'B'.
   rendered.length = 0
   serverTransport.send({ _tag: 'Snapshot', tree: [node('a', 'A')] })
   draw(client.node())
@@ -160,7 +146,6 @@ test('two clients each get their own server runtime — state is isolated', asyn
   try {
     await serverOne.start()
     await serverTwo.start()
-    // Render once so each probe captures its event callbacks.
     draw(clientOne.node())
     draw(clientTwo.node())
 
@@ -170,7 +155,6 @@ test('two clients each get their own server runtime — state is isolated', asyn
       expect(probeOne.props).toEqual({ count: 9 })
     })
 
-    // The second client's runtime never saw that bump.
     draw(clientTwo.node())
     expect(probeTwo.props).toEqual({ count: 0 })
   } finally {
@@ -196,12 +180,10 @@ test('serveShared: two clients share ONE runtime — one client drives state for
     views: remoteViews<{ Counter: typeof CounterUi }>({ Counter: probeView(probeTwo) }),
   })
 
-  // One shared server; both transports attach to the same runtime.
   const shared = serveShared({ scene: counterScene() })
   const handleOne = shared.addClient(one.server)
   const handleTwo = shared.addClient(two.server)
   try {
-    // Both clients receive the opening snapshot off the shared baseline.
     await vi.waitFor(() => {
       draw(clientOne.node())
       draw(clientTwo.node())
@@ -209,7 +191,6 @@ test('serveShared: two clients share ONE runtime — one client drives state for
       expect(probeTwo.props).toEqual({ count: 0 })
     })
 
-    // A bump from client ONE is broadcast to BOTH — they share the same state.
     probeOne.events?.['bump']?.({ by: 5 })
     await vi.waitFor(() => {
       draw(clientOne.node())
@@ -218,7 +199,6 @@ test('serveShared: two clients share ONE runtime — one client drives state for
       expect(probeTwo.props).toEqual({ count: 5 })
     })
 
-    // And a bump from client TWO lands on the same shared counter.
     probeTwo.events?.['bump']?.({ by: 3 })
     await vi.waitFor(() => {
       draw(clientOne.node())
@@ -258,7 +238,6 @@ test('serveShared: a client connecting mid-stream snapshots the current shared s
       expect(probeOne.props).toEqual({ count: 4 })
     })
 
-    // A late joiner must see the CURRENT shared count (4), not a fresh 0.
     const two = inMemoryTransportPair<ServerMessage, InvokeMessage>()
     const probeTwo: Probe = {}
     const clientTwo = connect({
@@ -300,7 +279,5 @@ test('dispose detaches both ends: a post-dispose invoke no longer reaches the se
   await server.dispose()
   client.dispose()
 
-  // After dispose the server's onMessage handler is detached; firing the stale
-  // callback is a no-op rather than a throw.
   expect(() => probe.events?.['bump']?.({ by: 1 })).not.toThrow()
 })

package/src/transport.ts

@@ -1,89 +1,53 @@
 import { Effect, Fiber, Match, Option } from 'effect'
 import type { ReactNode } from 'react'
-import { Wire, type WirePatch, type WireTree } from '@playfast/reform'
-import type { Scene } from '@playfast/reform'
+import { type AnyScene, Wire, type WirePatch, type WireTree } from '@playfast/reform/internal'
 import { makeRemoteServer } from './server'
-import { renderWireTree, type ClientConfig, type RemoteContract, type RemoteViewSet } from './client'
+import {
+  renderWireTree,
+  type ClientConfig,
+  type RemoteContract,
+  type RemoteViewSet,
+} from './client'
 
-/**
- * Binds the server driver and the client renderer to a transport. The wire
- * carries only serializable data — patches one way, trigger invocations the
- * other — so any duplex channel (WebSocket, postMessage, in-memory) works; a
- * concrete adapter just implements `RemoteTransport`. See REMOTE_UI.md §5.
- */
-
-/**
- * Server → client: the full current tree, replacing whatever the client holds.
- * The first frame of every (re)connection — a fresh server runtime diffs from
- * empty, so it can only *add* nodes; a snapshot is what lets a reconnecting
- * client drop the stale tree it accumulated on the previous socket.
- */
 export interface SnapshotMessage {
   readonly _tag: 'Snapshot'
   readonly tree: WireTree
 }
 
-/** Server → client: a batch of tree patches to fold with `Wire.apply`. */
 export interface PatchesMessage {
   readonly _tag: 'Patches'
   readonly patches: ReadonlyArray<WirePatch>
 }
 
-/** Everything the server sends the client: a fresh snapshot or incremental patches. */
 export type ServerMessage = SnapshotMessage | PatchesMessage
 
-/** Client → server: fire the trigger behind `handle` with an encoded payload. */
 export interface InvokeMessage {
   readonly _tag: 'Invoke'
   readonly handle: string
   readonly payload: unknown
 }
 
-/** A duplex channel: send `Out`, receive `In`. */
 export interface RemoteTransport<Out, In> {
   readonly send: (message: Out) => void
   readonly onMessage: (handler: (message: In) => void) => () => void
 }
 
 export interface ServerBinding {
-  /** Render the first frame and push it. Call once the client is connected. */
   readonly start: () => Promise<void>
   readonly dispose: () => Promise<void>
 }
 
-/**
- * Debounce window for SERVER-initiated frame pushes (background loads, scheduler ticks).
- * Long enough that the engine drain has folded the change into state and a burst of facts
- * coalesces into one render; short enough to feel live. Client invokes don't wait on this —
- * they push immediately.
- */
 const BACKGROUND_FLUSH_MS = 16
 
-/** Options for {@link serve} — a single named object so every reform-remote binding shares one shape. */
 export interface ServeOptions {
-  readonly scene: Scene
+  readonly scene: AnyScene
   readonly transport: RemoteTransport<ServerMessage, InvokeMessage>
 }
 
 export const serve = (options: ServeOptions): ServerBinding => {
   const { scene, transport } = options
   const server = makeRemoteServer(scene)
-  // The first frame is a full snapshot (replace); every frame after is the diff since the
-  // last (apply). Both keep the server's `frame` baseline in step, so the diffs always
-  // reference what the client actually holds. Diffs are emitted both after a client invoke
-  // AND whenever the server's OWN state changes (a background load resolving, a scheduler
-  // tick) — without the latter, anything the user didn't directly trigger would never reach
-  // the client (it would sit on the snapshot's loading state forever).
-  //
-  // `started` gates pushes until the opening snapshot is sent: a diff that raced ahead of
-  // the snapshot would reference a tree the client has not received.
-  //
-  // `push` is a COALESCING single-flight render: at most one `renderDiff` runs at a time
-  // (concurrent ones would interleave the sink captures and corrupt the frame baseline). If
-  // a change arrives WHILE a render is in flight — e.g. an async procedure folds its result
-  // mid-render — `dirty` is set and a follow-up render runs when the current one settles, so
-  // a late state change is never dropped. Both a client invoke and a server-side change
-  // (the bus subscriber) funnel through here, so there is exactly one push path.
+  // Snapshot gates diffs; single-flight rendering protects the shared frame baseline.
   const started = { value: false }
   const flight = { promise: Option.none<Promise<void>>(), dirty: false }
   const push = (): Promise<void> => {
@@ -94,8 +58,7 @@ export const serve = (options: ServeOptions): ServerBinding => {
       flight.dirty = true
       return flight.promise.value
     }
-    // `Effect.ensuring` runs the settle/re-render cleanup whether the render succeeds or fails
-    // (the old `.finally`), so the single-flight slot is never left stuck.
+    // ensuring clears the single-flight slot even when rendering fails.
     const run = Effect.runPromise(
       Effect.gen(function* () {
         const patches = yield* Effect.promise(() => server.renderDiff())
@@ -117,12 +80,7 @@ export const serve = (options: ServeOptions): ServerBinding => {
     flight.promise = Option.some(run)
     return run
   }
-  // Server-initiated changes are flushed on a short DEBOUNCE rather than synchronously: it
-  // coalesces a burst (a procedure that dispatches several facts) into one render, and the
-  // delay lets the drain fold the change into state before we read it — so the diff reflects
-  // the settled result, and the background flush never races the synchronous invoke push
-  // above. A client invoke still pushes immediately (its own settle path), so user actions
-  // stay snappy; this path only carries updates no interaction triggered.
+  // Background debounce lets the drain settle and coalesces bursts without delaying invokes.
   const debounce = { fiber: Option.none<Fiber.RuntimeFiber<void>>() }
   const scheduleFlush = (): void => {
     if (!started.value || Option.isSome(debounce.fiber)) {
@@ -144,7 +102,6 @@ export const serve = (options: ServeOptions): ServerBinding => {
     const tree = await server.render()
     transport.send({ _tag: 'Snapshot', tree })
     started.value = true
-    // Flush anything that changed during the (async) opening render window.
     scheduleFlush()
   }
   const off = transport.onMessage((message) => {
@@ -168,40 +125,21 @@ export const serve = (options: ServeOptions): ServerBinding => {
   }
 }
 
-/** A client's membership in a {@link SharedServerBinding}; `remove` detaches it. */
 export interface SharedClientHandle {
-  /** Stop sending this client frames and drop its invoke listener. Call on disconnect. */
   readonly remove: () => void
 }
 
 export interface SharedServerBinding {
-  /**
-   * Attach a freshly-connected transport to the ONE shared runtime: send it a
-   * Snapshot of the current shared tree, then fold it into the broadcast set so
-   * every later frame — and every other client's invoke result — reaches it too.
-   * Returns a handle to detach the client when its socket closes.
-   */
-  readonly addClient: (transport: RemoteTransport<ServerMessage, InvokeMessage>) => SharedClientHandle
-  /** Tear down the shared runtime and drop every client. */
+  readonly addClient: (
+    transport: RemoteTransport<ServerMessage, InvokeMessage>,
+  ) => SharedClientHandle
   readonly dispose: () => Promise<void>
 }
 
-/** Options for {@link serveShared} — one scene, run once, shared by every client. */
 export interface ServeSharedOptions {
-  readonly scene: Scene
+  readonly scene: AnyScene
 }
 
-/**
- * The single-instance counterpart to {@link serve}: ONE `makeRemoteServer(scene)` —
- * one runtime, one trigger registry, one frame baseline — shared by every connected
- * client. A client's invoke fires on the shared runtime and the resulting diff is
- * broadcast to ALL clients, so every connection sees and drives the same state.
- *
- * Sync is structural: all clients hold the same baseline, so one render's diff applies
- * to all. A client connecting mid-stream snapshots off the live `currentTree()` (after
- * the opening render settles) and joins the broadcast set in the same tick — it never
- * misses or double-applies a frame.
- */
 export const serveShared = (options: ServeSharedOptions): SharedServerBinding => {
   const { scene } = options
   const server = makeRemoteServer(scene)
@@ -210,9 +148,7 @@ export const serveShared = (options: ServeSharedOptions): SharedServerBinding =>
     clients.forEach((client) => client.send(message))
   }
 
-  // The shared push loop: same coalescing single-flight as `serve`, but one render's
-  // patches fan out to EVERY client. `started` gates pushes until the opening render has
-  // set the baseline; `dirty` re-runs a render that a late change raced into mid-flight.
+  // One shared render baseline requires the same single-flight discipline as serve.
   const started = { value: false }
   const flight = { promise: Option.none<Promise<void>>(), dirty: false }
   const push = (): Promise<void> => {
@@ -263,9 +199,7 @@ export const serveShared = (options: ServeSharedOptions): SharedServerBinding =>
     debounce.fiber = Option.some(fiber)
   }
 
-  // Render once up front so the shared baseline exists before any client snapshots off
-  // it. Clients `await ready`, so they never capture the empty pre-render tree. Anything
-  // that changed during the (async) opening render is flushed by the trailing scheduleFlush.
+  // Clients await the initial baseline so none snapshot an empty tree.
   const ready = (async (): Promise<void> => {
     await server.render()
     started.value = true
@@ -284,9 +218,7 @@ export const serveShared = (options: ServeSharedOptions): SharedServerBinding =>
         ),
       )
     })
-    // Once the baseline exists, send this client its opening Snapshot and join the
-    // broadcast set in the SAME tick — no async push can interleave between the two, so
-    // the client's first frame and every subsequent diff stay in lockstep.
+    // Snapshot and broadcast membership must change in one tick so no diff interleaves.
     void Effect.runPromise(
       Effect.promise(() => ready).pipe(
         Effect.zipRight(
@@ -319,20 +251,12 @@ export const serveShared = (options: ServeSharedOptions): SharedServerBinding =>
 }
 
 export interface ClientBinding {
-  /** The current rendered node — re-read on each `subscribe` notification. */
   readonly node: () => ReactNode
-  /** Notified whenever applied patches change the tree. */
   readonly subscribe: (listener: () => void) => () => void
-  /**
-   * The current wire tree — a stable reference that changes only when a frame is
-   * applied, so it is a valid `useSyncExternalStore` snapshot (the React binding
-   * builds on this).
-   */
   readonly snapshot: () => WireTree
   readonly dispose: () => void
 }
 
-/** Options for {@link connect} — a single named object, mirroring {@link ServeOptions}. */
 export interface ConnectOptions<C extends RemoteContract> {
   readonly transport: RemoteTransport<InvokeMessage, ServerMessage>
   readonly views: RemoteViewSet<C>
@@ -347,8 +271,6 @@ export const connect = <C extends RemoteContract>(options: ConnectOptions<C>): C
     invoke: (handle, payload) => transport.send({ _tag: 'Invoke', handle, payload }),
   }
   const off = transport.onMessage((message) => {
-    // A snapshot replaces the tree wholesale (a fresh or reconnected session);
-    // patches fold into it. So a reconnect re-syncs without leaking stale nodes.
     state.tree = Match.value(message).pipe(
       Match.tag('Snapshot', ({ tree }) => tree),
       Match.tag('Patches', ({ patches }) => Wire.apply(state.tree, patches)),