@playfast/reform-remote 1.0.2 → 1.1.0

package/README.md

@@ -19,7 +19,7 @@ data — UI-tree patches one way, trigger invocations the other — so there is
 This builds on reform's existing seams: the **`ui` contract** already separates logic from
 presentation, the **`CaptureSink`** already serializes the rendered surface headlessly (the same
 mechanism proofs use), and the **schema-first `ui`** form (`ui(name, { props, events })`) carries
-the wire schemas that make props and trigger payloads typed *and* runtime-validated at the seam.
+the wire schemas that make props and trigger payloads typed _and_ runtime-validated at the seam.
 See [`REMOTE_UI.md`](../../REMOTE_UI.md) for the design.
 
 ## Install
@@ -35,15 +35,15 @@ sockets pair with [`@playfast/reform-remote-node`](https://www.npmjs.com/package
 
 ## Key concepts
 
-| Concept | What it does |
-| --- | --- |
-| `makeRemoteServer(scene)` | Renders a `Scene` to a `WireTree`; `render()`/`renderDiff()` emit full tree/patches; `invoke(handle, payload)` fires a trigger. |
-| `renderWireTree(tree, { views, invoke })` | Folds a `WireTree` back into React using local presentations. |
-| `remoteContract({...})` / `remoteViews<C>({...})` | The trpc-style typesafe seam — server declares the contract, client implements exactly it. |
-| `serve({ scene, transport })` / `connect({ transport, views })` | Bind both ends to any `RemoteTransport`. |
-| `inMemoryTransportPair()` | In-process duplex `RemoteTransport` (the simplest concrete adapter). |
-| `<RemoteUI transport views />` / `useRemoteUI` | React binding that owns connect, subscription, re-render, teardown. |
-| `useConnectionStatus(reporter)` | Reads a transport's live `StatusReporter` status. |
+| Concept                                                         | What it does                                                                                                                    |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `makeRemoteServer(scene)`                                       | Renders a `Scene` to a `WireTree`; `render()`/`renderDiff()` emit full tree/patches; `invoke(handle, payload)` fires a trigger. |
+| `renderWireTree(tree, { views, invoke })`                       | Folds a `WireTree` back into React using local presentations.                                                                   |
+| `remoteContract({...})` / `remoteViews<C>({...})`               | The trpc-style typesafe seam — server declares the contract, client implements exactly it.                                      |
+| `serve({ scene, transport })` / `connect({ transport, views })` | Bind both ends to any `RemoteTransport`.                                                                                        |
+| `inMemoryTransportPair()`                                       | In-process duplex `RemoteTransport` (the simplest concrete adapter).                                                            |
+| `<RemoteUI transport views />` / `useRemoteUI`                  | React binding that owns connect, subscription, re-render, teardown.                                                             |
+| `useConnectionStatus(reporter)`                                 | Reads a transport's live `StatusReporter` status.                                                                               |
 
 ## How it fits together
 
@@ -106,12 +106,12 @@ sockets pair with [`@playfast/reform-remote-node`](https://www.npmjs.com/package
 
 ## Transport adapters
 
-| Package | Role | Built on |
-| --- | --- | --- |
-| `inMemoryTransportPair` (here) | in-process duplex | — |
-| [`@playfast/reform-remote-node`](https://www.npmjs.com/package/@playfast/reform-remote-node) | WebSocket server | `ws` |
-| [`@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` |
+| Package                                                                                      | Role                                       | Built on           |
+| -------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------ |
+| `inMemoryTransportPair` (here)                                                               | in-process duplex                          | —                  |
+| [`@playfast/reform-remote-node`](https://www.npmjs.com/package/@playfast/reform-remote-node) | WebSocket server                           | `ws`               |
+| [`@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` |
 
 ## License
 

package/package.json

@@ -1,36 +1,38 @@
 {
   "name": "@playfast/reform-remote",
-  "playbook": "./playbook",
-  "version": "1.0.2",
-  "type": "module",
+  "version": "1.1.0",
   "description": "Run a reform scene's logic on the server and stream its rendered UI to a thin client over any duplex transport.",
   "keywords": [
-    "reform",
     "effect",
+    "react",
+    "reform",
     "remote",
     "server-driven-ui",
-    "transport",
-    "react"
+    "transport"
   ],
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/playfast/reform.git",
     "directory": "packages/reform-remote"
   },
-  "bugs": {
-    "url": "https://github.com/playfast/reform/issues"
-  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
   "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
     ".": "./src/index.ts",
     "./*": "./src/*.ts"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "clean": "rm -rf dist .tsbuildinfo",
     "check": "tsc --noEmit",
@@ -42,11 +44,9 @@
     "lint:fix": "oxlint --fix src"
   },
   "peerDependencies": {
+    "@playfast/reform": "*",
     "effect": "*",
-    "react": "^19.0.0",
-    "@playfast/reform": "*"
+    "react": "^19.0.0"
   },
-  "publishConfig": {
-    "access": "public"
-  }
+  "playbook": "./playbook"
 }

package/src/client-keyed-slot.test.ts

@@ -4,13 +4,18 @@ import { createRoot } from 'react-dom/client'
 import { expect, test } from 'vitest'
 import { Schema as S } from 'effect'
 import { Composition, slot, Ui, ui } from '@playfast/reform'
-import type { WireNode } from '@playfast/reform'
+import type { WireNode } from '@playfast/reform/internal'
 import { remoteViews, renderWireTree, type RemoteViews } from './client'
 
 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>() {}
-class ListUi extends ui('List')<{ props: { mode: string }; slots: { Item: ItemSlot } }>() {}
+
+class ItemComp extends Composition.make('Item', { title: 'Item', ui: ItemUi })<ItemComp>() {}
+
+class ItemSlot extends slot('Item')<ItemSlot, typeof ItemComp>() {}
+class ListUi extends ui('List', {
+  props: S.Struct({ mode: S.String }),
+  slots: { Item: ItemSlot },
+}) {}
 
 const node = (over: Partial<WireNode> & Pick<WireNode, 'id' | 'name'>): WireNode => ({
   parentId: null,
@@ -77,8 +82,16 @@ test('a keyed slot renders ONE matching child per call site, not the whole list'
     createElement(
       'div',
       null,
-      createElement('section', { 'data-section': 'one' }, createElement(slots.Item, { slotKey: 'a' })),
-      createElement('section', { 'data-section': 'two' }, createElement(slots.Item, { slotKey: 'b' })),
+      createElement(
+        'section',
+        { 'data-section': 'one' },
+        createElement(slots.Item, { slotKey: 'a' }),
+      ),
+      createElement(
+        'section',
+        { 'data-section': 'two' },
+        createElement(slots.Item, { slotKey: 'b' }),
+      ),
     ),
   )
   const container = await renderWith(ListView, tree)

package/src/client-remount.test.ts

@@ -5,16 +5,21 @@ import { createRoot } from 'react-dom/client'
 import { expect, test } from 'vitest'
 import { Schema as S } from 'effect'
 import { Composition, slot, Ui, ui } from '@playfast/reform'
-import type { WireNode } from '@playfast/reform'
+import type { WireNode } from '@playfast/reform/internal'
 import type { ServerMessage } from './transport'
 import { connect } from './transport'
 import { inMemoryTransportPair } from './memory'
 import { remoteViews } from './client'
 
 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>() {}
-class HostUi extends ui('Host')<{ props: { count: number }; slots: { Main: MainSlot } }>() {}
+
+class ChildComp extends Composition.make('Child', { title: 'Child', ui: ChildUi })<ChildComp>() {}
+
+class MainSlot extends slot('Main')<MainSlot, typeof ChildComp>() {}
+class HostUi extends ui('Host', {
+  props: S.Struct({ count: S.Number }),
+  slots: { Main: MainSlot },
+}) {}
 
 const node = (over: Partial<WireNode> & Pick<WireNode, 'id' | 'name'>): WireNode => ({
   parentId: null,
@@ -84,7 +89,11 @@ test('a background patch on the PARENT keeps its slot child mounted (local useSt
         patches: [
           {
             _tag: 'Upsert',
-            node: node({ id: '0', name: 'Host', props: [{ _tag: 'Data', name: 'count', value: 7 }] }),
+            node: node({
+              id: '0',
+              name: 'Host',
+              props: [{ _tag: 'Data', name: 'count', value: 7 }],
+            }),
           },
         ],
       })

package/src/client.ts

@@ -1,19 +1,15 @@
 import { createElement, Fragment, type ReactNode, useRef } from 'react'
-import { Option, Record as Rec, Schema } from 'effect'
+import { Effect, Record as Rec, Schema } from 'effect'
+import { type MadeView, Ui, type UiContract, UiViewContract, type ViewImpl } from '@playfast/reform'
 import {
-  type MadeView,
-  Ui,
-  type UiClass,
-  UiViewContract,
+  type AnyMadeView,
+  type AnyUi,
+  type UiReflection,
+  type WiredUiManifest,
   Wire,
   type WireNode,
   type WireTree,
-} from '@playfast/reform'
-
-type AnyValue = Schema.Schema.Type<Schema.Schema.Any>
-
-// Variance escape (like Schema<any, any>): heterogeneous contract-typed views can't share one element type.
-type AnyMadeView = MadeView<AnyValue>
+} from '@playfast/reform/internal'
 
 export interface SlotPropsExternalApi {
   readonly slotKey?: string
@@ -28,40 +24,74 @@ export type RemoteView = (
 export interface RegisteredRemoteView {
   readonly name: string
   readonly view: RemoteView
-  readonly propsSchema: Option.Option<Schema.Schema<Record<string, unknown>, unknown>>
 }
 
 type ViewRegistry = Readonly<Record<string, RegisteredRemoteView>>
 
-// 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')
 
 export type RemoteViewSet<C extends RemoteContract> = ViewRegistry & {
-  readonly [ViewSetContract]: (contract: C) => void
+  readonly [ViewSetContract]: (contract: C) => C
 }
 
-export type RemoteContract = Readonly<Record<string, UiClass<AnyValue>>>
+type RemoteUi = UiReflection<UiContract, string> & AnyUi & { readonly manifest: WiredUiManifest }
+export type RemoteContract = Readonly<Record<string, RemoteUi>>
 
-export { remoteContract } from './contract'
+export const remoteContract = <const C extends RemoteContract>(contract: C): C => contract
 
+type RemoteViewFor<U extends RemoteUi> =
+  U extends UiReflection<infer Contract, infer Name> ? MadeView<Contract, Name, U> : never
 export type RemoteViews<C extends RemoteContract> = {
-  readonly [K in keyof C]: MadeView<Ui.Contract<C[K]>>
+  readonly [K in keyof C]: RemoteViewFor<C[K]>
+}
+
+type RemoteSlots = Record<string, (slotProps?: SlotPropsExternalApi) => ReactNode>
+type RemoteEvents = Record<string, (payload: unknown) => void>
+
+function bindSlots<C extends Ui.UiContract>(slots: RemoteSlots): Parameters<ViewImpl<C>>[1]
+function bindSlots(slots: RemoteSlots): unknown {
+  return slots
 }
 
+function bindEvents<C extends Ui.UiContract>(events: RemoteEvents): Parameters<ViewImpl<C>>[2]
+function bindEvents(events: RemoteEvents): unknown {
+  return events
+}
+
+const registerView = (view: AnyMadeView): RegisteredRemoteView =>
+  view.capture(
+    <C extends Ui.UiContract, N extends string, U extends Ui.AnyUi>(exact: MadeView<C, N, U>) => {
+      const contract = exact[UiViewContract]
+      const propsReflection = contract.manifest.props
+      if (propsReflection === undefined) {
+        return Effect.runSync(
+          Effect.dieMessage(
+            `reform-remote: view ${contract.manifest.name} needs a wire props schema`,
+          ),
+        )
+      }
+      const propsSchema = Schema.make<C['props'], unknown>(propsReflection.ast)
+      return {
+        name: contract.manifest.name,
+        view: (encoded, slots, events) =>
+          exact(
+            Schema.decodeUnknownSync(propsSchema)(encoded),
+            bindSlots<C>(slots),
+            bindEvents<C>(events),
+          ),
+      }
+    },
+  )
+
 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]
-      const entry: RegisteredRemoteView = {
-        name: viewContract.manifest.name,
-        view,
-        propsSchema: Option.fromNullable(viewContract.manifest.props),
-      }
+      const entry = registerView(view)
       return [entry.name, entry]
     }),
   )
-  return { ...byName, [ViewSetContract]: (_contract: C): void => {} }
+  return { ...byName, [ViewSetContract]: (contract: C): C => contract }
 }
 
 export interface ClientConfig<C extends RemoteContract> {
@@ -81,10 +111,10 @@ interface WireNodeViewProps {
 }
 
 const WireNodeView = ({ node, tree, config }: WireNodeViewProps): ReactNode => {
-  // latest mutates each render so stable slot closures always see current tree.
+  // Stable slot closures read current inputs through this ref.
   const latest = useRef({ node, tree, config })
   latest.current = { node, tree, config }
-  // Cache slot components by name: fresh closures remount the slot subtree and reset descendant hooks.
+  // Fresh slot component types remount descendants and reset their hooks.
   const slotCache = useRef<Record<string, () => ReactNode>>({})
 
   const registered = config.views[node.name]
@@ -93,21 +123,22 @@ const WireNodeView = ({ node, tree, config }: WireNodeViewProps): ReactNode => {
   }
 
   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]
-        : [],
+    node.props.flatMap(
+      (prop): ReadonlyArray<readonly [string, unknown]> =>
+        prop._tag === 'Data' ? [[prop.name, prop.value]] : [],
     ),
   )
-  const props: Record<string, unknown> = Option.match(registered.propsSchema, {
-    onNone: () => encoded,
-    onSome: (schema) => Schema.decodeUnknownSync(schema)(encoded),
-  })
+  const eventEntries = node.props.flatMap(
+    (prop): ReadonlyArray<readonly [string, (payload: unknown) => void]> => {
+      if (prop._tag !== 'Event') {
+        return []
+      }
+      return [[prop.name, (payload: unknown) => config.invoke(prop.handle, payload)]]
+    },
+  )
+  const events: Record<string, (payload: unknown) => void> = Rec.fromEntries(eventEntries)
 
-  // slotKey → one child by wire key (list-per-item); omit → all children of the slot.
+  // slotKey selects one wire child; omitting it renders every child in the slot.
   const slotFor = (slotName: string): ((slotProps?: SlotPropsExternalApi) => ReactNode) => {
     const cached = slotCache.current[slotName]
     if (cached !== undefined) {
@@ -136,13 +167,15 @@ const WireNodeView = ({ node, tree, config }: WireNodeViewProps): ReactNode => {
     return stable
   }
 
-  // Lazy by name: empty slots yield a no-op component, never undefined (invalid element type).
+  // Empty slots must still produce a callable component, not an invalid undefined element type.
   const slots: Record<string, (slotProps?: SlotPropsExternalApi) => ReactNode> = new Proxy(
     Object.create(null),
-    { get: (_target, key) => (typeof key === 'string' ? slotFor(key) : undefined) },
+    {
+      get: (_target, key) => (typeof key === 'string' ? slotFor(key) : undefined),
+    },
   )
 
-  return registered.view(props, slots, events)
+  return registered.view(encoded, slots, events)
 }
 
 export const renderWireTree = <C extends RemoteContract>(