@playfast/reform-remote 0.0.2 → 0.0.3

package/src/fixtures.ts

@@ -0,0 +1,246 @@
+import { createElement, Fragment } from 'react'
+import { Duration, Effect, Layer, Option, Schema as S } from 'effect'
+import {
+  Channel,
+  Composition,
+  type DerivedContract,
+  Engine,
+  Event,
+  type EventOf,
+  Procedure,
+  Props,
+  Reducer,
+  type Scene,
+  State,
+  StateGroup,
+  Ui,
+  type WiredUi,
+  provide,
+  scene,
+  slot,
+  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 presentations here are the
+ * server-side `Ui.make` views that *expand* the tree (a list view maps its state to
+ * N slot children); the client renders the resulting wire tree with its own
+ * `RemoteView`s (thunk slots), which the transport tests supply separately.
+ */
+
+// ── 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 })) {}
+class Bump extends Reducer.make('Bump', { states: [Count], events: [Bumped] }) {}
+const CounterUiBase: WiredUi<
+  DerivedContract<{
+    props: S.Struct<{ count: typeof S.Number }>
+    events: { bump: S.Struct<{ by: typeof S.Number }> }
+  }>
+> = ui('Counter', {
+  props: S.Struct({ count: S.Number }),
+  events: { bump: S.Struct({ by: S.Number }) },
+})
+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 counterScene = (boot?: ReadonlyArray<EventOf<'Bumped', { by: number }>>): Scene => {
+  const presentation = Layer.mergeAll(
+    provide(CounterUi, Ui.make(CounterUi, ({ count }) => `count:${count}`)),
+    StateGroup.live(Counters, { count: 0 }),
+  )
+  const app = Layer.mergeAll(
+    Composition.live(Counter, function* () {
+      const count = yield* StateGroup.select(Counters, 'count')
+      const bump = yield* Event.trigger(Bumped)
+      return (yield* CounterUi)({ count }, { bump })
+    }),
+    Reducer.live(Bump, (n, event) => n + event.by),
+  ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
+  return scene(Counter, boot === undefined ? { provide: [app] } : { provide: [app], boot })
+}
+
+// ── 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<
+  DerivedContract<{ props: S.Struct<{ label: S.Option<typeof S.String> }> }>
+> = ui('Optional', { props: S.Struct({ label: S.Option(S.String) }) })
+export class OptionalUi extends OptionalUiBase {}
+class Optional extends Composition.make('Optional', { title: 'Optional', ui: OptionalUi, states: [Label] }) {}
+
+export const optionScene = (initial: Option.Option<string> = Option.some('hi')): Scene => {
+  const presentation = Layer.mergeAll(
+    provide(OptionalUi, Ui.make(OptionalUi, () => null)),
+    StateGroup.live(Labels, { label: initial }),
+  )
+  const app = Layer.mergeAll(
+    Composition.live(Optional, function* () {
+      const label = yield* StateGroup.select(Labels, 'label')
+      return (yield* OptionalUi)({ label })
+    }),
+  ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
+  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({})) {}
+class SetGreeting extends Reducer.make('SetGreeting', { states: [Greeting], events: [Greeted] }) {}
+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] }) {}
+class MainSlot extends slot('Main')<typeof Panel>() {}
+class ShellUi extends ui('Shell')<{ props: {}; slots: { Main: MainSlot } }>() {}
+class Shell extends Composition.make('Shell', { title: 'Shell', slots: { Main: MainSlot }, ui: ShellUi }) {}
+
+export const slottedScene = (): Scene => {
+  const presentation = Layer.mergeAll(
+    provide(ShellUi, Ui.make(ShellUi, (_props, slots) => createElement(slots.Main, {}))),
+    provide(PanelUi, Ui.make(PanelUi, ({ greeting }) => greeting)),
+    provide(MainSlot, Panel),
+    State.live(Greeting, 'hi'),
+  )
+  const app = Layer.mergeAll(
+    Composition.live(Shell, function* () {
+      const view = yield* ShellUi
+      return view({})
+    }),
+    Composition.live(Panel, function* () {
+      const greeting = yield* Greeting
+      const greet = yield* Event.trigger(Greeted)
+      const clearTrigger = yield* Event.trigger(Cleared)
+      const clear = (): void => clearTrigger({})
+      return (yield* PanelUi)({ greeting }, { greet, clear })
+    }),
+    Reducer.live(SetGreeting, (_greeting, event) => event.text),
+    Reducer.live(ClearGreeting, () => ''),
+  ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
+  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) {}
+class Removed extends Event.make('Removed', S.Struct({ id: S.String })) {}
+class AddItem extends Reducer.make('AddItem', { states: [Items], events: [Added] }) {}
+class RemoveItem extends Reducer.make('RemoveItem', { states: [Items], events: [Removed] }) {}
+
+class BarUi extends ui('Bar', { props: S.Struct({}), events: { add: ListItem } }) {}
+class Bar extends Composition.make('Bar', { title: 'Bar', ui: BarUi }) {}
+class ItemUi extends ui('Item', { props: S.Struct({ label: S.String }), events: { remove: S.Struct({}) } }) {}
+class ItemComp extends Composition.make('Item', {
+  title: 'Item',
+  ui: ItemUi,
+  props: ListItem,
+}) {}
+class BarSlot extends slot('Bar')<typeof Bar>() {}
+class ItemSlot extends slot('Item')<typeof ItemComp>() {}
+class ListUi extends ui('List')<{
+  props: { items: ReadonlyArray<{ id: string; label: string }> }
+  slots: { Bar: BarSlot; Item: ItemSlot }
+}>() {}
+class ListComp extends Composition.make('List', {
+  title: 'List',
+  slots: { Bar: BarSlot, Item: ItemSlot },
+  ui: ListUi,
+  states: [Items],
+}) {}
+
+export const listScene = (
+  initial: ReadonlyArray<{ id: string; label: string }> = [
+    { id: 'a', label: 'A' },
+    { id: 'b', label: 'B' },
+  ],
+): Scene => {
+  const presentation = Layer.mergeAll(
+    provide(
+      ListUi,
+      Ui.make(ListUi, ({ items }, slots) =>
+        createElement(
+          Fragment,
+          null,
+          createElement(slots.Bar, {}),
+          ...items.map((item) => createElement(slots.Item, { id: item.id, label: item.label })),
+        ),
+      ),
+    ),
+    provide(BarUi, Ui.make(BarUi, () => null)),
+    provide(ItemUi, Ui.make(ItemUi, ({ label }) => label)),
+    provide(BarSlot, Bar),
+    provide(ItemSlot, ItemComp),
+    State.live(Items, initial),
+  )
+  const app = Layer.mergeAll(
+    Composition.live(ListComp, function* () {
+      const items = yield* Items
+      const view = yield* ListUi
+      return view({ items })
+    }),
+    Composition.live(Bar, function* () {
+      const add = yield* Event.trigger(Added)
+      return (yield* BarUi)({}, { add })
+    }),
+    Composition.live(ItemComp, function* () {
+      const item = (yield* Props) as { id: string; label: string }
+      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 (yield* ItemUi)({ label: item.label }, { 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)),
+  ).pipe(Layer.provideMerge(presentation), Layer.provideMerge(Engine))
+  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. ──────────
+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] }) {}
+
+export const asyncCounterScene = (delay: Duration.DurationInput = '40 millis'): Scene => {
+  const presentation = Layer.mergeAll(
+    provide(CounterUi, Ui.make(CounterUi, ({ count }) => `count:${count}`)),
+    StateGroup.live(Counters, { count: 0 }),
+  )
+  const app = Layer.mergeAll(
+    Composition.live(Counter, function* () {
+      const count = yield* StateGroup.select(Counters, 'count')
+      const bump = yield* Event.trigger(Bumped)
+      return (yield* CounterUi)({ count }, { bump })
+    }),
+    Reducer.live(Bump, (n, event) => n + 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.
+    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

@@ -0,0 +1,49 @@
+// @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'
+export * as Memory from './memory'
+export * as React from './react'
+
+export { makeRemoteServer, type RemoteServer } from './server'
+export {
+  type ClientConfig,
+  type RegisteredRemoteView,
+  type RemoteContract,
+  remoteContract,
+  type RemoteView,
+  type RemoteViews,
+  type RemoteViewSet,
+  remoteViews,
+  renderWireTree,
+} from './client'
+export {
+  type ClientBinding,
+  connect,
+  type ConnectOptions,
+  type InvokeMessage,
+  type PatchesMessage,
+  type RemoteTransport,
+  serve,
+  type ServeOptions,
+  type ServerBinding,
+  type ServerMessage,
+  type SnapshotMessage,
+} from './transport'
+export { inMemoryTransportPair, type TransportPair } from './memory'
+export {
+  RemoteUI,
+  type RemoteUIProps,
+  type StatusReporter,
+  useConnectionStatus,
+  useRemoteUI,
+} from './react'

package/src/memory.ts

@@ -0,0 +1,36 @@
+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>
+}
+
+export const inMemoryTransportPair = <Server, Client>(): TransportPair<Server, Client> => {
+  const serverHandlers = new Set<(message: Client) => void>()
+  const clientHandlers = new Set<(message: Server) => void>()
+  return {
+    server: {
+      send: (message) => clientHandlers.forEach((handler) => handler(message)),
+      onMessage: (handler) => {
+        serverHandlers.add(handler)
+        return () => void serverHandlers.delete(handler)
+      },
+    },
+    client: {
+      send: (message) => serverHandlers.forEach((handler) => handler(message)),
+      onMessage: (handler) => {
+        clientHandlers.add(handler)
+        return () => void clientHandlers.delete(handler)
+      },
+    },
+  }
+}

package/src/react.ts

@@ -0,0 +1,62 @@
+import { type ReactNode, useEffect, useState, useSyncExternalStore } from 'react'
+import {
+  connect,
+  type InvokeMessage,
+  type RemoteTransport,
+  type ServerMessage,
+} 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)

package/src/remote-view.typecheck.ts

@@ -0,0 +1,75 @@
+import { createElement } from 'react'
+import { Schema as S } from 'effect'
+import { Composition, slot, ui, Ui } from '@playfast/reform'
+import { remoteContract, remoteViews } from './client'
+
+/**
+ * Type-level proof that a remote client view — authored with the SAME `Ui.make`
+ * the local renderer uses and registered with `remoteViews` — is strict: props,
+ * event payloads, and slot names are all derived from the contract, so a wrong
+ * access fails to compile. Compiled by `tsc` (the `@ts-expect-error`s would
+ * themselves error if the line below them ever stopped being an error); not
+ * bundled, not a runtime test.
+ */
+
+class FooUi extends ui('Foo', {
+  props: S.Struct({ n: S.Number }),
+  events: { go: S.Struct({ x: S.String }) },
+}) {}
+
+// ✓ props and event payloads are inferred from the contract.
+const fooView = Ui.make(FooUi, (props, _slots, events) => {
+  events.go({ x: String(props.n) })
+  return null
+})
+
+Ui.make(FooUi, (props) => {
+  // @ts-expect-error — `nope` is not a prop of Foo.
+  props.nope
+  return null
+})
+
+Ui.make(FooUi, (_props, _slots, events) => {
+  // @ts-expect-error — `go` takes { x: string }, not { x: number }.
+  events.go({ x: 1 })
+  return null
+})
+
+Ui.make(FooUi, (_props, _slots, events) => {
+  // @ts-expect-error — `nope` is not an event of Foo.
+  events.nope({})
+  return null
+})
+
+// A local contract with a slot.
+class FooComp extends Composition.make('FooComp', { title: 'Foo', ui: FooUi }) {}
+class FooSlot extends slot('Foo')<typeof FooComp>() {}
+class ShellUi extends ui('Shell', { props: S.Struct({}), slots: { Main: FooSlot } }) {}
+
+// ✓ slot components are keyed by the contract's slot names.
+const shellView = Ui.make(ShellUi, (_props, slots) => createElement(slots.Main, {}))
+
+Ui.make(ShellUi, (_props, slots) =>
+  // @ts-expect-error — `Other` is not a slot of Shell.
+  createElement(slots.Other, {}),
+)
+
+// The server declares its shape ONCE and exports `typeof` it; the client implements that
+// type with `remoteViews<AppContract>(…)` — importing only the TYPE, never the value.
+const AppContractValue = remoteContract({ Foo: FooUi, Shell: ShellUi })
+type AppContract = typeof AppContractValue
+
+// ✓ a view per contract, each recovering its own name + schema; implements the full shape.
+remoteViews<AppContract>({ Foo: fooView, Shell: shellView })
+
+// @ts-expect-error — a view set MISSING `Shell` does not implement the server's shape.
+remoteViews<AppContract>({ Foo: fooView })
+
+remoteViews<AppContract>({
+  Foo: fooView,
+  // @ts-expect-error — `Shell` must be the Shell view, not a Foo view (wrong contract).
+  Shell: fooView,
+})
+
+// @ts-expect-error — `Extra` is not a contract of the server's shape.
+remoteViews<AppContract>({ Foo: fooView, Shell: shellView, Extra: fooView })