@playfast/reform-remote 0.0.5 → 0.1.0

package/README.md

@@ -9,9 +9,9 @@
 ---
 
 A fourth consumer of a reform [`Scene`](https://www.npmjs.com/package/@playfast/reform), alongside
-[`@playfast/react`](https://www.npmjs.com/package/@playfast/react),
-[`@playfast/react-native`](https://www.npmjs.com/package/@playfast/react-native), and
-[`@playfast/proof`](https://www.npmjs.com/package/@playfast/proof). State, events, reducers,
+[`@playfast/reform-react`](https://www.npmjs.com/package/@playfast/reform-react),
+[`@playfast/reform-react-native`](https://www.npmjs.com/package/@playfast/reform-react-native), and
+[`@playfast/reform-proof`](https://www.npmjs.com/package/@playfast/reform-proof). State, events, reducers,
 async/remote data, and compositions all run **server-side**; the client receives a serialized
 tree of rendered UI contracts and renders them with local presentations. The wire carries only
 data — UI-tree patches one way, trigger invocations the other — so there is no API layer to write.
@@ -113,13 +113,6 @@ sockets pair with [`@playfast/reform-remote-node`](https://www.npmjs.com/package
 | [`@playfast/reform-remote-bun`](https://www.npmjs.com/package/@playfast/reform-remote-bun) | WebSocket server | `Bun.serve` |
 | [`@playfast/reform-remote-web`](https://www.npmjs.com/package/@playfast/reform-remote-web) | WebSocket client (factory, auto-reconnect) | global `WebSocket` |
 
-## Status
-
-The full loop — scene → wire tree → diff → client render → trigger → server dispatch → re-render
-— is implemented and proven over the in-memory transport (flat, nested-slot, and dynamic-list
-scenes) and over real WebSockets via the adapter packages above. Remaining: `provideRemote` sugar
-that gates wiring on the `WiredUi` brand per remote.
-
 ## License
 
 MIT

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-remote",
   "playbook": "./playbook",
-  "version": "0.0.5",
+  "version": "0.1.0",
   "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

@@ -1,5 +1,5 @@
 import { createElement, Fragment, type ReactNode, useRef } from 'react'
-import { Schema } from 'effect'
+import { Option, Record as Rec, Schema } from 'effect'
 import {
   type MadeView,
   Ui,
@@ -42,11 +42,17 @@ type AnyMadeView = MadeView<any>
  * their runtime form. Views are authored with `Ui.make` (contract-typed); this is
  * only the internal shape `renderWireTree` invokes them through.
  */
+/** Props a slot thunk/component accepts — a React element-props boundary
+ *  (`<slots.Row slotKey={id}/>`), so it stays a plain optional-field shape. */
+export interface SlotPropsExternalApi {
+  readonly slotKey?: string
+}
+
 export type RemoteView = (
   props: Record<string, unknown>,
   // A slot thunk optionally takes `{ slotKey }` to select a single keyed child (see the keyed-
   // slot handling in `WireNodeView`); omitting it renders all of the slot's children.
-  slots: Record<string, (slotProps?: { readonly slotKey?: string }) => ReactNode>,
+  slots: Record<string, (slotProps?: SlotPropsExternalApi) => ReactNode>,
   events: Record<string, (payload: unknown) => void>,
 ) => ReactNode
 
@@ -58,7 +64,7 @@ export type RemoteView = (
 export interface RegisteredRemoteView {
   readonly name: string
   readonly view: RemoteView
-  readonly propsSchema?: Schema.Schema<Record<string, unknown>, unknown>
+  readonly propsSchema: Option.Option<Schema.Schema<Record<string, unknown>, unknown>>
 }
 
 /** The by-name presentation record the renderer walks — the unbranded runtime shape behind
@@ -144,17 +150,16 @@ export type RemoteViews<C extends RemoteContract> = {
  * accept); an unbranded `Record` can never be substituted.
  */
 export const remoteViews = <C extends RemoteContract>(views: RemoteViews<C>): RemoteViewSet<C> => {
-  const list: ReadonlyArray<AnyMadeView> = Object.values(views)
-  const byName: ViewRegistry = Object.fromEntries(
-    list.map((view): readonly [string, RegisteredRemoteView] => {
+  const madeViews: ReadonlyArray<AnyMadeView> = Object.values(views)
+  const byName: ViewRegistry = Rec.fromEntries(
+    madeViews.map((view): readonly [string, RegisteredRemoteView] => {
       const viewContract = view[UiViewContract]
-      const propsSchema = viewContract.manifest.props
       // `Node` is `ReactNode` and `ViewImpl`'s params widen to the dynamic shape the
       // renderer calls, so the contract-typed view IS a `RemoteView` — no cast.
       const entry: RegisteredRemoteView = {
         name: viewContract.manifest.name,
         view,
-        ...(propsSchema !== undefined ? { propsSchema } : {}),
+        propsSchema: Option.fromNullable(viewContract.manifest.props),
       }
       return [entry.name, entry]
     }),
@@ -163,7 +168,7 @@ export const remoteViews = <C extends RemoteContract>(views: RemoteViews<C>): Re
   // function OF `C` that is never called, so it needs NO runtime value of `C` — the set is
   // built cast-free even though the client only has the contract as a type. The renderer
   // reads the set by string key; the brand is never read at runtime.
-  return Object.assign(byName, { [ViewSetContract]: (_contract: C): void => {} })
+  return { ...byName, [ViewSetContract]: (_contract: C): void => {} }
 }
 
 export interface ClientConfig<C extends RemoteContract> {
@@ -188,15 +193,13 @@ interface RenderConfig {
  * slot components, and runs the registered view INSIDE this component so the view's
  * own hooks get a fiber. A child slot renders its wire children as nested `WireNodeView`s.
  */
-const WireNodeView = ({
-  node,
-  tree,
-  config,
-}: {
+interface WireNodeViewProps {
   readonly node: WireNode
   readonly tree: WireTree
   readonly config: RenderConfig
-}): ReactNode => {
+}
+
+const WireNodeView = ({ node, tree, config }: WireNodeViewProps): ReactNode => {
   // The latest render inputs, for the stable slot closures below to read. Mutated every
   // render so a slot always renders against the current tree, even though its function
   // identity never changes.
@@ -214,18 +217,24 @@ const WireNodeView = ({
   const slotCache = useRef<Record<string, () => ReactNode>>({})
 
   const registered = config.views[node.name]
-  if (registered === undefined) return null
-
-  const encoded: Record<string, unknown> = {}
-  const events: Record<string, (payload: unknown) => void> = {}
-  for (const prop of node.props) {
-    if (prop._tag === 'Data') encoded[prop.name] = prop.value
-    else events[prop.name] = (payload) => config.invoke(prop.handle, payload)
+  if (registered === undefined) {
+    return null
   }
-  const props: Record<string, unknown> =
-    registered.propsSchema === undefined
-      ? encoded
-      : Schema.decodeUnknownSync(registered.propsSchema)(encoded)
+
+  const encoded: Record<string, unknown> = Rec.fromEntries(
+    node.props.flatMap((prop) => (prop._tag === 'Data' ? [[prop.name, prop.value] as const] : [])),
+  )
+  const events: Record<string, (payload: unknown) => void> = Rec.fromEntries(
+    node.props.flatMap((prop) =>
+      prop._tag === 'Event'
+        ? [[prop.name, (payload: unknown) => config.invoke(prop.handle, payload)] as const]
+        : [],
+    ),
+  )
+  const props: Record<string, unknown> = Option.match(registered.propsSchema, {
+    onNone: () => encoded,
+    onSome: (schema) => Schema.decodeUnknownSync(schema)(encoded),
+  })
 
   // 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
@@ -238,10 +247,12 @@ const WireNodeView = ({
   // 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 slotFor = (slotName: string): ((slotProps?: SlotPropsExternalApi) => ReactNode) => {
     const cached = slotCache.current[slotName]
-    if (cached !== undefined) return cached
-    const stable = (slotProps?: { readonly slotKey?: string }): ReactNode => {
+    if (cached !== undefined) {
+      return cached
+    }
+    const stable = (slotProps?: SlotPropsExternalApi): ReactNode => {
       const { node: currentNode, tree: currentTree, config: currentConfig } = latest.current
       const requestedKey = slotProps?.slotKey
       return createElement(
@@ -268,7 +279,7 @@ const WireNodeView = ({
   // 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(
+  const slots: Record<string, (slotProps?: SlotPropsExternalApi) => ReactNode> = new Proxy(
     Object.create(null),
     { get: (_target, key) => (typeof key === 'string' ? slotFor(key) : undefined) },
   )

package/src/fixtures.ts

@@ -52,7 +52,8 @@ export class CounterUi extends CounterUiBase {}
 class Counter extends Composition.make('Counter', { title: 'Counter', ui: CounterUi, states: [Count] }) {}
 
 /** A boot event the counter scene dispatches before its first render. */
-export const bumpedBy = (by: number): EventOf<'Bumped', { by: number }> => Event.construct(Bumped, { by })
+export const bumpedBy = (amount: number): EventOf<'Bumped', { by: number }> =>
+  Event.construct(Bumped, { by: amount })
 
 export const counterScene = (boot?: ReadonlyArray<EventOf<'Bumped', { by: number }>>): Scene => {
   const presentation = Layer.mergeAll(
@@ -65,7 +66,7 @@ export const counterScene = (boot?: ReadonlyArray<EventOf<'Bumped', { by: number
       const bump = yield* Event.trigger(Bumped)
       return mount({ props: { count }, slots: {}, events: { bump } })
     }),
-    Reducer.live(Bump, (n, event) => n + event.by),
+    Reducer.live(Bump, (count, event) => count + event.by),
   ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
   return scene(Counter, boot === undefined ? { provide: [app] } : { provide: [app], boot })
 }
@@ -85,7 +86,7 @@ export const structureCounterScene = (): Scene => {
       const bump = yield* Event.trigger(Bumped)
       return mount({ props: { count }, slots: {}, events: { bump } })
     }),
-    Reducer.live(Bump, (n, event) => n + event.by),
+    Reducer.live(Bump, (count, event) => count + event.by),
   ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
   return scene(Counter, { provide: [app] })
 }
@@ -210,14 +211,14 @@ export const listScene = (
   )
   const app = Layer.mergeAll(
     Composition.live(ListComp, function* () {
-      const items = yield* Items
+      const listItems = yield* Items
       return mount({
-        props: { items },
+        props: { items: listItems },
         slots: {
           Bar: one({}),
-          Item: each(items, {
-            key: (item) => item.id,
-            props: (item) => ({ id: item.id, label: item.label }),
+          Item: each(listItems, {
+            key: (entry) => entry.id,
+            props: (entry) => ({ id: entry.id, label: entry.label }),
           }),
         },
       })
@@ -227,15 +228,15 @@ export const listScene = (
       return mount({ props: {}, slots: {}, events: { add } })
     }),
     Composition.live(ItemComp, function* () {
-      const item = (yield* Props) as { id: string; label: string }
+      const itemProps = S.decodeUnknownSync(ListItem)(yield* Props)
       const removeTrigger = yield* Event.trigger(Removed)
       // 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 mount({ props: { label: item.label }, slots: {}, events: { remove } })
+      const remove = (): void => removeTrigger({ id: itemProps.id })
+      return mount({ props: { label: itemProps.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)),
+    Reducer.live(AddItem, (current, event) => [...current, { id: event.id, label: event.label }]),
+    Reducer.live(RemoveItem, (current, event) => current.filter((entry) => entry.id !== event.id)),
   ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
   return scene(ListComp, { provide: [app] })
 }
@@ -260,7 +261,7 @@ export const asyncCounterScene = (delay: Duration.DurationInput = '40 millis'):
       const bump = yield* Event.trigger(Bumped)
       return mount({ props: { count }, slots: {}, events: { bump } })
     }),
-    Reducer.live(Bump, (n, event) => n + event.by),
+    Reducer.live(Bump, (count, event) => count + event.by),
     // The procedure runs on the bus AFTER the scene boots: it sleeps past the opening
     // snapshot, then dispatches `Bumped` — so the only way the client learns the new count
     // is the server pushing a diff nobody asked for.

package/src/index.ts

@@ -35,8 +35,12 @@ export {
   type RemoteTransport,
   serve,
   type ServeOptions,
+  serveShared,
+  type ServeSharedOptions,
   type ServerBinding,
   type ServerMessage,
+  type SharedClientHandle,
+  type SharedServerBinding,
   type SnapshotMessage,
 } from './transport'
 export { inMemoryTransportPair, type TransportPair } from './memory'

package/src/server.ts

@@ -1,4 +1,16 @@
-import { Effect, Layer, Match, ManagedRuntime, type ParseResult, PubSub, Queue, Schema } from 'effect'
+import {
+  Array as Arr,
+  Effect,
+  Layer,
+  Match,
+  ManagedRuntime,
+  Option,
+  type ParseResult,
+  PubSub,
+  Queue,
+  Record as Rec,
+  Schema,
+} from 'effect'
 import {
   Bus,
   Composition,
@@ -55,10 +67,14 @@ const settleDrain = Effect.yieldNow().pipe(Effect.repeatN(SETTLE_DRAIN))
 // 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 ?? {}))
+  Option.match(Option.fromNullable(structure.events), {
+    onNone: () => ({}),
+    onSome: (events) => events,
+  })
 
 const closedSceneLayer = (scene: Scene): Layer.Layer<RuntimeServices, never, never> =>
-  scene.provide.reduce((a, b) => Layer.merge(a, b)) as unknown as Layer.Layer<
+  // 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
@@ -69,11 +85,11 @@ interface Mounted {
   readonly comp: CompositionClass<unknown>
   readonly props: unknown
   readonly id: string
-  readonly parentId: string | null
-  readonly slot: string | null
+  readonly parentId: Option.Option<string>
+  readonly slot: Option.Option<string>
   readonly childIndex: number
-  /** The React `key` the parent gave this slot child, or `null` — the keyed-slot selector. */
-  readonly key: string | null
+  /** The React `key` the parent gave this slot child, if any — the keyed-slot selector. */
+  readonly key: Option.Option<string>
 }
 
 const childComposition = (child: SlotChild): CompositionClass<unknown> =>
@@ -92,131 +108,151 @@ const noRegister: TriggerRegistryApi['register'] = () => Effect.void
 // 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,
+const toWireNodeFromStructure = Effect.fn('toWireNodeFromStructure')(function* (
+  mounted: 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
+): Effect.fn.Return<WireNode, ParseResult.ParseError> {
+  const manifest: UiManifest = mounted.comp.manifest.ui.manifest
+  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 })
-      }
-    }
+  // `manifest.props` is `Schema.Schema<any, any>`, so the encoded shape is `any` — a record
+  // of wire-encoded prop values keyed by name (no view eval). Absent on the type-only form.
+  const encodedProps = yield* Option.match(Option.fromNullable(manifest.props), {
+    onNone: () => Effect.succeed({}),
+    onSome: (schema) => Schema.encodeUnknown(schema)(structure.props),
+  })
+  const dataProps: ReadonlyArray<WireProp> = Rec.toEntries(encodedProps).map(
+    ([propName, propValue]): WireProp => ({ _tag: 'Data', name: propName, value: propValue }),
+  )
 
-    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 })
-    }
+  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.value)
+      return Option.some<WireProp>({ _tag: 'Event', name: eventName, handle })
+    }),
+  ).pipe(Effect.map(Arr.getSomes))
 
-    return {
-      id: m.id,
-      name,
-      parentId: m.parentId,
-      childIndex: m.childIndex,
-      slot: m.slot,
-      key: m.key,
-      props: [...dataProps, ...eventProps],
-    }
-  })
+  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],
+  }
+})
 
 // 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')
+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')
 
 // 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] : [],
+  Rec.fromEntries(
+    Rec.toEntries(structure.slots).flatMap(([slotName, fillValue]) =>
+      isSlotFill(fillValue) ? [[slotName, fillValue] 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.
+/** A composition's declared slot map, defaulting to an empty record when it declares none. */
+const slotsOf = (comp: CompositionClass<unknown>): Record<string, SlotClass> =>
+  Option.getOrElse(Option.fromNullable(comp.manifest.slots), () => ({}))
+
 const enqueueStructureSlot = (
   parent: Mounted,
   slotName: string,
   child: CompositionClass<unknown>,
   fill: SlotFill<unknown>,
-  next: Mounted[],
-): void =>
+): ReadonlyArray<Mounted> =>
   Match.value(fill).pipe(
-    Match.tag('Each', (each) => {
-      each.items.forEach((item, index) => {
-        next.push({
+    Match.tag('Each', (each) =>
+      each.items.map(
+        (entry, index): Mounted => ({
           comp: child,
-          props: item.props,
+          props: entry.props,
           id: `${parent.id}.${slotName}.${index}`,
-          parentId: parent.id,
-          slot: slotName,
+          parentId: Option.some(parent.id),
+          slot: Option.some(slotName),
           childIndex: index,
-          key: item.key,
-        })
-      })
-    }),
-    Match.tag('One', (single) => {
-      next.push({
+          key: Option.fromNullable(entry.key),
+        }),
+      ),
+    ),
+    Match.tag('One', (single) => [
+      {
         comp: child,
         props: single.props,
         id: `${parent.id}.${slotName}.0`,
-        parentId: parent.id,
-        slot: slotName,
+        parentId: Option.some(parent.id),
+        slot: Option.some(slotName),
         childIndex: 0,
-        key: null,
-      })
-    }),
-    Match.tag('Absent', () => {}),
+        key: Option.none(),
+      } satisfies Mounted,
+    ]),
+    Match.tag('Absent', () => []),
     Match.exhaustive,
   )
 
-const collect = (
+const collect = Effect.fn('collect')(function* (
   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.fn.Return<Map<SlotClass, CompositionClass<unknown>>, never, SlotChild> {
+  const bindings = new Map<SlotClass, CompositionClass<unknown>>()
+  // `walk` recurses, so it carries an explicit type so its body can reference itself cast-free.
+  const walk: (comp: CompositionClass<unknown>) => Effect.Effect<void, never, SlotChild> = Effect.fn(
+    'walk',
+  )(function* (comp: CompositionClass<unknown>): Effect.fn.Return<void, never, SlotChild> {
+    yield* Effect.forEach(Rec.values(slotsOf(comp)), (slotClass) =>
       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)
+        if (bindings.has(slotClass)) {
+          return
         }
-      })
-    yield* walk(root)
-    return bindings
+        const child = childComposition(yield* slotClass.tag)
+        bindings.set(slotClass, child)
+        yield* walk(child)
+      }),
+    )
   })
+  yield* walk(root)
+  return bindings
+})
 
-const renderLevel = (
+// `renderLevel` recurses level by level, so it carries an explicit type so its body can
+// reference itself cast-free.
+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) {
+) => Effect.Effect<ReadonlyArray<WireNode>, ParseResult.ParseError, CompositionService> = Effect.fn(
+  'renderLevel',
+)(function* (
+  frontier: ReadonlyArray<Mounted>,
+  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
+  register: TriggerRegistryApi['register'],
+): Effect.fn.Return<ReadonlyArray<WireNode>, ParseResult.ParseError, CompositionService> {
+  if (frontier.length === 0) {
+    return []
+  }
+  const rendered = yield* Effect.forEach(frontier, (mounted) =>
+    Effect.gen(function* () {
       const service = yield* mounted.comp.tag
       const env: RenderEnv = { props: mounted.props, tracker: { add: () => {} } }
       const frame = yield* Composition.render(service, env)
@@ -228,19 +264,27 @@ const renderLevel = (
           `reform-remote server: composition ${mounted.comp.manifest.name} did not return a Structure`,
         )
       }
-      nodes.push(yield* toWireNodeFromStructure(mounted, frame, register))
+      const node = yield* toWireNodeFromStructure(mounted, frame, register)
       const fills = structureFills(frame)
-      for (const [slotName, slotClass] of Object.entries(mounted.comp.manifest.slots ?? {})) {
+      const children = Rec.toEntries(slotsOf(mounted.comp)).flatMap(([slotName, slotClass]) => {
         const child = bindings.get(slotClass)
-        if (child === undefined) continue
+        if (child === undefined) {
+          return []
+        }
         const fill = fills[slotName]
-        if (fill === undefined) continue
-        enqueueStructureSlot(mounted, slotName, child, fill, next)
-      }
-    }
-    const rest = yield* renderLevel(next, bindings, register)
-    return [...nodes, ...rest]
-  })
+        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)
+  return [...nodes, ...rest]
+})
 
 /**
  * Render the scene's CURRENT frame to a serializable `WireTree`, breadth-first from
@@ -251,9 +295,15 @@ const renderLevel = (
  * registry, while `makeRemoteServer` passes its connection registry so the streamed
  * client can invoke handles.
  */
+/** Options for {@link renderSceneToWire}; the registrar defaults to a no-op for one-shot renders. */
+export interface RenderSceneToWireOptions {
+  readonly register: TriggerRegistryApi['register']
+}
+
+// oxlint-disable-next-line reform-rules/prefer-effect-fn -- exported binding: Effect.fn's inferred type isn't portable under isolatedDeclarations
 export const renderSceneToWire = (
   scene: Scene,
-  options?: { readonly register?: TriggerRegistryApi['register'] },
+  options?: RenderSceneToWireOptions,
 ): Effect.Effect<WireTree, ParseResult.ParseError, CompositionService | SlotChild> =>
   Effect.gen(function* () {
     const register = options?.register ?? noRegister
@@ -262,10 +312,10 @@ export const renderSceneToWire = (
       comp: scene.composition,
       props: {},
       id: '0',
-      parentId: null,
-      slot: null,
+      parentId: Option.none(),
+      slot: Option.none(),
       childIndex: 0,
-      key: null,
+      key: Option.none(),
     }
     return yield* renderLevel([root], bindings, register)
   })
@@ -290,6 +340,12 @@ export interface RemoteServer {
    * no user interaction triggered. Returns an unsubscribe handle.
    */
   readonly subscribe: (listener: () => void) => () => void
+  /**
+   * The last emitted frame — the baseline every `renderDiff` diffs against. A new
+   * client attaching to a SHARED server snapshots off this (rather than a fresh
+   * `render()`, which would re-key the baseline and desync clients mid-stream).
+   */
+  readonly currentTree: () => WireTree
   /** Tear down the runtime and its forked fibers. */
   readonly dispose: () => Promise<void>
 }
@@ -312,7 +368,7 @@ export const makeRemoteServer = (scene: Scene): RemoteServer => {
   // binding's opening snapshot captures all state up to `start`).
   const changeListeners = new Set<() => void>()
   const notifyChange = (): void => {
-    for (const listener of changeListeners) listener()
+    changeListeners.forEach((listener) => listener())
   }
   runtime.runFork(
     Effect.scoped(
@@ -330,31 +386,43 @@ export const makeRemoteServer = (scene: Scene): RemoteServer => {
     ),
   )
 
-  runtime.runSync(Effect.forEach(scene.boot ?? [], (event) => publish('High', event)))
+  runtime.runSync(
+    Effect.forEach(
+      Option.getOrElse(Option.fromNullable(scene.boot), () => []),
+      (event) => publish('High', event),
+    ),
+  )
 
   // The last emitted frame, to diff against. A const holder whose field we swap
   // (no reassigned binding — house rule), not a `let`.
   const frame: { tree: WireTree } = { tree: [] }
 
   const render = (): Promise<WireTree> =>
-    runtime.runPromise(renderEffect).then((tree) => {
-      frame.tree = tree
-      return tree
-    })
+    runtime.runPromise(
+      renderEffect.pipe(
+        Effect.tap((tree) =>
+          Effect.sync(() => {
+            frame.tree = tree
+          }),
+        ),
+      ),
+    )
 
   const renderDiff = (): Promise<ReadonlyArray<WirePatch>> =>
-    runtime.runPromise(renderEffect).then((next) => {
-      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)
-      return runtime
-        .runPromise(Effect.forEach(staleHandles, (handle) => registry.revoke(handle)))
-        .then(() => patches)
-    })
+    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,
@@ -370,6 +438,7 @@ export const makeRemoteServer = (scene: Scene): RemoteServer => {
       changeListeners.add(listener)
       return () => void changeListeners.delete(listener)
     },
+    currentTree: () => frame.tree,
     dispose: () => runtime.dispose(),
   }
 }

package/src/transport.test.ts

@@ -4,7 +4,7 @@ import { expect, test, vi } from 'vitest'
 import { Schema as S } from 'effect'
 import { Ui, ui } from '@playfast/reform'
 import type { InvokeMessage, ServerMessage } from './transport'
-import { connect, serve } from './transport'
+import { connect, serve, serveShared } from './transport'
 import { inMemoryTransportPair } from './memory'
 import { remoteViews } from './client'
 import { asyncCounterScene, CounterUi, counterScene } from './fixtures'
@@ -181,6 +181,107 @@ test('two clients each get their own server runtime — state is isolated', asyn
   }
 })
 
+test('serveShared: two clients share ONE runtime — one client drives state for both', async () => {
+  const one = inMemoryTransportPair<ServerMessage, InvokeMessage>()
+  const two = inMemoryTransportPair<ServerMessage, InvokeMessage>()
+
+  const probeOne: Probe = {}
+  const probeTwo: Probe = {}
+  const clientOne = connect({
+    transport: one.client,
+    views: remoteViews<{ Counter: typeof CounterUi }>({ Counter: probeView(probeOne) }),
+  })
+  const clientTwo = connect({
+    transport: two.client,
+    views: remoteViews<{ Counter: typeof CounterUi }>({ Counter: probeView(probeTwo) }),
+  })
+
+  // One shared server; both transports attach to the same runtime.
+  const shared = serveShared({ scene: counterScene() })
+  const handleOne = shared.addClient(one.server)
+  const handleTwo = shared.addClient(two.server)
+  try {
+    // Both clients receive the opening snapshot off the shared baseline.
+    await vi.waitFor(() => {
+      draw(clientOne.node())
+      draw(clientTwo.node())
+      expect(probeOne.props).toEqual({ count: 0 })
+      expect(probeTwo.props).toEqual({ count: 0 })
+    })
+
+    // A bump from client ONE is broadcast to BOTH — they share the same state.
+    probeOne.events?.['bump']?.({ by: 5 })
+    await vi.waitFor(() => {
+      draw(clientOne.node())
+      draw(clientTwo.node())
+      expect(probeOne.props).toEqual({ count: 5 })
+      expect(probeTwo.props).toEqual({ count: 5 })
+    })
+
+    // And a bump from client TWO lands on the same shared counter.
+    probeTwo.events?.['bump']?.({ by: 3 })
+    await vi.waitFor(() => {
+      draw(clientOne.node())
+      draw(clientTwo.node())
+      expect(probeOne.props).toEqual({ count: 8 })
+      expect(probeTwo.props).toEqual({ count: 8 })
+    })
+  } finally {
+    handleOne.remove()
+    handleTwo.remove()
+    clientOne.dispose()
+    clientTwo.dispose()
+    await shared.dispose()
+  }
+})
+
+test('serveShared: a client connecting mid-stream snapshots the current shared state', async () => {
+  const one = inMemoryTransportPair<ServerMessage, InvokeMessage>()
+
+  const probeOne: Probe = {}
+  const clientOne = connect({
+    transport: one.client,
+    views: remoteViews<{ Counter: typeof CounterUi }>({ Counter: probeView(probeOne) }),
+  })
+
+  const shared = serveShared({ scene: counterScene() })
+  const handleOne = shared.addClient(one.server)
+  try {
+    await vi.waitFor(() => {
+      draw(clientOne.node())
+      expect(probeOne.props).toEqual({ count: 0 })
+    })
+
+    probeOne.events?.['bump']?.({ by: 4 })
+    await vi.waitFor(() => {
+      draw(clientOne.node())
+      expect(probeOne.props).toEqual({ count: 4 })
+    })
+
+    // A late joiner must see the CURRENT shared count (4), not a fresh 0.
+    const two = inMemoryTransportPair<ServerMessage, InvokeMessage>()
+    const probeTwo: Probe = {}
+    const clientTwo = connect({
+      transport: two.client,
+      views: remoteViews<{ Counter: typeof CounterUi }>({ Counter: probeView(probeTwo) }),
+    })
+    const handleTwo = shared.addClient(two.server)
+    try {
+      await vi.waitFor(() => {
+        draw(clientTwo.node())
+        expect(probeTwo.props).toEqual({ count: 4 })
+      })
+    } finally {
+      handleTwo.remove()
+      clientTwo.dispose()
+    }
+  } finally {
+    handleOne.remove()
+    clientOne.dispose()
+    await shared.dispose()
+  }
+})
+
 test('dispose detaches both ends: a post-dispose invoke no longer reaches the server', async () => {
   const { server: serverTransport, client: clientTransport } = inMemoryTransportPair<
     ServerMessage,

package/src/transport.ts

@@ -1,9 +1,9 @@
-import { Match } from 'effect'
+import { Effect, Fiber, Match, Option } from 'effect'
 import type { ReactNode } from 'react'
 import { Wire, type WirePatch, type WireTree } from '@playfast/reform'
 import type { Scene } from '@playfast/reform'
 import { makeRemoteServer } from './server'
-import { renderWireTree, type RemoteContract, type RemoteViewSet } from './client'
+import { renderWireTree, type ClientConfig, type RemoteContract, type RemoteViewSet } from './client'
 
 /**
  * Binds the server driver and the client renderer to a transport. The wire
@@ -85,24 +85,36 @@ export const serve = (options: ServeOptions): ServerBinding => {
   // a late state change is never dropped. Both a client invoke and a server-side change
   // (the bus subscriber) funnel through here, so there is exactly one push path.
   const started = { value: false }
-  const flight = { promise: null as Promise<void> | null, dirty: false }
+  const flight = { promise: Option.none<Promise<void>>(), dirty: false }
   const push = (): Promise<void> => {
-    if (!started.value) return Promise.resolve()
-    if (flight.promise !== null) {
+    if (!started.value) {
+      return Effect.runPromise(Effect.void)
+    }
+    if (Option.isSome(flight.promise)) {
       flight.dirty = true
-      return flight.promise
+      return flight.promise.value
     }
-    const run = (async (): Promise<void> => {
-      const patches = await server.renderDiff()
-      if (patches.length > 0) transport.send({ _tag: 'Patches', patches })
-    })().finally(() => {
-      flight.promise = null
-      if (flight.dirty) {
-        flight.dirty = false
-        void push()
-      }
-    })
-    flight.promise = run
+    // `Effect.ensuring` runs the settle/re-render cleanup whether the render succeeds or fails
+    // (the old `.finally`), so the single-flight slot is never left stuck.
+    const run = Effect.runPromise(
+      Effect.gen(function* () {
+        const patches = yield* Effect.promise(() => server.renderDiff())
+        if (patches.length > 0) {
+          transport.send({ _tag: 'Patches', patches })
+        }
+      }).pipe(
+        Effect.ensuring(
+          Effect.sync(() => {
+            flight.promise = Option.none()
+            if (flight.dirty) {
+              flight.dirty = false
+              void push()
+            }
+          }),
+        ),
+      ),
+    )
+    flight.promise = Option.some(run)
     return run
   }
   // Server-initiated changes are flushed on a short DEBOUNCE rather than synchronously: it
@@ -111,13 +123,22 @@ export const serve = (options: ServeOptions): ServerBinding => {
   // the settled result, and the background flush never races the synchronous invoke push
   // above. A client invoke still pushes immediately (its own settle path), so user actions
   // stay snappy; this path only carries updates no interaction triggered.
-  const debounce = { handle: null as ReturnType<typeof setTimeout> | null }
+  const debounce = { fiber: Option.none<Fiber.RuntimeFiber<void>>() }
   const scheduleFlush = (): void => {
-    if (!started.value || debounce.handle !== null) return
-    debounce.handle = setTimeout(() => {
-      debounce.handle = null
-      void push()
-    }, BACKGROUND_FLUSH_MS)
+    if (!started.value || Option.isSome(debounce.fiber)) {
+      return
+    }
+    const fiber = Effect.runFork(
+      Effect.sleep(BACKGROUND_FLUSH_MS).pipe(
+        Effect.zipRight(
+          Effect.sync(() => {
+            debounce.fiber = Option.none()
+            void push()
+          }),
+        ),
+      ),
+    )
+    debounce.fiber = Option.some(fiber)
   }
   const start = async (): Promise<void> => {
     const tree = await server.render()
@@ -127,7 +148,11 @@ export const serve = (options: ServeOptions): ServerBinding => {
     scheduleFlush()
   }
   const off = transport.onMessage((message) => {
-    void server.invoke(message.handle, message.payload).then(push)
+    void Effect.runPromise(
+      Effect.promise(() => server.invoke(message.handle, message.payload)).pipe(
+        Effect.zipRight(Effect.promise(push)),
+      ),
+    )
   })
   const offChange = server.subscribe(scheduleFlush)
   return {
@@ -135,7 +160,159 @@ export const serve = (options: ServeOptions): ServerBinding => {
     dispose: async (): Promise<void> => {
       off()
       offChange()
-      if (debounce.handle !== null) clearTimeout(debounce.handle)
+      if (Option.isSome(debounce.fiber)) {
+        Effect.runFork(Fiber.interrupt(debounce.fiber.value))
+      }
+      await server.dispose()
+    },
+  }
+}
+
+/** A client's membership in a {@link SharedServerBinding}; `remove` detaches it. */
+export interface SharedClientHandle {
+  /** Stop sending this client frames and drop its invoke listener. Call on disconnect. */
+  readonly remove: () => void
+}
+
+export interface SharedServerBinding {
+  /**
+   * Attach a freshly-connected transport to the ONE shared runtime: send it a
+   * Snapshot of the current shared tree, then fold it into the broadcast set so
+   * every later frame — and every other client's invoke result — reaches it too.
+   * Returns a handle to detach the client when its socket closes.
+   */
+  readonly addClient: (transport: RemoteTransport<ServerMessage, InvokeMessage>) => SharedClientHandle
+  /** Tear down the shared runtime and drop every client. */
+  readonly dispose: () => Promise<void>
+}
+
+/** Options for {@link serveShared} — one scene, run once, shared by every client. */
+export interface ServeSharedOptions {
+  readonly scene: Scene
+}
+
+/**
+ * The single-instance counterpart to {@link serve}: ONE `makeRemoteServer(scene)` —
+ * one runtime, one trigger registry, one frame baseline — shared by every connected
+ * client. A client's invoke fires on the shared runtime and the resulting diff is
+ * broadcast to ALL clients, so every connection sees and drives the same state.
+ *
+ * Sync is structural: all clients hold the same baseline, so one render's diff applies
+ * to all. A client connecting mid-stream snapshots off the live `currentTree()` (after
+ * the opening render settles) and joins the broadcast set in the same tick — it never
+ * misses or double-applies a frame.
+ */
+export const serveShared = (options: ServeSharedOptions): SharedServerBinding => {
+  const { scene } = options
+  const server = makeRemoteServer(scene)
+  const clients = new Set<RemoteTransport<ServerMessage, InvokeMessage>>()
+  const broadcast = (message: ServerMessage): void => {
+    clients.forEach((client) => client.send(message))
+  }
+
+  // The shared push loop: same coalescing single-flight as `serve`, but one render's
+  // patches fan out to EVERY client. `started` gates pushes until the opening render has
+  // set the baseline; `dirty` re-runs a render that a late change raced into mid-flight.
+  const started = { value: false }
+  const flight = { promise: Option.none<Promise<void>>(), dirty: false }
+  const push = (): Promise<void> => {
+    if (!started.value) {
+      return Effect.runPromise(Effect.void)
+    }
+    if (Option.isSome(flight.promise)) {
+      flight.dirty = true
+      return flight.promise.value
+    }
+    const run = Effect.runPromise(
+      Effect.gen(function* () {
+        const patches = yield* Effect.promise(() => server.renderDiff())
+        if (patches.length > 0) {
+          broadcast({ _tag: 'Patches', patches })
+        }
+      }).pipe(
+        Effect.ensuring(
+          Effect.sync(() => {
+            flight.promise = Option.none()
+            if (flight.dirty) {
+              flight.dirty = false
+              void push()
+            }
+          }),
+        ),
+      ),
+    )
+    flight.promise = Option.some(run)
+    return run
+  }
+
+  const debounce = { fiber: Option.none<Fiber.RuntimeFiber<void>>() }
+  const scheduleFlush = (): void => {
+    if (!started.value || Option.isSome(debounce.fiber)) {
+      return
+    }
+    const fiber = Effect.runFork(
+      Effect.sleep(BACKGROUND_FLUSH_MS).pipe(
+        Effect.zipRight(
+          Effect.sync(() => {
+            debounce.fiber = Option.none()
+            void push()
+          }),
+        ),
+      ),
+    )
+    debounce.fiber = Option.some(fiber)
+  }
+
+  // Render once up front so the shared baseline exists before any client snapshots off
+  // it. Clients `await ready`, so they never capture the empty pre-render tree. Anything
+  // that changed during the (async) opening render is flushed by the trailing scheduleFlush.
+  const ready = (async (): Promise<void> => {
+    await server.render()
+    started.value = true
+    scheduleFlush()
+  })()
+
+  const offChange = server.subscribe(scheduleFlush)
+
+  const addClient = (
+    transport: RemoteTransport<ServerMessage, InvokeMessage>,
+  ): SharedClientHandle => {
+    const off = transport.onMessage((message) => {
+      void Effect.runPromise(
+        Effect.promise(() => server.invoke(message.handle, message.payload)).pipe(
+          Effect.zipRight(Effect.promise(push)),
+        ),
+      )
+    })
+    // Once the baseline exists, send this client its opening Snapshot and join the
+    // broadcast set in the SAME tick — no async push can interleave between the two, so
+    // the client's first frame and every subsequent diff stay in lockstep.
+    void Effect.runPromise(
+      Effect.promise(() => ready).pipe(
+        Effect.zipRight(
+          Effect.sync(() => {
+            transport.send({ _tag: 'Snapshot', tree: server.currentTree() })
+            clients.add(transport)
+          }),
+        ),
+      ),
+    )
+    return {
+      remove: (): void => {
+        off()
+        clients.delete(transport)
+      },
+    }
+  }
+
+  return {
+    addClient,
+    dispose: async (): Promise<void> => {
+      offChange()
+      if (Option.isSome(debounce.fiber)) {
+        Effect.runFork(Fiber.interrupt(debounce.fiber.value))
+      }
+      clients.clear()
       await server.dispose()
     },
   }
@@ -165,10 +342,9 @@ export const connect = <C extends RemoteContract>(options: ConnectOptions<C>): C
   const { transport, views } = options
   const state: { tree: WireTree } = { tree: [] }
   const listeners = new Set<() => void>()
-  const config = {
+  const config: ClientConfig<C> = {
     views,
-    invoke: (handle: string, payload: unknown): void =>
-      transport.send({ _tag: 'Invoke', handle, payload }),
+    invoke: (handle, payload) => transport.send({ _tag: 'Invoke', handle, payload }),
   }
   const off = transport.onMessage((message) => {
     // A snapshot replaces the tree wholesale (a fresh or reconnected session);
@@ -178,7 +354,7 @@ export const connect = <C extends RemoteContract>(options: ConnectOptions<C>): C
       Match.tag('Patches', ({ patches }) => Wire.apply(state.tree, patches)),
       Match.exhaustive,
     )
-    for (const listener of listeners) listener()
+    listeners.forEach((listener) => listener())
   })
   return {
     node: () => renderWireTree(state.tree, config),