@playfast/reform-remote-web 1.0.1 → 1.0.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-remote-web",
   "playbook": "./playbook",
-  "version": "1.0.1",
+  "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/client.test.ts

@@ -20,11 +20,9 @@ import { connect, remoteViews } from '@playfast/reform-remote'
 import { type NodeWebSocketServer, serveNodeWebSocket } from '@playfast/reform-remote-node'
 import { createWebSocketClientTransport } from './index'
 
-// Real loopback round-trip (ws server + live client, incl. reconnect): headroom so the
-// full parallel suite can't starve it past the 5s default (30s still fails a real hang).
+// Real loopback I/O: headroom so parallel suite can't starve past 5s default.
 vi.setConfig({ testTimeout: 30_000, hookTimeout: 30_000 })
 
-// Self-contained counter scene for the server end of the round-trip.
 class Count extends State.make('count', S.Number) {}
 class Counters extends StateGroup.make(Count) {}
 class Bumped extends Event.make('Bumped', S.Struct({ by: S.Number })) {}
@@ -53,7 +51,6 @@ const counterScene = () => {
 
 interface Probe {
   props?: Record<string, unknown>
-  // The counter contract's only event, `bump`, takes `{ by: number }`.
   events?: Record<string, (payload: { by: number }) => void>
 }
 const probeView = (probe: Probe) =>
@@ -63,7 +60,6 @@ const probeView = (probe: Probe) =>
     return null
   })
 
-// Views render as React components now, so a test runs them by rendering node().
 const draw = (node: ReactNode): void => void renderToStaticMarkup(createElement(Fragment, null, node))
 
 const listening = (host: NodeWebSocketServer): Promise<number> =>
@@ -122,7 +118,6 @@ test('a dropped connection reconnects with backoff and re-syncs via the fresh sn
     views: remoteViews<{ Counter: typeof CounterUi }>({ Counter: probeView(probe) }),
   })
   try {
-    // Live, then bump so the client holds a non-zero count.
     await vi.waitFor(() => {
       draw(client.node())
       expect(probe.props).toEqual({ count: 0 })
@@ -133,14 +128,11 @@ test('a dropped connection reconnects with backoff and re-syncs via the fresh sn
       expect(probe.props).toEqual({ count: 5 })
     })
 
-    // Kill the server out from under the client.
     await host.stop()
     open.delete(host)
     await vi.waitFor(() => expect(transport.status()).toBe('reconnecting'))
 
-    // Bring a fresh runtime back on the same port. The client reconnects and the
-    // new session's snapshot resets the tree — count is 0 again, proving re-sync
-    // (not the stale 5).
+    // Fresh runtime on same port: reconnect snapshot resets tree (not stale 5).
     const restarted = serveNodeWebSocket({ scene: counterScene(), port })
     open.add(restarted)
     await listening(restarted)

package/src/errors.ts

@@ -1,16 +1,6 @@
 import { type Cause, Data } from 'effect'
 
-/**
- * Tagged errors for the web client transport. Every failure carries a `_tag` and
- * structured fields — never a bare `Error` — so callers can match with Effect
- * `catchTag` / `Match`. Tags are namespaced by package to stay globally unique.
- */
-
-/**
- * The constructor shape `Data.TaggedError(tag)<A>` produces, named so the
- * generated `.d.ts` can describe the `extends` base under `isolatedDeclarations`
- * (which forbids an inferred expression in an extends clause).
- */
+// Named so isolatedDeclarations can describe the extends base (inferred expression forbidden).
 type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = new (
   args: A,
 ) => Cause.YieldableError & { readonly _tag: Tag } & Readonly<A>
@@ -22,5 +12,4 @@ const MissingWebSocketBase: TaggedErrorClass<
   readonly message: string
 }>
 
-/** Thrown when no `WebSocket` is available and none was injected via options. */
 export class MissingWebSocket extends MissingWebSocketBase {}

package/src/index.ts

@@ -1,12 +1,3 @@
-/**
- * `@playfast/reform-remote-web` — the browser/web client side of the remote
- * transport. Public API is exposed two ways (Effect-style): namespace barrels for
- * discovery (`import { Transport } from "@playfast/reform-remote-web"`) and
- * per-path subpaths for direct use (`import { createWebSocketClientTransport }
- * from "@playfast/reform-remote-web/transport"`). The select re-exports below keep
- * the common entry points nameable from the root.
- */
-
 export * as Transport from './transport.js'
 export * as Errors from './errors.js'
 

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

@@ -2,73 +2,30 @@ import { Option, Redacted } from 'effect'
 import type { InvokeMessage, RemoteTransport, ServerMessage } from '@playfast/reform-remote'
 import { MissingWebSocket } from './errors.js'
 
-/**
- * The browser/web client side of the remote transport. A factory that wraps a
- * WebSocket into a `RemoteTransport` you hand to `connect({ transport, views })`:
- * it sends `Invoke`s up and surfaces `Snapshot`/`Patches` down, with JSON framing.
- *
- * It owns reconnection so the caller doesn't have to: a dropped socket is retried
- * with exponential backoff, 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 (no stale nodes leak). Works anywhere a global
- * `WebSocket` exists (browsers, Bun, Node 22+); inject one via `options` otherwise.
- * There is no React hook — this is the transport only.
- */
-
 export type ClientStatus = 'connecting' | 'open' | 'reconnecting' | 'closed'
 
-/** First reconnect delay; doubles each attempt up to {@link DEFAULT_MAX_DELAY_MS}. */
 const DEFAULT_BASE_DELAY_MS = 250
-/** Ceiling for the exponential backoff delay. */
 const DEFAULT_MAX_DELAY_MS = 5000
 
-/**
- * Options for {@link createWebSocketClientTransport}. A single named-options object
- * (no positional args) so every reform-remote adapter constructor has the same
- * shape and the client transports stay drop-in swappable.
- *
- * The `ExternalApi` postfix marks this as the package's public consumer-facing
- * surface, where optional config fields are idiomatic.
- */
 export interface WebSocketClientTransportOptionsExternalApi {
-  /** The WebSocket URL to connect to (e.g. `ws://127.0.0.1:8787/reform`). */
   readonly url: string
-  /** First reconnect delay; doubles each attempt up to `maxDelayMs`. Default 250ms. */
   readonly baseDelayMs?: number
-  /** Ceiling for the backoff delay. Default 5000ms. */
   readonly maxDelayMs?: number
-  /** Subprotocols passed to the `WebSocket` constructor. */
   readonly protocols?: string | ReadonlyArray<string>
-  /**
-   * A bearer token to authenticate the connection. A browser `WebSocket` can't set headers,
-   * so the only header-like channel is the subprotocol list: the token rides as an extra
-   * `bearer.<token>` subprotocol alongside any {@link protocols}. The server reads it off
-   * `Sec-WebSocket-Protocol` at the upgrade. Held `Redacted` so it never logs.
-   */
+  // Browser WebSocket can't set headers; auth rides as `bearer.<token>` subprotocol. Redacted so it never logs.
   readonly authToken?: Redacted.Redacted<string>
-  /** The `WebSocket` implementation to use. Defaults to the global. */
   readonly WebSocket?: typeof WebSocket
-  /** Notified on every connection-status transition. */
   readonly onStatus?: (status: ClientStatus) => void
 }
 
-/** Back-compat alias for the public options type. */
 export type WebSocketClientTransportOptions = WebSocketClientTransportOptionsExternalApi
 
-/** A `RemoteTransport` that also exposes its connection status and a manual close. */
 export type WebSocketClientTransport = RemoteTransport<InvokeMessage, ServerMessage> & {
   readonly status: () => ClientStatus
-  /**
-   * Subscribe to status transitions (returns an unsubscribe). With `status()`
-   * this satisfies the React binding's `StatusReporter`, so `useConnectionStatus`
-   * can drive a reconnecting badge with no manual store.
-   */
   readonly onStatusChange: (listener: () => void) => () => void
-  /** Stop reconnecting and close the socket. The transport is inert afterwards. */
   readonly close: () => void
 }
 
-/** DOM-boundary view of the global scope: the optional global `WebSocket` constructor. */
 interface GlobalWebSocketHolderExternalApi {
   readonly WebSocket?: typeof WebSocket
 }
@@ -93,9 +50,6 @@ export const createWebSocketClientTransport = (
   const baseDelayMs = options.baseDelayMs ?? DEFAULT_BASE_DELAY_MS
   const maxDelayMs = options.maxDelayMs ?? DEFAULT_MAX_DELAY_MS
 
-  // Normalize `protocols` to an array and fold in the auth token as a `bearer.<token>`
-  // subprotocol. Computed once (the token doesn't change across reconnects). `undefined`
-  // when there's nothing to send, so the no-auth path matches the original behavior.
   const baseProtocols: ReadonlyArray<string> =
     options.protocols === undefined
       ? []
@@ -111,14 +65,24 @@ export const createWebSocketClientTransport = (
 
   const handlers = new Set<(message: ServerMessage) => void>()
   const statusListeners = new Set<() => void>()
-  // A const holder whose fields swap — the codebase's no-`let` idiom.
   const state: {
     socket: Option.Option<WebSocket>
     status: ClientStatus
     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) {
@@ -154,10 +118,7 @@ export const createWebSocketClientTransport = (
     state.timer = Option.some(setTimeout(connect, delay))
   }
 
-  // A drop while live (or a failed connect) backs off and retries. A socket can
-  // fire both `error` and `close`, so guard on identity — clear the current
-  // socket on the first drop, so the second event is a no-op and only one
-  // reconnect is scheduled. A user `close` flips the status, making this inert.
+  // Socket may fire both error and close; clear on first drop so only one reconnect is scheduled.
   const handleDrop = (socket: WebSocket): void => {
     if (Option.isNone(state.socket) || state.socket.value !== socket) {
       return
@@ -177,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))
@@ -192,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,