@playfast/reform-remote 0.0.3 → 0.0.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-remote",
   "playbook": "./playbook",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "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/fixtures.ts

@@ -15,6 +15,9 @@ import {
   StateGroup,
   Ui,
   type WiredUi,
+  each,
+  mount,
+  one,
   provide,
   scene,
   slot,
@@ -25,10 +28,10 @@ import {
  * Shared scenes the remote-transport tests render server-side. Each is a closed
  * `Scene` wired the canonical way — compositions + reducers in `Layer.mergeAll`,
  * then `provideMerge(presentation)` (views + seeded state) and `provideMerge(Engine)`
- * — so they exercise the real runtime, not a stub. The presentations here are the
- * server-side `Ui.make` views that *expand* the tree (a list view maps its state to
- * N slot children); the client renders the resulting wire tree with its own
- * `RemoteView`s (thunk slots), which the transport tests supply separately.
+ * — so they exercise the real runtime, not a stub. The compositions return
+ * headless structures; the server expands slot fills from those structures and the
+ * client renders the resulting wire tree with its own `RemoteView`s (thunk slots),
+ * which the transport tests supply separately.
  */
 
 // ── counter: a flat composition with own state + one event ────────────────────
@@ -60,13 +63,33 @@ export const counterScene = (boot?: ReadonlyArray<EventOf<'Bumped', { by: number
     Composition.live(Counter, function* () {
       const count = yield* StateGroup.select(Counters, 'count')
       const bump = yield* Event.trigger(Bumped)
-      return (yield* CounterUi)({ count }, { bump })
+      return mount({ props: { count }, slots: {}, events: { bump } })
     }),
     Reducer.live(Bump, (n, event) => n + event.by),
   ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
   return scene(Counter, boot === undefined ? { provide: [app] } : { provide: [app], boot })
 }
 
+// ── structure counter: kept as explicit structure-event coverage. The `bump`
+// trigger rides ON the structure, so the server reads it from `structure.events`,
+// registers the handle, and produces the same wire shape as a legacy view body.
+// ───────────────────────────────────────────────────────────────────────────────
+export const structureCounterScene = (): Scene => {
+  const presentation = Layer.mergeAll(
+    provide(CounterUi, Ui.make(CounterUi, ({ count }) => `count:${count}`)),
+    StateGroup.live(Counters, { count: 0 }),
+  )
+  const app = Layer.mergeAll(
+    Composition.live(Counter, function* () {
+      const count = yield* StateGroup.select(Counters, 'count')
+      const bump = yield* Event.trigger(Bumped)
+      return mount({ props: { count }, slots: {}, events: { bump } })
+    }),
+    Reducer.live(Bump, (n, event) => n + event.by),
+  ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
+  return scene(Counter, { provide: [app] })
+}
+
 // ── option: a flat composition whose prop is an `Option` (an Effect-native, non-JSON
 // value) — exercises the symmetric schema encode/decode so the client receives a REAL
 // `Option`, not its raw `{_tag,value}` wire shape. ──────────────────────────────────
@@ -86,7 +109,7 @@ export const optionScene = (initial: Option.Option<string> = Option.some('hi')):
   const app = Layer.mergeAll(
     Composition.live(Optional, function* () {
       const label = yield* StateGroup.select(Labels, 'label')
-      return (yield* OptionalUi)({ label })
+      return mount({ props: { label }, slots: {} })
     }),
   ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
   return scene(Optional, { provide: [app] })
@@ -117,15 +140,14 @@ export const slottedScene = (): Scene => {
   )
   const app = Layer.mergeAll(
     Composition.live(Shell, function* () {
-      const view = yield* ShellUi
-      return view({})
+      return mount({ props: {}, slots: { Main: one({}) } })
     }),
     Composition.live(Panel, function* () {
       const greeting = yield* Greeting
       const greet = yield* Event.trigger(Greeted)
       const clearTrigger = yield* Event.trigger(Cleared)
       const clear = (): void => clearTrigger({})
-      return (yield* PanelUi)({ greeting }, { greet, clear })
+      return mount({ props: { greeting }, slots: {}, events: { greet, clear } })
     }),
     Reducer.live(SetGreeting, (_greeting, event) => event.text),
     Reducer.live(ClearGreeting, () => ''),
@@ -171,12 +193,12 @@ export const listScene = (
   const presentation = Layer.mergeAll(
     provide(
       ListUi,
-      Ui.make(ListUi, ({ items }, slots) =>
+      Ui.make(ListUi, (_props, slots) =>
         createElement(
           Fragment,
           null,
           createElement(slots.Bar, {}),
-          ...items.map((item) => createElement(slots.Item, { id: item.id, label: item.label })),
+          createElement(slots.Item, {}),
         ),
       ),
     ),
@@ -189,12 +211,20 @@ export const listScene = (
   const app = Layer.mergeAll(
     Composition.live(ListComp, function* () {
       const items = yield* Items
-      const view = yield* ListUi
-      return view({ items })
+      return mount({
+        props: { items },
+        slots: {
+          Bar: one({}),
+          Item: each(items, {
+            key: (item) => item.id,
+            props: (item) => ({ id: item.id, label: item.label }),
+          }),
+        },
+      })
     }),
     Composition.live(Bar, function* () {
       const add = yield* Event.trigger(Added)
-      return (yield* BarUi)({}, { add })
+      return mount({ props: {}, slots: {}, events: { add } })
     }),
     Composition.live(ItemComp, function* () {
       const item = (yield* Props) as { id: string; label: string }
@@ -202,7 +232,7 @@ export const listScene = (
       // The item binds its own id, so the wire `remove` carries no payload — the
       // client fires it knowing only the handle.
       const remove = (): void => removeTrigger({ id: item.id })
-      return (yield* ItemUi)({ label: item.label }, { remove })
+      return mount({ props: { label: item.label }, slots: {}, events: { remove } })
     }),
     Reducer.live(AddItem, (items, event) => [...items, { id: event.id, label: event.label }]),
     Reducer.live(RemoveItem, (items, event) => items.filter((item) => item.id !== event.id)),
@@ -228,7 +258,7 @@ export const asyncCounterScene = (delay: Duration.DurationInput = '40 millis'):
     Composition.live(Counter, function* () {
       const count = yield* StateGroup.select(Counters, 'count')
       const bump = yield* Event.trigger(Bumped)
-      return (yield* CounterUi)({ count }, { bump })
+      return mount({ props: { count }, slots: {}, events: { bump } })
     }),
     Reducer.live(Bump, (n, event) => n + event.by),
     // The procedure runs on the bus AFTER the scene boots: it sleeps past the opening

package/src/server.test.ts

@@ -14,6 +14,7 @@ import {
   OptionalUi,
   optionScene,
   slottedScene,
+  structureCounterScene,
 } from './fixtures'
 
 // The client renders views as React components, so a test runs them by RENDERING
@@ -65,6 +66,27 @@ test('invoking a trigger handle dispatches into the runtime and the next render
   }
 })
 
+// ── structure-path counter: events ride ON the structure (plan 03b) ─────────────
+
+test('a mount(...)-returning body registers its event from structure.events and invoking it dispatches', async () => {
+  const server = makeRemoteServer(structureCounterScene())
+  try {
+    const tree = await server.render()
+    const root = tree[0]!
+    expect(root.name).toBe('Counter')
+    // Props come from the structure value; the `bump` trigger rode on
+    // `structure.events` and was registered behind the standard handle.
+    expect(dataOf(root, 'count')).toEqual({ _tag: 'Data', name: 'count', value: 0 })
+    expect(eventOf(root, 'bump')).toEqual({ _tag: 'Event', name: 'bump', handle: '0:bump' })
+
+    await server.invoke('0:bump', { by: 4 })
+    const next = await server.render()
+    expect(dataOf(next[0]!, 'count')).toEqual({ _tag: 'Data', name: 'count', value: 4 })
+  } finally {
+    await server.dispose()
+  }
+})
+
 test('the wire payload is validated at the seam — a bad payload rejects', async () => {
   const server = makeRemoteServer(counterScene())
   try {

package/src/server.ts

@@ -1,24 +1,23 @@
-import { Effect, Layer, ManagedRuntime, type ParseResult, PubSub, Queue, Schema } from 'effect'
-import { isValidElement } from 'react'
+import { Effect, Layer, Match, ManagedRuntime, type ParseResult, PubSub, Queue, Schema } from 'effect'
 import {
   Bus,
-  CaptureSink,
-  type CaptureSinkApi,
   Composition,
   type CompositionClass,
   type CompositionService,
   forceSync,
   isFeatureBinding,
-  type Node,
+  isStructure,
   publish,
   type RenderEnv,
   type Scene,
   type SlotChild,
   type SlotClass,
-  type SlotHost,
+  type SlotFill,
+  type Structure,
   Triggers,
+  type Trigger,
   type TriggerRegistryApi,
-  type UiCapture,
+  type UiContract,
   type UiManifest,
   Wire,
   type WireNode,
@@ -30,11 +29,11 @@ import {
 /**
  * The server side of the remote transport (REMOTE_UI.md §5): render a closed
  * `Scene` to a serializable `WireTree`, registering each trigger behind a handle.
- * Built on the existing `CaptureSink` seam — the same one proofs use headlessly —
- * so nothing in core changes: production has no sink (renders to React), a host
- * provides one (here, to serialize). The render walk lifts proof's breadth-first
- * `collect`/`drive`, assigning stable ids and encoding props via each contract's
- * own wire schema (`WiredUiManifest`, Phase 1).
+ * Reads each composition's returned `Structure` value directly — props, per-slot
+ * fills, and event triggers are all DATA — so the server imports no React and never
+ * 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 runtime services a closed scene exposes (mirrors proof's erasure boundary:
@@ -45,24 +44,13 @@ type RuntimeServices = CompositionService | SlotChild | Bus
 const SETTLE_DRAIN = 30
 const settleDrain = Effect.yieldNow().pipe(Effect.repeatN(SETTLE_DRAIN))
 
-interface Sink {
-  readonly api: CaptureSinkApi
-  readonly captures: ReadonlyArray<UiCapture>
-  reset(): void
-}
-
-const makeSink = (): Sink => {
-  const state: { captures: UiCapture[] } = { captures: [] }
-  return {
-    api: { record: (capture) => state.captures.push(capture) },
-    get captures() {
-      return state.captures
-    },
-    reset: () => {
-      state.captures = []
-    },
-  }
-}
+// The event triggers a `Structure` frame carries (plan 03b). A composition's logic
+// returns its acquired triggers ON the structure value (it never evaluates a view),
+// so the server reads them straight from there. At the erased `UiContract` boundary the contract's event map
+// is `Record<never, never>`, so each value is `never` — assignable to
+// `Trigger<unknown>` without a cast — and an omitted `events` defaults to empty.
+const eventsOf = (structure: Structure<UiContract>): Record<string, Trigger<unknown>> =>
+  Object.fromEntries(Object.entries(structure.events ?? {}))
 
 const closedSceneLayer = (scene: Scene): Layer.Layer<RuntimeServices, never, never> =>
   scene.provide.reduce((a, b) => Layer.merge(a, b)) as unknown as Layer.Layer<
@@ -86,33 +74,6 @@ interface Mounted {
 const childComposition = (child: SlotChild): CompositionClass<unknown> =>
   isFeatureBinding(child) ? child.composition : child
 
-/**
- * Walk a rendered node and enqueue the child each slot placeholder stands for.
- * Slot components are matched by identity (the host defers them as JSX), so this
- * never invokes — nor needs hooks from — ordinary presentation components.
- */
-const drive = (
-  node: Node,
-  enqueueBy: Map<Function, (props: unknown, key: string | null) => void>,
-): void => {
-  if (Array.isArray(node)) {
-    for (const child of node) drive(child, enqueueBy)
-    return
-  }
-  if (!isValidElement<{ readonly children?: Node }>(node)) return
-  if (node.type instanceof Function) {
-    const enqueue = enqueueBy.get(node.type)
-    if (enqueue !== undefined) {
-      // `node.key` is the React key the parent set (`createElement(slots.Row, { key })`),
-      // carried onto the wire node so a KEYED slot can select this child on the client
-      // (see WireNode.key). React coerces a set key to a string; absent → null.
-      enqueue(node.props, node.key)
-      return
-    }
-  }
-  drive(node.props.children, enqueueBy)
-}
-
 const handlesOf = (node: WireNode): ReadonlyArray<string> =>
   node.props.flatMap((prop) => (prop._tag === 'Event' ? [prop.handle] : []))
 
@@ -141,10 +102,7 @@ export interface RemoteServer {
 }
 
 export const makeRemoteServer = (scene: Scene): RemoteServer => {
-  const sink = makeSink()
-  const runtime = ManagedRuntime.make(
-    Layer.provideMerge(closedSceneLayer(scene), Layer.succeed(CaptureSink, sink.api)),
-  )
+  const runtime = ManagedRuntime.make(closedSceneLayer(scene))
   const registry: TriggerRegistryApi = forceSync(() => runtime.runSync(Triggers.make))
 
   const collect = (
@@ -165,33 +123,40 @@ export const makeRemoteServer = (scene: Scene): RemoteServer => {
       return bindings
     })
 
-  const toWireNode = (m: Mounted, capture: UiCapture): Effect.Effect<WireNode, ParseResult.ParseError> =>
+  // 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* () {
-      // The composition's contract carries the wire schemas at runtime (the type is
-      // the erased `{ manifest }` carrier — `composition.ts:34`); read them as `UiManifest`.
       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)(capture.props)
-        for (const [name, value] of Object.entries(encoded as Record<string, unknown>)) {
-          dataProps.push({ _tag: 'Data', name, value })
+        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[] = []
-      for (const [name, trigger] of Object.entries(capture.events)) {
-        const schema = eventSchemas[name]
+      const events = eventsOf(structure)
+      for (const [eventName, trigger] of Object.entries(events)) {
+        const schema = eventSchemas[eventName]
         if (schema === undefined) continue
-        const handle = `${m.id}:${name}`
+        const handle = `${m.id}:${eventName}`
         yield* registry.register(handle, trigger, schema)
-        eventProps.push({ _tag: 'Event', name, handle })
+        eventProps.push({ _tag: 'Event', name: eventName, handle })
       }
 
       return {
         id: m.id,
-        name: capture.name,
+        name,
         parentId: m.parentId,
         childIndex: m.childIndex,
         slot: m.slot,
@@ -200,6 +165,64 @@ export const makeRemoteServer = (scene: Scene): RemoteServer => {
       }
     })
 
+  // 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] : [],
+      ),
+    )
+
+  // 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) => {
+        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>>,
@@ -210,37 +233,25 @@ export const makeRemoteServer = (scene: Scene): RemoteServer => {
       const nodes: WireNode[] = []
       for (const mounted of frontier) {
         const service = yield* mounted.comp.tag
-        const slotIndex = new Map<string, number>()
-        const enqueueBy = new Map<Function, (childProps: unknown, key: string | null) => void>()
-        const slots: SlotHost = {
-          slot: (name) => {
-            const slotClass = mounted.comp.manifest.slots?.[name]
-            const child = slotClass ? bindings.get(slotClass) : undefined
-            const component: (childProps: unknown) => Node = () => null
-            if (child !== undefined) {
-              enqueueBy.set(component, (childProps, key) => {
-                const index = slotIndex.get(name) ?? 0
-                slotIndex.set(name, index + 1)
-                next.push({
-                  comp: child,
-                  props: childProps,
-                  id: `${mounted.id}.${name}.${index}`,
-                  parentId: mounted.id,
-                  slot: name,
-                  childIndex: index,
-                  key,
-                })
-              })
-            }
-            return component
-          },
+        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 before = sink.captures.length
-        const env: RenderEnv = { props: mounted.props, tracker: { add: () => {} }, slots }
-        const node = yield* Composition.render(service, env)
-        const capture = sink.captures[before]
-        if (capture !== undefined) nodes.push(yield* toWireNode(mounted, capture))
-        drive(node, enqueueBy)
       }
       const rest = yield* renderLevel(next, bindings)
       return [...nodes, ...rest]
@@ -248,7 +259,6 @@ export const makeRemoteServer = (scene: Scene): RemoteServer => {
 
   const renderEffect = Effect.gen(function* () {
     yield* settleDrain
-    sink.reset()
     const bindings = yield* collect(scene.composition)
     const root: Mounted = {
       comp: scene.composition,
@@ -291,7 +301,7 @@ export const makeRemoteServer = (scene: Scene): RemoteServer => {
   runtime.runSync(Effect.forEach(scene.boot ?? [], (event) => publish('High', event)))
 
   // The last emitted frame, to diff against. A const holder whose field we swap
-  // (no reassigned binding), matching the sink's immutable-swap idiom.
+  // (no reassigned binding — house rule), not a `let`.
   const frame: { tree: WireTree } = { tree: [] }
 
   const render = (): Promise<WireTree> =>