@playfast/reform-proof 0.1.0 → 1.1.1

package/src/runtimeTreeSettle.ts

@@ -0,0 +1,34 @@
+import { Effect } from 'effect'
+import { SETTLE_MAX_RENDERS, SETTLE_STEP, settleDrain } from './sink'
+import type { SettleProgress } from './treeBindings'
+import type { TreeRenderState } from './runtimeTreeTypes'
+
+export const makeTreeSettle: (
+  render: () => TreeRenderState,
+) => Effect.Effect<void, never, never> = Effect.fn('makeTreeSettle')(function* (
+  render: () => TreeRenderState,
+): Effect.fn.Return<void, never, never> {
+    yield* settleDrain
+    const first = render()
+    yield* Effect.iterate(
+      {
+        previous: first.fingerprint,
+        remaining: SETTLE_MAX_RENDERS,
+        stable: false,
+      },
+      {
+        while: (progress: SettleProgress) => !progress.stable && progress.remaining > 0,
+        body: (progress) =>
+          Effect.gen(function* () {
+            yield* settleDrain
+            yield* Effect.sleep(SETTLE_STEP)
+            const current = render()
+            return {
+              previous: current.fingerprint,
+              remaining: progress.remaining - 1,
+              stable: current.fingerprint === progress.previous,
+            }
+          }),
+      },
+    )
+})

package/src/runtimeTreeTypes.ts

@@ -0,0 +1,99 @@
+import { Effect, Match, Option, Record as Rec } from 'effect'
+import {
+  type CompositionClass,
+  type FeatureBinding,
+  type RuntimeHandle,
+  type SlotFill,
+  type Trigger,
+} from '@playfast/reform'
+import type { MountedFacade } from './runtimeFacade'
+import { uiNameOf } from './sink'
+
+export type FeatureMountState =
+  | { readonly _tag: 'Loading' }
+  | { readonly _tag: 'Live'; readonly runtime: RuntimeHandle }
+  | { readonly _tag: 'Failed'; readonly error: unknown }
+
+export interface TreeFeatureMount {
+  readonly id: string
+  readonly binding: FeatureBinding
+  readonly parent: RuntimeHandle
+  readonly depth: number
+  readonly props: unknown
+  attempt: number
+  state: FeatureMountState
+  dispose: () => void
+}
+
+export interface TreeNode {
+  readonly path: string
+  readonly depth: number
+  readonly key: Option.Option<string>
+  readonly comp: CompositionClass<unknown>
+  readonly props: unknown
+  readonly events: Record<string, Trigger<unknown>>
+  readonly slots: Readonly<Record<string, ReadonlyArray<TreeNode>>>
+}
+
+export interface TreeRenderState {
+  readonly root: TreeNode
+  readonly fingerprint: string
+}
+
+export interface RuntimeTreeFacade {
+  readonly facade: MountedFacade
+  readonly settle: Effect.Effect<void, never, never>
+  dispose(): void
+}
+
+export interface TreeDriver {
+  readonly render: () => TreeRenderState
+  readonly settle: Effect.Effect<void, never, never>
+  readonly dispose: () => void
+}
+
+export interface MountIdentityInput {
+  readonly parent: RuntimeHandle
+  readonly parentPath: string
+  readonly slotName: string
+  readonly key: string
+  readonly binding: FeatureBinding
+}
+
+export interface FeatureRecordInput {
+  readonly id: string
+  readonly parent: RuntimeHandle
+  readonly binding: FeatureBinding
+  readonly depth: number
+  readonly props: unknown
+}
+
+export interface RenderCompositionInput {
+  readonly runtime: RuntimeHandle
+  readonly comp: CompositionClass<unknown>
+  readonly props: unknown
+  readonly key: Option.Option<string>
+  readonly path: string
+  readonly depth: number
+  readonly seen: Set<string>
+}
+
+export const encodeIdentityPart = (part: string): string => `${part.length}:${part}`
+
+export const fillEntries = (
+  slotName: string,
+  fill: SlotFill<unknown>,
+): ReadonlyArray<{ readonly key: string; readonly props: unknown }> =>
+  Match.value(fill).pipe(
+    Match.when({ _tag: 'Each' }, (each) => each.items),
+    Match.when({ _tag: 'One' }, (oneFill) => [{ key: `${slotName}.0`, props: oneFill.props }]),
+    Match.when({ _tag: 'Absent' }, () => []),
+    Match.exhaustive,
+  )
+
+export const treeFingerprint = (node: TreeNode): unknown => [
+  uiNameOf(node.comp),
+  node.key,
+  node.props,
+  Rec.map(node.slots, (children) => children.map(treeFingerprint)),
+]

package/src/sink.ts

@@ -0,0 +1,73 @@
+import { Effect, Layer, MutableRef } from 'effect'
+import {
+  Bus,
+  CaptureSink,
+  type CaptureSinkApi,
+  type CompositionClass,
+  type CompositionService,
+  type Instrumentation,
+  noopInstrumentation,
+  type Scene,
+  type SlotChild,
+  type Structure,
+  type Trigger,
+  type UiCapture,
+  type UiContract,
+} from '@playfast/reform'
+
+const SETTLE_DRAIN = 30
+export const SETTLE_STEP = '1 milli'
+export const SETTLE_MAX_RENDERS = 100
+
+export const settleDrain: Effect.Effect<void> = Effect.yieldNow().pipe(Effect.repeatN(SETTLE_DRAIN))
+
+export const keyed = <V>(get: (key: string) => V): Record<string, V> => {
+  const target: Record<string, V> = Object.create(null)
+  return new Proxy(target, { get: (_target, key) => get(String(key)) })
+}
+
+export const messageOf = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error)
+
+export const uiNameOf = (comp: CompositionClass<unknown>): string => comp.manifest.ui.manifest.name
+
+export const eventsOf = (structure: Structure<UiContract>): Record<string, Trigger<unknown>> => ({
+  ...structure.events,
+})
+
+export interface Sink {
+  readonly api: CaptureSinkApi
+  readonly captures: ReadonlyArray<UiCapture>
+  readonly instrumentation: Instrumentation
+  reset(): void
+}
+
+export const makeSink = (instrumentation: Instrumentation = noopInstrumentation): Sink => {
+  const captures = MutableRef.make<UiCapture[]>([])
+  return {
+    api: {
+      record: (capture) => {
+        MutableRef.update(captures, (current) => [...current, capture])
+      },
+    },
+    get captures() {
+      return MutableRef.get(captures)
+    },
+    instrumentation,
+    reset: () => {
+      MutableRef.set(captures, [])
+    },
+  }
+}
+
+export type RuntimeServices = CompositionService | SlotChild | Bus
+
+export const proofLayer = (scene: Scene, sink: Sink): Layer.Layer<RuntimeServices, never, never> => {
+  // oxlint-disable-next-line reform-rules/no-type-assertion -- the one erasure boundary: the scene's host-read `MountedServices` layer widens to the broader `RuntimeServices` a proof resolves
+  const sceneLayer = scene.provide.reduce((merged, layer) => Layer.merge(merged, layer)) as unknown as Layer.Layer<
+    RuntimeServices,
+    never,
+    never
+  >
+  return Layer.provideMerge(sceneLayer, Layer.succeed(CaptureSink, sink.api))
+}

package/src/structure-events.test.ts

@@ -16,15 +16,6 @@ import {
 import { describe, expect, test } from 'vitest'
 import { Product, Proof, ProductRequirement, expect as proofExpect } from './index'
 
-// Plan 03b — events ride ON the structure. A composition whose `live` body returns
-// `mount({ props, events })` never calls its view, so the event triggers it acquires
-// (`yield* Event.trigger(Bumped)`) are NOT captured by a view's CaptureSink — they
-// travel with the frame on `structure.events`. The proof engine's `driveStructure`
-// records them into the same capture the view path uses, so `app.actions.bump()`
-// resolves and settles identically for a Structure frame. This file is the only
-// runtime exercise of the structure EVENT path; the view path stays covered by
-// typed-seams.test.ts.
-
 class CountState extends State.make('scount', S.Number) {}
 class MiniStates extends StateGroup.make(CountState) {}
 class Bumped extends Event.make('SBumped', S.Struct({})) {}
@@ -41,8 +32,6 @@ class Counter extends Composition.make('SCounter', {
   events: [Bumped],
   ui: CounterUi,
 }) {}
-// Body returns a STRUCTURE carrying the bump trigger on `events` — the view is never
-// called, so the trigger must ride on the frame for the proof to resolve it.
 const CounterLive = Composition.live(Counter, function* () {
   const count = yield* StateGroup.select(MiniStates, 'scount')
   const bump = yield* Event.trigger(Bumped)

package/src/structure-locators.test.ts

@@ -16,15 +16,6 @@ import {
 import { describe, expect, test } from 'vitest'
 import { type Facade, Product, Proof, ProductRequirement, expect as proofExpect } from './index'
 
-// Plan 06 — typed recursive proof navigation. A list parent returns a STRUCTURE
-// whose `Item` slot is filled with `each`, so each child rides a stable `key` (the
-// SINGLE source of the wire key + family key). The proof facade selects a child by
-// that key (`byKey`), filters by computed props (`where`), and reads the fill length
-// (`count`) — all against the structure tree, no view evaluated. `byKey` returns a
-// facade still typed by the child contract, so `.expectProps` checks the CHILD's
-// props and `.slots` would keep descending type-safely.
-
-// A list of todos lives in state; the parent computes its props + the `each` fill.
 class TodosState extends State.make(
   'locTodos',
   S.Array(S.Struct({ id: S.String, done: S.Boolean })),
@@ -50,8 +41,6 @@ class List extends Composition.make('LocList', {
   ui: ListUi,
 }) {}
 
-// The parent body returns pure data: its own props, and the `Item` slot filled with
-// one keyed child per todo. No `.map`, no JSX — `each` owns multiplicity + key.
 const ListLive = Composition.live(List, function* () {
   const todos = yield* StateGroup.select(TodoStates, 'locTodos')
   return mount({
@@ -61,9 +50,6 @@ const ListLive = Composition.live(List, function* () {
     },
   })
 })
-// A leaf child in structure-as-data echoes the props its parent's `each` fed it
-// (read via the `Props` service), so the recorded capture carries the per-item
-// props `byKey`/`where`/`expectProps` assert against. No view, hook-free.
 const ItemLive = Composition.live(Item, function* () {
   const props: { id: string; done: boolean } = yield* Props
   return mount({ props, slots: {} })
@@ -94,18 +80,12 @@ class ListProduct extends Product.make(List, { requirements: [Locates] }) {}
 describe('typed recursive proof navigation (plan 06)', () => {
   test('byKey / where / count resolve children from the structure tree', async () => {
     const proof = Proof.implement(Locates, ListScene, function* (app) {
-      // The parent's computed props.
       yield* proofExpect((yield* app.props).total).toBe(3)
-      // count = the fill length.
       yield* proofExpect(yield* app.slots.Item.count).toBe(3)
-      // byKey selects the one child mounted under that `each` key; the facade is
-      // typed by the CHILD contract, so `expectProps` checks the child's props.
       const second = yield* app.slots.Item.byKey('todo-2')
       yield* second.expectProps({ id: 'todo-2', done: true })
       const first = yield* app.slots.Item.byKey('todo-1')
       yield* first.expectProps({ id: 'todo-1', done: false })
-      // where filters children by their computed props (predicate typed by the
-      // CHILD contract — `p.done` is known).
       const doneItems = yield* app.slots.Item.where((p) => p.done)
       yield* proofExpect(doneItems.length).toBe(1)
       yield* doneItems[0]!.expectProps({ id: 'todo-2' })
@@ -123,9 +103,6 @@ describe('typed recursive proof navigation (plan 06)', () => {
   })
 })
 
-// Type-only: the `byKey`-selected facade is typed by the Item CHILD contract
-// (`{ id, done }`) — recursive typed selection. A wrong prop key in `expectProps`
-// is a compile error. Non-exported, never called; exists only to be typechecked.
 const _negativeTypeCheck = (app: Facade<Ui.Contract<typeof ListUi>>): void => {
   Proof.implement(Locates, ListScene, function* () {
     const child = yield* app.slots.Item.byKey('todo-1')

package/src/treeBindings.ts

@@ -0,0 +1,121 @@
+import { Effect, Match, Option, Record as Rec } from 'effect'
+import {
+  type CompositionClass,
+  isFeatureBinding,
+  type SlotChild,
+  type SlotClass,
+  type SlotFill,
+  type Structure,
+  type UiContract,
+} from '@playfast/reform'
+import { eventsOf, type Sink, uiNameOf } from './sink'
+
+export interface Mounted {
+  readonly comp: CompositionClass<unknown>
+  readonly props: unknown
+  readonly key: Option.Option<string>
+}
+
+export interface NodeRef {
+  readonly name: string
+  readonly index: number
+}
+
+export interface SettleProgress {
+  readonly previous: string
+  readonly remaining: number
+  readonly stable: boolean
+}
+
+export interface PumpStep {
+  readonly input: unknown
+  readonly index: number
+}
+
+export const childComposition = (child: SlotChild): CompositionClass<unknown> =>
+  isFeatureBinding(child) ? child.composition : child
+
+export const slotsOf = (comp: CompositionClass<unknown>): Record<string, SlotClass> =>
+  Option.getOrElse(Option.fromNullable(comp.manifest.slots), () => ({}))
+
+const isSlotFill = (candidate: unknown): candidate is SlotFill<unknown> =>
+  typeof candidate === 'object' &&
+  candidate !== null &&
+  '_tag' in candidate &&
+  (candidate._tag === 'Each' || candidate._tag === 'One' || candidate._tag === 'Absent')
+
+export const structureFills = (
+  structure: Structure<UiContract>,
+): Record<string, SlotFill<unknown>> =>
+  Rec.fromEntries(
+    Rec.toEntries(structure.slots).flatMap(([slotName, fillValue]) =>
+      isSlotFill(fillValue) ? [[slotName, fillValue] as const] : [],
+    ),
+  )
+
+export const collectBindings: (
+  root: CompositionClass<unknown>,
+) => Effect.Effect<Map<SlotClass, CompositionClass<unknown>>, never, SlotChild> = Effect.fn(
+  'collectBindings',
+)(function* (
+  root: CompositionClass<unknown>,
+): Effect.fn.Return<Map<SlotClass, CompositionClass<unknown>>, never, SlotChild> {
+  const bindings = new Map<SlotClass, CompositionClass<unknown>>()
+  const walk: (comp: CompositionClass<unknown>) => Effect.Effect<void, never, SlotChild> = Effect.fn(
+    'collectBindings.walk',
+  )(function* (comp: CompositionClass<unknown>): Effect.fn.Return<void, never, SlotChild> {
+    yield* Effect.forEach(Rec.values(slotsOf(comp)), (slotClass) =>
+      Effect.gen(function* () {
+        if (bindings.has(slotClass)) {
+          return
+        }
+        const child = childComposition(yield* slotClass.tag)
+        bindings.set(slotClass, child)
+        yield* walk(child)
+      }),
+    )
+  })
+  yield* walk(root)
+  return bindings
+})
+
+const enqueueFill = (
+  slotName: string,
+  fill: SlotFill<unknown>,
+  child: CompositionClass<unknown>,
+): ReadonlyArray<Mounted> =>
+  Match.value(fill).pipe(
+    Match.when({ _tag: 'Each' }, (each) =>
+      each.items.map((entry) => ({
+        comp: child,
+        props: entry.props,
+        key: Option.some(entry.key),
+      })),
+    ),
+    Match.when({ _tag: 'One' }, (oneFill) => [
+      { comp: child, props: oneFill.props, key: Option.some(`${slotName}.0`) },
+    ]),
+    Match.when({ _tag: 'Absent' }, () => []),
+    Match.exhaustive,
+  )
+
+export const driveStructure = (
+  comp: CompositionClass<unknown>,
+  structure: Structure<UiContract>,
+  key: Option.Option<string>,
+  sink: Sink,
+  bindings: ReadonlyMap<SlotClass, CompositionClass<unknown>>,
+): ReadonlyArray<Mounted> => {
+  sink.api.record({
+    name: uiNameOf(comp),
+    props: structure.props,
+    events: eventsOf(structure),
+    ...(Option.isSome(key) ? { key: key.value } : {}),
+  })
+  const fills = structureFills(structure)
+  return Rec.toEntries(slotsOf(comp)).flatMap(([slotName, slotClass]) => {
+    const child = bindings.get(slotClass)
+    const fill = fills[slotName]
+    return child === undefined || fill === undefined ? [] : enqueueFill(slotName, fill, child)
+  })
+}

package/src/typed-seams.test.ts

@@ -18,23 +18,12 @@ import {
 import { describe, expect, test } from 'vitest'
 import { Product, Proof, ProductRequirement, expect as proofExpect } from './index'
 
-// Exercises the four type-safety seams closed in this change, each against a
-// self-contained mini Counter (the same fixture shape as the stepper test):
-//   #1 typed seeds       — seedScene is keyed/valued by the state tuple
-//   #2 action results    — an action resolves to the settled next props
-//   #4 typed assertions  — app.expectProps is a contract-typed subset match
-//   #5 event coverage     — a requirement's declared events must be dispatched
-// Negative cases are compile-time (`@ts-expect-error`) — the whole point is that
-// the bad input never reaches runtime.
-
 class CountState extends State.make('count', S.Number) {}
 class MiniStates extends StateGroup.make(CountState) {}
 class Bumped extends Event.make('Bumped', S.Struct({})) {}
 class BumpReducer extends Reducer.make('BumpReducer', { states: [CountState], events: [Bumped] }) {}
 const BumpReducerLive = Reducer.live(BumpReducer, (n) => n + 1)
 
-// A trivial slot child: a proof runtime resolves slot-bound compositions, so the
-// app needs at least one slot for the suite's provide layer to type-close.
 class LabelUi extends ui('Label')<{ props: { text: string } }>() {}
 class Label extends Composition.make('Label', { title: 'Label', ui: LabelUi }) {}
 const LabelLive = Composition.live(Label, function* () {