@playfast/reform-remote-web 0.1.0 → 1.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-remote-web",
   "playbook": "./playbook",
-  "version": "0.1.0",
+  "version": "1.0.2",
   "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.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,7 +65,6 @@ 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
@@ -154,10 +107,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