@playfast/reform 1.0.1 → 1.1.1

package/src/state/token.ts

@@ -1,12 +1,8 @@
 import { Context, Effect, Effectable } from 'effect'
 import type { Store } from '../internal/store'
+import type { AnyValue } from '../internal/variance'
 import { readTracked } from '../internal/track'
 
-/**
- * A reference to one slice of state: yieldable to its current value (`yield*`
- * reads + — under React — subscribes) and carrying the metadata calcs need
- * (its `name` and backing store tag). Returned by `StateGroup.select(group, name)`.
- */
 export class StateToken<out N extends string, in out A> extends Effectable.Class<A, never, Store<A>> {
   readonly name: N
   readonly store: Context.Tag<Store<A>, Store<A>>
@@ -20,20 +16,11 @@ export class StateToken<out N extends string, in out A> extends Effectable.Class
   }
 }
 
-/**
- * Anything a derived value can read and depend on: a named slice backed by a
- * subscribable store tag. A `StateToken` (group member), a `Calc`, and an
- * `AsyncCalc` all structurally satisfy this — so a `Calc`/`AsyncCalc` can take
- * any of them as an input. The `name` becomes the key in the inputs object.
- *
- * `StateToken` is the one concrete, *yieldable* `Source`; `Calc`/`AsyncCalc`
- * satisfy the same shape so the three are interchangeable as calc inputs.
- */
 export interface Source<out N extends string, in out A> {
   readonly name: N
   readonly store: Context.Tag<Store<A>, Store<A>>
 }
 
-export type AnySource = Source<string, any>
-export type SourceName<S> = S extends Source<infer N, any> ? N : never
-export type SourceValue<S> = S extends Source<any, infer A> ? A : never
+export type AnySource = Source<string, AnyValue>
+export type SourceName<S> = S extends Source<infer N, AnyValue> ? N : never
+export type SourceValue<S> = S extends Source<AnyValue, infer A> ? A : never

package/src/synced/syncedStore.ts

@@ -1,27 +1,13 @@
-import { Context, Effect, Layer, Option, type Schema, type Scope } from 'effect'
+import { Context, Effect, Layer, Option, type Scope } from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import { resolveScheduler } from '../internal/scheduler'
 import { makeDerivedStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
 import type { Source } from '../state/token'
 import type { StateOptions } from '../state/state'
+import type { AnySchema, AnyValue } from '../internal/variance'
 
-// `SyncedStore` is the seam between Reform's reactive `Store` and any *external*
-// reactive source — a PGlite live query, a TanStack DB collection, a socket feed.
-// It is the synchronous, useSyncExternalStore-shaped bridge: a source exposes a
-// `snapshot()` (the current value, synchronously) and a `subscribe(onChange)`,
-// which is exactly what `makeDerivedStore` consumes. Like `RemoteState`'s `truth`
-// store, a `SyncedStore` is written ONLY by its upstream subscription — never by a
-// user reducer — so the "state changes only in the loop (or its driver)" invariant
-// holds. `@playfast/reform-db` is the first consumer: it feeds a `SyncedStore` from
-// a SQL live query whose value is an `AsyncData<Rows>`.
-
-/**
- * The contract an external reactive source implements. `snapshot` must return a
- * stable reference until the value actually changes (the `makeDerivedStore`
- * memoization contract `useSyncExternalStore` requires); `subscribe` returns an
- * unsubscribe thunk, fired on every upstream change.
- */
 export interface SyncedSource<A> {
   readonly snapshot: () => A
   readonly subscribe: (onChange: () => void) => () => void
@@ -30,43 +16,30 @@ export interface SyncedSource<A> {
 export interface SyncedStoreManifest<N extends string, A> extends Manifest {
   readonly kind: 'SyncedStore'
   readonly name: N
-  readonly schema: Schema.Schema<A, any>
+  readonly schema: AnySchema<A>
   readonly title: Option.Option<string>
   readonly description: Option.Option<string>
 }
 
 export interface SyncedStoreClass<out N extends string, in out A>
-  extends Effect.Effect<A, never, Store<A>>,
+  extends EffectType<A, never, Store<A>>,
     Source<N, A> {
   new (): {}
   readonly manifest: SyncedStoreManifest<N, A>
-  /** Internal DI tag holding the live store. `SyncedStore.live` allocates it. */
   readonly store: Context.Tag<Store<A>, Store<A>>
-  /** The name, so the class doubles as a `Source` input to a calc/composition. */
   readonly name: N
 }
 
-/**
- * A minimal store-carrier — satisfied by a `SyncedStoreClass` and by any
- * companion primitive (e.g. `@playfast/reform-db`'s `DbQuery`) that allocates
- * its own `Store` tag, so `SyncedStore.live` is reusable beyond `SyncedStore`.
- */
 export interface StoreCarrier<A> {
   readonly store: Context.Tag<Store<A>, Store<A>>
 }
 
-export type AnySyncedStore = SyncedStoreClass<string, any>
+export type AnySyncedStore = SyncedStoreClass<string, AnyValue>
 export type SyncedValue<S> = S extends SyncedStoreClass<string, infer A> ? A : never
 
-/**
- * Define an externally-synced slice: a reflectable manifest + an internal store
- * tag, yieldable to its current value and usable as a calc/composition `Source`.
- * Carries no source — that is supplied at wiring time by `SyncedStore.live`,
- * exactly as `State.make` defers its seed to `State.live`.
- */
 export const make = <const N extends string, A>(
   name: N,
-  schema: Schema.Schema<A, any>,
+  schema: AnySchema<A>,
   options: StateOptions = {},
 ): SyncedStoreClass<N, A> => {
   const store = Context.GenericTag<Store<A>, Store<A>>(`reform/syncedStore/${name}`)
@@ -81,14 +54,6 @@ export const make = <const N extends string, A>(
   return yieldableClass(read, { manifest, store, name })
 }
 
-/**
- * Allocate a synced store's backing cell and bind it to an external source.
- * `acquire` yields the source within the layer's scope (so it can open a live
- * query / subscription whose `R` — e.g. a `Db` driver — is captured here); the
- * store mirrors `snapshot()` and re-notifies on every `subscribe` change through
- * the runtime's coalescing scheduler. The upstream subscription is released with
- * the layer's scope.
- */
 export const live = <A, R>(
   def: StoreCarrier<A>,
   acquire: Effect.Effect<SyncedSource<A>, never, R>,

package/src/ui/node.ts

@@ -1,9 +1,3 @@
 import type { ReactNode } from 'react'
 
-/**
- * What a view renders. Reform targets React, so a node is a `ReactNode` — this
- * is a *type-only* dependency: core never imports the React runtime nor renders
- * anything itself (that is `@reform/react`). Typing it precisely lets the `.ui`
- * presentations author real JSX and lets slots be valid components.
- */
 export type Node = ReactNode

package/src/ui/trigger.ts

@@ -1,6 +1 @@
-/**
- * A handler handed to the UI: a plain callback. Calling it dispatches the event
- * (High priority) through the runtime. The UI never sees Effect — it just calls
- * `events.submit({ text })`.
- */
 export type Trigger<P> = (payload: P) => void

package/src/wire/tree.test.ts

@@ -13,9 +13,6 @@ const node = (id: string, over: Partial<WireNode> = {}): WireNode => ({
   ...over,
 })
 
-// `diff` / `apply` are a round trip: folding `diff(prev, next)` into `prev`
-// reconstructs `next` exactly, for any pair of trees.
-
 test('a fresh tree diffs to one upsert per node', () => {
   const next: WireTree = [node('a'), node('b', { parentId: 'a', slot: 'body' })]
   const patches = Wire.diff([], next)

package/src/wire/tree.ts

@@ -1,55 +1,24 @@
 import { Array, Match, Option, Order, Record as Rec } from 'effect'
 import { sort as sortArray } from 'effect/Array'
 
-/**
- * The serializable model of a rendered UI tree, and the pure diff/apply over it.
- *
- * This is the renderer-neutral heart of the remote transport (REMOTE_UI.md §3):
- * the server renders a scene to a `WireTree`, sends `diff(prev, next)` as
- * `WirePatch`es, and the client folds them back with `apply`. No React, no
- * Effect — pure data, so both ends and the proofs share one source of truth.
- */
-
-/**
- * A prop on a wire node: either an already-encoded data value, or a handle the
- * client invokes to fire the server-side trigger (resolved by the trigger
- * registry, REMOTE_UI.md §4). Streams, when added, become a third arm.
- */
 export type WireProp =
   | { readonly _tag: 'Data'; readonly name: string; readonly value: unknown }
   | { readonly _tag: 'Event'; readonly name: string; readonly handle: string }
 
-/** One rendered UI contract instance, identified stably across frames. The serializable
- * wire-boundary shape (hence the `ExternalApi` postfix; `null` is part of the JSON contract). */
 export interface WireNodeExternalApi {
-  /** Stable identity across renders — the unit of diffing. */
   readonly id: string
-  /** The UI contract name (`UiCapture.name`) the client looks up a presentation by. */
   readonly name: string
-  /** Parent node id, or `null` for a root. */
   readonly parentId: string | null
-  /** Order among siblings under the same parent. */
   readonly childIndex: number
-  /** The slot name this node fills in its parent, or `null` for a root / direct child. */
   readonly slot: string | null
-  /**
-   * The React `key` the parent gave this slot child (`createElement(slots.Row, { key })`),
-   * or `null` when none was set. It is the per-child identity a KEYED slot selects on: the
-   * client renders `<slots.Row slotKey={id} />` and the slot thunk picks the one wire child
-   * whose `key` matches, instead of rendering every child of that slot at every call site.
-   * Without it the client slot is render-all-children (correct for singleton slots, wrong for
-   * a list slot invoked once per item — it duplicates the whole list under each call).
-   */
   readonly key: string | null
   readonly props: ReadonlyArray<WireProp>
 }
 
-/** Public alias preserving the established name across the codebase. */
 export type WireNode = WireNodeExternalApi
 
 export type WireTree = ReadonlyArray<WireNode>
 
-/** A change to apply to a client's tree: upsert a node, or drop one by id. */
 export type WirePatch =
   | { readonly _tag: 'Upsert'; readonly node: WireNode }
   | { readonly _tag: 'Delete'; readonly id: string }
@@ -75,7 +44,6 @@ const recordsEqual = (left: Record<string, unknown>, right: Record<string, unkno
   )
 }
 
-/** Structural equality over serializable wire values (and the tagged props that carry them). */
 const deepEqual = ({ left, right }: EqualPair): boolean => {
   if (left === right) {
     return true
@@ -108,10 +76,6 @@ const isUnchanged = (node: WireNode, previousById: ReadonlyMap<string, WireNode>
   return previous !== undefined && nodesEqual(previous, node)
 }
 
-/**
- * The patches that turn `previous` into `next`. Deletes precede upserts so a
- * client never holds a child whose reparented slot was freed in the same frame.
- */
 export const diff = (previous: WireTree, next: WireTree): ReadonlyArray<WirePatch> => {
   const previousById = new Map(previous.map((node) => [node.id, node]))
   const nextById = new Map(next.map((node) => [node.id, node]))
@@ -136,7 +100,6 @@ const upsertNode = (state: WireTree, node: WireNode): WireTree =>
     },
   )
 
-/** Fold patches into a client's tree (the receiving side's reducer). */
 export const apply = (state: WireTree, patches: ReadonlyArray<WirePatch>): WireTree =>
   patches.reduce(
     (current, patch) =>
@@ -150,14 +113,12 @@ export const apply = (state: WireTree, patches: ReadonlyArray<WirePatch>): WireT
 
 const bySiblingOrder = Order.mapInput(Order.number, (node: WireNode) => node.childIndex)
 
-/** The root nodes of a tree, in sibling order. */
 export const roots = (tree: WireTree): WireTree =>
   sortArray(
     tree.filter((node) => node.parentId === null),
     bySiblingOrder,
   )
 
-/** The children of a node, in sibling order. */
 export const childrenOf = (tree: WireTree, parentId: string): WireTree =>
   sortArray(
     tree.filter((node) => node.parentId === parentId),

package/src/wire/triggers.test.ts

@@ -5,10 +5,6 @@ import type { Trigger } from '../index'
 
 const ByPayload = S.Struct({ by: S.Number })
 
-// The registry holds a live trigger behind a caller-provided handle, decodes the
-// wire payload through the contract's event schema, and fires — never shipping a
-// function, and validating at the seam.
-
 test('re-registering a handle overwrites it with the fresh trigger', () => {
   const seen = Effect.runSync(
     Effect.gen(function* () {

package/src/wire/triggers.ts

@@ -1,29 +1,12 @@
 import { type Cause, Context, Data, Effect, Layer, type ParseResult, Ref, Schema } from 'effect'
 import type { Trigger } from '../ui/trigger'
-
-/**
- * The server-side bridge for trigger handles (REMOTE_UI.md §4). A rendered
- * `WireProp` of `_tag: 'Event'` carries a `handle`; the client invokes it by
- * sending `(handle, encodedPayload)`. Here we hold the live `Trigger` and its
- * payload schema, decode the wire payload, and fire — so the UI never ships a
- * function, only a handle, and the payload is validated at the seam.
- *
- * Handles are caller-provided keys, by convention `${nodeId}:${eventName}`: a
- * re-render re-`register`s the same handle with that frame's fresh trigger, so the
- * handle is stable across frames (the client's in-flight handle stays valid) and
- * the handle space never grows. The schema is the contract's own per-event wire
- * schema (`WiredUiManifest.events`, Phase 1) — the single source of truth for the
- * UI boundary, decoupled from which `Event` the composition binds behind it.
- */
+import type { AnySchema, AnyValue } from '../internal/variance'
 
 export type TriggerHandle = string
 
-// `any` in the schema/trigger slots is the documented Schema-variance escape
-// (same reason as `CompositionConfig.props`); only the registrar's call site,
-// where the trigger and its schema agree, sees the precise type.
 interface TriggerEntry {
-  readonly trigger: Trigger<any>
-  readonly schema: Schema.Schema<any, any>
+  readonly trigger: Trigger<AnyValue>
+  readonly schema: Schema.Schema.AnyNoContext
 }
 
 const UnknownTriggerBase: new (args: { readonly handle: TriggerHandle }) => Cause.YieldableError & {
@@ -32,7 +15,6 @@ const UnknownTriggerBase: new (args: { readonly handle: TriggerHandle }) => Caus
   readonly handle: TriggerHandle
 }>
 
-/** A wire message named a trigger handle the server no longer holds (a stale client). */
 export class UnknownTrigger extends UnknownTriggerBase {
   override get message(): string {
     return `reform: no trigger registered under handle '${this.handle}'`
@@ -40,18 +22,15 @@ export class UnknownTrigger extends UnknownTriggerBase {
 }
 
 export interface TriggerRegistryApi {
-  /** Register (or overwrite) a trigger + its payload schema under a handle key. */
   readonly register: <P>(
     handle: TriggerHandle,
     trigger: Trigger<P>,
-    schema: Schema.Schema<P, any>,
+    schema: AnySchema<P>,
   ) => Effect.Effect<void>
-  /** Decode an encoded payload via the handle's schema and fire the trigger. */
   readonly invoke: (
     handle: TriggerHandle,
     encodedPayload: unknown,
   ) => Effect.Effect<void, UnknownTrigger | ParseResult.ParseError>
-  /** Drop a handle once its node unmounts (the Phase 2 tree diff signals it). */
   readonly revoke: (handle: TriggerHandle) => Effect.Effect<void>
 }
 
@@ -69,7 +48,7 @@ export const make: Effect.Effect<TriggerRegistryApi> = Effect.gen(function* () {
   const register = <P>(
     handle: TriggerHandle,
     trigger: Trigger<P>,
-    schema: Schema.Schema<P, any>,
+    schema: AnySchema<P>,
   ): Effect.Effect<void> =>
     Ref.update(entries, (map) => new Map(map).set(handle, { trigger, schema }))
 
@@ -95,5 +74,4 @@ export const make: Effect.Effect<TriggerRegistryApi> = Effect.gen(function* () {
   return { register, invoke, revoke }
 })
 
-/** Provide a fresh registry — one per remote connection (each client gets its own handle space). */
 export const layer: Layer.Layer<TriggerRegistry> = Layer.effect(TriggerRegistry, make)