@playfast/reform 0.0.8 → 0.0.10

package/src/compose/structure.ts

@@ -0,0 +1,145 @@
+import type { SlotProps } from './slot'
+import type { EventsOf, UiContract } from './ui'
+
+/**
+ * Structure-as-data (the headless-structure keystone). A composition's logic
+ * body returns this *value* instead of a React node: pure, serializable data that
+ * describes — for this frame — the composition's own props and, per declared slot,
+ * how that slot is filled (a list / a singleton / absent). The engine, the wire
+ * server, and the proof harness consume this directly, so none of them needs to
+ * evaluate a view or import React to discover structure. Presentation (React)
+ * resolves a contract's markup separately, by name, on a host.
+ *
+ * `live` accepts BOTH a `Node` (legacy view body) and a `Structure` during the
+ * migration; hosts discriminate at runtime via {@link isStructure}.
+ */
+
+/** A list slot fill: one keyed entry per item. `key` is the SINGLE source of both
+ *  the wire `key` and the per-item `StateFamily` key — they can no longer drift. */
+export interface EachFill<P> {
+  readonly _tag: 'Each'
+  readonly items: ReadonlyArray<{ readonly key: string; readonly props: P }>
+}
+
+/** A singleton slot fill — the slot renders exactly one child with these props. */
+export interface OneFill<P> {
+  readonly _tag: 'One'
+  readonly props: P
+}
+
+/** A slot that renders nothing this frame (the data-driven analog of `cond && …`). */
+export interface AbsentFill {
+  readonly _tag: 'Absent'
+}
+
+/** How one declared slot is filled this frame, typed by the child's external props. */
+export type SlotFill<P> = EachFill<P> | OneFill<P> | AbsentFill
+
+/** The per-slot fill map a contract's structure carries — one fill per declared slot,
+ *  each typed by that child composition's external props (`SlotProps`). Empty when the
+ *  contract declares no slots. */
+export type StructureSlots<C extends UiContract> = C extends {
+  slots: infer S
+}
+  ? { readonly [K in keyof S]: SlotFill<SlotProps<S[K]>> }
+  : Record<never, never>
+
+/**
+ * The data a composition's logic returns for one frame: its computed props plus,
+ * for every declared slot, a fill description. Strict against the contract — props
+ * must match, and every declared slot must be filled (use {@link when} for
+ * conditional presence). Carries the child's contract per slot (via `SlotProps`),
+ * so consumers can select and descend into sub-compositions type-safely.
+ *
+ * `events` rides ON the structure: because a `mount(...)`-returning body never
+ * calls its view, the event triggers it acquired (`yield* Event.trigger(X)`) are
+ * no longer captured by a view's `CaptureSink` record — they must travel with the
+ * frame so hosts can register them (proof `actions`, the wire `TriggerRegistry`,
+ * the react presentation `events` arg). Triggers are functions, so `events` is NOT
+ * serializable and is intentionally excluded from {@link structureEquals}. Typed to
+ * the contract's event map; omit it (defaults to `{}`) when the contract has none.
+ */
+export interface Structure<C extends UiContract> {
+  readonly props: C['props']
+  readonly slots: StructureSlots<C>
+  readonly events?: EventsOf<C>
+}
+
+/** Runtime brand distinguishing a `Structure` value from a React `Node` (added by
+ *  {@link mount}; the authoring TYPE intentionally omits it so structure literals stay
+ *  plain). */
+export const StructureTypeId: unique symbol = Symbol.for('reform/Structure')
+export type StructureTypeId = typeof StructureTypeId
+
+/**
+ * Assemble a frame's structure, checked against the contract `C`. Identity at
+ * runtime apart from stamping the {@link StructureTypeId} brand; its real job is
+ * the compile-time contract check. `C` is recovered from the surrounding `live`
+ * body's return type (contextual typing), so call sites read `mount({ props, slots })`.
+ * A leaf composition (no declared slots) passes `slots: {}`. `events` defaults to an
+ * empty map when omitted, so a frame always carries an `events` record for hosts.
+ */
+export const mount = <C extends UiContract>(structure: Structure<C>): Structure<C> =>
+  Object.assign({ [StructureTypeId]: StructureTypeId, events: {} }, structure)
+
+/**
+ * A list slot fill. `key` derives the stable identity for BOTH the wire node and
+ * the per-item state family — passing the same id source to both is no longer
+ * possible to get wrong. `props` maps each item to the child's external props.
+ */
+export const each = <T, P>(
+  collection: Iterable<T>,
+  options: { readonly key: (item: T) => string; readonly props: (item: T) => P },
+): EachFill<P> => ({
+  _tag: 'Each',
+  items: Array.from(collection, (item) => ({ key: options.key(item), props: options.props(item) })),
+})
+
+/** A singleton slot fill — render one child with these external props. */
+export const one = <P>(props: P): OneFill<P> => ({ _tag: 'One', props })
+
+/** The shared empty fill — a slot that renders nothing this frame. */
+export const absent: AbsentFill = { _tag: 'Absent' }
+
+/** Conditional presence: the fill when `cond`, otherwise {@link absent}. */
+export const when = <F extends SlotFill<unknown>>(cond: boolean, fill: F): F | AbsentFill =>
+  cond ? fill : absent
+
+/** Whether a frame value is a `Structure` (vs a legacy React `Node`). The runtime
+ *  discriminator hosts use during the migration, replacing React's `isValidElement`. */
+export const isStructure = (frame: unknown): frame is Structure<UiContract> =>
+  typeof frame === 'object' && frame !== null && StructureTypeId in frame
+
+/** Whether a value is a plain record (not an array) — narrows for the deep compare
+ *  below without a cast. */
+const isRecord = (u: unknown): u is Record<string, unknown> =>
+  typeof u === 'object' && u !== null && !Array.isArray(u)
+
+/** Minimal structural deep-equality for serializable shapes (plain JSON — the
+ *  UI-contract guarantee). Avoids a heavyweight dep for the settle comparison. */
+const deepEquals = (a: unknown, b: unknown): boolean => {
+  if (Object.is(a, b)) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, index) => deepEquals(item, b[index]))
+  }
+  if (isRecord(a) && isRecord(b)) {
+    const aKeys = Object.keys(a)
+    const bKeys = Object.keys(b)
+    return (
+      aKeys.length === bKeys.length &&
+      aKeys.every(
+        (key) => Object.prototype.hasOwnProperty.call(b, key) && deepEquals(a[key], b[key]),
+      )
+    )
+  }
+  return false
+}
+
+/** Structural equality over two structures — props and every slot fill compared by
+ *  value. `events` is intentionally excluded: triggers are functions, freshly
+ *  acquired each render, so comparing them by identity would never match and would
+ *  break the settle fixpoint. The `StructureTypeId` brand is a symbol key, so
+ *  `Object.keys` skips it. Used by the proof/server settle loop to detect a
+ *  two-frame fixpoint. */
+export const structureEquals = (a: Structure<UiContract>, b: Structure<UiContract>): boolean =>
+  deepEquals(a.props, b.props) && deepEquals(a.slots, b.slots)

package/src/compose/ui.test.ts

@@ -1,8 +1,6 @@
 import { expect, test } from 'vitest'
-import { Effect, Schema as S } from 'effect'
-import { Ui, isUi, ui } from '../index'
-import { CaptureSink, type UiCapture } from '../internal/capture'
-import type { Trigger } from '../ui/trigger'
+import { Schema as S } from 'effect'
+import { isUi, ui } from '../index'
 
 // `ui` has two authoring forms with one source of truth each: the type-only form
 // (local, no schema) and the schema form (wired, the type is *derived*). Both are
@@ -34,29 +32,3 @@ test('schema `ui` with no events omits the events schema', () => {
   expect(S.isSchema(TitleUi.manifest.props)).toBe(true)
   expect(TitleUi.manifest.events).toBeUndefined()
 })
-
-test('a contract resolves its presentation and reports to a capturing sink', () => {
-  class CounterUi extends ui('Counter', {
-    props: S.Struct({ count: S.Number }),
-    events: { bump: S.Struct({ by: S.Number }) },
-  }) {}
-
-  const view = Ui.make(CounterUi, ({ count }) => `count:${count}`)
-  const records: UiCapture[] = []
-  const sink = { record: (capture: UiCapture): void => void records.push(capture) }
-
-  const logicView = Effect.runSync(
-    CounterUi.pipe(
-      Effect.provideService(CounterUi.impl, view),
-      Effect.provideService(CaptureSink, sink),
-    ),
-  )
-
-  const bump: Trigger<{ by: number }> = () => {}
-  const node = logicView({ count: 3 }, { bump })
-
-  expect(node).toBe('count:3')
-  expect(records).toHaveLength(1)
-  expect(records[0]?.name).toBe('Counter')
-  expect(records[0]?.props).toEqual({ count: 3 })
-})

package/src/compose/ui.ts

@@ -1,10 +1,7 @@
 import type { FunctionComponent } from 'react'
-import { Context, Effect, Option, type Schema } from 'effect'
-import { type Manifest, yieldableClass } from '../definition/definition'
-import { CaptureSink } from '../internal/capture'
-import { SlotRenderingUnavailable } from '../internal/errors'
+import { Context, type Schema } from 'effect'
+import { type Manifest, definitionClass } from '../definition/definition'
 import type { Trigger } from '../ui/trigger'
-import { CurrentSlots } from './host'
 import { type Node, type SlotClass, type SlotInstance, type SlotProps } from './slot'
 
 export interface UiContract {
@@ -14,7 +11,10 @@ export interface UiContract {
 }
 
 type PropsOf<C extends UiContract> = C['props']
-type EventsOf<C extends UiContract> = C extends { events: infer E } ? E : Record<never, never>
+/** The contract's event map (`{ [name]: Trigger<P> }`), or empty when it declares
+ *  none. Exported so a `Structure<C>` can type its optional `events` field to the
+ *  same map a composition body acquires. */
+export type EventsOf<C extends UiContract> = C extends { events: infer E } ? E : Record<never, never>
 // A slot is a React COMPONENT whose props are OPTIONAL (a `Partial`): a parent that
 // drives a child supplies them (`<slots.Item id=… />` / `createElement(slots.Item, {…})`),
 // but a placeholder render (the remote client, where the per-child props were captured
@@ -35,15 +35,18 @@ type SlotsOf<C extends UiContract> = C extends { slots: infer S }
       // child props are `any` the whole thing still collapses to `any` (`any & X = any`), keeping
       // the component assignable to a bare `(props: unknown) => Node` slot-renderer shape. An
       // outer intersection would leave a required-shape object that `unknown` can't satisfy.
+      //
+      // A slot handle is BOTH renderable (the `FunctionComponent` — places the keyed children)
+      // AND inspectable (`.props` — the array of per-child fill props the structure carried, one
+      // entry per mounted child, typed by the child contract). A presentation can read the fills
+      // (`slots.Item.props.length`, a header, layout decisions) and still render them
+      // (`<slots.Item/>`); it never DERIVES multiplicity — the engine already fixed it. Read-only.
       readonly [K in keyof S]: FunctionComponent<
         Partial<SlotProps<S[K]> & { readonly slotKey?: string }>
-      >
+      > & { readonly props: ReadonlyArray<SlotProps<S[K]>> }
     }
   : Record<never, never>
 
-/** What the composition logic calls: props + handlers in, a node out. Slots are bound by the renderer. */
-export type LogicView<C extends UiContract> = (props: PropsOf<C>, events?: EventsOf<C>) => Node
-
 /** What `.make` authors: the pure presentation. Slots are injected by the renderer. */
 export type ViewImpl<C extends UiContract> = (
   props: PropsOf<C>,
@@ -73,8 +76,9 @@ export interface WiredUiManifest extends UiManifest {
   readonly props: Schema.Schema<any, any>
 }
 
-export interface UiClass<C extends UiContract>
-  extends Effect.Effect<LogicView<C>, never, ViewImpl<C>> {
+// A branded, extendable class carrying the wire `manifest` + the DI `impl` tag. Not
+// yieldable: bodies return a `Structure`, and the host reads `impl` to resolve the view.
+export interface UiClass<C extends UiContract> {
   new (): {}
   readonly [UiTypeId]: UiTypeId
   readonly manifest: UiManifest
@@ -144,34 +148,9 @@ const buildUi = <C extends UiContract, M extends UiManifest>(
   manifest: M,
 ): UiClass<C> & { readonly manifest: M } => {
   const impl = Context.GenericTag<ViewImpl<C>, ViewImpl<C>>(`reform/ui/${name}`)
-  const read = Effect.gen(function* () {
-    const render = yield* impl
-    // Slots are bound by the host (`@reform/react`) per composition instance.
-    // Core has no renderer, so without a host every slot access throws.
-    const host = yield* Effect.serviceOption(CurrentSlots)
-    const slots = new Proxy({} as SlotsOf<C>, {
-      get(_t, key) {
-        if (Option.isNone(host)) {
-          throw new SlotRenderingUnavailable({ slot: String(key) })
-        }
-        return host.value.slot(String(key))
-      },
-    })
-    // A capturing host (proofs, the dev tool) reports each render's observable
-    // surface without replacing the presentation. Absent in production.
-    const sink = yield* Effect.serviceOption(CaptureSink)
-    return (props: PropsOf<C>, events?: EventsOf<C>) => {
-      if (Option.isSome(sink)) {
-        sink.value.record({
-          name,
-          props,
-          events: (events ?? {}) as Record<string, Trigger<unknown>>,
-        })
-      }
-      return render(props, slots, (events ?? {}) as EventsOf<C>)
-    }
-  })
-  return yieldableClass(read, {
+  // Extendable definition class (`class Counter extends ui('Counter', …) {}`); resolved
+  // by name on a host via `impl`, never yielded.
+  return definitionClass<UiClass<C> & { readonly manifest: M }>({
     [UiTypeId]: UiTypeId,
     manifest,
     impl,
@@ -179,9 +158,8 @@ const buildUi = <C extends UiContract, M extends UiManifest>(
 }
 
 /**
- * A renderer-neutral UI contract. The logic resolves it (`yield* TodoAppUi`) to
- * a `(props, events) => node` view with slots already bound; `.make` authors the
- * presentation. Core defines the contract; `@reform/react` does the rendering.
+ * A renderer-neutral UI contract: `.make` authors the presentation, a composition
+ * names it, and `@reform/react` resolves it to a view. Core defines the contract.
  *
  * Two authoring forms, one source of truth each:
  *

package/src/index.ts

@@ -31,6 +31,23 @@ export {
   type AsyncLoading,
   type AsyncSuccess,
 } from './calc/asyncData'
+// The flat, data-oriented query value (`data`/`error`/`isFetching`/`isStale`) an
+// `AsyncCalc` is driven by; `toAsyncData` projects it onto the matchable arms.
+export { isLoading, type QueryState, toAsyncData } from './calc/queryState'
+// Optional host seams an `AsyncCalc` consults — persistence and lifecycle signals.
+// Concrete implementations live in edge packages (e.g. `@playfast/reform-query-browser`).
+export {
+  noopQueryStore,
+  QueryStore,
+  type QueryStoreApi,
+  resolveQueryStore,
+} from './internal/queryStore'
+export {
+  noopQueryEvents,
+  QueryEvents,
+  type QueryEventsApi,
+  resolveQueryEvents,
+} from './internal/queryEvents'
 export * as RemoteState from './remote/remoteState'
 // Direct type re-exports alongside the namespace (TS2742 nameability): an app
 // layer's inferred type references these (`Store<ReadonlyArray<PendingIntent<…>>>`),
@@ -56,8 +73,25 @@ export * as Composition from './compose/composition'
 export type {
   CompositionClass,
   CompositionService,
+  Frame,
   RenderEnv,
 } from './compose/composition'
+export {
+  absent,
+  each,
+  type EachFill,
+  isStructure,
+  mount,
+  one,
+  type OneFill,
+  type AbsentFill,
+  type SlotFill,
+  type Structure,
+  structureEquals,
+  type StructureSlots,
+  StructureTypeId,
+  when,
+} from './compose/structure'
 export { Props } from './compose/props'
 export {
   isSlot,
@@ -68,12 +102,11 @@ export {
   type SlotProps,
   SlotTypeId,
 } from './compose/slot'
-export { CurrentSlots, type SlotHost } from './compose/host'
+export { type SlotRenderer } from './compose/host'
 export * as Ui from './compose/ui'
 export {
   type DerivedContract,
   isUi,
-  type LogicView,
   type MadeView,
   ui,
   type UiClass,
@@ -130,10 +163,14 @@ export { type SlotChild } from './compose/slot'
 // A scene bundles a composition with the closed wiring that runs it — the single
 // handle the react host, proofs, and the dev tool all consume.
 export { isScene, type MountedServices, type Scene, scene, seedScene } from './scene/scene'
+export type { SeedsOf } from './state/stateGroup'
 
 // Runtime surface for hosts (`@reform/react`) and headless tests.
 export { Bus, type Envelope, type Priority, publish, type Tagged } from './runtime/bus'
 export { Engine, type ReducerEntry, Reducers } from './runtime/loop'
+// The runtime-wide registry of live query handles. `AsyncCalc.invalidate` /
+// `AsyncCalc.refetch` and provider layers act on a query by name through it.
+export { Queries, type QueryHandle, type QueryRegistry } from './runtime/queries'
 export {
   type ChannelClass,
   type ChannelPolicy,
@@ -151,7 +188,6 @@ export {
   FeatureLoadFailed,
   forceSync,
   InvalidProvideTarget,
-  SlotRenderingUnavailable,
   UnknownGroupState,
 } from './internal/errors'
 // Notification scheduler: hosts that need per-runtime isolation (concurrent SSR,

package/src/internal/capture.ts

@@ -10,6 +10,14 @@ export interface UiCapture {
   readonly name: string
   readonly props: unknown
   readonly events: Record<string, Trigger<unknown>>
+  /**
+   * The stable slot-fill key this render was mounted under (an `each` item's
+   * `key`, or a synthesized singleton key for a `one`). Present only on the
+   * structure path — the legacy Node path defers slot expansion to host
+   * components and has no fill key, so it is omitted there. Lets the proof
+   * facade select a child by key (`byKey`) instead of by render index.
+   */
+  readonly key?: string
 }
 
 /** Where captured renders are reported, when a capturing host is present. */

package/src/internal/errors.ts

@@ -19,18 +19,6 @@ type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = n
 /** The fieldless variant — a `Data.TaggedError(tag)<{}>` constructor. */
 type EmptyTaggedErrorClass<Tag extends string> = new () => Cause.YieldableError & { readonly _tag: Tag }
 
-const SlotRenderingUnavailableBase: TaggedErrorClass<
-  'reform/SlotRenderingUnavailable',
-  { readonly slot: string }
-> = Data.TaggedError('reform/SlotRenderingUnavailable')<{ readonly slot: string }>
-
-/** A `<slots.X/>` was rendered without a render-target host to realize it. */
-export class SlotRenderingUnavailable extends SlotRenderingUnavailableBase {
-  override get message(): string {
-    return `reform: rendering slot '${this.slot}' requires @reform/react`
-  }
-}
-
 const InvalidProvideTargetBase: EmptyTaggedErrorClass<'reform/InvalidProvideTarget'> =
   Data.TaggedError('reform/InvalidProvideTarget')<{}>