@playfast/reform-remote-web 1.0.2 → 1.1.0

package/README.md

@@ -33,7 +33,7 @@ const App = () => {
 **Reconnection is built in.** A dropped socket is retried with exponential backoff
 (`baseDelayMs`/`maxDelayMs`), and because the message handlers persist across sockets, the
 server's first frame on the new connection — always a `Snapshot` — re-syncs the tree
-automatically, with no stale nodes left behind. The returned value *is* a `RemoteTransport`
+automatically, with no stale nodes left behind. The returned value _is_ a `RemoteTransport`
 (pass it straight to `connect` or `<RemoteUI>`) that additionally carries `status()`,
 `onStatusChange()` — together a `StatusReporter`, so `useConnectionStatus` drives the badge
 above — and `close()` to stop reconnecting.

package/package.json

@@ -1,35 +1,37 @@
 {
   "name": "@playfast/reform-remote-web",
-  "playbook": "./playbook",
-  "version": "1.0.2",
-  "type": "module",
+  "version": "1.1.0",
   "description": "Browser/web WebSocket client transport for reform-remote — streams a server-run reform scene to a thin renderer.",
   "keywords": [
-    "reform",
     "effect",
-    "websocket",
+    "reform",
     "remote",
-    "transport"
+    "transport",
+    "websocket"
   ],
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/playfast/reform.git",
     "directory": "packages/reform-remote-web"
   },
-  "bugs": {
-    "url": "https://github.com/playfast/reform/issues"
-  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
   "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": "./src/index.ts",
     "./*": "./src/*.ts"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "clean": "rm -rf dist .tsbuildinfo",
     "check": "tsc --noEmit",
@@ -40,17 +42,15 @@
     "lint": "oxlint src",
     "lint:fix": "oxlint --fix src"
   },
-  "peerDependencies": {
-    "effect": "*",
-    "@playfast/reform-remote": "*"
-  },
   "devDependencies": {
     "@playfast/reform": "*",
     "@playfast/reform-remote": "*",
     "@playfast/reform-remote-node": "*",
     "react": "^19.0.0"
   },
-  "publishConfig": {
-    "access": "public"
-  }
+  "peerDependencies": {
+    "@playfast/reform-remote": "*",
+    "effect": "*"
+  },
+  "playbook": "./playbook"
 }

package/src/client.test.ts

@@ -31,11 +31,19 @@ class CounterUi extends ui('Counter', {
   props: S.Struct({ count: S.Number }),
   events: { bump: S.Struct({ by: S.Number }) },
 }) {}
-class Counter extends Composition.make('Counter', { title: 'Counter', ui: CounterUi, states: [Count] }) {}
+
+class Counter extends Composition.make('Counter', {
+  title: 'Counter',
+  ui: CounterUi,
+  states: [Count],
+})<Counter>() {}
 
 const counterScene = () => {
   const presentation = Layer.mergeAll(
-    provide(CounterUi, Ui.make(CounterUi, ({ count }) => `count:${count}`)),
+    provide(
+      CounterUi,
+      Ui.make(CounterUi, ({ count }) => `count:${count}`),
+    ),
     StateGroup.live(Counters, { count: 0 }),
   )
   const app = Layer.mergeAll(
@@ -60,7 +68,8 @@ const probeView = (probe: Probe) =>
     return null
   })
 
-const draw = (node: ReactNode): void => void renderToStaticMarkup(createElement(Fragment, null, node))
+const draw = (node: ReactNode): void =>
+  void renderToStaticMarkup(createElement(Fragment, null, node))
 
 const listening = (host: NodeWebSocketServer): Promise<number> =>
   new Promise((resolve) =>

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

@@ -1,4 +1,4 @@
-import { Option, Redacted } from 'effect'
+import { Effect, Fiber, Option, Redacted, Schema } from 'effect'
 import type { InvokeMessage, RemoteTransport, ServerMessage } from '@playfast/reform-remote'
 import { MissingWebSocket } from './errors.js'
 
@@ -7,12 +7,60 @@ export type ClientStatus = 'connecting' | 'open' | 'reconnecting' | 'closed'
 const DEFAULT_BASE_DELAY_MS = 250
 const DEFAULT_MAX_DELAY_MS = 5000
 
+const WirePropSchema = Schema.Union(
+  Schema.Struct({
+    _tag: Schema.Literal('Data'),
+    name: Schema.String,
+    value: Schema.Unknown,
+  }),
+  Schema.Struct({
+    _tag: Schema.Literal('Event'),
+    name: Schema.String,
+    handle: Schema.String,
+  }),
+)
+const WireNodeSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  parentId: Schema.NullOr(Schema.String),
+  childIndex: Schema.Number,
+  slot: Schema.NullOr(Schema.String),
+  key: Schema.NullOr(Schema.String),
+  props: Schema.Array(WirePropSchema),
+})
+const WirePatchSchema = Schema.Union(
+  Schema.Struct({ _tag: Schema.Literal('Upsert'), node: WireNodeSchema }),
+  Schema.Struct({ _tag: Schema.Literal('Delete'), id: Schema.String }),
+)
+const InvokeMessageJson: Schema.Schema<InvokeMessage, string, never> = Schema.parseJson(
+  Schema.Struct({
+    _tag: Schema.Literal('Invoke'),
+    handle: Schema.String,
+    payload: Schema.Unknown,
+  }),
+)
+const ServerMessageJson: Schema.Schema<ServerMessage, string, never> = Schema.parseJson(
+  Schema.Union(
+    Schema.Struct({
+      _tag: Schema.Literal('Snapshot'),
+      tree: Schema.Array(WireNodeSchema),
+    }),
+    Schema.Struct({
+      _tag: Schema.Literal('Patches'),
+      patches: Schema.Array(WirePatchSchema),
+    }),
+  ),
+)
+const encodeInvokeMessage: (message: InvokeMessage) => string = Schema.encodeSync(InvokeMessageJson)
+const decodeServerMessage: (input: unknown) => ServerMessage =
+  Schema.decodeUnknownSync(ServerMessageJson)
+
 export interface WebSocketClientTransportOptionsExternalApi {
   readonly url: string
   readonly baseDelayMs?: number
   readonly maxDelayMs?: number
   readonly protocols?: string | ReadonlyArray<string>
-  // Browser WebSocket can't set headers; auth rides as `bearer.<token>` subprotocol. Redacted so it never logs.
+  // Browser WebSocket cannot set headers; auth uses a bearer subprotocol and stays redacted.
   readonly authToken?: Redacted.Redacted<string>
   readonly WebSocket?: typeof WebSocket
   readonly onStatus?: (status: ClientStatus) => void
@@ -33,13 +81,14 @@ interface GlobalWebSocketHolderExternalApi {
 const resolveWebSocket = (injected: typeof WebSocket | undefined): typeof WebSocket => {
   const globalScope: GlobalWebSocketHolderExternalApi = globalThis
   const impl = injected ?? globalScope.WebSocket
-  if (impl === undefined) {
-    // oxlint-disable-next-line reform-rules/no-throw -- sync public transport factory invariant; no Effect context at construction
-    throw new MissingWebSocket({
-      message: 'No global WebSocket; pass `WebSocket` in options (e.g. the `ws` package in Node <22).',
-    })
-  }
-  return impl
+  return Option.getOrThrowWith(
+    Option.fromNullable(impl),
+    () =>
+      new MissingWebSocket({
+        message:
+          'No global WebSocket; pass `WebSocket` in options (e.g. the `ws` package in Node <22).',
+      }),
+  )
 }
 
 export const createWebSocketClientTransport = (
@@ -69,9 +118,18 @@ export const createWebSocketClientTransport = (
     socket: Option.Option<WebSocket>
     status: ClientStatus
     attempts: number
-    timer: Option.Option<ReturnType<typeof setTimeout>>
+    timer: Option.Option<Fiber.RuntimeFiber<void, never>>
     queue: ReadonlyArray<InvokeMessage>
-  } = { socket: Option.none(), status: 'connecting', attempts: 0, timer: Option.none(), queue: [] }
+    // The opening Snapshot can arrive before RemoteUI subscribes.
+    inbox: ReadonlyArray<ServerMessage>
+  } = {
+    socket: Option.none(),
+    status: 'connecting',
+    attempts: 0,
+    timer: Option.none(),
+    queue: [],
+    inbox: [],
+  }
 
   const setStatus = (status: ClientStatus): void => {
     if (status === state.status) {
@@ -92,8 +150,7 @@ export const createWebSocketClientTransport = (
     }
     const pending = state.queue
     state.queue = []
-    // oxlint-disable-next-line reform-rules/no-json-parse-stringify -- wire frame encode; InvokeMessage is a structural type with no Schema here
-    pending.forEach((message) => socket.send(JSON.stringify(message)))
+    pending.forEach((message) => socket.send(encodeInvokeMessage(message)))
   }
 
   const scheduleReconnect = (): void => {
@@ -103,11 +160,12 @@ export const createWebSocketClientTransport = (
     setStatus('reconnecting')
     const delay = Math.min(maxDelayMs, baseDelayMs * 2 ** state.attempts)
     state.attempts += 1
-    // oxlint-disable-next-line reform-rules/no-set-timeout-interval -- DOM transport reconnect backoff; sync factory has no Effect runtime
-    state.timer = Option.some(setTimeout(connect, delay))
+    state.timer = Option.some(
+      Effect.runFork(Effect.sleep(delay).pipe(Effect.andThen(Effect.sync(connect)))),
+    )
   }
 
-  // Socket may fire both error and close; clear on first drop so only one reconnect is scheduled.
+  // A socket may fire both error and close; clearing first prevents duplicate reconnects.
   const handleDrop = (socket: WebSocket): void => {
     if (Option.isNone(state.socket) || state.socket.value !== socket) {
       return
@@ -117,16 +175,20 @@ export const createWebSocketClientTransport = (
   }
 
   function connect(): void {
-    const socket = protocols === undefined ? new WebSocketImpl(url) : new WebSocketImpl(url, [...protocols])
+    const socket =
+      protocols === undefined ? new WebSocketImpl(url) : new WebSocketImpl(url, [...protocols])
     state.socket = Option.some(socket)
     socket.addEventListener('open', () => {
       state.attempts = 0
       setStatus('open')
       flush()
     })
-    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
+    socket.addEventListener('message', (event: MessageEvent<unknown>) => {
+      const message = decodeServerMessage(event.data)
+      if (handlers.size === 0) {
+        state.inbox = [...state.inbox, message]
+        return
+      }
       handlers.forEach((handler) => handler(message))
     })
     socket.addEventListener('close', () => handleDrop(socket))
@@ -136,23 +198,28 @@ export const createWebSocketClientTransport = (
   connect()
 
   return {
-    send: (message) => {
+    send: (message: InvokeMessage): void => {
       state.queue = [...state.queue, message]
       flush()
     },
-    onMessage: (handler) => {
+    onMessage: (handler: (message: ServerMessage) => void): (() => void) => {
       handlers.add(handler)
+      if (state.inbox.length > 0) {
+        const buffered = state.inbox
+        state.inbox = []
+        buffered.forEach((message) => handler(message))
+      }
       return () => void handlers.delete(handler)
     },
     status: () => state.status,
-    onStatusChange: (listener) => {
+    onStatusChange: (listener: () => void): (() => void) => {
       statusListeners.add(listener)
       return () => void statusListeners.delete(listener)
     },
     close: () => {
       setStatus('closed')
       if (Option.isSome(state.timer)) {
-        clearTimeout(state.timer.value)
+        Effect.runSync(Fiber.interrupt(state.timer.value))
       }
       if (Option.isSome(state.socket)) {
         state.socket.value.close()