@playfast/reform-remote 1.0.2 → 1.1.0

package/src/transport.ts

@@ -1,30 +1,53 @@
-import { Effect, Fiber, Option } from 'effect'
-import type { Scene } from '@playfast/reform'
+import { Effect, Fiber, Match, Option } from 'effect'
+import type { ReactNode } from 'react'
+import { type AnyScene, Wire, type WirePatch, type WireTree } from '@playfast/reform/internal'
 import { makeRemoteServer } from './server'
-export { connect, type ClientBinding, type ConnectOptions } from './connect'
-import type { InvokeMessage, RemoteTransport, ServerBinding, ServerMessage } from './transport.types'
-export type {
-  InvokeMessage,
-  PatchesMessage,
-  RemoteTransport,
-  ServerBinding,
-  ServerMessage,
-  SnapshotMessage,
-} from './transport.types'
-
-// Debounce for server-initiated pushes: drain settles + burst coalesces; client invokes push immediately.
+import {
+  renderWireTree,
+  type ClientConfig,
+  type RemoteContract,
+  type RemoteViewSet,
+} from './client'
+
+export interface SnapshotMessage {
+  readonly _tag: 'Snapshot'
+  readonly tree: WireTree
+}
+
+export interface PatchesMessage {
+  readonly _tag: 'Patches'
+  readonly patches: ReadonlyArray<WirePatch>
+}
+
+export type ServerMessage = SnapshotMessage | PatchesMessage
+
+export interface InvokeMessage {
+  readonly _tag: 'Invoke'
+  readonly handle: string
+  readonly payload: unknown
+}
+
+export interface RemoteTransport<Out, In> {
+  readonly send: (message: Out) => void
+  readonly onMessage: (handler: (message: In) => void) => () => void
+}
+
+export interface ServerBinding {
+  readonly start: () => Promise<void>
+  readonly dispose: () => Promise<void>
+}
+
 const BACKGROUND_FLUSH_MS = 16
 
 export interface ServeOptions {
-  readonly scene: Scene
+  readonly scene: AnyScene
   readonly transport: RemoteTransport<ServerMessage, InvokeMessage>
 }
 
 export const serve = (options: ServeOptions): ServerBinding => {
   const { scene, transport } = options
   const server = makeRemoteServer(scene)
-  // Snapshot first; then diffs. `started` gates races before snapshot.
-  // Single-flight push + dirty re-run: concurrent renderDiff would corrupt frame baseline.
+  // Snapshot gates diffs; single-flight rendering protects the shared frame baseline.
   const started = { value: false }
   const flight = { promise: Option.none<Promise<void>>(), dirty: false }
   const push = (): Promise<void> => {
@@ -35,7 +58,7 @@ export const serve = (options: ServeOptions): ServerBinding => {
       flight.dirty = true
       return flight.promise.value
     }
-    // ensuring so single-flight slot clears even on render failure.
+    // ensuring clears the single-flight slot even when rendering fails.
     const run = Effect.runPromise(
       Effect.gen(function* () {
         const patches = yield* Effect.promise(() => server.renderDiff())
@@ -57,7 +80,7 @@ export const serve = (options: ServeOptions): ServerBinding => {
     flight.promise = Option.some(run)
     return run
   }
-  // Background debounce so drain folds state before read; never races invoke's immediate push.
+  // Background debounce lets the drain settle and coalesces bursts without delaying invokes.
   const debounce = { fiber: Option.none<Fiber.RuntimeFiber<void>>() }
   const scheduleFlush = (): void => {
     if (!started.value || Option.isSome(debounce.fiber)) {
@@ -107,12 +130,14 @@ export interface SharedClientHandle {
 }
 
 export interface SharedServerBinding {
-  readonly addClient: (transport: RemoteTransport<ServerMessage, InvokeMessage>) => SharedClientHandle
+  readonly addClient: (
+    transport: RemoteTransport<ServerMessage, InvokeMessage>,
+  ) => SharedClientHandle
   readonly dispose: () => Promise<void>
 }
 
 export interface ServeSharedOptions {
-  readonly scene: Scene
+  readonly scene: AnyScene
 }
 
 export const serveShared = (options: ServeSharedOptions): SharedServerBinding => {
@@ -123,7 +148,7 @@ export const serveShared = (options: ServeSharedOptions): SharedServerBinding =>
     clients.forEach((client) => client.send(message))
   }
 
-  // Same single-flight + dirty as serve; patches broadcast to every client.
+  // One shared render baseline requires the same single-flight discipline as serve.
   const started = { value: false }
   const flight = { promise: Option.none<Promise<void>>(), dirty: false }
   const push = (): Promise<void> => {
@@ -174,7 +199,7 @@ export const serveShared = (options: ServeSharedOptions): SharedServerBinding =>
     debounce.fiber = Option.some(fiber)
   }
 
-  // Baseline before any client snapshots; clients await ready so they never see empty tree.
+  // Clients await the initial baseline so none snapshot an empty tree.
   const ready = (async (): Promise<void> => {
     await server.render()
     started.value = true
@@ -193,7 +218,7 @@ export const serveShared = (options: ServeSharedOptions): SharedServerBinding =>
         ),
       )
     })
-    // Snapshot + join broadcast in same tick so no push interleaves between them.
+    // Snapshot and broadcast membership must change in one tick so no diff interleaves.
     void Effect.runPromise(
       Effect.promise(() => ready).pipe(
         Effect.zipRight(
@@ -224,3 +249,42 @@ export const serveShared = (options: ServeSharedOptions): SharedServerBinding =>
     },
   }
 }
+
+export interface ClientBinding {
+  readonly node: () => ReactNode
+  readonly subscribe: (listener: () => void) => () => void
+  readonly snapshot: () => WireTree
+  readonly dispose: () => void
+}
+
+export interface ConnectOptions<C extends RemoteContract> {
+  readonly transport: RemoteTransport<InvokeMessage, ServerMessage>
+  readonly views: RemoteViewSet<C>
+}
+
+export const connect = <C extends RemoteContract>(options: ConnectOptions<C>): ClientBinding => {
+  const { transport, views } = options
+  const state: { tree: WireTree } = { tree: [] }
+  const listeners = new Set<() => void>()
+  const config: ClientConfig<C> = {
+    views,
+    invoke: (handle, payload) => transport.send({ _tag: 'Invoke', handle, payload }),
+  }
+  const off = transport.onMessage((message) => {
+    state.tree = Match.value(message).pipe(
+      Match.tag('Snapshot', ({ tree }) => tree),
+      Match.tag('Patches', ({ patches }) => Wire.apply(state.tree, patches)),
+      Match.exhaustive,
+    )
+    listeners.forEach((listener) => listener())
+  })
+  return {
+    node: () => renderWireTree(state.tree, config),
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => void listeners.delete(listener)
+    },
+    snapshot: () => state.tree,
+    dispose: off,
+  }
+}

package/src/connect.ts

@@ -1,44 +0,0 @@
-import { Match } from 'effect'
-import type { ReactNode } from 'react'
-import { Wire, type WireTree } from '@playfast/reform'
-import { renderWireTree, type ClientConfig, type RemoteContract, type RemoteViewSet } from './client'
-import type { InvokeMessage, RemoteTransport, ServerMessage } from './transport'
-
-export interface ClientBinding {
-  readonly node: () => ReactNode
-  readonly subscribe: (listener: () => void) => () => void
-  readonly snapshot: () => WireTree
-  readonly dispose: () => void
-}
-
-export interface ConnectOptions<C extends RemoteContract> {
-  readonly transport: RemoteTransport<InvokeMessage, ServerMessage>
-  readonly views: RemoteViewSet<C>
-}
-
-export const connect = <C extends RemoteContract>(options: ConnectOptions<C>): ClientBinding => {
-  const { transport, views } = options
-  const state: { tree: WireTree } = { tree: [] }
-  const listeners = new Set<() => void>()
-  const config: ClientConfig<C> = {
-    views,
-    invoke: (handle, payload) => transport.send({ _tag: 'Invoke', handle, payload }),
-  }
-  const off = transport.onMessage((message) => {
-    state.tree = Match.value(message).pipe(
-      Match.tag('Snapshot', ({ tree }) => tree),
-      Match.tag('Patches', ({ patches }) => Wire.apply(state.tree, patches)),
-      Match.exhaustive,
-    )
-    listeners.forEach((listener) => listener())
-  })
-  return {
-    node: () => renderWireTree(state.tree, config),
-    subscribe: (listener) => {
-      listeners.add(listener)
-      return () => void listeners.delete(listener)
-    },
-    snapshot: () => state.tree,
-    dispose: off,
-  }
-}

package/src/contract.ts

@@ -1,3 +0,0 @@
-import type { RemoteContract } from './client'
-
-export const remoteContract = <const C extends RemoteContract>(contract: C): C => contract

package/src/remote-server.ts

@@ -1,109 +0,0 @@
-import { Effect, Layer, ManagedRuntime, Option, PubSub, Queue } from 'effect'
-import {
-  Bus,
-  type CompositionService,
-  forceSync,
-  publish,
-  type Scene,
-  type SlotChild,
-  Triggers,
-  type TriggerRegistryApi,
-  Wire,
-  type WirePatch,
-  type WireTree,
-  type WireNode,
-} from '@playfast/reform'
-import { renderSceneToWire } from './server'
-
-type RuntimeServices = CompositionService | SlotChild | Bus
-const SETTLE_DRAIN = 30
-const settleDrain: Effect.Effect<void> = Effect.yieldNow().pipe(Effect.repeatN(SETTLE_DRAIN))
-const closedSceneLayer = (scene: Scene): Layer.Layer<RuntimeServices, never, never> =>
-  // oxlint-disable-next-line reform-rules/no-type-assertion -- closed-scene erasure: scene.provide is typed to MountedServices, recovered structurally as RuntimeServices
-  scene.provide.reduce((acc, layer) => Layer.merge(acc, layer)) as unknown as Layer.Layer<
-    RuntimeServices,
-    never,
-    never
-  >
-const handlesOf = (node: WireNode): ReadonlyArray<string> =>
-  node.props.flatMap((prop) => (prop._tag === 'Event' ? [prop.handle] : []))
-
-export interface RemoteServer {
-  readonly render: () => Promise<WireTree>
-  readonly renderDiff: () => Promise<ReadonlyArray<WirePatch>>
-  readonly invoke: (handle: string, encodedPayload: unknown) => Promise<void>
-  readonly subscribe: (listener: () => void) => () => void
-  readonly currentTree: () => WireTree
-  readonly dispose: () => Promise<void>
-}
-
-export const makeRemoteServer = (scene: Scene): RemoteServer => {
-  const runtime = ManagedRuntime.make(closedSceneLayer(scene))
-  const registry: TriggerRegistryApi = forceSync(() => runtime.runSync(Triggers.make))
-  const renderEffect = settleDrain.pipe(
-    Effect.zipRight(renderSceneToWire(scene, { register: registry.register })),
-  )
-  const changeListeners = new Set<() => void>()
-  const notifyChange = (): void => {
-    changeListeners.forEach((listener) => listener())
-  }
-  runtime.runFork(
-    Effect.scoped(
-      Effect.gen(function* () {
-        const bus = yield* Bus
-        const subscription = yield* PubSub.subscribe(bus)
-        yield* Queue.take(subscription).pipe(
-          Effect.zipRight(Effect.sync(notifyChange)),
-          Effect.forever,
-        )
-      }),
-    ),
-  )
-  runtime.runSync(
-    Effect.forEach(
-      Option.getOrElse(Option.fromNullable(scene.boot), () => []),
-      (event) => publish('High', event),
-    ),
-  )
-  const frame: { tree: WireTree } = { tree: [] }
-  const render = (): Promise<WireTree> =>
-    runtime.runPromise(
-      renderEffect.pipe(
-        Effect.tap((tree) =>
-          Effect.sync(() => {
-            frame.tree = tree
-          }),
-        ),
-      ),
-    )
-  const renderDiff = (): Promise<ReadonlyArray<WirePatch>> =>
-    runtime.runPromise(
-      Effect.gen(function* () {
-        const next = yield* renderEffect
-        const previous = frame.tree
-        const patches = Wire.diff(previous, next)
-        frame.tree = next
-        const nextIds = new Set(next.map((node) => node.id))
-        const staleHandles = previous.filter((node) => !nextIds.has(node.id)).flatMap(handlesOf)
-        yield* Effect.forEach(staleHandles, (handle) => registry.revoke(handle))
-        return patches
-      }),
-    )
-  return {
-    render,
-    renderDiff,
-    invoke: (handle, encodedPayload) =>
-      runtime.runPromise(
-        Effect.gen(function* () {
-          yield* registry.invoke(handle, encodedPayload)
-          yield* settleDrain
-        }),
-      ),
-    subscribe: (listener) => {
-      changeListeners.add(listener)
-      return () => void changeListeners.delete(listener)
-    },
-    currentTree: () => frame.tree,
-    dispose: () => runtime.dispose(),
-  }
-}

package/src/transport.types.ts

@@ -1,29 +0,0 @@
-import type { WirePatch, WireTree } from '@playfast/reform'
-
-export interface SnapshotMessage {
-  readonly _tag: 'Snapshot'
-  readonly tree: WireTree
-}
-
-export interface PatchesMessage {
-  readonly _tag: 'Patches'
-  readonly patches: ReadonlyArray<WirePatch>
-}
-
-export type ServerMessage = SnapshotMessage | PatchesMessage
-
-export interface InvokeMessage {
-  readonly _tag: 'Invoke'
-  readonly handle: string
-  readonly payload: unknown
-}
-
-export interface RemoteTransport<Out, In> {
-  readonly send: (message: Out) => void
-  readonly onMessage: (handler: (message: In) => void) => () => void
-}
-
-export interface ServerBinding {
-  readonly start: () => Promise<void>
-  readonly dispose: () => Promise<void>
-}