@playfast/reform-remote 0.0.4 → 0.0.5

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-remote",
   "playbook": "./playbook",
-  "version": "0.0.4",
+  "version": "0.0.5",
   "type": "module",
   "description": "Run a reform scene's logic on the server and stream its rendered UI to a thin client over any duplex transport.",
   "keywords": [

package/src/client.ts

@@ -227,47 +227,52 @@ const WireNodeView = ({
       ? encoded
       : Schema.decodeUnknownSync(registered.propsSchema)(encoded)
 
-  const children = Wire.childrenOf(tree, node.id)
-  const slots: Record<string, (slotProps?: { readonly slotKey?: string }) => ReactNode> = {}
-  for (const slotName of new Set(children.map((child) => child.slot))) {
-    if (slotName === null) continue
-    // A slot is a COMPONENT rendering that slot's wire children — usable as `<slots.Foo/>`
-    // (Ui.make convention) or `slots.Foo()` (thunk convention). The function is cached so its
-    // identity is STABLE across renders (see `slotCache` above); it reads `latest.current` so
-    // each invocation renders against the current tree/config.
-    //
-    // KEYED SLOTS: when the caller passes `slotKey` (`<slots.Row slotKey={id} />`), render only
-    // the ONE wire child whose `key` matches — the per-item identity the server captured from
-    // the parent's React `key` (see WireNode.key). This is what lets a LIST slot be invoked once
-    // per item without each call rendering the WHOLE list (the duplicate-rows bug). With NO
-    // `slotKey` the behaviour is unchanged: render every child of the slot (correct for a
-    // singleton slot rendered once, e.g. `<slots.Create/>`).
+  // A slot resolves to a COMPONENT rendering that slot's wire children — usable as
+  // `<slots.Foo/>` (Ui.make convention) or `slots.Foo()` (thunk convention). The function is
+  // cached so its identity is STABLE across renders (see `slotCache` above); it reads
+  // `latest.current` so each invocation renders against the current tree/config.
+  //
+  // KEYED SLOTS: when the caller passes `slotKey` (`<slots.Row slotKey={id} />`), render only
+  // the ONE wire child whose `key` matches — the per-item identity the server captured from
+  // the parent's React `key` (see WireNode.key). This is what lets a LIST slot be invoked once
+  // per item without each call rendering the WHOLE list (the duplicate-rows bug). With NO
+  // `slotKey` the behaviour is unchanged: render every child of the slot (correct for a
+  // singleton slot rendered once, e.g. `<slots.Create/>`).
+  const slotFor = (slotName: string): ((slotProps?: { readonly slotKey?: string }) => ReactNode) => {
     const cached = slotCache.current[slotName]
-    const stable =
-      cached ??
-      ((slotProps?: { readonly slotKey?: string }): ReactNode => {
-        const { node: currentNode, tree: currentTree, config: currentConfig } = latest.current
-        const requestedKey = slotProps?.slotKey
-        return createElement(
-          Fragment,
-          null,
-          ...Wire.childrenOf(currentTree, currentNode.id)
-            .filter((child) => child.slot === slotName)
-            .filter((child) => requestedKey === undefined || child.key === requestedKey)
-            .map((child) =>
-              createElement(WireNodeView, {
-                key: child.id,
-                node: child,
-                tree: currentTree,
-                config: currentConfig,
-              }),
-            ),
-        )
-      })
+    if (cached !== undefined) return cached
+    const stable = (slotProps?: { readonly slotKey?: string }): ReactNode => {
+      const { node: currentNode, tree: currentTree, config: currentConfig } = latest.current
+      const requestedKey = slotProps?.slotKey
+      return createElement(
+        Fragment,
+        null,
+        ...Wire.childrenOf(currentTree, currentNode.id)
+          .filter((child) => child.slot === slotName)
+          .filter((child) => requestedKey === undefined || child.key === requestedKey)
+          .map((child) =>
+            createElement(WireNodeView, {
+              key: child.id,
+              node: child,
+              tree: currentTree,
+              config: currentConfig,
+            }),
+          ),
+      )
+    }
     slotCache.current[slotName] = stable
-    slots[slotName] = stable
+    return stable
   }
 
+  // Resolve slots LAZILY by name: a view referencing `<slots.Item/>` when that slot has no
+  // wire children this frame (e.g. an empty list) gets a component that renders nothing,
+  // rather than `undefined` (which React rejects as an invalid element type). Mirrors the
+  // engine's total slot proxies — every declared slot is always callable.
+  const slots: Record<string, (slotProps?: { readonly slotKey?: string }) => ReactNode> = new Proxy(
+    Object.create(null),
+    { get: (_target, key) => (typeof key === 'string' ? slotFor(key) : undefined) },
+  )
+
   return registered.view(props, slots, events)
 }
 

package/src/index.ts

@@ -14,7 +14,7 @@ export * as Transport from './transport'
 export * as Memory from './memory'
 export * as React from './react'
 
-export { makeRemoteServer, type RemoteServer } from './server'
+export { makeRemoteServer, type RemoteServer, renderSceneToWire } from './server'
 export {
   type ClientConfig,
   type RegisteredRemoteView,

package/src/server.ts

@@ -34,6 +34,11 @@ import {
  * evaluates a view. The render walk is breadth-first over the structure tree,
  * assigning stable ids and encoding props via each contract's own wire schema
  * (`WiredUiManifest`, Phase 1).
+ *
+ * The render walk (`renderSceneToWire`) is a free-standing effect that requires only
+ * `CompositionService | SlotChild` — so any runtime that supplies a scene's services
+ * can render a frame, not just `makeRemoteServer`'s own. `@playfast/reform-driver-shot`
+ * runs it against `@playfast/reform-drive`'s runtime to screenshot a driven state.
  */
 
 // The runtime services a closed scene exposes (mirrors proof's erasure boundary:
@@ -77,188 +82,181 @@ const childComposition = (child: SlotChild): CompositionClass<unknown> =>
 const handlesOf = (node: WireNode): ReadonlyArray<string> =>
   node.props.flatMap((prop) => (prop._tag === 'Event' ? [prop.handle] : []))
 
-export interface RemoteServer {
-  /** Render the current frame to a full wire tree; triggers are (re-)registered behind stable handles. */
-  readonly render: () => Promise<WireTree>
-  /**
-   * Render and return only the patches since the previous frame (the streaming
-   * form). Handles of deleted nodes are revoked, so a stale client invocation
-   * fails cleanly rather than firing a dangling trigger.
-   */
-  readonly renderDiff: () => Promise<ReadonlyArray<WirePatch>>
-  /** Fire a trigger the client referenced by handle, then settle the runtime. */
-  readonly invoke: (handle: string, encodedPayload: unknown) => Promise<void>
-  /**
-   * Observe SERVER-INITIATED state changes. The listener fires (after the drain
-   * settles) whenever an event flows on the engine bus — i.e. when an async procedure
-   * resolves, a boot loader completes, or a scheduler ticks — NOT just in response to a
-   * client invoke. `serve` registers a `renderDiff`-and-push listener here so the client
-   * sees background updates (a repo list that finishes loading, a reconcile sweep) that
-   * no user interaction triggered. Returns an unsubscribe handle.
-   */
-  readonly subscribe: (listener: () => void) => () => void
-  /** Tear down the runtime and its forked fibers. */
-  readonly dispose: () => Promise<void>
-}
+// A static render (a screenshot) has no client to receive trigger handles, so the
+// default registrar is a no-op: the wire node still carries its `Event` props (with
+// deterministic handles), they're just never registered for invocation.
+const noRegister: TriggerRegistryApi['register'] = () => Effect.void
 
-export const makeRemoteServer = (scene: Scene): RemoteServer => {
-  const runtime = ManagedRuntime.make(closedSceneLayer(scene))
-  const registry: TriggerRegistryApi = forceSync(() => runtime.runSync(Triggers.make))
+// Structure → wire encoding (plan 02 + 03b). Props come straight from the
+// `Structure` value (data, never a view render). Event triggers ride ON the
+// structure (`structure.events`) and are registered through `register` (the live
+// registry for a streaming server, a no-op for a one-shot render). Produces the
+// wire shape the transport and `Wire.diff` consume.
+const toWireNodeFromStructure = (
+  m: Mounted,
+  structure: Structure<UiContract>,
+  register: TriggerRegistryApi['register'],
+): Effect.Effect<WireNode, ParseResult.ParseError> =>
+  Effect.gen(function* () {
+    const manifest = m.comp.manifest.ui.manifest as UiManifest
+    const name = manifest.name
 
-  const collect = (
-    root: CompositionClass<unknown>,
-  ): Effect.Effect<Map<SlotClass, CompositionClass<unknown>>, never, SlotChild> =>
-    Effect.gen(function* () {
-      const bindings = new Map<SlotClass, CompositionClass<unknown>>()
-      const walk = (comp: CompositionClass<unknown>): Effect.Effect<void, never, SlotChild> =>
-        Effect.gen(function* () {
-          for (const slotClass of Object.values(comp.manifest.slots ?? {})) {
-            if (bindings.has(slotClass)) continue
-            const child = childComposition(yield* slotClass.tag)
-            bindings.set(slotClass, child)
-            yield* walk(child)
-          }
-        })
-      yield* walk(root)
-      return bindings
-    })
-
-  // Structure → wire encoding (plan 02 + 03b). Props come straight from the
-  // `Structure` value (data, never a view render). Event triggers ride ON the
-  // structure (`structure.events`) and are registered from there. Produces the wire
-  // shape the transport and `Wire.diff` consume.
-  const toWireNodeFromStructure = (
-    m: Mounted,
-    structure: Structure<UiContract>,
-  ): Effect.Effect<WireNode, ParseResult.ParseError> =>
-    Effect.gen(function* () {
-      const manifest = m.comp.manifest.ui.manifest as UiManifest
-      const name = manifest.name
-
-      const dataProps: WireProp[] = []
-      if (manifest.props !== undefined) {
-        const encoded = yield* Schema.encodeUnknown(manifest.props)(structure.props)
-        for (const [propName, value] of Object.entries(encoded as Record<string, unknown>)) {
-          dataProps.push({ _tag: 'Data', name: propName, value })
-        }
+    const dataProps: WireProp[] = []
+    if (manifest.props !== undefined) {
+      const encoded = yield* Schema.encodeUnknown(manifest.props)(structure.props)
+      for (const [propName, value] of Object.entries(encoded as Record<string, unknown>)) {
+        dataProps.push({ _tag: 'Data', name: propName, value })
       }
+    }
 
-      const eventSchemas = manifest.events ?? {}
-      const eventProps: WireProp[] = []
-      const events = eventsOf(structure)
-      for (const [eventName, trigger] of Object.entries(events)) {
-        const schema = eventSchemas[eventName]
-        if (schema === undefined) continue
-        const handle = `${m.id}:${eventName}`
-        yield* registry.register(handle, trigger, schema)
-        eventProps.push({ _tag: 'Event', name: eventName, handle })
-      }
+    const eventSchemas = manifest.events ?? {}
+    const eventProps: WireProp[] = []
+    const events = eventsOf(structure)
+    for (const [eventName, trigger] of Object.entries(events)) {
+      const schema = eventSchemas[eventName]
+      if (schema === undefined) continue
+      const handle = `${m.id}:${eventName}`
+      yield* register(handle, trigger, schema)
+      eventProps.push({ _tag: 'Event', name: eventName, handle })
+    }
 
-      return {
-        id: m.id,
-        name,
-        parentId: m.parentId,
-        childIndex: m.childIndex,
-        slot: m.slot,
-        key: m.key,
-        props: [...dataProps, ...eventProps],
-      }
-    })
+    return {
+      id: m.id,
+      name,
+      parentId: m.parentId,
+      childIndex: m.childIndex,
+      slot: m.slot,
+      key: m.key,
+      props: [...dataProps, ...eventProps],
+    }
+  })
 
-  // Narrow an erased slot value to a `SlotFill` by its discriminant. `Structure<
-  // UiContract>` erases its per-slot fill types at this boundary (the strict typing
-  // lives on the concrete contract), so the runtime fills arrive as `unknown` and
-  // are recovered structurally — no `as`.
-  const isSlotFill = (u: unknown): u is SlotFill<unknown> =>
-    typeof u === 'object' &&
-    u !== null &&
-    '_tag' in u &&
-    (u._tag === 'Each' || u._tag === 'One' || u._tag === 'Absent')
+// Narrow an erased slot value to a `SlotFill` by its discriminant. `Structure<
+// UiContract>` erases its per-slot fill types at this boundary (the strict typing
+// lives on the concrete contract), so the runtime fills arrive as `unknown` and
+// are recovered structurally — no `as`.
+const isSlotFill = (u: unknown): u is SlotFill<unknown> =>
+  typeof u === 'object' &&
+  u !== null &&
+  '_tag' in u &&
+  (u._tag === 'Each' || u._tag === 'One' || u._tag === 'Absent')
 
-  // Read a structure's fills by slot name, recovering each erased value via the
-  // discriminant guard. Returns a plain record keyed by declared slot name.
-  const structureFills = (structure: Structure<UiContract>): Record<string, SlotFill<unknown>> =>
-    Object.fromEntries(
-      Object.entries(structure.slots).flatMap(([name, value]) =>
-        isSlotFill(value) ? [[name, value] as const] : [],
-      ),
-    )
+// Read a structure's fills by slot name, recovering each erased value via the
+// discriminant guard. Returns a plain record keyed by declared slot name.
+const structureFills = (structure: Structure<UiContract>): Record<string, SlotFill<unknown>> =>
+  Object.fromEntries(
+    Object.entries(structure.slots).flatMap(([name, value]) =>
+      isSlotFill(value) ? [[name, value] as const] : [],
+    ),
+  )
 
-  // Enqueue the children a single declared slot is filled with, reading the fill
-  // (Each / One / Absent) from the returned `Structure`. Multiplicity, per-item
-  // `key`, and props are carried as data — no view walk, no reconstruction.
-  const enqueueStructureSlot = (
-    parent: Mounted,
-    slotName: string,
-    child: CompositionClass<unknown>,
-    fill: SlotFill<unknown>,
-    next: Mounted[],
-  ): void =>
-    Match.value(fill).pipe(
-      Match.tag('Each', (each) => {
-        each.items.forEach((item, index) => {
-          next.push({
-            comp: child,
-            props: item.props,
-            id: `${parent.id}.${slotName}.${index}`,
-            parentId: parent.id,
-            slot: slotName,
-            childIndex: index,
-            key: item.key,
-          })
-        })
-      }),
-      Match.tag('One', (single) => {
+// Enqueue the children a single declared slot is filled with, reading the fill
+// (Each / One / Absent) from the returned `Structure`. Multiplicity, per-item
+// `key`, and props are carried as data — no view walk, no reconstruction.
+const enqueueStructureSlot = (
+  parent: Mounted,
+  slotName: string,
+  child: CompositionClass<unknown>,
+  fill: SlotFill<unknown>,
+  next: Mounted[],
+): void =>
+  Match.value(fill).pipe(
+    Match.tag('Each', (each) => {
+      each.items.forEach((item, index) => {
         next.push({
           comp: child,
-          props: single.props,
-          id: `${parent.id}.${slotName}.0`,
+          props: item.props,
+          id: `${parent.id}.${slotName}.${index}`,
           parentId: parent.id,
           slot: slotName,
-          childIndex: 0,
-          key: null,
+          childIndex: index,
+          key: item.key,
         })
-      }),
-      Match.tag('Absent', () => {}),
-      Match.exhaustive,
-    )
+      })
+    }),
+    Match.tag('One', (single) => {
+      next.push({
+        comp: child,
+        props: single.props,
+        id: `${parent.id}.${slotName}.0`,
+        parentId: parent.id,
+        slot: slotName,
+        childIndex: 0,
+        key: null,
+      })
+    }),
+    Match.tag('Absent', () => {}),
+    Match.exhaustive,
+  )
 
-  const renderLevel = (
-    frontier: ReadonlyArray<Mounted>,
-    bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
-  ): Effect.Effect<ReadonlyArray<WireNode>, ParseResult.ParseError, CompositionService> =>
-    Effect.gen(function* () {
-      if (frontier.length === 0) return []
-      const next: Mounted[] = []
-      const nodes: WireNode[] = []
-      for (const mounted of frontier) {
-        const service = yield* mounted.comp.tag
-        const env: RenderEnv = { props: mounted.props, tracker: { add: () => {} } }
-        const frame = yield* Composition.render(service, env)
-        // Every composition returns a `Structure` (the Node render path is gone): its
-        // wire node's props come from `frame.props`, event triggers from `frame.events`,
-        // and children are enqueued by reading each declared slot's fill — no view eval.
-        if (!isStructure(frame)) {
-          return yield* Effect.dieMessage(
-            `reform-remote server: composition ${mounted.comp.manifest.name} did not return a Structure`,
-          )
-        }
-        nodes.push(yield* toWireNodeFromStructure(mounted, frame))
-        const fills = structureFills(frame)
-        for (const [slotName, slotClass] of Object.entries(mounted.comp.manifest.slots ?? {})) {
-          const child = bindings.get(slotClass)
-          if (child === undefined) continue
-          const fill = fills[slotName]
-          if (fill === undefined) continue
-          enqueueStructureSlot(mounted, slotName, child, fill, next)
+const collect = (
+  root: CompositionClass<unknown>,
+): Effect.Effect<Map<SlotClass, CompositionClass<unknown>>, never, SlotChild> =>
+  Effect.gen(function* () {
+    const bindings = new Map<SlotClass, CompositionClass<unknown>>()
+    const walk = (comp: CompositionClass<unknown>): Effect.Effect<void, never, SlotChild> =>
+      Effect.gen(function* () {
+        for (const slotClass of Object.values(comp.manifest.slots ?? {})) {
+          if (bindings.has(slotClass)) continue
+          const child = childComposition(yield* slotClass.tag)
+          bindings.set(slotClass, child)
+          yield* walk(child)
         }
+      })
+    yield* walk(root)
+    return bindings
+  })
+
+const renderLevel = (
+  frontier: ReadonlyArray<Mounted>,
+  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
+  register: TriggerRegistryApi['register'],
+): Effect.Effect<ReadonlyArray<WireNode>, ParseResult.ParseError, CompositionService> =>
+  Effect.gen(function* () {
+    if (frontier.length === 0) return []
+    const next: Mounted[] = []
+    const nodes: WireNode[] = []
+    for (const mounted of frontier) {
+      const service = yield* mounted.comp.tag
+      const env: RenderEnv = { props: mounted.props, tracker: { add: () => {} } }
+      const frame = yield* Composition.render(service, env)
+      // Every composition returns a `Structure` (the Node render path is gone): its
+      // wire node's props come from `frame.props`, event triggers from `frame.events`,
+      // and children are enqueued by reading each declared slot's fill — no view eval.
+      if (!isStructure(frame)) {
+        return yield* Effect.dieMessage(
+          `reform-remote server: composition ${mounted.comp.manifest.name} did not return a Structure`,
+        )
       }
-      const rest = yield* renderLevel(next, bindings)
-      return [...nodes, ...rest]
-    })
+      nodes.push(yield* toWireNodeFromStructure(mounted, frame, register))
+      const fills = structureFills(frame)
+      for (const [slotName, slotClass] of Object.entries(mounted.comp.manifest.slots ?? {})) {
+        const child = bindings.get(slotClass)
+        if (child === undefined) continue
+        const fill = fills[slotName]
+        if (fill === undefined) continue
+        enqueueStructureSlot(mounted, slotName, child, fill, next)
+      }
+    }
+    const rest = yield* renderLevel(next, bindings, register)
+    return [...nodes, ...rest]
+  })
 
-  const renderEffect = Effect.gen(function* () {
-    yield* settleDrain
+/**
+ * Render the scene's CURRENT frame to a serializable `WireTree`, breadth-first from
+ * the root composition. Requires only the scene's render services
+ * (`CompositionService | SlotChild`), so it runs on any runtime built from the same
+ * closed scene — `makeRemoteServer`'s, or `@playfast/reform-drive`'s (the screenshot
+ * path). `register` defaults to a no-op: a one-shot render needs no live trigger
+ * registry, while `makeRemoteServer` passes its connection registry so the streamed
+ * client can invoke handles.
+ */
+export const renderSceneToWire = (
+  scene: Scene,
+  options?: { readonly register?: TriggerRegistryApi['register'] },
+): Effect.Effect<WireTree, ParseResult.ParseError, CompositionService | SlotChild> =>
+  Effect.gen(function* () {
+    const register = options?.register ?? noRegister
     const bindings = yield* collect(scene.composition)
     const root: Mounted = {
       comp: scene.composition,
@@ -269,9 +267,43 @@ export const makeRemoteServer = (scene: Scene): RemoteServer => {
       childIndex: 0,
       key: null,
     }
-    return yield* renderLevel([root], bindings)
+    return yield* renderLevel([root], bindings, register)
   })
 
+export interface RemoteServer {
+  /** Render the current frame to a full wire tree; triggers are (re-)registered behind stable handles. */
+  readonly render: () => Promise<WireTree>
+  /**
+   * Render and return only the patches since the previous frame (the streaming
+   * form). Handles of deleted nodes are revoked, so a stale client invocation
+   * fails cleanly rather than firing a dangling trigger.
+   */
+  readonly renderDiff: () => Promise<ReadonlyArray<WirePatch>>
+  /** Fire a trigger the client referenced by handle, then settle the runtime. */
+  readonly invoke: (handle: string, encodedPayload: unknown) => Promise<void>
+  /**
+   * Observe SERVER-INITIATED state changes. The listener fires (after the drain
+   * settles) whenever an event flows on the engine bus — i.e. when an async procedure
+   * resolves, a boot loader completes, or a scheduler ticks — NOT just in response to a
+   * client invoke. `serve` registers a `renderDiff`-and-push listener here so the client
+   * sees background updates (a repo list that finishes loading, a reconcile sweep) that
+   * no user interaction triggered. Returns an unsubscribe handle.
+   */
+  readonly subscribe: (listener: () => void) => () => void
+  /** Tear down the runtime and its forked fibers. */
+  readonly dispose: () => Promise<void>
+}
+
+export const makeRemoteServer = (scene: Scene): RemoteServer => {
+  const runtime = ManagedRuntime.make(closedSceneLayer(scene))
+  const registry: TriggerRegistryApi = forceSync(() => runtime.runSync(Triggers.make))
+
+  // The shared render walk, registering triggers in this connection's registry so the
+  // client can invoke them. `settleDrain` first so an in-flight batch folds into state.
+  const renderEffect = settleDrain.pipe(
+    Effect.zipRight(renderSceneToWire(scene, { register: registry.register })),
+  )
+
   // Server-initiated change notification: a forked daemon subscribes to the engine bus
   // and, after each batch settles, fans out to registered listeners. This is what lets a
   // streaming binding push frames the client never asked for — a background load resolving