@playfast/reform-remote 0.1.0 → 1.0.2

package/package.json

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

@@ -7,20 +7,6 @@ import { Composition, slot, Ui, ui } from '@playfast/reform'
 import type { WireNode } from '@playfast/reform'
 import { remoteViews, renderWireTree, type RemoteViews } from './client'
 
-/**
- * Regression for the KEYED-SLOT bug ("the sidebar showed every branch row under every repo
- * section"). The client slot thunk renders ALL of a slot's wire children on EACH invocation and
- * ignores call-site props — correct for a singleton slot rendered once, but wrong for a LIST
- * slot a view invokes once PER ITEM (each section did `<slots.Row .../>` per branch), so every
- * call rendered the whole list: N sections × M rows.
- *
- * The fix: a view passes `<slots.Row slotKey={id} />` and the thunk renders only the ONE wire
- * child whose `key` matches (the per-item identity captured server-side from the React `key`).
- * Omitting `slotKey` keeps the render-all-children behaviour (the singleton case). These tests
- * pin both halves directly at the framework boundary, with NO app wiring.
- */
-
-// A list item carrying a `label` so each rendered child is identifiable in the DOM.
 class ItemUi extends ui('Item', { props: S.Struct({ label: S.String }) }) {}
 class ItemComp extends Composition.make('Item', { title: 'Item', ui: ItemUi }) {}
 class ItemSlot extends slot('Item')<typeof ItemComp>() {}
@@ -39,8 +25,6 @@ const ItemView = Ui.make(ItemUi, ({ label }) =>
   createElement('span', { 'data-item': label }, label),
 )
 
-// Three keyed children (a/b/c) under one `Item` slot — the wire shape the server emits for a
-// list. `mode` switches the parent view between keyed selection and the legacy render-all.
 const tree: ReadonlyArray<WireNode> = [
   node({ id: '0', name: 'List', props: [{ _tag: 'Data', name: 'mode', value: 'keyed' }] }),
   node({
@@ -89,8 +73,6 @@ const renderWith = async (
 }
 
 test('a keyed slot renders ONE matching child per call site, not the whole list', async () => {
-  // Two "sections", each invoking the SAME `Item` slot once with a different `slotKey` — the
-  // exact shape that duplicated rows. Each must render only its own child.
   const ListView = Ui.make(ListUi, (_props, slots) =>
     createElement(
       'div',
@@ -101,20 +83,16 @@ test('a keyed slot renders ONE matching child per call site, not the whole list'
   )
   const container = await renderWith(ListView, tree)
 
-  // Exactly two items rendered total — NOT 2 sections × 3 children = 6 (the bug).
   expect(container.querySelectorAll('[data-item]').length).toBe(2)
-  // Each section shows ONLY its keyed child.
   const one = container.querySelector('[data-section="one"]')
   const two = container.querySelector('[data-section="two"]')
   expect(one?.querySelectorAll('[data-item]').length).toBe(1)
   expect(one?.querySelector('[data-item]')?.getAttribute('data-item')).toBe('a')
   expect(two?.querySelector('[data-item]')?.getAttribute('data-item')).toBe('b')
-  // The unreferenced child 'c' is rendered nowhere.
   expect(container.querySelector('[data-item="c"]')).toBeNull()
 })
 
 test('an un-keyed slot still renders ALL its children (singleton/back-compat path)', async () => {
-  // No `slotKey` → render every child of the slot, unchanged from before the keyed API.
   const ListView = Ui.make(ListUi, (_props, slots) =>
     createElement('div', null, createElement(slots.Item)),
   )

package/src/client-remount.test.ts

@@ -11,27 +11,9 @@ import { connect } from './transport'
 import { inMemoryTransportPair } from './memory'
 import { remoteViews } from './client'
 
-/**
- * Regression for the slot-remount bug: a background patch that re-renders ONLY a parent node
- * must NOT unmount + remount the parent's slot children. Before the fix, `renderWireTree`
- * rebuilt each slot's component closure every render, so a parent rendering a child as
- * `<slots.Child/>` handed React a NEW component type each frame — React then tore down the
- * whole child subtree and rebuilt it, wiping every descendant view's local `useState` (in the
- * app: the onboarding modal's open/step state snapped back, closing the modal on any unrelated
- * background patch once server-initiated streaming started delivering them).
- *
- * This test renders the client into a REAL React root (static markup can't observe fiber
- * preservation), captures the child view's mount-time `useState` id, sends a patch touching
- * only the parent, and asserts the child id is unchanged — i.e. the child fiber survived.
- */
-
-// A child whose CLIENT view owns local state. Each fresh mount picks the next mount id, so a
-// remount is observable as a changed id.
 class ChildUi extends ui('Child', { props: S.Struct({}) }) {}
 class ChildComp extends Composition.make('Child', { title: 'Child', ui: ChildUi }) {}
 class MainSlot extends slot('Main')<typeof ChildComp>() {}
-// A parent carrying a `count` prop (the thing a background patch bumps) and one slot child it
-// renders as `<slots.Main/>` — the component form that triggered the remount.
 class HostUi extends ui('Host')<{ props: { count: number }; slots: { Main: MainSlot } }>() {}
 
 const node = (over: Partial<WireNode> & Pick<WireNode, 'id' | 'name'>): WireNode => ({
@@ -82,7 +64,6 @@ test('a background patch on the PARENT keeps its slot child mounted (local useSt
       root.render(createElement(Root))
     })
 
-    // First frame: a host (count 0) holding one slot child.
     await act(async () => {
       serverTransport.send({
         _tag: 'Snapshot',
@@ -97,8 +78,6 @@ test('a background patch on the PARENT keeps its slot child mounted (local useSt
     const childIdBefore = container.querySelector('[data-child-id]')?.getAttribute('data-child-id')
     expect(childIdBefore).toBe('mount-1')
 
-    // A background patch that touches ONLY the host (count 0 → 7). The child node is unchanged
-    // and not in the patch at all.
     await act(async () => {
       serverTransport.send({
         _tag: 'Patches',
@@ -111,9 +90,7 @@ test('a background patch on the PARENT keeps its slot child mounted (local useSt
       })
     })
 
-    // The parent re-rendered with the new count…
     expect(container.querySelector('[data-count]')?.getAttribute('data-count')).toBe('7')
-    // …but the child was NOT remounted: same fiber, same mount id, and no second mount ran.
     expect(container.querySelector('[data-child-id]')?.getAttribute('data-child-id')).toBe(
       childIdBefore,
     )

package/src/client.ts

@@ -10,152 +10,49 @@ import {
   type WireTree,
 } from '@playfast/reform'
 
-// A `Ui.make` view of any contract. The `any` is the same variance escape the core
-// uses for `Schema<any, any>`: a heterogeneous list of contract-typed views cannot
-// share one element type (function params are contravariant in the contract), and the
-// real contract is recovered at runtime from the view's carried brand.
-type AnyMadeView = MadeView<any>
+type AnyValue = Schema.Schema.Type<Schema.Schema.Any>
 
-/**
- * The client side of the remote transport: fold the server's patches with
- * `Wire.apply`, then render the resulting `WireTree` with locally registered
- * presentations. The presentations are the SAME `Ui.make` views the local
- * `@playfast/react` renderer uses — one presentation, many consumers (REMOTE_UI.md):
- *
- *  - Each wire node's view runs as a stable React COMPONENT, so a view body's own
- *    hooks (`useState`, effects) work exactly as under `@playfast/react`.
- *  - Slots are COMPONENTS that render that slot's wire children, so a view's
- *    `<slots.Foo/>` / `createElement(slots.Foo, props)` works unchanged (the
- *    per-slot props were captured server-side; the client component ignores them).
- *  - Data props are DECODED through the contract's own props schema — the inverse of
- *    the server's `Schema.encodeUnknown` — so `Option`/`Date`/branded props arrive as
- *    real instances, not their `{_tag,value}` wire shape.
- *
- * A client view is authored with `Ui.make(SomeUi, …)` — exactly like a local view —
- * and registered with `remoteViews<AppContract>({ Some: SomeView, … })`. There is no
- * separate `remoteView` call: a `Ui.make` view carries its own contract, so `remoteViews`
- * recovers each view's wire name + props schema straight from it.
- */
+// Variance escape (like Schema<any, any>): heterogeneous contract-typed views can't share one element type.
+type AnyMadeView = MadeView<AnyValue>
 
-/**
- * The dynamic presentation shape the renderer calls — slots and events erased to
- * 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?: SlotPropsExternalApi) => ReactNode>,
   events: Record<string, (payload: unknown) => void>,
 ) => ReactNode
 
-/** A contract-bound view paired with the contract name the renderer looks it up by, and
- *  (for a WIRED contract) the props schema used to DECODE wire props back into their
- *  decoded domain types — the symmetric inverse of the server's `Schema.encodeUnknown`.
- *  Without it, an `Option`/`Date`/branded prop would reach the view as its raw encoded
- *  shape (e.g. `{_tag:'Some',value}`) instead of a real `Option`. */
 export interface RegisteredRemoteView {
   readonly name: string
   readonly view: RemoteView
   readonly propsSchema: Option.Option<Schema.Schema<Record<string, unknown>, unknown>>
 }
 
-/** The by-name presentation record the renderer walks — the unbranded runtime shape behind
- *  a `RemoteViewSet`. Internal: it is NOT part of the public API, so a raw record of this
- *  shape can never be handed to `connect`/`renderWireTree`/`<RemoteUI>` (those demand the
- *  branded `RemoteViewSet<C>`). A `RemoteViewSet<C>` is structurally `ViewRegistry & brand`,
- *  so it always widens back to this when the renderer needs the plain lookup. */
 type ViewRegistry = Readonly<Record<string, RegisteredRemoteView>>
 
-/** Phantom brand carrying the server `RemoteContract` a view set was checked against. Typed
- *  as a function OF `C` (never called) so the contract appears in the type WITHOUT needing a
- *  runtime value of `C` — `remoteViews<C>(views)` can brand the set cast-free even though the
- *  client imports the contract as a TYPE only (trpc-style), never as a value. */
+// Phantom brand of C (function never called) so remoteViews can brand cast-free with type-only C.
 const ViewSetContract: unique symbol = Symbol.for('reform-remote/view-set-contract')
 
-/**
- * The presentation set the client renders by contract name — the `ViewRegistry` the renderer
- * walks, BRANDED with the server `RemoteContract` `C` it was checked against. The brand is
- * what makes the whole client chain typesafe: `connect`, `renderWireTree`, and `<RemoteUI>`
- * accept only a `RemoteViewSet` *produced by* `remoteViews<C>(…)` — never an arbitrary
- * `Record`, which lacks the brand — so a view set cannot reach the renderer without having
- * been type-checked to implement exactly the server's shape. `C` is recovered by inference at
- * each consumer, so passing a `RemoteViewSet<AppContract>` types the whole chain to that app.
- *
- * No default for `C`: a `RemoteViewSet` is ALWAYS bound to a concrete contract (inferred from
- * `remoteViews<AppContract>(…)`), never silently widened to the `RemoteContract` bound — that
- * is what keeps the safety end to end.
- */
 export type RemoteViewSet<C extends RemoteContract> = ViewRegistry & {
   readonly [ViewSetContract]: (contract: C) => void
 }
 
-/**
- * The shared "shape" the server publishes and the client implements — the trpc `AppRouter`
- * analog. It is a registry of the server's UI contracts (the `ui(...)` classes the scene's
- * wire tree can emit) keyed by a label. The SERVER declares it ONCE (`remoteContract({…})`)
- * and exports `typeof` it; the CLIENT imports THAT TYPE and `remoteViews<AppContract>(…)`
- * checks its view set against it, so the client is forced to implement exactly the server's
- * views. The wire name + props schema are read from each view's own contract at runtime, so
- * the label is only the type-level join key — the contract is never needed as a value here.
- *
- * `UiClass<any>` is the registry's *upper bound*; the precise per-contract types are
- * preserved by inferring `C` narrowly at the `remoteContract` declaration site (so
- * `Ui.Contract<C[K]>` recovers the real contract, not `any`).
- */
-export type RemoteContract = Readonly<Record<string, UiClass<any>>>
+export type RemoteContract = Readonly<Record<string, UiClass<AnyValue>>>
 
-/**
- * Declare a server's `RemoteContract` with its precise key/contract types inferred (the
- * `const` type parameter keeps each value's specific `UiClass<…>` instead of widening to
- * the `UiClass<any>` bound). Define it ONCE next to the scene and export `typeof` it as the
- * UI requirements the client implements against:
- *
- *   export const AppContract = remoteContract({ Shell: ShellUi, Sidebar: SidebarUi })
- *   export type AppContract = typeof AppContract
- *
- * The client then imports only the TYPE and implements it:
- *
- *   import type { AppContract } from '…/app-contract'
- *   export const views = remoteViews<AppContract>({ Shell: ShellView, Sidebar: SidebarView })
- */
-export const remoteContract = <const C extends RemoteContract>(contract: C): C => contract
+export { remoteContract } from './contract'
 
-/**
- * The client view set a `RemoteContract` demands: exactly one `Ui.make` view per contract,
- * each typed to THAT contract (`MadeView<Ui.Contract<C[K]>>`). A missing key, an extra key,
- * or a view authored for the wrong contract is a COMPILE error — the client cannot connect
- * to the server without implementing precisely its shape, the same guarantee trpc gives a
- * client built from `AppRouter`.
- */
 export type RemoteViews<C extends RemoteContract> = {
   readonly [K in keyof C]: MadeView<Ui.Contract<C[K]>>
 }
 
-/**
- * Implement a server's UI shape: `remoteViews<AppContract>({ … })` takes the server's
- * `RemoteContract` as a TYPE PARAMETER (the client imports only `typeof AppContract`, never a
- * value — trpc-style) and a set of `Ui.make` views type-checked to implement EXACTLY that
- * contract. Each view carries its own contract (`Ui.make(SomeUi, …)`), so the wire name and
- * props schema are recovered from the view itself — a renamed/retyped contract can never
- * drift from its presentation, and the SAME view authored for the local renderer is reused.
- * The result is a `RemoteViewSet<C>` (the branded set `connect`/`renderWireTree`/`<RemoteUI>`
- * accept); an unbranded `Record` can never be substituted.
- */
 export const remoteViews = <C extends RemoteContract>(views: RemoteViews<C>): RemoteViewSet<C> => {
   const madeViews: ReadonlyArray<AnyMadeView> = Object.values(views)
   const byName: ViewRegistry = Rec.fromEntries(
     madeViews.map((view): readonly [string, RegisteredRemoteView] => {
       const viewContract = view[UiViewContract]
-      // `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,
@@ -164,35 +61,19 @@ export const remoteViews = <C extends RemoteContract>(views: RemoteViews<C>): Re
       return [entry.name, entry]
     }),
   )
-  // Brand the record with the contract `C` it was checked against. The brand is a phantom
-  // 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 { ...byName, [ViewSetContract]: (_contract: C): void => {} }
 }
 
 export interface ClientConfig<C extends RemoteContract> {
-  /** Presentation (+ optional props schema) per contract name — a contract-checked set. */
   readonly views: RemoteViewSet<C>
-  /** Deliver a trigger invocation to the server (the transport's send). */
   readonly invoke: (handle: string, payload: unknown) => void
 }
 
-/** What the renderer actually walks: the unbranded `ViewRegistry` + `invoke`. Any
- *  `ClientConfig<C>` widens to this (its `RemoteViewSet<C>` views widen to `ViewRegistry`),
- *  so the recursive renderer is contract-agnostic — the contract check already happened at
- *  `remoteViews`. Internal: callers only ever supply a `ClientConfig<C>`. */
 interface RenderConfig {
   readonly views: ViewRegistry
   readonly invoke: (handle: string, payload: unknown) => void
 }
 
-/**
- * A stable top-level component for one wire node — stable identity so React keeps a
- * view's local state across frames (the `node.id` keys it). It decodes props, builds
- * 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.
- */
 interface WireNodeViewProps {
   readonly node: WireNode
   readonly tree: WireTree
@@ -200,20 +81,10 @@ interface WireNodeViewProps {
 }
 
 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.
+  // latest mutates each render so stable slot closures always see current tree.
   const latest = useRef({ node, tree, config })
   latest.current = { node, tree, config }
-  // Slot components cached by name across renders. CRITICAL for state preservation: a parent
-  // view that renders a slot as `<slots.Foo/>` (the Ui.make convention) passes the slot value
-  // as the element TYPE — if that value were a fresh closure each render (as it was before),
-  // React would see a new component type every frame and UNMOUNT+REMOUNT the whole slot
-  // subtree, resetting every descendant view's local hook state (e.g. a modal's open/step
-  // `useState` would snap back, closing the modal on any unrelated background patch). Caching
-  // the closure by slot name gives `<slots.Foo/>` a stable type, so React reconciles the slot's
-  // children by id instead of remounting them. The closure reads `latest` so it still renders
-  // the current tree.
+  // Cache slot components by name: fresh closures remount the slot subtree and reset descendant hooks.
   const slotCache = useRef<Record<string, () => ReactNode>>({})
 
   const registered = config.views[node.name]
@@ -236,17 +107,7 @@ const WireNodeView = ({ node, tree, config }: WireNodeViewProps): ReactNode => {
     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
-  // 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/>`).
+  // slotKey → one child by wire key (list-per-item); omit → all children of the slot.
   const slotFor = (slotName: string): ((slotProps?: SlotPropsExternalApi) => ReactNode) => {
     const cached = slotCache.current[slotName]
     if (cached !== undefined) {
@@ -275,10 +136,7 @@ const WireNodeView = ({ node, tree, config }: WireNodeViewProps): ReactNode => {
     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.
+  // Lazy by name: empty slots yield a no-op component, never undefined (invalid element type).
   const slots: Record<string, (slotProps?: SlotPropsExternalApi) => ReactNode> = new Proxy(
     Object.create(null),
     { get: (_target, key) => (typeof key === 'string' ? slotFor(key) : undefined) },

package/src/connect.ts

@@ -0,0 +1,44 @@
+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

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

package/src/fixtures.ts

@@ -24,17 +24,6 @@ import {
   ui,
 } from '@playfast/reform'
 
-/**
- * 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 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 ────────────────────
 class Count extends State.make('count', S.Number) {}
 class Counters extends StateGroup.make(Count) {}
 class Bumped extends Event.make('Bumped', S.Struct({ by: S.Number })) {}
@@ -51,7 +40,6 @@ const CounterUiBase: WiredUi<
 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 = (amount: number): EventOf<'Bumped', { by: number }> =>
   Event.construct(Bumped, { by: amount })
 
@@ -71,10 +59,6 @@ export const counterScene = (boot?: ReadonlyArray<EventOf<'Bumped', { by: number
   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}`)),
@@ -91,9 +75,6 @@ export const structureCounterScene = (): Scene => {
   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. ──────────────────────────────────
 class Label extends State.make('label', S.OptionFromSelf(S.String)) {}
 class Labels extends StateGroup.make(Label) {}
 const OptionalUiBase: WiredUi<
@@ -116,7 +97,6 @@ export const optionScene = (initial: Option.Option<string> = Option.some('hi')):
   return scene(Optional, { provide: [app] })
 }
 
-// ── slotted: a shell whose one slot holds a child with its OWN state + event ───
 class Greeting extends State.make('greeting', S.String) {}
 class Greeted extends Event.make('Greeted', S.Struct({ text: S.String })) {}
 class Cleared extends Event.make('Cleared', S.Struct({})) {}
@@ -124,7 +104,6 @@ class SetGreeting extends Reducer.make('SetGreeting', { states: [Greeting], even
 class ClearGreeting extends Reducer.make('ClearGreeting', { states: [Greeting], events: [Cleared] }) {}
 class PanelUi extends ui('Panel', {
   props: S.Struct({ greeting: S.String }),
-  // Two events on one node — each registers behind its own `${id}:${name}` handle.
   events: { greet: S.Struct({ text: S.String }), clear: S.Struct({}) },
 }) {}
 class Panel extends Composition.make('Panel', { title: 'Panel', ui: PanelUi, states: [Greeting] }) {}
@@ -141,6 +120,7 @@ export const slottedScene = (): Scene => {
   )
   const app = Layer.mergeAll(
     Composition.live(Shell, function* () {
+      yield* Effect.void
       return mount({ props: {}, slots: { Main: one({}) } })
     }),
     Composition.live(Panel, function* () {
@@ -156,7 +136,6 @@ export const slottedScene = (): Scene => {
   return scene(Shell, { provide: [app] })
 }
 
-// ── list: a parent with two slots — a single-child toolbar and a dynamic list ──
 const ListItem = S.Struct({ id: S.String, label: S.String })
 class Items extends State.make('items', S.Array(ListItem)) {}
 class Added extends Event.make('Added', ListItem) {}
@@ -230,8 +209,7 @@ export const listScene = (
     Composition.live(ItemComp, function* () {
       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.
+      // Item binds its own id into remove so the wire event has empty payload.
       const remove = (): void => removeTrigger({ id: itemProps.id })
       return mount({ props: { label: itemProps.label }, slots: {}, events: { remove } })
     }),
@@ -241,11 +219,7 @@ export const listScene = (
   return scene(ListComp, { provide: [app] })
 }
 
-// ── async: a counter whose state changes AFTER the opening snapshot, with no client
-// invoke. A boot event kicks a procedure that sleeps, then dispatches `Bumped` — modelling
-// a background load (a repo list, a reconcile sweep) that resolves long after connect. This
-// is the ONLY fixture that exercises the server-initiated streaming push: every other scene
-// settles before its first render, so its full state is already in the snapshot. ──────────
+// Boot Kick → DelayedBump sleeps past opening snapshot, then Bumped — only path for server-pushed diffs.
 class Kick extends Event.make('Kick', S.Struct({ to: S.Number })) {}
 class Loader extends Channel.make('Loader', { policy: { _tag: 'latest' } }) {}
 class DelayedBump extends Procedure.make('DelayedBump', { channel: Loader, events: [Kick] }) {}
@@ -262,15 +236,11 @@ export const asyncCounterScene = (delay: Duration.DurationInput = '40 millis'):
       return mount({ props: { count }, slots: {}, events: { bump } })
     }),
     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.
     Procedure.live(DelayedBump, function* (event) {
       yield* Effect.sleep(delay)
       yield* Event.dispatch(Bumped, { by: event.to })
     }),
-    // The procedure runs on a named channel; without its queue+fiber (`Channel.live`)
-    // the boot `Kick` is dropped and nothing ever bumps.
+    // Without Channel.live the boot Kick is dropped.
     Channel.live(Loader),
   ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
   return scene(Counter, { provide: [app], boot: [Event.construct(Kick, { to: 7 })] })

package/src/index.ts

@@ -1,13 +1,3 @@
-// @playfast/reform-remote — run a reform scene's logic on the server and stream
-// its rendered UI to a thin client over a transport. A fourth consumer of a
-// `Scene`, alongside @playfast/react, @playfast/react-native, and @playfast/proof.
-// See REMOTE_UI.md.
-//
-// Public API is exposed two ways (Effect-style): namespace barrels for discovery
-// (`import { Transport } from "@playfast/reform-remote"`) and per-path subpaths
-// for direct use (`import { connect } from "@playfast/reform-remote/transport"`).
-// The select re-exports below keep the common entry points nameable from the root.
-
 export * as Server from './server'
 export * as Client from './client'
 export * as Transport from './transport'

package/src/memory.ts

@@ -1,14 +1,5 @@
 import type { RemoteTransport } from './transport'
 
-/**
- * The in-memory transport adapter: a duplex pair where what one end sends, the
- * other receives — synchronously, in process. It is the simplest concrete
- * `RemoteTransport`, and the one the test suite drives `serve`/`connect` over
- * without a socket. A WebSocket adapter is the same shape with JSON framing
- * across a wire; proving the loop here proves it everywhere.
- */
-
-/** A linked `server`/`client` transport: each receives exactly what the other sends. */
 export interface TransportPair<Server, Client> {
   readonly server: RemoteTransport<Server, Client>
   readonly client: RemoteTransport<Client, Server>

package/src/react.ts

@@ -7,56 +7,30 @@ import {
 } from './transport'
 import type { RemoteContract, RemoteViewSet } from './client'
 
-/**
- * The React binding for the remote client. A consumer hands it a transport and a
- * `views` map and gets a live React subtree — the framework owns the transport
- * wiring (connect, the patch subscription, re-render on each frame, teardown on
- * unmount). No `useSyncExternalStore`, `binding.subscribe`, or `binding.node()`
- * at the call site.
- */
-
-/**
- * Render the remote scene as React. Pass a stable `transport` (created once,
- * e.g. by `createWebSocketClientTransport`) — the binding is established on mount
- * and disposed on unmount.
- */
 export const useRemoteUI = <C extends RemoteContract>(
   transport: RemoteTransport<InvokeMessage, ServerMessage>,
   views: RemoteViewSet<C>,
 ): ReactNode => {
-  // One binding for the life of the component (the transport is stable).
   const [binding] = useState(() => connect({ transport, views }))
   useEffect(() => () => binding.dispose(), [binding])
-  // Re-render whenever a frame changes the tree; `snapshot` is a stable ref.
   useSyncExternalStore(binding.subscribe, binding.snapshot, binding.snapshot)
   return binding.node()
 }
 
 export interface RemoteUIProps<C extends RemoteContract> {
   readonly transport: RemoteTransport<InvokeMessage, ServerMessage>
-  /** A contract-checked view set from `remoteViews<C>(…)` — an unbranded `Record` is rejected,
-   *  so `<RemoteUI>` can only render views proven to implement the server's shape. */
   readonly views: RemoteViewSet<C>
 }
 
-/** Component form of {@link useRemoteUI}: `<RemoteUI transport={…} views={…} />`. `C` is
- *  inferred from `views` (the `remoteViews<AppContract>(…)` result), so the whole subtree is
- *  typed to that app's contract. */
 export const RemoteUI = <C extends RemoteContract>({
   transport,
   views,
 }: RemoteUIProps<C>): ReactNode => useRemoteUI(transport, views)
 
-/**
- * Anything that reports an observable connection status — implemented by the
- * WebSocket client transport. Kept structural so the React binding needs no
- * dependency on a specific adapter.
- */
 export interface StatusReporter<S> {
   readonly status: () => S
   readonly onStatusChange: (listener: () => void) => () => void
 }
 
-/** Subscribe to a transport's connection status (e.g. to show a reconnecting badge). */
 export const useConnectionStatus = <S>(reporter: StatusReporter<S>): S =>
   useSyncExternalStore(reporter.onStatusChange, reporter.status, reporter.status)