@playfast/reform-remote-web 1.0.2 → 1.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-remote-web",
   "playbook": "./playbook",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "type": "module",
   "description": "Browser/web WebSocket client transport for reform-remote — streams a server-run reform scene to a thin renderer.",
   "keywords": [

package/src/transport.test.ts

@@ -0,0 +1,118 @@
+import { expect, test } from 'vitest'
+import type { ServerMessage } from '@playfast/reform-remote'
+import { createWebSocketClientTransport } from './transport'
+
+// The scene-handshake race that blanks the app on WebKit ~8% of cold loads.
+//
+// `serveShared.addClient` (reform-remote) pushes the initial `Snapshot` the instant the WebSocket
+// opens — the client never asks for it. On our side the socket is opened eagerly (connectRemote)
+// while `RemoteUI` only registers its `onMessage` handler during its FIRST React render, a
+// scheduler flush later. So there is a window where the server's Snapshot arrives before any
+// handler is subscribed. If the transport drops messages that land in that window, `RemoteUI`
+// never receives the scene, renders null forever, and the whole app is silently blank. WebKit's
+// scheduler/WS-I/O timing loses this race intermittently; Chromium wins it.
+//
+// These tests pin the transport's contract deterministically with a fake WebSocket whose open and
+// message events we fire by hand — no real I/O, no timing flake.
+
+type Listener = (event: unknown) => void
+
+class FakeSocket {
+  static readonly CONNECTING = 0
+  static readonly OPEN = 1
+  static readonly CLOSING = 2
+  static readonly CLOSED = 3
+  static instances: FakeSocket[] = []
+
+  readyState: number = FakeSocket.CONNECTING
+  readonly sent: string[] = []
+  readonly url: string
+  readonly protocols: string | ReadonlyArray<string> | undefined
+  private readonly listeners = new Map<string, Set<Listener>>()
+
+  constructor(url: string, protocols?: string | ReadonlyArray<string>) {
+    this.url = url
+    this.protocols = protocols
+    FakeSocket.instances.push(this)
+  }
+
+  addEventListener(type: string, cb: Listener): void {
+    const set = this.listeners.get(type) ?? new Set<Listener>()
+    set.add(cb)
+    this.listeners.set(type, set)
+  }
+
+  removeEventListener(type: string, cb: Listener): void {
+    this.listeners.get(type)?.delete(cb)
+  }
+
+  send(data: string): void {
+    this.sent.push(data)
+  }
+
+  close(): void {
+    this.readyState = FakeSocket.CLOSED
+    this.fire('close', {})
+  }
+
+  // --- test controls (not part of the WebSocket API) ---
+  emitOpen(): void {
+    this.readyState = FakeSocket.OPEN
+    this.fire('open', {})
+  }
+
+  emitServerMessage(message: ServerMessage): void {
+    this.fire('message', { data: JSON.stringify(message) })
+  }
+
+  private fire(type: string, event: unknown): void {
+    this.listeners.get(type)?.forEach((cb) => cb(event))
+  }
+}
+
+const makeTransport = () => {
+  FakeSocket.instances = []
+  const transport = createWebSocketClientTransport({
+    url: 'ws://handshake-race',
+    WebSocket: FakeSocket as unknown as typeof WebSocket,
+  })
+  const socket = FakeSocket.instances[0]
+  if (socket === undefined) {
+    throw new Error('transport did not construct a socket')
+  }
+  return { transport, socket }
+}
+
+const SNAPSHOT: ServerMessage = { _tag: 'Snapshot', tree: [] }
+
+test('delivers a server message that arrived before the first subscriber (handshake race)', () => {
+  const { transport, socket } = makeTransport()
+  socket.emitOpen()
+  // Server pushes the Snapshot on connect, BEFORE RemoteUI mounts and subscribes.
+  socket.emitServerMessage(SNAPSHOT)
+  // RemoteUI renders and subscribes only now.
+  const received: ServerMessage[] = []
+  transport.onMessage((message) => received.push(message))
+  expect(received).toEqual([SNAPSHOT])
+})
+
+test('still delivers messages that arrive after subscription', () => {
+  const { transport, socket } = makeTransport()
+  socket.emitOpen()
+  const received: ServerMessage[] = []
+  transport.onMessage((message) => received.push(message))
+  socket.emitServerMessage(SNAPSHOT)
+  expect(received).toEqual([SNAPSHOT])
+})
+
+test('does not replay the buffered message to a later second subscriber', () => {
+  const { transport, socket } = makeTransport()
+  socket.emitOpen()
+  socket.emitServerMessage(SNAPSHOT)
+  const first: ServerMessage[] = []
+  transport.onMessage((message) => first.push(message))
+  const second: ServerMessage[] = []
+  transport.onMessage((message) => second.push(message))
+  expect(first).toEqual([SNAPSHOT])
+  expect(second).toEqual([])
+})

package/src/transport.ts

@@ -71,7 +71,18 @@ export const createWebSocketClientTransport = (
     attempts: number
     timer: Option.Option<ReturnType<typeof setTimeout>>
     queue: ReadonlyArray<InvokeMessage>
-  } = { socket: Option.none(), status: 'connecting', attempts: 0, timer: Option.none(), queue: [] }
+    // Inbound messages that arrived before any handler subscribed. The server pushes the initial
+    // Snapshot the instant the socket opens, but a consumer (e.g. RemoteUI) only subscribes after
+    // it mounts — so without this buffer the first scene is dropped and the UI blanks forever.
+    inbox: ReadonlyArray<ServerMessage>
+  } = {
+    socket: Option.none(),
+    status: 'connecting',
+    attempts: 0,
+    timer: Option.none(),
+    queue: [],
+    inbox: [],
+  }
 
   const setStatus = (status: ClientStatus): void => {
     if (status === state.status) {
@@ -127,6 +138,12 @@ export const createWebSocketClientTransport = (
     socket.addEventListener('message', (event: MessageEvent) => {
       // oxlint-disable-next-line reform-rules/no-json-parse-stringify, reform-rules/no-type-assertion -- wire frame decode; ServerMessage is a structural type with no Schema here
       const message = JSON.parse(event.data as string) as ServerMessage
+      if (handlers.size === 0) {
+        // No subscriber yet: buffer so the first one to subscribe still receives this message
+        // rather than losing it (the server's initial Snapshot can beat the consumer's mount).
+        state.inbox = [...state.inbox, message]
+        return
+      }
       handlers.forEach((handler) => handler(message))
     })
     socket.addEventListener('close', () => handleDrop(socket))
@@ -142,6 +159,13 @@ export const createWebSocketClientTransport = (
     },
     onMessage: (handler) => {
       handlers.add(handler)
+      // Replay anything that arrived before this first subscription, then clear the buffer so a
+      // later second subscriber does not receive the same messages again.
+      if (state.inbox.length > 0) {
+        const buffered = state.inbox
+        state.inbox = []
+        buffered.forEach((message) => handler(message))
+      }
       return () => void handlers.delete(handler)
     },
     status: () => state.status,