@playfast/reform-remote 1.0.2 → 1.2.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/wireNode.ts

@@ -0,0 +1,153 @@
+import { Array as Arr, Effect, Option, type ParseResult, Record as Rec, Schema } from 'effect'
+import {
+  isFeatureBinding,
+  isSlot,
+  type SlotFill,
+  type Structure,
+  type Trigger,
+  type UiContract,
+} from '@playfast/reform'
+import {
+  type AnyComposition,
+  type AnySlot,
+  type AnySlotChild,
+  type TriggerRegistryApi,
+  type UiManifest,
+  type WireNode,
+  type WireProp,
+} from '@playfast/reform/internal'
+
+export const SETTLE_DRAIN = 30
+export const settleDrain: Effect.Effect<void> = Effect.yieldNow().pipe(Effect.repeatN(SETTLE_DRAIN))
+
+// The erased event map's never values remain assignable to Trigger<unknown> without a cast.
+export const eventsOf = (structure: Structure<UiContract>): Record<string, Trigger<unknown>> =>
+  Option.match(Option.fromNullable(structure.events), {
+    onNone: () => ({}),
+    onSome: (events) => events,
+  })
+
+export interface Mounted {
+  readonly comp: AnyComposition
+  readonly props: unknown
+  readonly id: string
+  readonly parentId: Option.Option<string>
+  readonly slot: Option.Option<string>
+  readonly childIndex: number
+  readonly key: Option.Option<string>
+}
+
+export const childComposition = (child: AnySlotChild): AnyComposition => {
+  if (!isFeatureBinding(child)) {
+    return child
+  }
+  return child.capture<AnyComposition>((binding): AnyComposition => binding.composition)
+}
+
+export const isRecord = (candidate: unknown): candidate is Record<string, unknown> =>
+  typeof candidate === 'object' && candidate !== null && !Array.isArray(candidate)
+
+export const handlesOf = (node: WireNode): ReadonlyArray<string> =>
+  node.props.flatMap((prop) => (prop._tag === 'Event' ? [prop.handle] : []))
+
+// One-shot renders still emit deterministic handles but have no client registry.
+export const noRegister: TriggerRegistryApi['register'] = () => Effect.void
+
+export const toWireNodeFromStructure: (
+  mounted: Mounted,
+  structure: Structure<UiContract>,
+  register: TriggerRegistryApi['register'],
+) => Effect.Effect<WireNode, ParseResult.ParseError> = Effect.fn('toWireNodeFromStructure')(
+  function* (
+  mounted: Mounted,
+  structure: Structure<UiContract>,
+  register: TriggerRegistryApi['register'],
+): Effect.fn.Return<WireNode, ParseResult.ParseError> {
+  const manifest: UiManifest = mounted.comp.manifest.ui.manifest
+  const name = manifest.name
+
+  // The manifest stores schema AST only; reconstruct an unknown-safe schema at this wire seam.
+  const encodedProps = yield* Option.match(Option.fromNullable(manifest.props), {
+    onNone: () => Effect.succeed({}),
+    onSome: (reflection) =>
+      Schema.encodeUnknown(Schema.make<unknown, unknown>(reflection.ast))(structure.props).pipe(
+        Effect.flatMap((encoded) => {
+          if (isRecord(encoded)) {
+            return Effect.succeed(encoded)
+          }
+          return Effect.dieMessage(
+            `reform-remote: ${manifest.name} props did not encode to a record`,
+          )
+        }),
+      ),
+  })
+  const dataProps: ReadonlyArray<WireProp> = Rec.toEntries(encodedProps).map(
+    ([propName, propValue]): WireProp => ({
+      _tag: 'Data',
+      name: propName,
+      value: propValue,
+    }),
+  )
+
+  const eventSchemas = Option.fromNullable(manifest.events)
+  const events = eventsOf(structure)
+  const eventProps: ReadonlyArray<WireProp> = yield* Effect.forEach(
+    Rec.toEntries(events),
+    ([eventName, trigger]) =>
+      Effect.gen(function* () {
+        const schema = Option.flatMap(eventSchemas, (schemas) => Rec.get(schemas, eventName))
+        if (Option.isNone(schema)) {
+          return Option.none<WireProp>()
+        }
+        const handle = `${mounted.id}:${eventName}`
+        yield* register(handle, trigger, Schema.make<unknown, unknown>(schema.value.ast))
+        return Option.some<WireProp>({
+          _tag: 'Event',
+          name: eventName,
+          handle,
+        })
+      }),
+  ).pipe(Effect.map(Arr.getSomes))
+
+  return {
+    id: mounted.id,
+    name,
+    parentId: Option.getOrNull(mounted.parentId),
+    childIndex: mounted.childIndex,
+    slot: Option.getOrNull(mounted.slot),
+    key: Option.getOrNull(mounted.key),
+    props: [...dataProps, ...eventProps],
+  }
+})
+
+// Structure erases per-slot fill types; recover SlotFill structurally without `as`.
+export const isSlotFill = (candidate: unknown): candidate is SlotFill<unknown> =>
+  typeof candidate === 'object' &&
+  candidate !== null &&
+  '_tag' in candidate &&
+  (candidate._tag === 'Each' || candidate._tag === 'One' || candidate._tag === 'Absent')
+
+export const structureFills = (structure: Structure<UiContract>): Record<string, SlotFill<unknown>> =>
+  Rec.fromEntries(
+    Rec.toEntries(structure.slots).flatMap(
+      ([slotName, fillValue]): ReadonlyArray<readonly [string, SlotFill<unknown>]> =>
+        isSlotFill(fillValue) ? [[slotName, fillValue]] : [],
+    ),
+  )
+
+export const slotsOf = (comp: AnyComposition): Record<string, AnySlot> =>
+  comp.capture<Record<string, AnySlot>>((exact) => {
+    if (!('slots' in exact.manifest)) {
+      return {}
+    }
+    const candidate: unknown = exact.manifest.slots
+    if (!isRecord(candidate)) {
+      return {}
+    }
+    return Rec.fromEntries(
+      Rec.toEntries(candidate).flatMap(
+        ([name, slotDefinition]): ReadonlyArray<readonly [string, AnySlot]> =>
+          isSlot(slotDefinition) ? [[name, slotDefinition]] : [],
+      ),
+    )
+  })

package/src/wireRender.ts

@@ -0,0 +1,235 @@
+import { Context, Effect, Match, Option, type ParseResult, Record as Rec } from 'effect'
+import {
+  Composition,
+  type CompositionClass,
+  isStructure,
+  type SlotFill,
+  type Structure,
+  type UiContract,
+} from '@playfast/reform'
+import {
+  type AnyComposition,
+  type AnyScene,
+  type AnySlot,
+  type AnySlotChild,
+  type TriggerRegistryApi,
+  type WireNode,
+  type WireTree,
+} from '@playfast/reform/internal'
+import {
+  childComposition,
+  type Mounted,
+  noRegister,
+  slotsOf,
+  structureFills,
+  toWireNodeFromStructure,
+} from './wireNode'
+
+export interface RenderSceneToWireOptions {
+  readonly register: TriggerRegistryApi['register']
+}
+
+export const serviceFromContext = <Services, Identifier, Service>(
+  context: Context.Context<Services>,
+  tag: Context.Tag<Identifier, Service>,
+  missing: string,
+): Effect.Effect<Service, never, never> =>
+  Option.match(Context.getOption(context, tag), {
+    onNone: () => Effect.dieMessage(missing),
+    onSome: Effect.succeed,
+  })
+
+export const capturedSlotProvider = <Services>(
+  context: Context.Context<Services>,
+  slotDefinition: AnySlot,
+): Effect.Effect<AnySlotChild, never, never> =>
+  slotDefinition.capture((exact) =>
+    serviceFromContext(
+      context,
+      exact.provider,
+      'reform-remote: scene does not provide a declared slot',
+    ),
+  )
+
+export const renderCapturedComposition = <Services>(
+  context: Context.Context<Services>,
+  composition: AnyComposition,
+  props: unknown,
+): Effect.Effect<Structure<UiContract>, never, never> =>
+  composition.capture<Effect.Effect<Structure<UiContract>, never, never>>(
+    <P, C extends UiContract, S extends ReadonlyArray<unknown>, N extends string, Identity>(
+      exact: CompositionClass<P, C, S, N, Identity>,
+    ): Effect.Effect<Structure<UiContract>, never, never> =>
+      Option.match(exact.parseProps(props), {
+        onNone: () =>
+          Effect.dieMessage(
+            `reform-remote: invalid props for composition ${composition.manifest.name}`,
+          ),
+        onSome: (parsed) =>
+          serviceFromContext(
+            context,
+            exact.tag,
+            `reform-remote: scene does not provide composition ${composition.manifest.name}`,
+          ).pipe(
+            Effect.flatMap((service) =>
+              Composition.render<P, C>(service, {
+                props: parsed,
+                tracker: { add: () => {} },
+              }),
+            ),
+            Effect.flatMap((frame) => {
+              if (isStructure(frame)) {
+                return Effect.succeed(frame)
+              }
+              return Effect.dieMessage(
+                `reform-remote: composition ${composition.manifest.name} did not return a Structure`,
+              )
+            }),
+          ),
+      }),
+  )
+
+export const enqueueStructureSlot = (
+  parent: Mounted,
+  slotName: string,
+  child: AnyComposition,
+  fill: SlotFill<unknown>,
+): ReadonlyArray<Mounted> =>
+  Match.value(fill).pipe(
+    Match.tag('Each', (each) =>
+      each.items.map(
+        (entry, index): Mounted => ({
+          comp: child,
+          props: entry.props,
+          id: `${parent.id}.${slotName}.${index}`,
+          parentId: Option.some(parent.id),
+          slot: Option.some(slotName),
+          childIndex: index,
+          key: Option.fromNullable(entry.key),
+        }),
+      ),
+    ),
+    Match.tag('One', (single) => [
+      {
+        comp: child,
+        props: single.props,
+        id: `${parent.id}.${slotName}.0`,
+        parentId: Option.some(parent.id),
+        slot: Option.some(slotName),
+        childIndex: 0,
+        key: Option.none(),
+      } satisfies Mounted,
+    ]),
+    Match.tag('Absent', () => []),
+    Match.exhaustive,
+  )
+
+export type SlotProvider<Services> = (
+  slotDefinition: AnySlot,
+) => Effect.Effect<AnySlotChild, never, Services>
+
+export const collect: <Services>(
+  root: AnyComposition,
+  provideSlot: SlotProvider<Services>,
+) => Effect.Effect<Map<AnySlot, AnyComposition>, never, Services> = Effect.fn('collect')(
+  function* <Services>(
+  root: AnyComposition,
+  provideSlot: SlotProvider<Services>,
+): Effect.fn.Return<Map<AnySlot, AnyComposition>, never, Services> {
+  const bindings = new Map<AnySlot, AnyComposition>()
+  // Explicit type keeps the recursive reference cast-free.
+  const walk: (comp: AnyComposition) => Effect.Effect<void, never, Services> = Effect.fn('walk')(
+    function* (comp: AnyComposition): Effect.fn.Return<void, never, Services> {
+      yield* Effect.forEach(Rec.values(slotsOf(comp)), (slotClass) =>
+        Effect.gen(function* () {
+          if (bindings.has(slotClass)) {
+            return
+          }
+          const child = childComposition(yield* provideSlot(slotClass))
+          bindings.set(slotClass, child)
+          yield* walk(child)
+        }),
+      )
+    },
+  )
+  yield* walk(root)
+  return bindings
+})
+
+export type CompositionRenderer<Services> = (
+  composition: AnyComposition,
+  props: unknown,
+) => Effect.Effect<Structure<UiContract>, never, Services>
+
+export interface RenderLevel {
+  <Services>(
+    frontier: ReadonlyArray<Mounted>,
+    bindings: ReadonlyMap<AnySlot, AnyComposition>,
+    register: TriggerRegistryApi['register'],
+    render: CompositionRenderer<Services>,
+  ): Effect.Effect<ReadonlyArray<WireNode>, ParseResult.ParseError, Services>
+}
+
+export const renderLevel: RenderLevel = Effect.fn('renderLevel')(function* <Services>(
+  frontier: ReadonlyArray<Mounted>,
+  bindings: ReadonlyMap<AnySlot, AnyComposition>,
+  register: TriggerRegistryApi['register'],
+  render: CompositionRenderer<Services>,
+): Effect.fn.Return<ReadonlyArray<WireNode>, ParseResult.ParseError, Services> {
+  if (frontier.length === 0) {
+    return []
+  }
+  const rendered = yield* Effect.forEach(frontier, (mounted) =>
+    Effect.gen(function* () {
+      const frame = yield* render(mounted.comp, mounted.props)
+      const node = yield* toWireNodeFromStructure(mounted, frame, register)
+      const fills = structureFills(frame)
+      const children = Rec.toEntries(slotsOf(mounted.comp)).flatMap(([slotName, slotClass]) => {
+        const child = bindings.get(slotClass)
+        if (child === undefined) {
+          return []
+        }
+        const fill = fills[slotName]
+        if (fill === undefined) {
+          return []
+        }
+        return enqueueStructureSlot(mounted, slotName, child, fill)
+      })
+      return { node, children }
+    }),
+  )
+  const nodes = rendered.map((entry) => entry.node)
+  const next = rendered.flatMap((entry) => entry.children)
+  const rest = yield* renderLevel(next, bindings, register, render)
+  return [...nodes, ...rest]
+})
+
+export const renderSceneWith: <SlotServices, CompositionServices>(
+  scene: AnyScene,
+  options: RenderSceneToWireOptions | undefined,
+  provideSlot: SlotProvider<SlotServices>,
+  render: CompositionRenderer<CompositionServices>,
+) => Effect.Effect<
+  WireTree,
+  ParseResult.ParseError,
+  SlotServices | CompositionServices
+> = Effect.fn('renderSceneWith')(
+  function* <SlotServices, CompositionServices>(
+  scene: AnyScene,
+  options: RenderSceneToWireOptions | undefined,
+  provideSlot: SlotProvider<SlotServices>,
+  render: CompositionRenderer<CompositionServices>,
+): Effect.fn.Return<WireTree, ParseResult.ParseError, SlotServices | CompositionServices> {
+  const register = options?.register ?? noRegister
+  const bindings = yield* collect(scene.composition, provideSlot)
+  const root: Mounted = {
+    comp: scene.composition,
+    props: {},
+    id: '0',
+    parentId: Option.none(),
+    slot: Option.none(),
+    childIndex: 0,
+    key: Option.none(),
+  }
+  return yield* renderLevel([root], bindings, register, render)
+})

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