@playfast/reform 1.0.1 → 1.2.0

package/src/remote/remoteState.typecheck.ts

@@ -1,13 +1,8 @@
-// Type-level proofs enforced by `tsc --noEmit` over `src` (not a vitest file).
-// These guard the cast-free seam: if a guarantee regresses, a `@ts-expect-error`
-// goes unused or an assignment fails, and `tsc` breaks.
-
 import { Context, Effect, Layer, Match, Schema as S } from 'effect'
 import * as Boundary from '../boundary/boundary'
 import type { AsyncData } from '../calc/asyncData'
 import { type Channels, type Procedures } from '../channel/channel'
 import * as Event from '../event/event'
-import type { Store } from '../internal/store'
 import * as Reducer from '../reducer/reducer'
 import type { Bus } from '../runtime/bus'
 import { type Reducers } from '../runtime/loop'
@@ -16,8 +11,10 @@ import * as StateGroup from '../state/stateGroup'
 import { type AnySource, type Source } from '../state/token'
 import * as RemoteState from './remoteState'
 
-const AddIntentBase: Event.EventClass<'TAddIntent', { readonly id: string; readonly name: string }> =
-  Event.make('TAddIntent', S.Struct({ id: S.String, name: S.String }))
+const AddIntentBase: Event.EventClass<
+  'TAddIntent',
+  { readonly id: string; readonly name: string }
+> = Event.make('TAddIntent', S.Struct({ id: S.String, name: S.String }))
 class AddIntent extends AddIntentBase {}
 const RenameIntentBase: Event.EventClass<
   'TRenameIntent',
@@ -25,15 +22,16 @@ const RenameIntentBase: Event.EventClass<
 > = Event.make('TRenameIntent', S.Struct({ id: S.String, name: S.String }))
 class RenameIntent extends RenameIntentBase {}
 type Intent = Event.EventType<typeof AddIntent> | Event.EventType<typeof RenameIntent>
-// An undeclared intent tag, named so the negative `apply` below avoids an inline
-// object-type parameter.
 type DeleteIntentTag = { readonly _tag: 'TDeleteIntent' }
 
 const PageBase: State.StateClass<'tcPage', number> = State.make('tcPage', S.Number)
 class Page extends PageBase {}
 const InputsBase: StateGroup.StateGroupClass<readonly [typeof Page]> = StateGroup.make(Page)
 class Inputs extends InputsBase {}
-const page: Source<'tcPage', number> = StateGroup.select(Inputs, 'tcPage')
+const page: Source<'tcPage', number, State.StateStore<'tcPage', number>> = StateGroup.select(
+  Inputs,
+  'tcPage',
+)
 
 const Row: S.Struct<{ id: typeof S.String; name: typeof S.String }> = S.Struct({
   id: S.String,
@@ -63,15 +61,12 @@ const ItemsBase: RemoteState.RemoteStateClass<
 })
 class Items extends ItemsBase {}
 
-// --- intent-union inference: apply/send receive exactly the declared union ---
-
-// POSITIVE: a Match.exhaustive fold over the declared intents compiles, `send`'s
-// R2 flows from its body, and gated `disabled` is accepted.
 export const okLive: Layer.Layer<
-  | Store<AsyncData<ReadonlyArray<Row>, string, true>>
-  | Store<ReadonlyArray<RemoteState.PendingIntent<Intent>>>,
+  | RemoteState.RemoteStateVisibleStore<'TItems'>
+  | RemoteState.RemoteStateTruthStore<'TItems'>
+  | RemoteState.RemoteStatePendingStore<'TItems'>,
   never,
-  Store<number> | SendDep | Reducers | Procedures | Channels | Bus
+  State.StateStore<'tcPage', number> | SendDep | Reducers | Procedures | Channels | Bus
 > = RemoteState.live(Items, {
   query: ({ tcPage }) =>
     tcPage > 0 ? Effect.succeed<ReadonlyArray<Row>>([]) : Effect.fail('empty page'),
@@ -87,12 +82,12 @@ export const okLive: Layer.Layer<
   disabled: ({ tcPage }) => tcPage < 0,
 })
 
-// NEGATIVE: a handler typed for an undeclared tag does not fit the union.
 export const badIntent: Layer.Layer<
-  | Store<AsyncData<ReadonlyArray<Row>, string, true>>
-  | Store<ReadonlyArray<RemoteState.PendingIntent<Intent>>>,
+  | RemoteState.RemoteStateVisibleStore<'TItems'>
+  | RemoteState.RemoteStateTruthStore<'TItems'>
+  | RemoteState.RemoteStatePendingStore<'TItems'>,
   never,
-  Store<number> | Reducers | Procedures | Channels | Bus
+  State.StateStore<'tcPage', number> | Reducers | Procedures | Channels | Bus
 > = RemoteState.live(Items, {
   query: () => Effect.succeed<ReadonlyArray<Row>>([]),
   send: () => Effect.void,
@@ -100,27 +95,23 @@ export const badIntent: Layer.Layer<
   apply: (rows: ReadonlyArray<Row>, intent: DeleteIntentTag) => rows,
 })
 
-// --- layer requirement honesty: RIn is complete and exact ---
-
-// POSITIVE: the layer's RIn is exactly the input stores, the query/send context,
-// and the engine registries — and its ROut names the overlay + pending stores.
 export const okLayer: Layer.Layer<
-  Store<AsyncData<ReadonlyArray<Row>, string, true>> | Store<ReadonlyArray<RemoteState.PendingIntent<Intent>>>,
+  | RemoteState.RemoteStateVisibleStore<'TItems'>
+  | RemoteState.RemoteStateTruthStore<'TItems'>
+  | RemoteState.RemoteStatePendingStore<'TItems'>,
   never,
-  Store<number> | SendDep | Reducers | Procedures | Channels | Bus
+  State.StateStore<'tcPage', number> | SendDep | Reducers | Procedures | Channels | Bus
 > = okLive
 
-// NEGATIVE: dropping the send dependency (R2) from the annotation fails —
-// requirements cannot be silently widened away.
 // @ts-expect-error the send body's R2 must appear in the layer's requirements
 export const badLayer: Layer.Layer<
-  Store<AsyncData<ReadonlyArray<Row>, string, true>> | Store<ReadonlyArray<RemoteState.PendingIntent<Intent>>>,
+  | RemoteState.RemoteStateVisibleStore<'TItems'>
+  | RemoteState.RemoteStateTruthStore<'TItems'>
+  | RemoteState.RemoteStatePendingStore<'TItems'>,
   never,
-  Store<number> | Reducers | Procedures | Channels | Bus
+  State.StateStore<'tcPage', number> | Reducers | Procedures | Channels | Bus
 > = okLive
 
-// --- alwaysOn / error narrowing: the read carries exactly the possible arms ---
-
 const AlwaysItemsBase: RemoteState.RemoteStateClass<
   'TAlwaysItems',
   readonly [typeof page],
@@ -136,12 +127,12 @@ const AlwaysItemsBase: RemoteState.RemoteStateClass<
 })
 class AlwaysItems extends AlwaysItemsBase {}
 
-// NEGATIVE: an alwaysOn remote state rejects `disabled` (erased to never).
 export const badDisabled: Layer.Layer<
-  | Store<AsyncData<ReadonlyArray<Row>, never, false>>
-  | Store<ReadonlyArray<RemoteState.PendingIntent<Event.EventType<typeof AddIntent>>>>,
+  | RemoteState.RemoteStateVisibleStore<'TAlwaysItems'>
+  | RemoteState.RemoteStateTruthStore<'TAlwaysItems'>
+  | RemoteState.RemoteStatePendingStore<'TAlwaysItems'>,
   never,
-  Store<number> | Reducers | Procedures | Channels | Bus
+  State.StateStore<'tcPage', number> | Reducers | Procedures | Channels | Bus
 > = RemoteState.live(AlwaysItems, {
   query: () => Effect.succeed<ReadonlyArray<Row>>([]),
   send: () => Effect.void,
@@ -156,41 +147,41 @@ declare const idleArm: 'Idle'
 declare const errorArm: 'Error'
 declare const fourArms: 'Idle' | 'Loading' | 'Success' | 'Error'
 
-// POSITIVE: alwaysOn + no `error` schema ⇒ at most Loading | Success…
 export const alwaysExact: 'Loading' | 'Success' = alwaysArms
-// …and gated + `error` schema ⇒ exactly all four arms (both directions).
 export const gatedSubset: 'Idle' | 'Loading' | 'Success' | 'Error' = gatedArms
 export const gatedAll: Effect.Effect.Success<typeof Items>['_tag'] = fourArms
 
-// NEGATIVE: the excluded arms really are gone from the read type.
 // @ts-expect-error an alwaysOn remote state has no Idle arm
 export const noIdle: Effect.Effect.Success<typeof AlwaysItems>['_tag'] = idleArm
 // @ts-expect-error no `error` schema ⇒ no Error arm
 export const noError: Effect.Effect.Success<typeof AlwaysItems>['_tag'] = errorArm
 
-// --- surface shape: Sources where expected, never a reducer target ---
-
-// POSITIVE: the class itself is a `Source` (a calc input / boundary coverage),
-// valued at the overlaid lifecycle.
-export const classAsSource: Source<'TItems', AsyncData<ReadonlyArray<Row>, string, true>> = Items
+export const classAsSource: Source<
+  'TItems',
+  AsyncData<ReadonlyArray<Row>, string, true>,
+  RemoteState.RemoteStateVisibleStore<'TItems'>
+> = Items
 export const classAsAnySource: AnySource = Items
 
-// POSITIVE: `pending` is an ordinary read-only `Source` (badges, "saving…" chrome).
-export const pendingAsSource: Source<'TItems/pending', ReadonlyArray<RemoteState.PendingIntent<Intent>>> =
-  Items.pending
+export const pendingAsSource: Source<
+  'TItems/pending',
+  ReadonlyArray<RemoteState.PendingIntent<Intent>>,
+  RemoteState.RemoteStatePendingStore<'TItems'>
+> = Items.pending
 
-// POSITIVE: `truth` is the un-overlaid lifecycle under the same arms.
-export const truthAsSource: Source<'TItems/truth', AsyncData<ReadonlyArray<Row>, string, true>> =
-  Items.truth
+export const truthAsSource: Source<
+  'TItems/truth',
+  AsyncData<ReadonlyArray<Row>, string, true>,
+  RemoteState.RemoteStateTruthStore<'TItems'>
+> = Items.truth
 
-// POSITIVE: a boundary covers the remote state like any lifecycle source.
 export const covered: Boundary.BoundaryClass<'TItemsBoundary', readonly [typeof Items]> =
   Boundary.make('TItemsBoundary', { over: [Items] })
 
-// NEGATIVE: the pending queue is NOT user state — `Reducer.make` cannot target
-// it (it is a `StateToken`, not a `StateClass`; the hidden queue reducer is the
-// sole writer).
-export const badReducerTarget: Reducer.StateReducerClass<State.AnyState, readonly [typeof AddIntent]> =
+export const badReducerTarget: Reducer.StateReducerClass<
+  State.AnyState,
+  readonly [typeof AddIntent]
+> =
   // @ts-expect-error the pending queue is not a reducible state
   Reducer.make('TBadReducer', {
     states: [Items.pending],

package/src/runtime/appRuntime.activation.test.ts

@@ -0,0 +1,100 @@
+import { Context, Duration, Effect, Layer, Option, Schema } from 'effect'
+import { expect, it } from '@effect/vitest'
+import * as Composition from '../compose/composition'
+import { mount } from '../compose/structure'
+import { ui } from '../compose/ui'
+import { scene } from '../scene/scene'
+import { Engine } from './loop'
+import { makeAppRuntime } from './appRuntime'
+
+interface ActivationProbeService {
+  readonly acquired: Array<string>
+  readonly released: Array<string>
+}
+
+class ActivationProbe extends Context.Tag('appRuntime.ActivationProbe')<
+  ActivationProbe,
+  ActivationProbeService
+>() {}
+
+class ScopedUi extends ui('appRuntime.ScopedUi')<{
+  props: { readonly id: string }
+}>() {}
+
+class ScopedComposition extends Composition.make('appRuntime.Scoped', {
+  title: 'Scoped',
+  props: Schema.Struct({ id: Schema.String }),
+  ui: ScopedUi,
+})<ScopedComposition>() {}
+
+const ScopedLive = Composition.liveScoped(ScopedComposition, {
+  render: function* () {
+    const { id } = yield* ScopedComposition.props
+    return mount({ props: { id }, slots: {} })
+  },
+  activate: function* () {
+    const { id } = yield* ScopedComposition.props
+    const probe = yield* ActivationProbe
+    yield* Effect.acquireRelease(
+      Effect.sync(() => probe.acquired.push(id)),
+      () => Effect.sync(() => probe.released.push(id)),
+    )
+  },
+})
+
+class PlainUi extends ui('appRuntime.PlainUi')<{ props: {} }>() {}
+class PlainComposition extends Composition.make('appRuntime.Plain', {
+  title: 'Plain',
+  ui: PlainUi,
+})<PlainComposition>() {}
+
+const PlainLive = Composition.live(PlainComposition, function* () {
+  return mount({ props: {}, slots: {} })
+})
+
+const makeScene = (probe: ActivationProbeService) =>
+  scene(ScopedComposition, {
+    provide: [
+      Layer.mergeAll(ScopedLive, PlainLive).pipe(
+        Layer.provideMerge(Layer.succeed(ActivationProbe, probe)),
+        Layer.provideMerge(Engine),
+      ),
+    ],
+  })
+
+const settle = Effect.sleep(Duration.millis(50))
+
+it.scopedLive(
+  'keeps activation lazy, scopes sibling mounts independently, and closes them at teardown',
+  () =>
+    Effect.gen(function* () {
+      const probe: ActivationProbeService = { acquired: [], released: [] }
+      const app = makeAppRuntime(makeScene(probe))
+      yield* Effect.addFinalizer(() => Effect.sync(() => app.dispose()))
+      const service = app.read(ScopedComposition.tag)
+      const plain = app.read(PlainComposition.tag)
+
+      yield* Composition.render(service, {
+        props: { id: 'first' },
+        tracker: { add: () => undefined },
+      })
+      expect(probe.acquired).toEqual([])
+      expect(Option.isNone(Composition.activation(plain, {}))).toBe(true)
+
+      const first = app.mountScoped(
+        Option.getOrThrow(Composition.activation(service, { id: 'first' })),
+      )
+      app.mountScoped(Option.getOrThrow(Composition.activation(service, { id: 'second' })))
+      yield* settle
+      expect(probe.acquired).toEqual(['first', 'second'])
+
+      first()
+      first()
+      yield* settle
+      expect(probe.released).toEqual(['first'])
+
+      app.dispose()
+      yield* settle
+      expect(probe.released).toEqual(['first', 'second'])
+    }),
+)

package/src/runtime/appRuntime.test.ts

@@ -0,0 +1,249 @@
+import { Context, Duration, Effect, Layer, Option, Schema as S } from 'effect'
+import { expect, it } from '@effect/vitest'
+import * as Composition from '../compose/composition'
+import { provide } from '../compose/provide'
+import { mount } from '../compose/structure'
+import * as Ui from '../compose/ui'
+import { ui } from '../compose/ui'
+import * as Event from '../event/event'
+import * as Feature from '../feature/feature'
+import { featureModule } from '../feature/feature'
+import * as Reducer from '../reducer/reducer'
+import { scene } from '../scene/scene'
+import * as State from '../state/state'
+import { Engine, Reducers } from './loop'
+import { makeAppRuntime } from './appRuntime'
+
+// The host-level mount lifecycle: `RuntimeHandle.mountFeature` forks the mount,
+// and its disposer must CANCEL a mount whose fiber has not run yet (StrictMode
+// cleanup/setup, fast remounts) — a scope close alone does not interrupt, so a
+// stale mount would still register reducers and dispatch `binding.boot` onto the
+// shared bus.
+
+class Tick extends Event.make('appRuntime.Tick', S.Struct({})) {}
+class Count extends State.make('appRuntime.count', S.Number) {}
+class CountReducer extends Reducer.make('appRuntime.CountReducer', {
+  states: [Count],
+  events: [Tick],
+}) {}
+
+class CtrUi extends ui('appRuntime.CtrUi')<{ props: {} }>() {}
+class CtrComp extends Composition.make('appRuntime.CtrComp', {
+  title: 'Counter',
+  ui: CtrUi,
+})<CtrComp>() {}
+const CtrLive = Composition.live(CtrComp, function* () {
+  return mount({ props: {}, slots: {}, events: {} })
+})
+
+class CounterFeature extends Feature.make('appRuntime.counter', {
+  composition: CtrComp,
+  module: featureModule(
+    [],
+    Layer.merge(
+      CtrLive,
+      Reducer.live(CountReducer, (n) => n + 1).pipe(Layer.provideMerge(State.live(Count, 0))),
+    ),
+  ),
+  boot: [Event.construct(Tick, {})],
+}) {}
+
+class RootUi extends ui('appRuntime.RootUi')<{ props: {} }>() {}
+class RootComp extends Composition.make('appRuntime.RootComp', {
+  title: 'Root',
+  ui: RootUi,
+})<RootComp>() {}
+const RootLive = Composition.live(RootComp, function* () {
+  return mount({ props: {}, slots: {}, events: {} })
+})
+
+const rootScene = () =>
+  scene(RootComp, {
+    provide: [
+      RootLive.pipe(
+        Layer.provideMerge(
+          provide(
+            RootUi,
+            Ui.make(RootUi, () => null),
+          ),
+        ),
+        Layer.provideMerge(Engine),
+      ),
+    ],
+  })
+
+const settle = Effect.sleep(Duration.millis(50))
+const appRuntime = Effect.acquireRelease(
+  Effect.sync(() => makeAppRuntime(rootScene())),
+  (app) => Effect.sync(() => app.dispose()),
+)
+
+interface ParentValueService {
+  readonly value: string
+}
+const ParentValueBase: Context.TagClass<ParentValue, 'appRuntime.ParentValue', ParentValueService> =
+  Context.Tag('appRuntime.ParentValue')<ParentValue, ParentValueService>()
+class ParentValue extends ParentValueBase {}
+
+interface ChildValueService {
+  readonly value: string
+}
+const ChildValueBase: Context.TagClass<ChildValue, 'appRuntime.ChildValue', ChildValueService> =
+  Context.Tag('appRuntime.ChildValue')<ChildValue, ChildValueService>()
+class ChildValue extends ChildValueBase {}
+
+class ParentFeature extends Feature.make('appRuntime.parent', {
+  composition: CtrComp,
+  module: featureModule(
+    [],
+    Layer.merge(CtrLive, Layer.succeed(ParentValue, { value: 'from-parent' })),
+  ),
+}) {}
+
+class ChildFeature extends Feature.make('appRuntime.child', {
+  composition: CtrComp,
+  module: featureModule(
+    [ParentValue],
+    Layer.merge(
+      CtrLive,
+      Layer.effect(
+        ChildValue,
+        Effect.map(ParentValue, ({ value }) => ({ value })),
+      ),
+    ),
+  ),
+}) {}
+
+const CounterNative = Feature.tree<typeof CounterFeature>(CounterFeature.token)
+const ParentNative = Feature.tree<typeof ParentFeature>(ParentFeature.token)
+const ChildNative = Feature.tree<typeof ChildFeature>(ChildFeature.token)
+
+it.scopedLive(
+  'disposing a mount before its fiber runs cancels it — no registration, no boot, no handler calls',
+  () =>
+    Effect.gen(function* () {
+      const app = yield* appRuntime
+      const baseline = app.read(Reducers).entries.length
+      const calls = { live: 0, failed: 0 }
+      const dispose = app.mountFeature(CounterNative.binding, {
+        onLive: () => {
+          calls.live += 1
+        },
+        onFailed: () => {
+          calls.failed += 1
+        },
+      })
+      // Same-tick dispose (the StrictMode cleanup shape): the fork has not run yet.
+      dispose()
+      yield* settle
+      expect(calls).toEqual({ live: 0, failed: 0 })
+      expect(app.read(Reducers).entries.length).toBe(baseline)
+      expect(app.read(Reducers).byTag.get('appRuntime.Tick')).toBeUndefined()
+    }),
+)
+
+it.scopedLive(
+  'an undisposed mount still goes live, and disposing it after live reclaims the registration',
+  () =>
+    Effect.gen(function* () {
+      const app = yield* appRuntime
+      const baseline = app.read(Reducers).entries.length
+      const calls = { live: 0, failed: 0 }
+      const dispose = app.mountFeature(CounterNative.binding, {
+        onLive: () => {
+          calls.live += 1
+        },
+        onFailed: () => {
+          calls.failed += 1
+        },
+      })
+      yield* Effect.sleep(Duration.millis(1)).pipe(
+        Effect.repeat({ until: () => calls.live === 1 }),
+        Effect.timeout(Duration.seconds(2)),
+      )
+      expect(calls).toEqual({ live: 1, failed: 0 })
+      expect(app.read(Reducers).entries.length).toBe(baseline + 1)
+      dispose()
+      yield* settle
+      expect(app.read(Reducers).entries.length).toBe(baseline)
+    }),
+)
+
+it.scopedLive('a nested Feature mounts against its immediate parent context', () =>
+  Effect.gen(function* () {
+    const app = yield* appRuntime
+    const observed: Array<string> = []
+    const disposers: Array<() => void> = []
+    yield* Effect.addFinalizer(() =>
+      Effect.sync(() => disposers.reverse().forEach((dispose) => dispose())),
+    )
+    disposers.push(
+      app.mountFeature(ParentNative.binding, {
+        onFailed: () => observed.push('parent-failed'),
+        onLive: (parent) => {
+          disposers.push(
+            parent.mountFeature(ChildNative.binding, {
+              onFailed: () => observed.push('child-failed'),
+              onLive: (child) => observed.push(child.read(ChildValue).value),
+            }),
+          )
+        },
+      }),
+    )
+    yield* Effect.sleep(Duration.millis(1)).pipe(
+      Effect.repeat({ until: () => observed.length > 0 }),
+      Effect.timeout(Duration.seconds(2)),
+    )
+    expect(observed).toEqual(['from-parent'])
+  }),
+)
+
+it.scopedLive(
+  'an existential Feature binding validates its graph and exposes only safe optional reads',
+  () =>
+    Effect.gen(function* () {
+      const app = yield* appRuntime
+      const observed: Array<string> = []
+      const binding: Feature.AnyFeatureBinding = ParentNative.binding
+      const dispose = app.mountAnyFeature(binding, {
+        props: {},
+        onFailed: () => observed.push('failed'),
+        onLive: (child) => {
+          const service = child.readOption(ParentValue)
+          observed.push(
+            Option.match(service, {
+              onNone: () => 'missing',
+              onSome: ({ value }) => value,
+            }),
+          )
+        },
+      })
+      yield* Effect.addFinalizer(() => Effect.sync(dispose))
+      yield* Effect.sleep(Duration.millis(1)).pipe(
+        Effect.repeat({ until: () => observed.length > 0 }),
+        Effect.timeout(Duration.seconds(2)),
+      )
+      expect(observed).toEqual(['from-parent'])
+    }),
+)
+
+it.scopedLive(
+  'an existential Feature binding fails before build when a requirement is absent',
+  () =>
+    Effect.gen(function* () {
+      const app = yield* appRuntime
+      const observed: Array<string> = []
+      const binding: Feature.AnyFeatureBinding = ChildNative.binding
+      const dispose = app.mountAnyFeature(binding, {
+        props: {},
+        onFailed: () => observed.push('failed'),
+        onLive: () => observed.push('live'),
+      })
+      yield* Effect.addFinalizer(() => Effect.sync(dispose))
+      yield* Effect.sleep(Duration.millis(1)).pipe(
+        Effect.repeat({ until: () => observed.length > 0 }),
+        Effect.timeout(Duration.seconds(2)),
+      )
+      expect(observed).toEqual(['failed'])
+    }),
+)