@playfast/reform-proof 1.1.1 → 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/{runtimeTreeTypes.ts → engineTreeTypes.ts}

@@ -1,23 +1,22 @@
-import { Effect, Match, Option, Record as Rec } from 'effect'
+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 CompositionClass,
-  type FeatureBinding,
-  type RuntimeHandle,
-  type SlotFill,
-  type Trigger,
-} from '@playfast/reform'
-import type { MountedFacade } from './runtimeFacade'
-import { uiNameOf } from './sink'
+  type HostRuntime,
+  type MountedFacade,
+  type MountedFacadeHandleErasure,
+  uiNameOf,
+} from './engineSink'
 
 export type FeatureMountState =
   | { readonly _tag: 'Loading' }
-  | { readonly _tag: 'Live'; readonly runtime: RuntimeHandle }
-  | { readonly _tag: 'Failed'; readonly error: unknown }
+  | { readonly _tag: 'Live'; readonly runtime: HostRuntime }
+  | { readonly _tag: 'Failed'; readonly error: FeatureLoadFailed }
 
 export interface TreeFeatureMount {
   readonly id: string
-  readonly binding: FeatureBinding
-  readonly parent: RuntimeHandle
+  readonly binding: AnyFeatureBinding
+  readonly parent: HostRuntime
   readonly depth: number
   readonly props: unknown
   attempt: number
@@ -29,7 +28,7 @@ export interface TreeNode {
   readonly path: string
   readonly depth: number
   readonly key: Option.Option<string>
-  readonly comp: CompositionClass<unknown>
+  readonly comp: AnyComposition
   readonly props: unknown
   readonly events: Record<string, Trigger<unknown>>
   readonly slots: Readonly<Record<string, ReadonlyArray<TreeNode>>>
@@ -40,12 +39,16 @@ export interface TreeRenderState {
   readonly fingerprint: string
 }
 
-export interface RuntimeTreeFacade {
-  readonly facade: MountedFacade
+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>
@@ -53,29 +56,30 @@ export interface TreeDriver {
 }
 
 export interface MountIdentityInput {
-  readonly parent: RuntimeHandle
+  readonly parent: HostRuntime
   readonly parentPath: string
   readonly slotName: string
   readonly key: string
-  readonly binding: FeatureBinding
+  readonly binding: AnyFeatureBinding
 }
 
 export interface FeatureRecordInput {
   readonly id: string
-  readonly parent: RuntimeHandle
-  readonly binding: FeatureBinding
+  readonly parent: HostRuntime
+  readonly binding: AnyFeatureBinding
   readonly depth: number
   readonly props: unknown
 }
 
 export interface RenderCompositionInput {
-  readonly runtime: RuntimeHandle
-  readonly comp: CompositionClass<unknown>
+  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}`

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."
+  }
+}