@playfast/reform-proof 1.2.0 → 1.2.1

package/src/engineTreeDriver.ts

@@ -0,0 +1,247 @@
+import { Effect, Match, Option, Record as Rec } from 'effect'
+import { isFeatureBinding } from '@playfast/reform'
+import { formatFingerprint } from './fingerprint'
+import {
+  eventsOf,
+  type HostRuntime,
+  renderCompositionRuntime,
+  SETTLE_MAX_RENDERS,
+  settleDrain,
+  settleStep,
+  type Sink,
+  uiNameOf,
+} from './engineSink'
+import type { AnyComposition } from '@playfast/reform/internal'
+import {
+  ensureSettled,
+  readRuntimeSlotChild,
+  type SettleProgress,
+  slotsOf,
+  structureFills,
+} from './engineTree'
+import { makeFeatureMountRegistry } from './engineMounts'
+import {
+  encodeIdentityPart,
+  fillEntries,
+  type RenderCompositionInput,
+  type TreeDriver,
+  type TreeNode,
+  type TreeRenderState,
+  treeFingerprint,
+} from './engineTreeTypes'
+
+export const makeTreeDriver = (
+  runtime: HostRuntime,
+  root: AnyComposition,
+  rootProps: unknown,
+  sink: Sink,
+): TreeDriver => {  const status = { disposed: false }
+  const registry = makeFeatureMountRegistry(status)
+  const { disposeStale, mountId, retryMount } = registry
+  const featureRecordForRender = registry.recordForRender
+
+  const renderComposition = ({
+    runtime: currentRuntime,
+    comp,
+    props,
+    key,
+    path,
+    depth,
+    seen,
+    mountMissing,
+  }: RenderCompositionInput): TreeNode => {
+    const endRenderSpan = sink.instrumentation.uiRendered(uiNameOf(comp))
+    const frame = renderCompositionRuntime(currentRuntime, comp, props)
+    endRenderSpan()
+    sink.api.record({
+      name: uiNameOf(comp),
+      props: frame.props,
+      events: eventsOf(frame),
+      ...(Option.isSome(key) ? { key: key.value } : {}),
+    })
+
+    const fills = structureFills(frame)
+    const renderedSlots = Rec.map(slotsOf(comp), (slotClass, slotName) => {
+      const fill = fills[slotName]
+      if (fill === undefined) {
+        return []
+      }
+      const child = readRuntimeSlotChild({
+        runtime: currentRuntime,
+        slotDefinition: slotClass,
+        parent: comp,
+      })
+      return fillEntries(slotName, fill).flatMap((entry) => {
+        const childPath = `${path}${encodeIdentityPart(slotName)}${encodeIdentityPart(entry.key)}`
+        if (!isFeatureBinding(child)) {
+          return [
+            renderComposition({
+              runtime: currentRuntime,
+              comp: child,
+              props: entry.props,
+              key: Option.some(entry.key),
+              path: childPath,
+              depth: depth + 1,
+              seen,
+              mountMissing,
+            }),
+          ]
+        }
+        const id = mountId({
+          parent: currentRuntime,
+          parentPath: path,
+          slotName,
+          key: entry.key,
+          binding: child,
+        })
+        seen.add(id)
+        const record = featureRecordForRender(
+          {
+            id,
+            parent: currentRuntime,
+            binding: child,
+            depth: depth + 1,
+            props: entry.props,
+          },
+          mountMissing,
+        )
+        if (record === undefined) {
+          return []
+        }
+        return child.capture<ReadonlyArray<TreeNode>>((binding) =>
+          Match.value(record.state).pipe(
+            Match.when({ _tag: 'Live' }, (live) => [
+              renderComposition({
+                runtime: live.runtime,
+                comp: binding.composition,
+                props: entry.props,
+                key: Option.some(entry.key),
+                path: childPath,
+                depth: depth + 1,
+                seen,
+                mountMissing,
+              }),
+            ]),
+            Match.when({ _tag: 'Failed' }, (failed) =>
+              Option.match(binding.placeholder, {
+                onNone: () => [],
+                onSome: (placeholder) => [
+                  renderComposition({
+                    runtime: currentRuntime,
+                    comp: placeholder.failed,
+                    props: {
+                      error: failed.error,
+                      retry: () => retryMount(record),
+                    },
+                    key: Option.some(entry.key),
+                    path: `${childPath}/failed`,
+                    depth: depth + 1,
+                    seen,
+                    mountMissing,
+                  }),
+                ],
+              }),
+            ),
+            Match.when({ _tag: 'Loading' }, () =>
+              Option.match(binding.placeholder, {
+                onNone: () => [],
+                onSome: (placeholder) => [
+                  renderComposition({
+                    runtime: currentRuntime,
+                    comp: placeholder.loading,
+                    props: entry.props,
+                    key: Option.some(entry.key),
+                    path: `${childPath}/loading`,
+                    depth: depth + 1,
+                    seen,
+                    mountMissing,
+                  }),
+                ],
+              }),
+            ),
+            Match.exhaustive,
+          ),
+        )
+      })
+    })
+
+    return {
+      path,
+      depth,
+      key,
+      comp,
+      props: frame.props,
+      events: eventsOf(frame),
+      slots: renderedSlots,
+    }
+  }
+  const render = (): TreeRenderState => {
+    // Discover the desired graph without acquiring missing Features, then release
+    // removed scopes deepest-first before the live pass mounts replacements.
+    sink.reset()
+    const retained = new Set<string>()
+    renderComposition({
+      runtime,
+      comp: root,
+      props: rootProps,
+      key: Option.none(),
+      path: 'root',
+      depth: 0,
+      seen: retained,
+      mountMissing: false,
+    })
+    disposeStale(retained)
+    sink.reset()
+    const seen = new Set<string>()
+    const rootNode = renderComposition({
+      runtime,
+      comp: root,
+      props: rootProps,
+      key: Option.none(),
+      path: 'root',
+      depth: 0,
+      seen,
+      mountMissing: true,
+    })
+    return {
+      root: rootNode,
+      fingerprint: formatFingerprint(treeFingerprint(rootNode)),
+    }
+  }
+
+  const settle = Effect.gen(function* () {
+    yield* settleDrain
+    const first = render()
+    const progress = 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* settleStep
+            const current = render()
+            return {
+              previous: current.fingerprint,
+              remaining: progress.remaining - 1,
+              stable: current.fingerprint === progress.previous,
+            }
+          }),
+      },
+    )
+    yield* ensureSettled(progress)
+  })
+  const dispose = (): void => {
+    if (status.disposed) {
+      return
+    }
+    status.disposed = true
+    registry.disposeAll()
+  }
+
+  return { render, settle, dispose }
+}

package/src/engineTreeFacade.ts

@@ -0,0 +1,183 @@
+import { Array as Arr, type Duration, Effect, Option, TestClock } from 'effect'
+import { AssertionFailed, NoTestClock, UnknownAction, UnknownSlot } from './errors'
+import { matchProps } from './assert'
+import { type RuntimeHandle, type UiContract } from '@playfast/reform'
+import type { AnyComposition } from '@playfast/reform/internal'
+import {
+  type HostRuntime,
+  keyed,
+  type MountedFacadeErasure,
+  type MountedSlotFacadeErasure,
+  type RuntimeRootComposition,
+  type Sink,
+  uiNameOf,
+} from './engineSink'
+import { makeTreeDriver } from './engineTreeDriver'
+import type { RuntimeTreeFacade, RuntimeTreeFacadeErasure, TreeNode } from './engineTreeTypes'
+
+export function makeRuntimeTreeFacade<
+  Services,
+  RootIdentifier extends NoInfer<Services>,
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+>(
+  runtime: RuntimeHandle<Services>,
+  root: RuntimeRootComposition<RootIdentifier, P, C, S, N, Identity>,
+  rootProps: P,
+  sink: Sink,
+  dispatched: Set<string>,
+): RuntimeTreeFacade<C>
+export function makeRuntimeTreeFacade(
+  runtime: HostRuntime,
+  root: AnyComposition,
+  rootProps: unknown,
+  sink: Sink,
+  dispatched: Set<string>,
+): RuntimeTreeFacadeErasure {
+  const driver = makeTreeDriver(runtime, root, rootProps, sink)
+  const currentRoot = (): TreeNode => driver.render().root
+
+  // The nested-Feature twin of the mounted facade's `advance`: same virtual clock
+  // off the same runtime, settled through this driver instead.
+  const advance = (duration: Duration.DurationInput): Effect.Effect<void, never, never> =>
+    Option.match(runtime.readOption(TestClock.TestClock), {
+      onNone: () => Effect.dieMessage(new NoTestClock().message),
+      onSome: (clock) => clock.adjust(duration).pipe(Effect.flatMap(() => driver.settle)),
+    })
+
+  // `peek` is the non-dying half of `resolve`: None once the node has left the
+  // tree, so an action that removed its own node can still report a result.
+  const nodeFacade = (
+    resolve: () => TreeNode,
+    peek: () => Option.Option<TreeNode>,
+  ): MountedFacadeErasure => ({
+    props: Effect.sync(() => resolve().props),
+    expectProps: (partial) =>
+      Effect.sync(() => {
+        const mismatch = matchProps({
+          actual: resolve().props,
+          expected: partial,
+        })
+        if (mismatch !== undefined) {
+          return Effect.runSync(
+            Effect.dieMessage(new AssertionFailed({ detail: mismatch }).message),
+          )
+        }
+      }),
+    actions: keyed(
+      (event) => (payload: unknown) =>
+        Effect.gen(function* () {
+          const node = resolve()
+          const trigger = node.events[event]
+          if (trigger === undefined) {
+            return yield* Effect.dieMessage(
+              new UnknownAction({
+                composition: uiNameOf(node.comp),
+                action: event,
+                rendered: 1,
+              }).message,
+            )
+          }
+          dispatched.add(event)
+          trigger(payload)
+          yield* driver.settle
+          // A self-removing action leaves nothing to re-read; report what the
+          // node last rendered instead of dying on the vanished child.
+          return Option.match(peek(), {
+            onNone: () => node.props,
+            onSome: (settled) => settled.props,
+          })
+        }),
+    ),
+    slots: keyed((slotName) => slotFacade(resolve, slotName)),
+    frame: driver.settle,
+    advance,
+  })
+
+  const slotFacade = (
+    resolveParent: () => TreeNode,
+    slotName: string,
+  ): MountedSlotFacadeErasure => {
+    const children = (): ReadonlyArray<TreeNode> => {
+      const parent = resolveParent()
+      const resolved = parent.slots[slotName]
+      if (resolved === undefined) {
+        return Effect.runSync(
+          Effect.dieMessage(
+            new UnknownSlot({ parent: uiNameOf(parent.comp), slot: slotName }).message,
+          ),
+        )
+      }
+      return resolved
+    }
+    const peekAt = (index: number): Option.Option<TreeNode> =>
+      Option.fromNullable(children()[index])
+    const peekByKey = (key: string): Option.Option<TreeNode> =>
+      Arr.findFirst(children(), (candidate) => Option.contains(candidate.key, key))
+    const childAt = (index: number): MountedFacadeErasure =>
+      nodeFacade(
+        () => children()[index] ?? missingChild(index),
+        () => peekAt(index),
+      )
+    const childByKey = (key: string): MountedFacadeErasure =>
+      nodeFacade(
+        () => Option.getOrElse(peekByKey(key), () => missingKey(key)),
+        () => peekByKey(key),
+      )
+    const missingChild = (index: number): never => {
+      const parent = resolveParent()
+      return Effect.runSync(
+        Effect.dieMessage(
+          new UnknownSlot({
+            parent: uiNameOf(parent.comp),
+            slot: `${slotName}[${index}]`,
+          }).message,
+        ),
+      )
+    }
+    const missingKey = (key: string): never => {
+      const parent = resolveParent()
+      return Effect.runSync(
+        Effect.dieMessage(
+          new UnknownSlot({
+            parent: uiNameOf(parent.comp),
+            slot: `${slotName}[key=${key}]`,
+          }).message,
+        ),
+      )
+    }
+    const first = childAt(0)
+    return {
+      first: Effect.sync(() => childAt(0)),
+      at: (index) => Effect.sync(() => childAt(index)),
+      all: Effect.sync(() => children().map((_child, index) => childAt(index))),
+      byKey: (key) =>
+        Effect.sync(() => {
+          const child = Arr.findFirst(children(), (candidate) =>
+            Option.contains(candidate.key, key),
+          )
+          return Option.isNone(child) ? missingKey(key) : childByKey(key)
+        }),
+      where: (predicate) =>
+        Effect.sync(() =>
+          children().flatMap((child, index) => (predicate(child.props) ? [childAt(index)] : [])),
+        ),
+      count: Effect.sync(() => children().length),
+      props: first.props,
+      expectProps: first.expectProps,
+      actions: first.actions,
+      slots: first.slots,
+      frame: driver.settle,
+      advance,
+    }
+  }
+
+  return {
+    facade: nodeFacade(currentRoot, () => Option.some(currentRoot())),
+    settle: driver.settle,
+    dispose: driver.dispose,
+  }
+}

package/src/engineTreeTypes.ts

@@ -0,0 +1,103 @@
+import { type Effect, Match, type Option, Record as Rec } from 'effect'
+import type { FeatureLoadFailed, SlotFill, Trigger, UiContract } from '@playfast/reform'
+import type { AnyComposition, AnyFeatureBinding } from '@playfast/reform/internal'
+import {
+  type HostRuntime,
+  type MountedFacade,
+  type MountedFacadeHandleErasure,
+  uiNameOf,
+} from './engineSink'
+
+export type FeatureMountState =
+  | { readonly _tag: 'Loading' }
+  | { readonly _tag: 'Live'; readonly runtime: HostRuntime }
+  | { readonly _tag: 'Failed'; readonly error: FeatureLoadFailed }
+
+export interface TreeFeatureMount {
+  readonly id: string
+  readonly binding: AnyFeatureBinding
+  readonly parent: HostRuntime
+  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: AnyComposition
+  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<C extends UiContract> {
+  readonly facade: MountedFacade<C>
+  readonly settle: Effect.Effect<void, never, never>
+  dispose(): void
+}
+
+export interface RuntimeTreeFacadeErasure extends MountedFacadeHandleErasure {
+  dispose(): void
+}
+
+export interface TreeDriver {
+  readonly render: () => TreeRenderState
+  readonly settle: Effect.Effect<void, never, never>
+  readonly dispose: () => void
+}
+
+export interface MountIdentityInput {
+  readonly parent: HostRuntime
+  readonly parentPath: string
+  readonly slotName: string
+  readonly key: string
+  readonly binding: AnyFeatureBinding
+}
+
+export interface FeatureRecordInput {
+  readonly id: string
+  readonly parent: HostRuntime
+  readonly binding: AnyFeatureBinding
+  readonly depth: number
+  readonly props: unknown
+}
+
+export interface RenderCompositionInput {
+  readonly runtime: HostRuntime
+  readonly comp: AnyComposition
+  readonly props: unknown
+  readonly key: Option.Option<string>
+  readonly path: string
+  readonly depth: number
+  readonly seen: Set<string>
+  readonly mountMissing: boolean
+}
+
+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/errors.ts

@@ -40,3 +40,22 @@ export class UnknownSlot extends UnknownSlotBase {
     return `reform-proof: '${this.parent}' has no slot '${this.slot}'`
   }
 }
+
+/** The `Data.TaggedError(tag)` shape for a payload-free error: a `void` argument. */
+type TaggedErrorClassVoid<Tag extends string> = new (
+  args: void,
+) => Cause.YieldableError & { readonly _tag: Tag }
+
+const NoTestClockBase: TaggedErrorClassVoid<'reform-proof/NoTestClock'> = Data.TaggedError(
+  'reform-proof/NoTestClock',
+)
+
+/**
+ * `app.advance(...)` ran against a scene whose runtime still holds the real clock,
+ * so there is no product time to move.
+ */
+export class NoTestClock extends NoTestClockBase {
+  override get message(): string {
+    return "reform-proof: app.advance(...) needs a virtual clock — wrap the scene's layers with `Proof.withTestClock(...)`. Without it the scene's procedures sleep on the real clock and only elapse in real time."
+  }
+}

package/src/facade.ts

@@ -0,0 +1,78 @@
+import type { Duration, Effect } from 'effect'
+import type {
+  SlotContract as ReformSlotContract,
+  Trigger,
+  UiContract,
+} from '@playfast/reform'
+
+export type EventsOf<C extends UiContract> = C extends {
+  readonly events: infer E extends NonNullable<UiContract['events']>
+}
+  ? E
+  : Readonly<Record<PropertyKey, never>>
+export type EventNamesOf<C extends UiContract> = C extends {
+  readonly events: NonNullable<UiContract['events']>
+}
+  ? keyof EventsOf<C>
+  : never
+export type SlotsOf<C extends UiContract> = C extends {
+  readonly slots: infer S extends NonNullable<UiContract['slots']>
+}
+  ? S
+  : Readonly<Record<PropertyKey, never>>
+export type PayloadOf<T> = T extends Trigger<infer P> ? P : never
+export type ContractOf<Comp> = Comp extends {
+  readonly Contract: infer C extends UiContract
+}
+  ? C
+  : never
+export type ContractOfSlot<S> = ReformSlotContract<S>
+
+export type ActionsOf<C extends UiContract, R = never> = C extends {
+  readonly events: NonNullable<UiContract['events']>
+}
+  ? {
+      readonly [K in keyof EventsOf<C>]: (
+        payload: PayloadOf<EventsOf<C>[K]>,
+      ) => Effect.Effect<C['props'], never, R>
+    }
+  : Readonly<Record<PropertyKey, never>>
+export type SlotFacadesOf<C extends UiContract, R = never> = C extends {
+  readonly slots: NonNullable<UiContract['slots']>
+}
+  ? {
+      readonly [K in keyof SlotsOf<C>]: SlotFacade<ContractOfSlot<SlotsOf<C>[K]>, R>
+    }
+  : Readonly<Record<PropertyKey, never>>
+
+export type Action<R = never> = (payload: unknown) => Effect.Effect<unknown, never, R>
+
+export interface Facade<C extends UiContract, R = never> {
+  readonly props: Effect.Effect<C['props'], never, R>
+  readonly expectProps: (partial: Partial<C['props']>) => Effect.Effect<void, never, R>
+  readonly actions: ActionsOf<C, R>
+  readonly slots: SlotFacadesOf<C, R>
+  readonly frame: Effect.Effect<void, never, R>
+  /**
+   * Elapse `duration` of the scene's product time, then settle. Every timer the
+   * scene's procedures hold — `Effect.sleep`, `Schedule`, `Clock` reads — moves by
+   * exactly this much and no real time passes, so a 1500ms poll interval is observed
+   * in microseconds and never races the runner.
+   *
+   * Requires the scene's layers to be wrapped in `Proof.withTestClock(...)`. Against
+   * the real clock there is no virtual time to move, so the proof dies with
+   * `NoTestClock` instead of silently doing nothing.
+   */
+  readonly advance: (duration: Duration.DurationInput) => Effect.Effect<void, never, R>
+}
+
+export interface SlotFacade<C extends UiContract, R = never> extends Facade<C, R> {
+  readonly first: Effect.Effect<Facade<C, R>, never, R>
+  readonly at: (index: number) => Effect.Effect<Facade<C, R>, never, R>
+  readonly all: Effect.Effect<ReadonlyArray<Facade<C, R>>, never, R>
+  readonly byKey: (key: string) => Effect.Effect<Facade<C, R>, never, R>
+  readonly where: (
+    predicate: (props: C['props']) => boolean,
+  ) => Effect.Effect<ReadonlyArray<Facade<C, R>>, never, R>
+  readonly count: Effect.Effect<number, never, R>
+}