@playfast/reform 0.1.0 → 1.1.1

package/src/state/stateFamily.ts

@@ -1,47 +1,23 @@
-import { Context, Effect, Layer, Option, type Schema } from 'effect'
+import { Context, Effect, Layer, Option } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
 import { resolveScheduler, type Scheduler } from '../internal/scheduler'
 import { claimStateTag } from '../internal/stateRegistry'
+import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 import { makeStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
+import type { AnySchema, AnyValue } from '../internal/variance'
 
-/**
- * A reducer fold returns this to evict the key it folded over, instead of a new
- * value. The loop drops the entry's store from the family, so a normalized
- * collection (chat messages, search hits, transient rows) does not grow without
- * bound — the one fix for the otherwise-unbounded per-key `Map`.
- */
 export const Tombstone: unique symbol = Symbol.for('reform/StateFamily/Tombstone')
 export type Tombstone = typeof Tombstone
 
-/** Per-key stores, created lazily so a write to one key wakes only its subscribers. */
 export interface FamilyStore<K, V> {
   at(key: K): Store<V>
-  /**
-   * Drop a key's store so it stops occupying memory. A live subscriber keeps its
-   * own closure over the previous store, so eviction is for keys whose entity is
-   * gone (the component is unmounting) — re-`at`-ing the key allocates a fresh,
-   * reseeded store.
-   */
   forget(key: K): void
-  /** Drop every key's store — a wholesale reset of the family. */
   clear(): void
-  /** Number of live keys — for tests/diagnostics. */
   size(): number
 }
 
-/** Options for a family's keyed store. */
 export interface FamilyOptionsExternalApi {
-  /**
-   * Drop a key's store automatically once it has no live subscribers (checked on
-   * the next microtask, so a same-commit re-subscribe — e.g. a key that just moved
-   * position in a list — cancels the eviction). This bounds an otherwise-unbounded
-   * family without explicit `Tombstone`s, but it also DISCARDS the key's value —
-   * re-`at`-ing a dropped key reseeds from `initial`. Use only for keys whose value
-   * is disposable when nothing renders them (search hits, transient rows); for a
-   * source-of-truth entity that may be temporarily off-screen (a virtualized list),
-   * keep this off and reclaim with an explicit reducer `Tombstone`. Default: off.
-   */
   readonly evictWhenUnused?: boolean
 }
 export type FamilyOptions = FamilyOptionsExternalApi
@@ -50,17 +26,14 @@ const makeFamilyStore = <K, V>(
   seed: (key: K) => V,
   scheduler: Scheduler,
   options: FamilyOptions = {},
+  onChange: () => void = () => {},
 ): FamilyStore<K, V> => {
   const entries = new Map<K, Store<V>>()
   const evictWhenUnused = options.evictWhenUnused === true
-  // Live subscriber count per key — maintained only when eviction is on.
   const subscribers = new Map<K, number>()
   const liveSubscriberCount = (key: K): number =>
     Option.getOrElse(Option.fromNullable(subscribers.get(key)), () => 0)
 
-  // Wrap a store's `subscribe` to ref-count, evicting the key when it falls idle.
-  // `get`/`set`/`getVersion` are delegated unchanged, so the loop writes and the
-  // host reads see the same cell; only subscribe/unsubscribe are instrumented.
   const refCounted = (key: K, store: Store<V>): Store<V> => ({
     ...store,
     subscribe: (listener) => {
@@ -94,7 +67,7 @@ const makeFamilyStore = <K, V>(
       if (existing !== undefined) {
         return existing
       }
-      const base = makeStore(seed(key), scheduler)
+      const base = makeStore(seed(key), scheduler, onChange)
       const created = evictWhenUnused ? refCounted(key, base) : base
       entries.set(key, created)
       return created
@@ -114,28 +87,23 @@ const makeFamilyStore = <K, V>(
 export interface StateFamilyManifestExternalApi<N extends string, K, V> extends Manifest {
   readonly kind: 'StateFamily'
   readonly name: N
-  readonly key: Schema.Schema<K, any>
-  readonly value: Schema.Schema<V, any>
+  readonly key: AnySchema<K>
+  readonly value: AnySchema<V>
   readonly title?: string
   readonly description?: string
 }
 export type StateFamilyManifest<N extends string, K, V> = StateFamilyManifestExternalApi<N, K, V>
 
 export interface StateFamilyClass<out N extends string, in out K, in out V> {
-  /** Instance carries the key phantom so `Family['Key']` resolves in `keyOf` types. */
   new (): { readonly Key: K }
   readonly manifest: StateFamilyManifest<N, K, V>
   readonly store: Context.Tag<FamilyStore<K, V>, FamilyStore<K, V>>
 }
 
-export type AnyFamily = StateFamilyClass<string, any, any>
-export type FamilyKey<F> = F extends StateFamilyClass<any, infer K, any> ? K : never
-export type FamilyValue<F> = F extends StateFamilyClass<any, any, infer V> ? V : never
+export type AnyFamily = StateFamilyClass<string, AnyValue, AnyValue>
+export type FamilyKey<F> = F extends StateFamilyClass<string, infer K, AnyValue> ? K : never
+export type FamilyValue<F> = F extends StateFamilyClass<string, AnyValue, infer V> ? V : never
 
-/**
- * Normalized keyed state: one logical State per key, backed by a single family
- * store. Scales with the collection without re-rendering unrelated entries.
- */
 export interface StateFamilyMakeOptionsExternalApi {
   readonly title?: string
   readonly description?: string
@@ -143,8 +111,8 @@ export interface StateFamilyMakeOptionsExternalApi {
 
 export const make = <const N extends string, K, V>(
   name: N,
-  key: Schema.Schema<K, any>,
-  valueSchema: Schema.Schema<V, any>,
+  key: AnySchema<K>,
+  valueSchema: AnySchema<V>,
   options: StateFamilyMakeOptionsExternalApi = {},
 ): StateFamilyClass<N, K, V> => {
   const identifier = `reform/family/${name}`
@@ -161,21 +129,12 @@ export const make = <const N extends string, K, V>(
   return definitionClass<StateFamilyClass<N, K, V>>({ manifest, store })
 }
 
-/**
- * Read one entry by key — `StateFamily.read(ItemUi, id)`. Inside a render it
- * subscribes that key's slice; elsewhere it just snapshots (D5).
- */
 export const read = <N extends string, K, V>(
   family: StateFamilyClass<N, K, V>,
   key: K,
 ): Effect.Effect<V, never, FamilyStore<K, V>> =>
   Effect.flatMap(family.store, (familyStore) => readTracked(familyStore.at(key)))
 
-/**
- * Allocate a family's keyed store — `StateFamily.live(ItemUi, seed)`. The seed
- * is a plain value or a factory; a factory receives the key, so a new entry can
- * derive its starting value from its own id (`(id) => ({ ...blank, id }))`).
- */
 export const live = <N extends string, K, V>(
   family: StateFamilyClass<N, K, V>,
   initial: V | ((key: K) => V),
@@ -185,6 +144,13 @@ export const live = <N extends string, K, V>(
   const seed: (key: K) => V = typeof initial === 'function' ? (initial as (key: K) => V) : () => initial
   return Layer.effect(
     family.store,
-    Effect.map(resolveScheduler, (scheduler) => makeFamilyStore<K, V>(seed, scheduler, options)),
+    Effect.zipWith(resolveScheduler, resolveInstrumentation, (scheduler, instrumentation) =>
+      makeFamilyStore<K, V>(
+        seed,
+        scheduler,
+        options,
+        stateUpdateHook(instrumentation, family.manifest.name),
+      ),
+    ),
   )
 }

package/src/state/stateGroup.ts

@@ -1,35 +1,23 @@
 import { Array as Arr, Layer, Option } from 'effect'
 import { definitionClass } from '../definition/definition'
 import { DuplicateRegistration, UnknownGroupState } from '../internal/errors'
-// A group's members each carry a `store` tag, so the shared `StoresOf` (used for
-// calc inputs too) distributes them into the union of distinct stores their
-// `live` layer provides — no group-specific mapped type needed.
 import { type StoresOf } from '../internal/sources'
 import { type AnyState, live as stateLive, type StateClass, type StateName } from './state'
 import { StateToken } from './token'
+import type { AnyValue } from '../internal/variance'
 
 type ValueForName<Members extends ReadonlyArray<AnyState>, N extends string> =
-  Extract<Members[number], StateClass<N, any>> extends StateClass<any, infer A> ? A : never
+  Extract<Members[number], StateClass<N, AnyValue>> extends StateClass<string, infer A> ? A : never
 
 export interface StateGroupClass<Members extends ReadonlyArray<AnyState>> {
   new (): {}
   readonly kind: 'StateGroup'
   readonly members: Members
-  /** Members indexed by name, so `select` is an O(1) lookup instead of a scan. */
   readonly byName: ReadonlyMap<string, AnyState>
 }
 
 export type AnyStateGroup = StateGroupClass<ReadonlyArray<AnyState>>
 
-/**
- * Compile-time uniqueness guard for `StateGroup.make`. Member names key the tag,
- * the seed record, `byName`, and `select` — duplicates are unaddressable, so a
- * repeated name is replaced (positionally) by this marker tuple, which a real
- * `StateClass` is not assignable to. The offending argument fails to typecheck
- * with the colliding name spelled out in the message, rather than collapsing
- * silently. Runtime `make` throws the same clash for seeds the root tsconfig
- * never typechecks (test files live outside it).
- */
 type DuplicateStateName<N extends string> = readonly ['reform: duplicate state name in group', N]
 
 type NoDuplicateNames<
@@ -42,41 +30,24 @@ type NoDuplicateNames<
     ]
   : readonly []
 
-// The seed record `StateGroup.live` requires: one entry per member, keyed by the
-// member's name and typed to that member's value (so a missing or mistyped seed
-// is a compile error). Written against the group class, so call sites read
-// `GroupSeeds<typeof TodosStates>`.
 export type GroupSeeds<G extends AnyStateGroup> =
   G extends StateGroupClass<infer Members>
     ? { readonly [N in StateName<Members[number]>]: ValueForName<Members, N> }
     : never
 
-// Collapse a union of records into their intersection — merges every group's
-// seed record into one. (The classic contravariant-position trick.)
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
   k: infer I,
 ) => void
   ? I
   : never
 
-/** The seed record for one tuple entry: a group's `GroupSeeds`, else nothing. */
 type EntrySeeds<G> = G extends AnyStateGroup ? GroupSeeds<G> : never
 
-/**
- * The optional seed overrides for a composition's whole `states` tuple, keyed by
- * member name and typed to each member's value. Every key is optional (seeds are
- * overrides over the authored initial). Tuple entries that aren't state groups
- * contribute no keys, so a partially-grouped `states` still types its groups.
- * Powers `seedScene` — a typo'd key or mistyped value is a compile error.
- */
 export type SeedsOf<St extends ReadonlyArray<unknown>> = Partial<UnionToIntersection<EntrySeeds<St[number]>>>
 
-/** Compose atomic States into a group provided (and addressed) as a unit. */
 export const make = <const Members extends ReadonlyArray<AnyState>>(
   ...members: Members & NoDuplicateNames<Members>
 ): StateGroupClass<Members> => {
-  // `byName` already de-dupes, so a smaller map than the member list means two
-  // members claimed one name — unaddressable, and a silent footgun on merge.
   const names = members.map((member) => member.manifest.name)
   const duplicate = Arr.findFirst(names, (name, index) =>
     Option.exists(
@@ -95,16 +66,6 @@ export const make = <const Members extends ReadonlyArray<AnyState>>(
   })
 }
 
-/**
- * Address a member by its tag — `StateGroup.select(TodosStates, 'feed')` —
- * yielding a `StateToken` for reads and calc inputs (still `yield*`-able).
- *
- * Data-first only (not `dual`): the member name's type depends on the group, and
- * a group is not `Pipeable`, so a data-last form would be both more verbose and
- * harder to type than the direct call. Effect reserves `dual` for operators on a
- * `Pipeable` self with an independent value arg (e.g. `ref.pipe(Ref.set(v))`);
- * this is not that shape.
- */
 export const select = <Members extends ReadonlyArray<AnyState>, N extends StateName<Members[number]>>(
   group: StateGroupClass<Members>,
   name: N,
@@ -117,18 +78,10 @@ export const select = <Members extends ReadonlyArray<AnyState>, N extends StateN
   return new StateToken(name, member.store)
 }
 
-/**
- * Allocate every member's store as one merged layer, each seeded from `seeds`
- * keyed by member name — `StateGroup.live(BoardStates, { board: { _tag: 'Idle' } })`.
- */
 export const live = <Members extends ReadonlyArray<AnyState>>(
   group: StateGroupClass<Members>,
   seeds: GroupSeeds<StateGroupClass<Members>>,
 ): Layer.Layer<StoresOf<Members>> => {
-  // Index the typed seed record by the member's runtime name — a genuine
-  // reflection boundary (string key into a mapped type). Each member's store
-  // layer is then merged; the union of stores is exactly `StoresOf<Members>`,
-  // which `reduce`'s single-layer accumulator can't express, so restate it.
   // oxlint-disable-next-line reform-rules/no-type-assertion -- reflection boundary: index a mapped seed type by runtime member name
   const seedRecord = seeds as Record<string, unknown>
   // oxlint-disable-next-line reform-rules/no-type-assertion -- union-of-stores Rout can't be expressed by reduce's single-layer accumulator

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)