@playfast/reform-remote 0.1.0 → 1.0.2

package/src/transport.test.ts

@@ -9,18 +9,10 @@ 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.
 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 +56,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 +70,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 +80,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 +114,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 +145,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 +154,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 +179,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 +190,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 +198,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 +237,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 +278,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,65 +1,20 @@
-import { Effect, Fiber, Match, Option } from 'effect'
-import type { ReactNode } from 'react'
-import { Wire, type WirePatch, type WireTree } from '@playfast/reform'
+import { Effect, Fiber, Option } from 'effect'
 import type { Scene } from '@playfast/reform'
 import { makeRemoteServer } from './server'
-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.
- */
+export { connect, type ClientBinding, type ConnectOptions } from './connect'
+import type { InvokeMessage, RemoteTransport, ServerBinding, ServerMessage } from './transport.types'
+export type {
+  InvokeMessage,
+  PatchesMessage,
+  RemoteTransport,
+  ServerBinding,
+  ServerMessage,
+  SnapshotMessage,
+} from './transport.types'
+
+// Debounce for server-initiated pushes: drain settles + burst coalesces; client invokes 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 transport: RemoteTransport<ServerMessage, InvokeMessage>
@@ -68,22 +23,8 @@ export interface ServeOptions {
 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 first; then diffs. `started` gates races before snapshot.
+  // Single-flight push + dirty re-run: concurrent renderDiff would corrupt frame baseline.
   const started = { value: false }
   const flight = { promise: Option.none<Promise<void>>(), dirty: false }
   const push = (): Promise<void> => {
@@ -94,8 +35,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 so single-flight slot clears even on render failure.
     const run = Effect.runPromise(
       Effect.gen(function* () {
         const patches = yield* Effect.promise(() => server.renderDiff())
@@ -117,12 +57,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 so drain folds state before read; never races invoke's immediate push.
   const debounce = { fiber: Option.none<Fiber.RuntimeFiber<void>>() }
   const scheduleFlush = (): void => {
     if (!started.value || Option.isSome(debounce.fiber)) {
@@ -144,7 +79,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 +102,19 @@ 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 dispose: () => Promise<void>
 }
 
-/** Options for {@link serveShared} — one scene, run once, shared by every client. */
 export interface ServeSharedOptions {
   readonly scene: Scene
 }
 
-/**
- * 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 +123,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.
+  // Same single-flight + dirty as serve; patches broadcast to every client.
   const started = { value: false }
   const flight = { promise: Option.none<Promise<void>>(), dirty: false }
   const push = (): Promise<void> => {
@@ -263,9 +174,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.
+  // Baseline before any client snapshots; clients await ready so they never see empty tree.
   const ready = (async (): Promise<void> => {
     await server.render()
     started.value = true
@@ -284,9 +193,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 + join broadcast in same tick so no push interleaves between them.
     void Effect.runPromise(
       Effect.promise(() => ready).pipe(
         Effect.zipRight(
@@ -317,52 +224,3 @@ 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>
-}
-
-export const connect = <C extends RemoteContract>(options: ConnectOptions<C>): ClientBinding => {
-  const { transport, views } = options
-  const state: { tree: WireTree } = { tree: [] }
-  const listeners = new Set<() => void>()
-  const config: ClientConfig<C> = {
-    views,
-    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)),
-      Match.exhaustive,
-    )
-    listeners.forEach((listener) => listener())
-  })
-  return {
-    node: () => renderWireTree(state.tree, config),
-    subscribe: (listener) => {
-      listeners.add(listener)
-      return () => void listeners.delete(listener)
-    },
-    snapshot: () => state.tree,
-    dispose: off,
-  }
-}

package/src/transport.types.ts

@@ -0,0 +1,29 @@
+import type { WirePatch, WireTree } from '@playfast/reform'
+
+export interface SnapshotMessage {
+  readonly _tag: 'Snapshot'
+  readonly tree: WireTree
+}
+
+export interface PatchesMessage {
+  readonly _tag: 'Patches'
+  readonly patches: ReadonlyArray<WirePatch>
+}
+
+export type ServerMessage = SnapshotMessage | PatchesMessage
+
+export interface InvokeMessage {
+  readonly _tag: 'Invoke'
+  readonly handle: string
+  readonly payload: unknown
+}
+
+export interface RemoteTransport<Out, In> {
+  readonly send: (message: Out) => void
+  readonly onMessage: (handler: (message: In) => void) => () => void
+}
+
+export interface ServerBinding {
+  readonly start: () => Promise<void>
+  readonly dispose: () => Promise<void>
+}