@playfast/reform 1.1.1 → 1.2.0

package/src/runtime/loop.ts

@@ -1,10 +1,6 @@
 import { Array as Arr, Cause, Chunk, Context, Effect, Layer, Option, PubSub, Queue } from 'effect'
-import {
-  Channels,
-  channelsLayer,
-  Procedures,
-  proceduresLayer,
-} from '../channel/channel'
+import { Channels, channelsLayer, Procedures, proceduresLayer } from '../channel/channel'
+import { makeBucketCache } from '../internal/bucketCache'
 import { notificationsLayer } from '../internal/scheduler'
 import { Bus, busLayer, type Envelope, type Tagged } from './bus'
 import { enforceBudget, makeTickCounter, resolveCurrentEventBudget } from './eventBudget'
@@ -19,56 +15,78 @@ export interface ReducerEntry {
 
 export interface ReducerRegistry {
   readonly entries: Array<ReducerEntry>
-  readonly byTag: Map<string, Array<ReducerEntry>>
+  readonly byName: Map<string, Set<ReducerEntry>>
+  readonly byTag: Map<string, Set<ReducerEntry>>
+  readonly tagged: (tag: string) => ReadonlyArray<ReducerEntry>
   readonly register: (entry: ReducerEntry) => void
   readonly unregister: (entry: ReducerEntry) => void
 }
 
-const ReducersBase: Context.TagClass<Reducers, 'reform/Reducers', ReducerRegistry> =
-  Context.Tag('reform/Reducers')<Reducers, ReducerRegistry>()
+const ReducersBase: Context.TagClass<Reducers, 'reform/Reducers', ReducerRegistry> = Context.Tag(
+  'reform/Reducers',
+)<Reducers, ReducerRegistry>()
 export class Reducers extends ReducersBase {}
 
-const dropFromBuckets = <T>(map: Map<string, Array<T>>, key: string, target: T): void => {
+const dropFromBuckets = <T>(map: Map<string, Set<T>>, key: string, target: T): void => {
   const bucket = map.get(key)
   if (bucket === undefined) {
     return
   }
-  const next = bucket.filter((entry) => entry !== target)
-  if (next.length === 0) {
+  bucket.delete(target)
+  if (bucket.size === 0) {
     map.delete(key)
-  } else {
-    map.set(key, next)
   }
 }
 
 const makeReducerRegistry = (): ReducerRegistry => {
-  const byTag = new Map<string, Array<ReducerEntry>>()
-  const state: { entries: Array<ReducerEntry> } = { entries: [] }
+  const entries = new Set<ReducerEntry>()
+  const byName = new Map<string, Set<ReducerEntry>>()
+  const byTag = new Map<string, Set<ReducerEntry>>()
+  const tagged = makeBucketCache(byTag)
+  const snapshot: { value: Option.Option<Array<ReducerEntry>> } = {
+    value: Option.some([]),
+  }
   return {
     get entries() {
-      return state.entries
+      return Option.getOrElse(snapshot.value, () => {
+        const current = Array.from(entries)
+        snapshot.value = Option.some(current)
+        return current
+      })
     },
+    byName,
     byTag,
+    tagged: tagged.read,
     register: (entry) => {
-      state.entries = [...state.entries, entry]
+      entries.add(entry)
+      snapshot.value = Option.none()
+      getOrCreateBucket(byName, entry.name).add(entry)
       entry.handles.forEach((tag) => {
-        const bucket = byTag.get(tag)
-        if (bucket === undefined) {
-          byTag.set(tag, [entry])
-        } else {
-          byTag.set(tag, [...bucket, entry])
-        }
+        getOrCreateBucket(byTag, tag).add(entry)
+        tagged.invalidate(tag)
       })
     },
     unregister: (entry) => {
-      state.entries = state.entries.filter((existing) => existing !== entry)
-      entry.handles.forEach((tag) => dropFromBuckets(byTag, tag, entry))
+      entries.delete(entry)
+      snapshot.value = Option.none()
+      dropFromBuckets(byName, entry.name, entry)
+      entry.handles.forEach((tag) => {
+        dropFromBuckets(byTag, tag, entry)
+        tagged.invalidate(tag)
+      })
     },
   }
 }
 
-const bucketOf = <V>(map: Map<string, Array<V>>, tag: string): Array<V> =>
-  Option.getOrElse(Option.fromNullable(map.get(tag)), (): Array<V> => [])
+const getOrCreateBucket = <T>(map: Map<string, Set<T>>, key: string): Set<T> => {
+  const existing = map.get(key)
+  if (existing !== undefined) {
+    return existing
+  }
+  const created = new Set<T>()
+  map.set(key, created)
+  return created
+}
 
 const isolateApply = (
   reducer: ReducerEntry,
@@ -78,9 +96,10 @@ const isolateApply = (
   const end = instrumentation.reducerRun(reducer.name, event._tag)
   return Effect.runSync(
     Effect.match(
-      Effect.try({ try: () => reducer.apply(event), catch: (error) => error }).pipe(
-        Effect.ensuring(Effect.sync(end)),
-      ),
+      Effect.try({
+        try: () => reducer.apply(event),
+        catch: (error) => error,
+      }).pipe(Effect.ensuring(Effect.sync(end))),
       {
         onFailure: (error) => Option.some({ event, error }),
         onSuccess: () => Option.none(),
@@ -91,7 +110,7 @@ const isolateApply = (
 
 export const reducersLayer: Layer.Layer<Reducers> = Layer.sync(Reducers, makeReducerRegistry)
 
-// High before Normal; partition preserves intra-priority dispatch order
+// Partitioning keeps dispatch order stable within each priority.
 const rank = (priority: Envelope['priority']): number => (priority === 'High' ? 0 : 1)
 
 const drain = Effect.gen(function* () {
@@ -100,8 +119,8 @@ const drain = Effect.gen(function* () {
   const { byName: channels } = yield* Channels
   const procedures = yield* Procedures
   const instrumentation = yield* resolveInstrumentation
-  // One counter per engine: feature child runtimes share the app budget
   const budget = yield* resolveCurrentEventBudget
+  // Child feature runtimes share this engine-level counter with the root.
   const counter = makeTickCounter(budget)
   const subscription = yield* PubSub.subscribe(bus)
 
@@ -115,25 +134,25 @@ const drain = Effect.gen(function* () {
         const [high, normal] = Arr.partition(frame, (envelope) => rank(envelope.priority) !== 0)
         const ordered = [...high, ...normal]
 
-        // Budget before folding — EventLoopOverflow is this tick's only typed failure
+        // Check before folding so runaway frames stop at the hard limit.
         const sample = yield* Effect.sync(() => counter.add(ordered.length))
         yield* enforceBudget(budget, sample)
 
-        // Sync block: coalesce reducer writes into one flush; no yield* mid-frame
+        // One synchronous block coalesces reducer writes into a single flush.
         const failures = yield* Effect.sync(() => {
           const endFrame = instrumentation.frame(ordered.length)
           ordered.forEach((envelope) =>
             instrumentation.eventDispatched(envelope.event._tag, envelope.priority),
           )
-          // Isolate folds so one throw cannot kill the drain fiber
           const collected = Arr.flatMap(ordered, (envelope) =>
-            Arr.filterMap(bucketOf(reducers.byTag, envelope.event._tag), (reducer) =>
+            // A reducer defect must not abandon the remaining frame.
+            Arr.filterMap(reducers.tagged(envelope.event._tag), (reducer) =>
               isolateApply(reducer, envelope.event, instrumentation),
             ),
           )
-          // Offer each distinct channel once (per-procedure would double-run shared channels)
           ordered.forEach((envelope) => {
-            bucketOf(procedures.channelsByTag, envelope.event._tag).forEach((channelName) => {
+            // channelsFor is distinct; per-procedure offers would double-run shared channels.
+            procedures.channelsFor(envelope.event._tag).forEach((channelName) => {
               channels.get(channelName)?.offer(envelope.event)
             })
           })
@@ -150,7 +169,7 @@ const drain = Effect.gen(function* () {
           { discard: true },
         )
       }).pipe(
-        // Only typed failures (overflow) escape; defects restart the tick so the bus never goes deaf
+        // Typed overflow halts the loop; defects are logged and the next tick continues.
         Effect.catchAllCause((cause) =>
           Option.match(Cause.failureOption(cause), {
             onSome: () => Effect.failCause(cause),
@@ -180,3 +199,13 @@ export const Engine: Layer.Layer<Bus | Reducers | Channels | Procedures | Querie
       ),
     ),
   )
+
+export const EngineRequirements: readonly [
+  typeof Bus,
+  typeof Reducers,
+  typeof Channels,
+  typeof Procedures,
+  typeof Queries,
+] = [Bus, Reducers, Channels, Procedures, Queries]
+
+export type EngineServices = Layer.Layer.Success<typeof Engine>

package/src/scene/featureScene.test.ts

@@ -19,11 +19,13 @@ const GreetingBase: Context.TagClass<Greeting, 'featureScene.Greeting', Greeting
 class Greeting extends GreetingBase {}
 
 class Started extends Event.make('featureScene.Started', S.Struct({})) {}
-class RootUi extends ui('featureScene.RootUi')<{ props: { readonly greeting: string } }>() {}
+class RootUi extends ui('featureScene.RootUi')<{
+  props: { readonly greeting: string }
+}>() {}
 class RootComp extends Composition.make('featureScene.RootComp', {
   title: 'Feature root',
   ui: RootUi,
-}) {}
+})<RootComp>() {}
 
 const RootLive = Composition.live(RootComp, function* () {
   const greeting = yield* Greeting

package/src/scene/scene.ts

@@ -1,13 +1,14 @@
-import { Layer, Struct } from 'effect'
-import type { CompositionClass, CompositionService } from '../compose/composition'
+import { Layer, Predicate, Struct } from 'effect'
+import type {
+  AnyComposition,
+  CompositionClass,
+  CompositionId,
+  CompositionReflection,
+  HasExactCompositionId,
+} from '../compose/composition'
 import type { UiContract } from '../compose/ui'
 import type { EventOf } from '../event/event'
-import type {
-  EagerFeatureClass,
-  EngineServices,
-  FeatureRequirement,
-  ProvidedBy,
-} from '../feature/feature'
+import { type EagerFeatureClass, type FeatureRequirement, tree } from '../feature/feature'
 import { CurrentSeedOverrides } from '../internal/seeds'
 import type { SeedsOf } from '../state/stateGroup'
 import type { Bus } from '../runtime/bus'
@@ -16,88 +17,257 @@ import {
   type Instrumentation,
   noopInstrumentation,
 } from '../runtime/instrumentation'
+import type { EngineServices } from '../runtime/loop'
 
-export type MountedServices = CompositionService | Bus
+export type MountedServices = CompositionId<string> | Bus
 
-type BootEvent = EventOf<string, unknown>
+export type SceneCapture<C extends UiContract, S extends ReadonlyArray<unknown>, Result> = <
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  scene: CapturedScene<C, S, Services, P, N, Identity>,
+) => Result
+
+export type AnySceneCapture<Result> = <
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  scene: CapturedScene<C, S, Services, P, N, Identity>,
+) => Result
+
+interface SceneOptionalFields {
+  readonly boot: ReadonlyArray<BootEvent>
+  // Hosts record render spans outside the scene's layer context.
+  readonly instrumentation: Instrumentation
+}
+
+export interface AnySceneExternalApi extends Partial<SceneOptionalFields> {
+  readonly kind: 'Scene'
+  readonly composition: AnyComposition
+  readonly captureAny: <Result>(visit: AnySceneCapture<Result>) => Result
+}
+
+export type AnyScene = AnySceneExternalApi
 
 export interface Scene<
   C extends UiContract = UiContract,
   S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
-> {
+> extends AnySceneExternalApi {
+  readonly composition: AnyComposition & CompositionReflection<unknown, C, S>
+  readonly capture: <Result>(visit: SceneCapture<C, S, Result>) => Result
+}
+
+type BootEvent = EventOf<string, unknown>
+
+export interface CapturedScene<
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity = unknown,
+> extends Scene<C, S> {
   readonly kind: 'Scene'
-  readonly composition: CompositionClass<unknown, C, S>
-  readonly provide: ReadonlyArray<Layer.Layer<MountedServices, never, never>>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- presence-optional boot read as `scene.boot ?? []` across non-batch hosts (drive/proof/remote/react/editor); Option would break them
-  readonly boot?: ReadonlyArray<BootEvent>
-  // instrumentation on the scene (not only layers): host render spans live outside layer context
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- presence-optional carrier like `boot`; absent on every unprofiled scene, so Option would tax all authoring call sites
-  readonly instrumentation?: Instrumentation
+  readonly composition: CompositionClass<P, C, S, N, Identity>
+  readonly provide: ReadonlyArray<Layer.Layer<Services, never, never>>
+}
+
+interface SceneConfigOptionalFields {
+  readonly boot: ReadonlyArray<BootEvent>
+}
+
+export interface SceneConfig<Services> extends Partial<SceneConfigOptionalFields> {
+  readonly provide: ReadonlyArray<Layer.Layer<Services, never, never>>
+}
+
+type SceneConfigIncludingRootComposition<Services, N extends string, Identity> =
+  HasExactCompositionId<Services, N, Identity> extends true
+    ? SceneConfig<Services>
+    : SceneConfig<Services> & {
+        readonly missingCompositionService: 'The scene must provide its root composition'
+      }
+
+interface SceneValueConfigExternalApi<Services>
+  extends SceneConfig<Services>, Partial<Pick<SceneOptionalFields, 'instrumentation'>> {}
+
+const makeSceneValue = <
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  Services,
+>(
+  composition: CompositionClass<P, C, S, N, Identity>,
+  config: SceneValueConfigExternalApi<Services>,
+): CapturedScene<C, S, Services, P, N, Identity> => {
+  const sceneValue: CapturedScene<C, S, Services, P, N, Identity> = {
+    kind: 'Scene',
+    composition,
+    provide: config.provide,
+    ...(config.boot !== undefined ? { boot: config.boot } : {}),
+    ...(config.instrumentation !== undefined ? { instrumentation: config.instrumentation } : {}),
+    capture: <Result>(visit: SceneCapture<C, S, Result>): Result => visit(sceneValue),
+    captureAny: <Result>(visit: AnySceneCapture<Result>): Result => visit(sceneValue),
+  }
+  return sceneValue
 }
 
-export interface SceneConfig {
-  readonly provide: ReadonlyArray<Layer.Layer<MountedServices, never, never>>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- mirrors Scene.boot; presence-optional to keep the authoring call site terse and back-compatible
-  readonly boot?: ReadonlyArray<BootEvent>
+export const scene = <
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  Services,
+>(
+  composition: CompositionClass<P, C, S, N, Identity>,
+  config: SceneConfigIncludingRootComposition<Services, N, Identity>,
+): CapturedScene<C, S, Services, P, N, Identity> => {
+  return makeSceneValue(composition, config)
 }
 
-export const scene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
-  composition: CompositionClass<unknown, C, S>,
-  config: SceneConfig,
-): Scene<C, S> => ({
-  kind: 'Scene',
-  composition,
-  provide: config.provide,
-  ...(config.boot !== undefined ? { boot: config.boot } : {}),
-})
-
-export interface FeatureSceneConfig<
-  Requires extends ReadonlyArray<FeatureRequirement>,
-> {
-  readonly provide: Layer.Layer<EngineServices | ProvidedBy<Requires>, never, never>
+export interface FeatureSceneConfig<OpenServices> {
+  readonly provide: Layer.Layer<EngineServices | OpenServices, never, never>
 }
 
 export const featureScene = <
+  FeatureIdentity,
   P,
   C extends UiContract,
   ROut,
-  Requires extends ReadonlyArray<FeatureRequirement>,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
+  OpenServices,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
 >(
-  feature: EagerFeatureClass<P, C, ROut, Requires>,
-  config: FeatureSceneConfig<Requires>,
-): Scene<C> => {
-  const app = feature.eagerModule.layer.pipe(Layer.provideMerge(config.provide))
-  // oxlint-disable-next-line reform-rules/no-type-assertion -- close the generic root module's erased output to the host-readable Scene subset
-  const closed = app as Layer.Layer<MountedServices, never, never>
-  return scene(feature.composition, {
-    provide: [closed],
-    boot: feature.binding.boot,
+  feature: EagerFeatureClass<
+    FeatureIdentity,
+    P,
+    C,
+    ROut,
+    DirectRequires,
+    OpenServices,
+    S,
+    N,
+    Identity
+  >,
+  config: FeatureSceneConfig<OpenServices>,
+): CapturedScene<C, S, ROut | EngineServices | OpenServices, P, N, Identity> => {
+  const native = tree<typeof feature>(feature.token)
+  const app = native.eagerModule.layer.pipe(Layer.provideMerge(config.provide))
+  return makeSceneValue(native.composition, {
+    provide: [app],
+    boot: native.binding.boot,
   })
 }
 
-// Tooling seam: wrap closed layers with seed overrides; keys are member names (not group names)
-export const seedScene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
+export function seedScene<
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  base: CapturedScene<C, S, Services, P, N, Identity>,
+  seeds: SeedsOf<S>,
+): CapturedScene<C, S, Services, P, N, Identity>
+export function seedScene<C extends UiContract, S extends ReadonlyArray<unknown>>(
   base: Scene<C, S>,
   seeds: SeedsOf<S>,
-): Scene<C, S> =>
-  Struct.keys(seeds).length === 0
-    ? base
-    : { ...base, provide: base.provide.map(Layer.locally(CurrentSeedOverrides, seeds)) }
+): Scene<C, S>
+export function seedScene<C extends UiContract, S extends ReadonlyArray<unknown>>(
+  base: Scene<C, S>,
+  seeds: SeedsOf<S>,
+): Scene<C, S> {
+  if (Struct.keys(seeds).length === 0) {
+    return base
+  }
+  // Tooling overlays closed layers; member names, not group names, are the keys.
+  return base.capture<Scene<C, S>>(
+    (exactScene): Scene<C, S> =>
+      makeSceneValue(exactScene.composition, {
+        provide: exactScene.provide.map(Layer.locally(CurrentSeedOverrides, seeds)),
+        ...(exactScene.boot === undefined ? {} : { boot: exactScene.boot }),
+        ...(exactScene.instrumentation === undefined
+          ? {}
+          : { instrumentation: exactScene.instrumentation }),
+      }),
+  )
+}
 
-export const profiledScene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
+export const seedAnyScene = (
+  base: AnyScene,
+  seeds: Readonly<Record<string, unknown>>,
+): AnyScene => {
+  if (Struct.keys(seeds).length === 0) {
+    return base
+  }
+  return base.captureAny<AnyScene>(
+    (exactScene): AnyScene =>
+      makeSceneValue(exactScene.composition, {
+        provide: exactScene.provide.map(Layer.locally(CurrentSeedOverrides, seeds)),
+        ...(exactScene.boot === undefined ? {} : { boot: exactScene.boot }),
+        ...(exactScene.instrumentation === undefined
+          ? {}
+          : { instrumentation: exactScene.instrumentation }),
+      }),
+  )
+}
+
+export function profiledScene<
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  base: CapturedScene<C, S, Services, P, N, Identity>,
+  instrumentation: Instrumentation,
+): CapturedScene<C, S, Services, P, N, Identity>
+export function profiledScene<C extends UiContract, S extends ReadonlyArray<unknown>>(
+  base: Scene<C, S>,
+  instrumentation: Instrumentation,
+): Scene<C, S>
+export function profiledScene<C extends UiContract, S extends ReadonlyArray<unknown>>(
   base: Scene<C, S>,
   instrumentation: Instrumentation,
-): Scene<C, S> => ({
-  ...base,
-  instrumentation,
-  provide: base.provide.map(Layer.locally(CurrentInstrumentation, instrumentation)),
-})
+): Scene<C, S> {
+  return base.capture<Scene<C, S>>(
+    (exactScene): Scene<C, S> =>
+      makeSceneValue(exactScene.composition, {
+        provide: exactScene.provide.map(Layer.locally(CurrentInstrumentation, instrumentation)),
+        ...(exactScene.boot === undefined ? {} : { boot: exactScene.boot }),
+        instrumentation,
+      }),
+  )
+}
 
-export const sceneInstrumentation = (candidate: Scene): Instrumentation =>
+export const sceneInstrumentation = (candidate: AnyScene): Instrumentation =>
   candidate.instrumentation ?? noopInstrumentation
 
-export const isScene = (candidate: unknown): candidate is Scene =>
-  typeof candidate === 'object' &&
-  candidate !== null &&
-  'kind' in candidate &&
-  candidate.kind === 'Scene'
+const isReflectableComposition = (candidate: unknown): candidate is AnyComposition =>
+  typeof candidate === 'function' &&
+  Predicate.hasProperty(candidate, 'manifest') &&
+  Predicate.isRecord(candidate.manifest) &&
+  candidate.manifest['kind'] === 'Composition' &&
+  Predicate.hasProperty(candidate, 'parseProps') &&
+  typeof candidate.parseProps === 'function' &&
+  Predicate.hasProperty(candidate, 'capture') &&
+  typeof candidate.capture === 'function'
+
+export const isScene = (candidate: unknown): candidate is AnyScene =>
+  Predicate.isRecord(candidate) &&
+  candidate['kind'] === 'Scene' &&
+  isReflectableComposition(candidate['composition']) &&
+  typeof candidate['capture'] === 'function' &&
+  typeof candidate['captureAny'] === 'function'