@playfast/reform-proof 1.2.0 → 1.3.0

package/src/engineMounted.ts

@@ -0,0 +1,271 @@
+import { Array as Arr, type Duration, Effect, ManagedRuntime, Option, TestClock } from 'effect'
+import { NoTestClock, UnknownAction, UnknownSlot } from './errors'
+import {
+  type CapturedScene,
+  type CompositionClass,
+  type RuntimeHandle,
+  type Trigger,
+  type UiContract,
+} from '@playfast/reform'
+import { type AnyComposition, CaptureSink } from '@playfast/reform/internal'
+import type { Facade } from './facade'
+import {
+  directSettle,
+  expectMatchingProps,
+  keyed,
+  type MountedFacade,
+  type MountedFacadeErasure,
+  type MountedFacadeHandleErasure,
+  type MountedSlotFacadeErasure,
+  type RenderRuntime,
+  type RuntimeRootComposition,
+  type SettleBoundary,
+  type Sink,
+  uiNameOf,
+} from './engineSink'
+import {
+  makeCaptureLookup,
+  nodeCaptureFor,
+  type NodeRef,
+  renderRuntimeFromContext,
+  rootRef,
+  slotCapturesFor,
+  slotsOf,
+} from './engineTree'
+import {
+  collectRuntimeBindings,
+  renderTreeRuntime,
+  settleTreeRuntime,
+} from './engineRender'
+
+export function makeFacade<
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  runtime: ManagedRuntime.ManagedRuntime<Services | CaptureSink, never>,
+  scene: CapturedScene<C, S, Services, P, N, Identity>,
+  sink: Sink,
+  dispatched: Set<string>,
+): {
+  readonly facade: Facade<C, never>
+  readonly settle: Effect.Effect<void, never, never>
+} {
+  const context = runtime.runSync(Effect.context<Services | CaptureSink>())
+  return makeMountedFacade(
+    renderRuntimeFromContext(context, sink.instrumentation),
+    scene.composition,
+    sink,
+    dispatched,
+    (settlement) => Effect.promise(() => runtime.runPromise(settlement)),
+  )
+}
+
+function makeMountedFacade<
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+>(
+  runtime: RenderRuntime,
+  root: CompositionClass<P, C, S, N, Identity>,
+  sink: Sink,
+  dispatched: Set<string>,
+  settleBoundary: SettleBoundary,
+): {
+  readonly facade: MountedFacade<C>
+  readonly settle: Effect.Effect<void, never, never>
+}
+function makeMountedFacade(
+  runtime: RenderRuntime,
+  root: AnyComposition,
+  sink: Sink,
+  dispatched: Set<string>,
+  settleBoundary: SettleBoundary,
+): MountedFacadeHandleErasure
+function makeMountedFacade(
+  runtime: RenderRuntime,
+  root: AnyComposition,
+  sink: Sink,
+  dispatched: Set<string>,
+  settleBoundary: SettleBoundary,
+): MountedFacadeHandleErasure {
+  const bindings = collectRuntimeBindings(root, runtime)
+  const lookup = makeCaptureLookup()
+  const settle = settleBoundary(settleTreeRuntime(runtime, root, bindings, sink, lookup))
+  const rerender = renderTreeRuntime(runtime, root, bindings, sink, lookup)
+
+  // Move the scene's virtual clock, then settle the tree the woken fibers dirty.
+  // The clock is read off the runtime the scene's procedures run on, so adjusting it
+  // resumes their `Effect.sleep`s even though the proof body drives from outside.
+  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(() => settle)),
+    })
+
+  const triggerOf = (ref: NodeRef, event: string): Effect.Effect<Trigger<unknown>, never, never> =>
+    Option.match(
+      Option.flatMap(nodeCaptureFor(lookup, ref), (capture) =>
+        Option.fromNullable(capture.events[event]),
+      ),
+      {
+        onNone: () =>
+          Effect.dieMessage(
+            new UnknownAction({
+              composition: ref.name,
+              action: event,
+              rendered: lookup.captures.filter((entry) => entry.ref.name === ref.name).length,
+            }).message,
+          ),
+        onSome: Effect.succeed,
+      },
+    )
+
+  const propsFor = (ref: NodeRef): Effect.Effect<unknown, never, never> =>
+    Effect.map(rerender, () =>
+      Option.match(nodeCaptureFor(lookup, ref), {
+        onNone: () => undefined,
+        onSome: (capture) => capture.props,
+      }),
+    )
+
+  const nodeFacade = (ref: NodeRef, comp: AnyComposition): MountedFacadeErasure => ({
+    props: propsFor(ref),
+    expectProps: (partial) =>
+      propsFor(ref).pipe(
+        Effect.flatMap((props) => expectMatchingProps({ actual: props, expected: partial })),
+      ),
+    actions: keyed(
+      (event) => (payload: unknown) =>
+        rerender.pipe(
+          Effect.flatMap(() => triggerOf(ref, event)),
+          Effect.flatMap((trigger) =>
+            Effect.sync(() => {
+              dispatched.add(event)
+              trigger(payload)
+            }),
+          ),
+          Effect.flatMap(() => settle),
+          Effect.flatMap(() => propsFor(ref)),
+        ),
+    ),
+    slots: keyed((slotName) => slotFacade(ref, comp, slotName)),
+    frame: settle,
+    advance,
+  })
+
+  const slotFacade = (
+    parentRef: NodeRef,
+    parent: AnyComposition,
+    slotName: string,
+  ): MountedSlotFacadeErasure => {
+    const slotClass = slotsOf(parent)[slotName]
+    const child = slotClass && bindings.get(slotClass)
+    if (child === undefined) {
+      return Effect.runSync(
+        Effect.dieMessage(new UnknownSlot({ parent: uiNameOf(parent), slot: slotName }).message),
+      )
+    }
+    const childName = uiNameOf(child)
+    const childRefAt = (index: number): NodeRef =>
+      slotCapturesFor(lookup, parentRef, slotName)[index]?.ref ?? {
+        name: childName,
+        parent: Option.some(parentRef),
+        slot: Option.some({
+          name: slotName,
+          index,
+          key: Option.none(),
+          keyOccurrence: 0,
+        }),
+      }
+    const atIndex = (index: number): Effect.Effect<MountedFacadeErasure, never, never> =>
+      Effect.as(rerender, nodeFacade(childRefAt(index), child))
+    const first = nodeFacade(childRefAt(0), child)
+    return {
+      first: atIndex(0),
+      at: atIndex,
+      all: Effect.map(rerender, () =>
+        slotCapturesFor(lookup, parentRef, slotName).map((entry) => nodeFacade(entry.ref, child)),
+      ),
+      byKey: (key) =>
+        Effect.flatMap(rerender, () =>
+          Option.match(
+            Arr.findFirst(
+              slotCapturesFor(lookup, parentRef, slotName),
+              (entry) => entry.capture.key === key,
+            ),
+            {
+              onNone: () =>
+                Effect.dieMessage(
+                  new UnknownSlot({
+                    parent: uiNameOf(parent),
+                    slot: `${slotName}[key=${key}]`,
+                  }).message,
+                ),
+              onSome: (entry) => Effect.succeed(nodeFacade(entry.ref, child)),
+            },
+          ),
+        ),
+      where: (predicate) =>
+        Effect.map(rerender, () =>
+          slotCapturesFor(lookup, parentRef, slotName).flatMap((entry) =>
+            predicate(entry.capture.props) ? [nodeFacade(entry.ref, child)] : [],
+          ),
+        ),
+      count: Effect.map(rerender, () => slotCapturesFor(lookup, parentRef, slotName).length),
+      props: first.props,
+      expectProps: first.expectProps,
+      actions: first.actions,
+      slots: first.slots,
+      frame: first.frame,
+      advance: first.advance,
+    }
+  }
+
+  return {
+    facade: nodeFacade(rootRef(root), root),
+    settle,
+  }
+}
+
+export const makeProofFacade = <
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  runtime: ManagedRuntime.ManagedRuntime<Services | CaptureSink, never>,
+  scene: CapturedScene<C, S, Services, P, N, Identity>,
+  sink: Sink,
+  dispatched: Set<string>,
+): {
+  readonly facade: Facade<C, never>
+  readonly settle: Effect.Effect<void, never, never>
+} => {
+  return makeFacade(runtime, scene, sink, dispatched)
+}
+
+export const makeRuntimeHandleFacade = <
+  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>,
+  sink: Sink,
+  dispatched: Set<string>,
+): {
+  readonly facade: MountedFacade<C>
+  readonly settle: Effect.Effect<void, never, never>
+} => makeMountedFacade(runtime, root, sink, dispatched, directSettle)

package/src/engineMounts.ts

@@ -0,0 +1,165 @@
+import { Array as Arr, Order } from 'effect'
+import type { HostRuntime } from './engineSink'
+import {
+  encodeIdentityPart,
+  type FeatureRecordInput,
+  type MountIdentityInput,
+  type TreeFeatureMount,
+} from './engineTreeTypes'
+
+export interface RegistryStatus {
+  disposed: boolean
+}
+
+export interface FeatureMountRegistry {
+  readonly mountId: (input: MountIdentityInput) => string
+  readonly retryMount: (record: TreeFeatureMount) => void
+  readonly recordForRender: (
+    input: FeatureRecordInput,
+    mountMissing: boolean,
+  ) => TreeFeatureMount | undefined
+  readonly disposeStale: (seen: ReadonlySet<string>) => void
+  readonly disposeAll: () => void
+}
+
+// Owns every mounted Feature scope: identity, (re)mount attempts, and deepest-first teardown.
+export const makeFeatureMountRegistry = (status: RegistryStatus): FeatureMountRegistry => {
+  const mounts = new Map<string, TreeFeatureMount>()
+  const runtimeIds = new WeakMap<HostRuntime, number>()
+  const bindingIds = new WeakMap<object, number>()
+  const sequence = { runtime: 0, binding: 0 }
+
+  const identity = <Subject extends object>(
+    identities: WeakMap<Subject, number>,
+    subject: Subject,
+    next: () => number,
+  ): number => {
+    const current = identities.get(subject)
+    if (current !== undefined) {
+      return current
+    }
+    const created = next()
+    identities.set(subject, created)
+    return created
+  }
+
+  const mountId = ({ parent, parentPath, slotName, key, binding }: MountIdentityInput): string => {
+    const runtimeId = identity(runtimeIds, parent, () => ++sequence.runtime)
+    const bindingId = identity(bindingIds, binding, () => ++sequence.binding)
+    return [String(runtimeId), parentPath, slotName, String(bindingId), key]
+      .map(encodeIdentityPart)
+      .join('')
+  }
+
+  const startMount = (record: TreeFeatureMount): void => {
+    record.attempt += 1
+    const attempt = record.attempt
+    record.binding.capture<void>((binding) => {
+      if (binding.strategy === 'default') {
+        record.state = { _tag: 'Live', runtime: record.parent }
+        binding.boot.forEach((event) => record.parent.dispatch('High', event))
+        record.dispose = () => {}
+        return
+      }
+      record.state = { _tag: 'Loading' }
+      record.dispose = record.parent.mountAnyFeature(binding, {
+        props: record.props,
+        onLive: (childRuntime) => {
+          if (status.disposed || record.attempt !== attempt || mounts.get(record.id) !== record) {
+            return
+          }
+          record.state = { _tag: 'Live', runtime: childRuntime }
+        },
+        onFailed: (error) => {
+          if (status.disposed || record.attempt !== attempt || mounts.get(record.id) !== record) {
+            return
+          }
+          record.state = { _tag: 'Failed', error }
+        },
+      })
+    })
+  }
+
+  const retryMount = (record: TreeFeatureMount): void => {
+    if (status.disposed || mounts.get(record.id) !== record || record.state._tag !== 'Failed') {
+      return
+    }
+    record.dispose()
+    startMount(record)
+  }
+
+  const featureRecord = ({
+    id,
+    parent,
+    binding,
+    depth,
+    props,
+  }: FeatureRecordInput): TreeFeatureMount => {
+    const current = mounts.get(id)
+    if (current !== undefined && current.binding === binding && current.parent === parent) {
+      return current
+    }
+    if (current !== undefined) {
+      current.attempt += 1
+      current.dispose()
+    }
+    const created: TreeFeatureMount = {
+      id,
+      binding,
+      parent,
+      depth,
+      props,
+      attempt: 0,
+      state: { _tag: 'Loading' },
+      dispose: () => {},
+    }
+    mounts.set(id, created)
+    startMount(created)
+    return created
+  }
+  const featureRecordForRender = (
+    input: FeatureRecordInput,
+    mountMissing: boolean,
+  ): TreeFeatureMount | undefined => {
+    const current = mounts.get(input.id)
+    if (current !== undefined || !mountMissing) {
+      return current
+    }
+    return featureRecord(input)
+  }
+
+  const disposeStale = (seen: ReadonlySet<string>): void => {
+    Arr.sortWith(
+      Array.from(mounts.values()).filter((record) => !seen.has(record.id)),
+      (record) => -record.depth,
+      Order.number,
+    ).forEach((record) => {
+      mounts.delete(record.id)
+      record.attempt += 1
+      record.dispose()
+    })
+  }
+
+  const disposeAll = (): void => {
+    if (status.disposed) {
+      return
+    }
+    status.disposed = true
+    Arr.sortWith(Array.from(mounts.values()), (record) => -record.depth, Order.number).forEach(
+      (record) => {
+        record.attempt += 1
+        record.dispose()
+      },
+    )
+    mounts.clear()
+  }
+
+
+  return {
+    mountId,
+    retryMount,
+    recordForRender: featureRecordForRender,
+    disposeStale,
+    disposeAll,
+  }
+}

package/src/engineRender.ts

@@ -0,0 +1,136 @@
+import { Effect, Record as Rec } from 'effect'
+import type { AnyComposition, AnySlot } from '@playfast/reform/internal'
+import {
+  type RenderRuntime,
+  renderCompositionRuntime,
+  SETTLE_MAX_RENDERS,
+  settleDrain,
+  settleStep,
+  type Sink,
+  uiNameOf,
+} from './engineSink'
+import {
+  type CaptureLookup,
+  childComposition,
+  driveStructure,
+  ensureSettled,
+  fingerprint,
+  type Mounted,
+  readRuntimeSlotChild,
+  rootRef,
+  type SettleProgress,
+  slotsOf,
+} from './engineTree'
+
+export const collectRuntimeBindings = (
+  root: AnyComposition,
+  runtime: RenderRuntime,
+): Map<AnySlot, AnyComposition> => {
+  const bindings = new Map<AnySlot, AnyComposition>()
+  const walk = (comp: AnyComposition): void => {
+    Rec.values(slotsOf(comp)).forEach((slotClass) => {
+      if (bindings.has(slotClass)) {
+        return
+      }
+      const child = childComposition(
+        readRuntimeSlotChild({
+          runtime,
+          slotDefinition: slotClass,
+          parent: comp,
+        }),
+      )
+      bindings.set(slotClass, child)
+      walk(child)
+    })
+  }
+  walk(root)
+  return bindings
+}
+
+export const renderMountedRuntime = (
+  runtime: RenderRuntime,
+  mounted: Mounted,
+  bindings: ReadonlyMap<AnySlot, AnyComposition>,
+  sink: Sink,
+  lookup: CaptureLookup,
+): ReadonlyArray<Mounted> => {
+  const endRenderSpan = sink.instrumentation.uiRendered(uiNameOf(mounted.comp))
+  const frame = renderCompositionRuntime(runtime, mounted.comp, mounted.props)
+  endRenderSpan()
+  return driveStructure(mounted.comp, frame, mounted.ref, sink, lookup, bindings)
+}
+
+export const renderLevelRuntime = (
+  runtime: RenderRuntime,
+  frontier: ReadonlyArray<Mounted>,
+  bindings: ReadonlyMap<AnySlot, AnyComposition>,
+  sink: Sink,
+  lookup: CaptureLookup,
+): void => {
+  if (frontier.length === 0) {
+    return
+  }
+  const levels = frontier.map((mounted) =>
+    renderMountedRuntime(runtime, mounted, bindings, sink, lookup),
+  )
+  renderLevelRuntime(runtime, levels.flat(), bindings, sink, lookup)
+}
+
+export const renderTreeRuntime = (
+  runtime: RenderRuntime,
+  root: AnyComposition,
+  bindings: ReadonlyMap<AnySlot, AnyComposition>,
+  sink: Sink,
+  lookup: CaptureLookup,
+): Effect.Effect<void, never, never> =>
+  Effect.sync(() => {
+    sink.reset()
+    lookup.reset()
+    renderLevelRuntime(
+      runtime,
+      [{ comp: root, props: {}, ref: rootRef(root) }],
+      bindings,
+      sink,
+      lookup,
+    )
+  })
+
+export const settleTreeRuntime: (
+  runtime: RenderRuntime,
+  root: AnyComposition,
+  bindings: ReadonlyMap<AnySlot, AnyComposition>,
+  sink: Sink,
+  lookup: CaptureLookup,
+) => Effect.Effect<void, never, never> = Effect.fn('settleTreeRuntime')(function* (
+  runtime: RenderRuntime,
+  root: AnyComposition,
+  bindings: ReadonlyMap<AnySlot, AnyComposition>,
+  sink: Sink,
+  lookup: CaptureLookup,
+): Effect.fn.Return<void, never, never> {
+  yield* settleDrain
+  yield* renderTreeRuntime(runtime, root, bindings, sink, lookup)
+  const progress = yield* Effect.iterate(
+    {
+      previous: fingerprint(lookup),
+      remaining: SETTLE_MAX_RENDERS,
+      stable: false,
+    },
+    {
+      while: (progress: SettleProgress) => !progress.stable && progress.remaining > 0,
+      body: (progress) =>
+        Effect.gen(function* () {
+          yield* settleDrain
+          yield* settleStep
+          yield* renderTreeRuntime(runtime, root, bindings, sink, lookup)
+          const current = fingerprint(lookup)
+          return {
+            previous: current,
+            remaining: progress.remaining - 1,
+            stable: current === progress.previous,
+          }
+        }),
+    },
+  )
+  yield* ensureSettled(progress)
+})