@playfast/reform-remote-node 0.0.4 → 0.1.0

package/README.md

@@ -9,10 +9,10 @@
 ---
 
 A concrete WebSocket server adapter for
-[`@playfast/reform-remote`](https://www.npmjs.com/package/@playfast/reform-remote). Each
-connection gets its own `serve({ scene, transport })` — its own isolated runtime — wrapped around the
-socket with JSON framing. The wire messages are already `_tag`-discriminated and serializable, so
-there is no envelope to write.
+[`@playfast/reform-remote`](https://www.npmjs.com/package/@playfast/reform-remote). The scene runs
+**once** as a single shared runtime (`serveShared`); every connection attaches to it via `addClient`,
+so all clients see and drive the same state. Sockets are wrapped with JSON framing — the wire
+messages are already `_tag`-discriminated and serializable, so there is no envelope to write.
 
 ```ts
 import { serveNodeWebSocket } from '@playfast/reform-remote-node'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-remote-node",
   "playbook": "./playbook",
-  "version": "0.0.4",
+  "version": "0.1.0",
   "type": "module",
   "description": "Node WebSocket server adapter for reform-remote — serves a reform scene's UI over the `ws` package, one isolated runtime per connection.",
   "keywords": [

package/src/index.ts

@@ -4,22 +4,22 @@ import type { Scene } from '@playfast/reform'
 import {
   type InvokeMessage,
   type RemoteTransport,
-  type ServerBinding,
   type ServerMessage,
-  serve,
+  serveShared,
 } from '@playfast/reform-remote'
 
 /**
  * @playfast/reform-remote-node — serve a reform scene's UI over WebSocket from a
- * Node process, using the `ws` package. Each connection gets its own
- * `serve({ scene, transport })` — its own isolated runtime — wrapped around the
- * socket with JSON framing: the already-`_tag`-discriminated wire messages need
- * no envelope. The Bun-native equivalent is `@playfast/reform-remote-bun`; the
- * browser/web client is `@playfast/reform-remote-web`.
+ * Node process, using the `ws` package. The scene runs ONCE as a single shared
+ * runtime (`serveShared`); every connection attaches to it via `addClient`, so all
+ * clients see and drive the same state. Sockets are wrapped with JSON framing: the
+ * already-`_tag`-discriminated wire messages need no envelope. The Bun-native
+ * equivalent is `@playfast/reform-remote-bun`; the browser/web client is
+ * `@playfast/reform-remote-web`.
  */
 
-export interface NodeWebSocketOptions {
-  /** The scene to run — a fresh runtime per connection. */
+export interface NodeWebSocketOptionsExternalApi {
+  /** The scene to run — ONE shared runtime that every connection attaches to. */
   readonly scene: Scene
   /** Listen on this port (use `0` for an ephemeral port; read it back from `wss.address()`). */
   readonly port?: number
@@ -32,53 +32,49 @@ export interface NodeWebSocketOptions {
 export interface NodeWebSocketServer {
   /** The underlying `ws` server — for reading the bound address, or further config. */
   readonly wss: WebSocketServer
-  /** Dispose every live connection's runtime and close the server. */
+  /** Dispose the shared runtime and close the server. */
   readonly stop: () => Promise<void>
 }
 
-const parseInvoke = (data: RawData): InvokeMessage => JSON.parse(data.toString()) as InvokeMessage
+const parseInvoke = (frame: RawData): InvokeMessage =>
+  // oxlint-disable-next-line reform-rules/no-json-parse-stringify, reform-rules/no-type-assertion -- wire frame decode; InvokeMessage is a structural type with no Schema here
+  JSON.parse(frame.toString()) as InvokeMessage
 
-export const serveNodeWebSocket = (options: NodeWebSocketOptions): NodeWebSocketServer => {
+export const serveNodeWebSocket = (options: NodeWebSocketOptionsExternalApi): NodeWebSocketServer => {
   const wss =
     options.server !== undefined
       ? new WebSocketServer({ server: options.server, path: options.path })
-      : new WebSocketServer({ port: options.port ?? 0, path: options.path })
+      : new WebSocketServer({ port: options.port === undefined ? 0 : options.port, path: options.path })
 
-  // Every open connection's binding, so `stop` can tear them all down.
-  const bindings = new Set<ServerBinding>()
+  // One shared runtime for the whole server; every socket attaches to it.
+  const shared = serveShared({ scene: options.scene })
 
   wss.on('connection', (socket) => {
     const handlers = new Set<(message: InvokeMessage) => void>()
     const transport: RemoteTransport<ServerMessage, InvokeMessage> = {
+      // oxlint-disable-next-line reform-rules/no-json-parse-stringify -- wire frame encode; ServerMessage is a structural type with no Schema here
       send: (message) => socket.send(JSON.stringify(message)),
       onMessage: (handler) => {
         handlers.add(handler)
         return () => void handlers.delete(handler)
       },
     }
-    socket.on('message', (data) => {
-      const message = parseInvoke(data)
-      for (const handler of handlers) handler(message)
+    socket.on('message', (frame) => {
+      const message = parseInvoke(frame)
+      handlers.forEach((handler) => handler(message))
     })
 
-    const binding = serve({ scene: options.scene, transport })
-    bindings.add(binding)
-    socket.on('close', () => {
-      bindings.delete(binding)
-      void binding.dispose()
-    })
-    // Push the first snapshot once the socket is live.
-    void binding.start()
+    const handle = shared.addClient(transport)
+    socket.on('close', () => handle.remove())
   })
 
   return {
     wss,
     stop: async (): Promise<void> => {
-      await Promise.all([...bindings].map((binding) => binding.dispose()))
-      bindings.clear()
+      await shared.dispose()
       // Terminate live sockets so `wss.close` doesn't block waiting for them to
       // drain on their own — `close` only fires its callback once all are gone.
-      for (const client of wss.clients) client.terminate()
+      wss.clients.forEach((client) => client.terminate())
       await new Promise<void>((resolve, reject) =>
         wss.close((error) => (error === undefined ? resolve() : reject(error))),
       )

package/src/server.test.ts

@@ -106,29 +106,43 @@ test('a native WebSocket client receives a snapshot and drives the server back o
   }
 })
 
-test('each connection runs an isolated runtime', async () => {
+test('every connection shares ONE runtime — a bump on one socket reaches the others', async () => {
   const host = serveNodeWebSocket({ scene: counterScene() })
   open.add(host)
   const port = await listening(host)
 
+  // Attach every listener BEFORE awaiting: the shared server snapshots a new client
+  // off its pre-rendered baseline immediately, so a lazily-attached listener could miss
+  // the frame (a real `connect()` client registers its handler synchronously).
   const a = new WebSocket(`ws://localhost:${port}`)
+  const snapAP = nextMessage(a, (m) => m._tag === 'Snapshot')
   const b = new WebSocket(`ws://localhost:${port}`)
+  const snapBP = nextMessage(b, (m) => m._tag === 'Snapshot')
   try {
-    const snapA = await nextMessage(a, (m) => m._tag === 'Snapshot')
-    await nextMessage(b, (m) => m._tag === 'Snapshot')
+    const snapA = await snapAP
+    const snapB = await snapBP
 
+    // a bumps; BOTH a and b receive the broadcast diff off the shared runtime.
+    const frameAP = nextMessage(a, (m) => m._tag === 'Patches')
+    const frameBP = nextMessage(b, (m) => m._tag === 'Patches')
     a.send(JSON.stringify({ _tag: 'Invoke', handle: '0:bump', payload: { by: 4 } }))
-    const frameA = await nextMessage(a, (m) => m._tag === 'Patches')
+    const frameA = await frameAP
+    const frameB = await frameBP
 
     const treeA = Wire.apply(
       snapA._tag === 'Snapshot' ? snapA.tree : [],
       frameA._tag === 'Patches' ? frameA.patches : [],
     )
+    const treeB = Wire.apply(
+      snapB._tag === 'Snapshot' ? snapB.tree : [],
+      frameB._tag === 'Patches' ? frameB.patches : [],
+    )
     expect(countOf(treeA[0]!)).toBe(4)
-    // b's runtime never saw a's bump — a re-snapshot on a fresh socket would read 0.
+    expect(countOf(treeB[0]!)).toBe(4)
+    // A late joiner snapshots the CURRENT shared count (4), not a fresh 0.
     const c = new WebSocket(`ws://localhost:${port}`)
     const snapC = await nextMessage(c, (m) => m._tag === 'Snapshot')
-    expect(countOf((snapC._tag === 'Snapshot' ? snapC.tree : [])[0]!)).toBe(0)
+    expect(countOf((snapC._tag === 'Snapshot' ? snapC.tree : [])[0]!)).toBe(4)
     c.close()
   } finally {
     a.close()