@playfast/reform 1.0.1 → 1.1.1

package/src/scene/seedScene.test.ts

@@ -1,5 +1,5 @@
-import { Effect, Layer, ManagedRuntime, Schema as S } from 'effect'
-import { expect, test } from 'vitest'
+import { Effect, Layer, Schema as S } from "effect";
+import { expect, it } from "@effect/vitest";
 import {
   Composition,
   Engine,
@@ -17,93 +17,84 @@ import {
   StateGroup,
   Ui,
   ui,
-} from '../index'
-import { CurrentSeedOverrides } from '../internal/seeds'
+} from "../index";
+import { CurrentSeedOverrides } from "../internal/seeds";
 
-// `seedScene` is the tooling seam over CLOSED scenes: the app bundle below seeds
-// `count: 1` itself (no open store), and the overlay must reach the nested
-// `State.live` through `Layer.locally(CurrentSeedOverrides, …)` on the scene's
-// pre-composed layers. The harness mirrors the dev-tool preview: merge the
-// scene's `provide`, mount it in a ManagedRuntime, and read the root
-// composition's rendered props through the headless Structure.
-
-class CountState extends State.make('count', S.Number) {}
+class CountState extends State.make("count", S.Number) {}
 class MiniStates extends StateGroup.make(CountState) {}
 
-class Bumped extends Event.make('Bumped', S.Struct({})) {}
+class Bumped extends Event.make("Bumped", S.Struct({})) {}
 
-class BumpReducer extends Reducer.make('BumpReducer', {
+class BumpReducer extends Reducer.make("BumpReducer", {
   states: [CountState],
   events: [Bumped],
 }) {}
-const BumpReducerLive = Reducer.live(BumpReducer, (n) => n + 1)
+const BumpReducerLive = Reducer.live(BumpReducer, (n) => n + 1);
 
-class CounterUi extends ui('Counter')<{ props: { count: number } }>() {}
-class Counter extends Composition.make('Counter', {
-  title: 'Counter',
+class CounterUi extends ui("Counter")<{ props: { count: number } }>() {}
+class Counter extends Composition.make("Counter", {
+  title: "Counter",
   states: [MiniStates],
   events: [Bumped],
   ui: CounterUi,
 }) {}
 const CounterLive = Composition.live(Counter, function* () {
-  const count = yield* StateGroup.select(MiniStates, 'count')
-  return mount({ props: { count }, slots: {} })
-})
-
-// The closed app layer a scene provides: views + logic + Engine, with the state
-// group seeding its AUTHORED value `count: 1` itself.
-const presentations = provide(CounterUi, Ui.make(CounterUi, () => null))
-const Views = CounterLive.pipe(Layer.provideMerge(presentations))
+  const count = yield* StateGroup.select(MiniStates, "count");
+  return mount({ props: { count }, slots: {} });
+});
+
+const presentations = provide(
+  CounterUi,
+  Ui.make(CounterUi, () => null),
+);
+const Views = CounterLive.pipe(Layer.provideMerge(presentations));
 const Logic = Layer.mergeAll(BumpReducerLive).pipe(
-  Layer.provideMerge(Layer.mergeAll(Engine, StateGroup.live(MiniStates, { count: 1 }))),
-)
-const MiniApp = Views.pipe(Layer.provideMerge(Logic))
-
-const CounterScene = scene(Counter, { provide: [MiniApp] })
-
-// The dev-tool inspector overlays raw, user-typed seeds (`Record<string, unknown>`)
-// — the untyped seam that `seedScene` wraps once a composition's state tuple is
-// known. These two cases (absent key / schema-invalid value) are compile errors
-// through the now-typed `seedScene`, so they're exercised here at the raw overlay
-// to prove `resolveSeed`'s runtime defensiveness still falls back to the seed.
-const overlayRawSeeds = (base: Scene, seeds: Readonly<Record<string, unknown>>): Scene => ({
+  Layer.provideMerge(
+    Layer.mergeAll(Engine, StateGroup.live(MiniStates, { count: 1 })),
+  ),
+);
+const MiniApp = Views.pipe(Layer.provideMerge(Logic));
+
+const CounterScene = scene(Counter, { provide: [MiniApp] });
+
+const overlayRawSeeds = (
+  base: Scene,
+  seeds: Readonly<Record<string, unknown>>,
+): Scene => ({
   ...base,
   provide: base.provide.map(Layer.locally(CurrentSeedOverrides, seeds)),
-})
+});
 
 const headlessEnv: RenderEnv = {
   props: {},
   tracker: { add: () => {} },
-}
+};
 
 const isCountProps = (props: unknown): props is { readonly count: number } =>
-  typeof props === 'object' &&
+  typeof props === "object" &&
   props !== null &&
-  'count' in props &&
-  typeof props.count === 'number'
+  "count" in props &&
+  typeof props.count === "number";
 
-// One ManagedRuntime per scene under test. Each `read` re-renders the root
-// composition and reads the Structure built from the stores that runtime actually
-// constructed.
 const makeHarness = (s: Scene) => {
-  const layer = s.provide.reduce((a, b) => Layer.merge(a, b))
-  const runtime = ManagedRuntime.make(layer)
+  const layer = s.provide.reduce((a, b) => Layer.merge(a, b));
   const read = Effect.flatMap(Counter.tag, (c) =>
     Composition.render(c, headlessEnv).pipe(
       Effect.flatMap((frame) => {
         if (!isStructure(frame)) {
-          return Effect.dieMessage('Counter must render a Structure')
+          return Effect.dieMessage("Counter must render a Structure");
         }
         return isCountProps(frame.props)
           ? Effect.succeed(frame.props.count)
-          : Effect.dieMessage('Counter Structure props must include numeric count')
+          : Effect.dieMessage(
+              "Counter Structure props must include numeric count",
+            );
       }),
     ),
-  )
-  return { runtime, read }
-}
+  );
+  return { layer, read };
+};
 
-// Drive a read until a predicate holds, handing forked fibers the scheduler.
 const waitUntil = <A, R>(
   read: Effect.Effect<A, never, R>,
   pred: (a: A) => boolean,
@@ -112,65 +103,54 @@ const waitUntil = <A, R>(
   Effect.flatMap(read, (a) =>
     pred(a) || rounds <= 0
       ? Effect.succeed(a)
-      : Effect.flatMap(Effect.yieldNow(), () => waitUntil(read, pred, rounds - 1)),
-  )
-
-test('a seeded scene boots its store from the override', async () => {
-  const { runtime, read } = makeHarness(seedScene(CounterScene, { count: 5 }))
-  try {
-    expect(await runtime.runPromise(read)).toBe(5)
-  } finally {
-    await runtime.dispose()
-  }
-})
-
-test('the live reducer drives the SAME overridden store', async () => {
-  const { runtime, read } = makeHarness(seedScene(CounterScene, { count: 5 }))
-  try {
-    const next = await runtime.runPromise(
-      Effect.gen(function* () {
-        expect(yield* read).toBe(5)
-        yield* publish('High', Event.construct(Bumped, {}))
-        return yield* waitUntil(read, (n) => n === 6)
-      }),
-    )
-    expect(next).toBe(6)
-  } finally {
-    await runtime.dispose()
-  }
-})
-
-test('an absent key leaves the authored seed in place', async () => {
-  const { runtime, read } = makeHarness(overlayRawSeeds(CounterScene, { other: 1 }))
-  try {
-    expect(await runtime.runPromise(read)).toBe(1)
-  } finally {
-    await runtime.dispose()
-  }
-})
-
-test('a schema-invalid override falls back to the authored seed', async () => {
-  const { runtime, read } = makeHarness(overlayRawSeeds(CounterScene, { count: 'not-a-number' }))
-  try {
-    expect(await runtime.runPromise(read)).toBe(1)
-  } finally {
-    await runtime.dispose()
-  }
-})
-
-test('seeding does not leak into the original scene', async () => {
-  const seeded = makeHarness(seedScene(CounterScene, { count: 5 }))
-  try {
-    expect(await seeded.runtime.runPromise(seeded.read)).toBe(5)
-  } finally {
-    await seeded.runtime.dispose()
-  }
-  // Building the ORIGINAL scene's layers again boots from the authored seed —
-  // the overlay lives only on the seeded variant's wrapped layers.
-  const original = makeHarness(CounterScene)
-  try {
-    expect(await original.runtime.runPromise(original.read)).toBe(1)
-  } finally {
-    await original.runtime.dispose()
-  }
-})
+      : Effect.flatMap(Effect.yieldNow(), () =>
+          waitUntil(read, pred, rounds - 1),
+        ),
+  );
+
+it.scopedLive("a seeded scene boots its store from the override", () => {
+  const { layer, read } = makeHarness(seedScene(CounterScene, { count: 5 }));
+  return Effect.gen(function* () {
+    expect(yield* read).toBe(5);
+  }).pipe(Effect.provide(layer));
+});
+
+it.scopedLive("the live reducer drives the SAME overridden store", () => {
+  const { layer, read } = makeHarness(seedScene(CounterScene, { count: 5 }));
+  return Effect.gen(function* () {
+    expect(yield* read).toBe(5);
+    yield* publish("High", Event.construct(Bumped, {}));
+    const next = yield* waitUntil(read, (n) => n === 6);
+    expect(next).toBe(6);
+  }).pipe(Effect.provide(layer));
+});
+
+it.scopedLive("an absent key leaves the authored seed in place", () => {
+  const { layer, read } = makeHarness(
+    overlayRawSeeds(CounterScene, { other: 1 }),
+  );
+  return Effect.gen(function* () {
+    expect(yield* read).toBe(1);
+  }).pipe(Effect.provide(layer));
+});
+
+it.scopedLive(
+  "a schema-invalid override falls back to the authored seed",
+  () => {
+    const { layer, read } = makeHarness(
+      overlayRawSeeds(CounterScene, { count: "not-a-number" }),
+    );
+    return Effect.gen(function* () {
+      expect(yield* read).toBe(1);
+    }).pipe(Effect.provide(layer));
+  },
+);
+
+it.scopedLive("seeding does not leak into the original scene", () => {
+  const seeded = makeHarness(seedScene(CounterScene, { count: 5 }));
+  const original = makeHarness(CounterScene);
+  return Effect.gen(function* () {
+    expect(yield* seeded.read.pipe(Effect.provide(seeded.layer))).toBe(5);
+    expect(yield* original.read.pipe(Effect.provide(original.layer))).toBe(1);
+  });
+});

package/src/state/state.ts

@@ -1,4 +1,5 @@
 import { Context, Effect, FiberRef, Layer, Option, Schema } from 'effect'
+import type { Effect as EffectType } from 'effect/Effect'
 import { type Manifest, yieldableClass } from '../definition/definition'
 import { resolveScheduler } from '../internal/scheduler'
 import { CurrentSeedOverrides } from '../internal/seeds'
@@ -6,6 +7,7 @@ import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentat
 import { claimStateTag } from '../internal/stateRegistry'
 import { makeStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
+import type { AnySchema, AnyValue } from '../internal/variance'
 
 export interface StateOptionsExternalApi {
   readonly title?: string
@@ -16,32 +18,25 @@ export type StateOptions = StateOptionsExternalApi
 export interface StateManifestExternalApi<N extends string, A> extends Manifest {
   readonly kind: 'State'
   readonly name: N
-  readonly schema: Schema.Schema<A, any>
+  readonly schema: AnySchema<A>
   readonly title?: string
   readonly description?: string
 }
 export type StateManifest<N extends string, A> = StateManifestExternalApi<N, A>
 
-export interface StateClass<out N extends string, in out A> extends Effect.Effect<A, never, Store<A>> {
+export interface StateClass<out N extends string, in out A> extends EffectType<A, never, Store<A>> {
   new (): {}
   readonly manifest: StateManifest<N, A>
-  /** Internal DI tag holding the live store. The loop reads/writes through it. */
   readonly store: Context.Tag<Store<A>, Store<A>>
 }
 
-export type AnyState = StateClass<string, any>
+export type AnyState = StateClass<string, AnyValue>
 export type StateValue<S> = S extends StateClass<string, infer A> ? A : never
-export type StateName<S> = S extends StateClass<infer N, any> ? N : never
+export type StateName<S> = S extends StateClass<infer N, AnyValue> ? N : never
 
-/**
- * Atomic reactive state. `State.make` is the *definition* (a reflectable
- * manifest + an internal store tag); it carries no starting value — the seed is
- * an implementation detail supplied at create-time by `State.live(state, seed)`.
- * Composed into a `StateGroup` exactly as `@effect/rpc` composes rpcs.
- */
 export const make = <const N extends string, A>(
   name: N,
-  schema: Schema.Schema<A, any>,
+  schema: AnySchema<A>,
   options: StateOptions = {},
 ): StateClass<N, A> => {
   const identifier = `reform/state/${name}`
@@ -58,15 +53,6 @@ export const make = <const N extends string, A>(
   return yieldableClass(read, { manifest, store })
 }
 
-/**
- * Resolve the value a store should boot from: the ambient seed override when
- * one is present (and valid) for this state's member name, else the authored
- * `initial`. Reads `CurrentSeedOverrides` — empty outside the tooling seam
- * (`Scene.seedScene`), so production wiring always boots from `initial`. An
- * override is decoded against the state's schema; an invalid value silently
- * falls back to `initial` — a half-typed override from the dev tool must never
- * crash a preview.
- */
 const resolveSeed = <S extends AnyState>(
   state: S,
   initial: StateValue<S>,
@@ -79,11 +65,6 @@ const resolveSeed = <S extends AnyState>(
     return Option.getOrElse(override, () => initial)
   })
 
-/**
- * Allocate a state's store, seeded with `initial` — `State.live(Feed, seed)`.
- * The seed lives here (implementation), not on the definition, so the same
- * definition can boot from different values in app vs. test wiring.
- */
 export const live = <S extends AnyState>(
   state: S,
   initial: StateValue<S>,

package/src/state/stateFamily.test.ts

@@ -2,9 +2,6 @@ import { expect, it } from '@effect/vitest'
 import { Duration, Effect, Layer, Schema as S } from 'effect'
 import { Engine, Event, publish, Reducer, StateFamily } from '../index'
 
-// A family is normalized keyed state: one logical slice per key, so a write to
-// one key must wake only that key's subscribers (the point of the primitive).
-
 const tick = Effect.sleep(Duration.millis(1))
 
 it.live("writing one key does not notify another key's subscribers", () => {
@@ -53,7 +50,6 @@ it.live('forget(key) drops the store; re-reading the key reseeds it', () => {
     expect(family.at('k').get()).toBe(42)
 
     family.forget('k')
-    // A fresh store, reseeded to the family's initial value — not the old 42.
     const reseeded = family.at('k')
     expect(reseeded).not.toBe(first)
     expect(reseeded.get()).toBe(0)
@@ -71,16 +67,13 @@ it.live('evictWhenUnused drops a key once its last subscriber leaves', () => {
     const offB = store.subscribe(() => {})
     expect(family.size()).toBe(1)
 
-    // One subscriber leaving keeps the key (another still reads it).
     offA()
     yield* tick
     expect(family.size()).toBe(1)
 
-    // The last subscriber leaving evicts the key on the next microtask.
     offB()
     yield* tick
     expect(family.size()).toBe(0)
-    // Re-reading reseeds a fresh store.
     expect(family.at('k').get()).toBe(0)
   }).pipe(Effect.provide(TestLayer))
 })
@@ -94,10 +87,9 @@ it.live('evictWhenUnused: a same-tick re-subscribe cancels eviction', () => {
     const store = family.at('k')
     store.set(7)
     const off = store.subscribe(() => {})
-    off() // count → 0, eviction scheduled for the next microtask
-    store.subscribe(() => {}) // re-subscribe in the same tick → count back to 1
+    off()
+    store.subscribe(() => {})
     yield* tick
-    // Not evicted: the value survives and `at` returns the same live store.
     expect(family.size()).toBe(1)
     expect(family.at('k').get()).toBe(7)
   }).pipe(Effect.provide(TestLayer))
@@ -128,7 +120,6 @@ it.live('a family reducer fold returning Tombstone evicts the key', () => {
     const before = family.at('a')
     expect(before.get()).toBe(1)
 
-    // The fold returns the eviction sentinel: the key's store is dropped.
     yield* publish('High', Event.construct(Removed, { id: 'a' }))
     yield* Effect.sleep(Duration.millis(5))
     const after = family.at('a')

package/src/state/stateFamily.ts

@@ -1,48 +1,23 @@
-import { Context, Effect, Layer, Option, type Schema } from 'effect'
+import { Context, Effect, Layer, Option } from 'effect'
 import { type Manifest, definitionClass } from '../definition/definition'
 import { resolveScheduler, type Scheduler } from '../internal/scheduler'
 import { claimStateTag } from '../internal/stateRegistry'
 import { resolveInstrumentation, stateUpdateHook } from '../runtime/instrumentation'
 import { makeStore, type Store } from '../internal/store'
 import { readTracked } from '../internal/track'
+import type { AnySchema, AnyValue } from '../internal/variance'
 
-/**
- * A reducer fold returns this to evict the key it folded over, instead of a new
- * value. The loop drops the entry's store from the family, so a normalized
- * collection (chat messages, search hits, transient rows) does not grow without
- * bound — the one fix for the otherwise-unbounded per-key `Map`.
- */
 export const Tombstone: unique symbol = Symbol.for('reform/StateFamily/Tombstone')
 export type Tombstone = typeof Tombstone
 
-/** Per-key stores, created lazily so a write to one key wakes only its subscribers. */
 export interface FamilyStore<K, V> {
   at(key: K): Store<V>
-  /**
-   * Drop a key's store so it stops occupying memory. A live subscriber keeps its
-   * own closure over the previous store, so eviction is for keys whose entity is
-   * gone (the component is unmounting) — re-`at`-ing the key allocates a fresh,
-   * reseeded store.
-   */
   forget(key: K): void
-  /** Drop every key's store — a wholesale reset of the family. */
   clear(): void
-  /** Number of live keys — for tests/diagnostics. */
   size(): number
 }
 
-/** Options for a family's keyed store. */
 export interface FamilyOptionsExternalApi {
-  /**
-   * Drop a key's store automatically once it has no live subscribers (checked on
-   * the next microtask, so a same-commit re-subscribe — e.g. a key that just moved
-   * position in a list — cancels the eviction). This bounds an otherwise-unbounded
-   * family without explicit `Tombstone`s, but it also DISCARDS the key's value —
-   * re-`at`-ing a dropped key reseeds from `initial`. Use only for keys whose value
-   * is disposable when nothing renders them (search hits, transient rows); for a
-   * source-of-truth entity that may be temporarily off-screen (a virtualized list),
-   * keep this off and reclaim with an explicit reducer `Tombstone`. Default: off.
-   */
   readonly evictWhenUnused?: boolean
 }
 export type FamilyOptions = FamilyOptionsExternalApi
@@ -55,14 +30,10 @@ const makeFamilyStore = <K, V>(
 ): FamilyStore<K, V> => {
   const entries = new Map<K, Store<V>>()
   const evictWhenUnused = options.evictWhenUnused === true
-  // Live subscriber count per key — maintained only when eviction is on.
   const subscribers = new Map<K, number>()
   const liveSubscriberCount = (key: K): number =>
     Option.getOrElse(Option.fromNullable(subscribers.get(key)), () => 0)
 
-  // Wrap a store's `subscribe` to ref-count, evicting the key when it falls idle.
-  // `get`/`set`/`getVersion` are delegated unchanged, so the loop writes and the
-  // host reads see the same cell; only subscribe/unsubscribe are instrumented.
   const refCounted = (key: K, store: Store<V>): Store<V> => ({
     ...store,
     subscribe: (listener) => {
@@ -116,28 +87,23 @@ const makeFamilyStore = <K, V>(
 export interface StateFamilyManifestExternalApi<N extends string, K, V> extends Manifest {
   readonly kind: 'StateFamily'
   readonly name: N
-  readonly key: Schema.Schema<K, any>
-  readonly value: Schema.Schema<V, any>
+  readonly key: AnySchema<K>
+  readonly value: AnySchema<V>
   readonly title?: string
   readonly description?: string
 }
 export type StateFamilyManifest<N extends string, K, V> = StateFamilyManifestExternalApi<N, K, V>
 
 export interface StateFamilyClass<out N extends string, in out K, in out V> {
-  /** Instance carries the key phantom so `Family['Key']` resolves in `keyOf` types. */
   new (): { readonly Key: K }
   readonly manifest: StateFamilyManifest<N, K, V>
   readonly store: Context.Tag<FamilyStore<K, V>, FamilyStore<K, V>>
 }
 
-export type AnyFamily = StateFamilyClass<string, any, any>
-export type FamilyKey<F> = F extends StateFamilyClass<any, infer K, any> ? K : never
-export type FamilyValue<F> = F extends StateFamilyClass<any, any, infer V> ? V : never
+export type AnyFamily = StateFamilyClass<string, AnyValue, AnyValue>
+export type FamilyKey<F> = F extends StateFamilyClass<string, infer K, AnyValue> ? K : never
+export type FamilyValue<F> = F extends StateFamilyClass<string, AnyValue, infer V> ? V : never
 
-/**
- * Normalized keyed state: one logical State per key, backed by a single family
- * store. Scales with the collection without re-rendering unrelated entries.
- */
 export interface StateFamilyMakeOptionsExternalApi {
   readonly title?: string
   readonly description?: string
@@ -145,8 +111,8 @@ export interface StateFamilyMakeOptionsExternalApi {
 
 export const make = <const N extends string, K, V>(
   name: N,
-  key: Schema.Schema<K, any>,
-  valueSchema: Schema.Schema<V, any>,
+  key: AnySchema<K>,
+  valueSchema: AnySchema<V>,
   options: StateFamilyMakeOptionsExternalApi = {},
 ): StateFamilyClass<N, K, V> => {
   const identifier = `reform/family/${name}`
@@ -163,21 +129,12 @@ export const make = <const N extends string, K, V>(
   return definitionClass<StateFamilyClass<N, K, V>>({ manifest, store })
 }
 
-/**
- * Read one entry by key — `StateFamily.read(ItemUi, id)`. Inside a render it
- * subscribes that key's slice; elsewhere it just snapshots (D5).
- */
 export const read = <N extends string, K, V>(
   family: StateFamilyClass<N, K, V>,
   key: K,
 ): Effect.Effect<V, never, FamilyStore<K, V>> =>
   Effect.flatMap(family.store, (familyStore) => readTracked(familyStore.at(key)))
 
-/**
- * Allocate a family's keyed store — `StateFamily.live(ItemUi, seed)`. The seed
- * is a plain value or a factory; a factory receives the key, so a new entry can
- * derive its starting value from its own id (`(id) => ({ ...blank, id }))`).
- */
 export const live = <N extends string, K, V>(
   family: StateFamilyClass<N, K, V>,
   initial: V | ((key: K) => V),

package/src/state/stateGroup.ts

@@ -1,35 +1,23 @@
 import { Array as Arr, Layer, Option } from 'effect'
 import { definitionClass } from '../definition/definition'
 import { DuplicateRegistration, UnknownGroupState } from '../internal/errors'
-// A group's members each carry a `store` tag, so the shared `StoresOf` (used for
-// calc inputs too) distributes them into the union of distinct stores their
-// `live` layer provides — no group-specific mapped type needed.
 import { type StoresOf } from '../internal/sources'
 import { type AnyState, live as stateLive, type StateClass, type StateName } from './state'
 import { StateToken } from './token'
+import type { AnyValue } from '../internal/variance'
 
 type ValueForName<Members extends ReadonlyArray<AnyState>, N extends string> =
-  Extract<Members[number], StateClass<N, any>> extends StateClass<any, infer A> ? A : never
+  Extract<Members[number], StateClass<N, AnyValue>> extends StateClass<string, infer A> ? A : never
 
 export interface StateGroupClass<Members extends ReadonlyArray<AnyState>> {
   new (): {}
   readonly kind: 'StateGroup'
   readonly members: Members
-  /** Members indexed by name, so `select` is an O(1) lookup instead of a scan. */
   readonly byName: ReadonlyMap<string, AnyState>
 }
 
 export type AnyStateGroup = StateGroupClass<ReadonlyArray<AnyState>>
 
-/**
- * Compile-time uniqueness guard for `StateGroup.make`. Member names key the tag,
- * the seed record, `byName`, and `select` — duplicates are unaddressable, so a
- * repeated name is replaced (positionally) by this marker tuple, which a real
- * `StateClass` is not assignable to. The offending argument fails to typecheck
- * with the colliding name spelled out in the message, rather than collapsing
- * silently. Runtime `make` throws the same clash for seeds the root tsconfig
- * never typechecks (test files live outside it).
- */
 type DuplicateStateName<N extends string> = readonly ['reform: duplicate state name in group', N]
 
 type NoDuplicateNames<
@@ -42,41 +30,24 @@ type NoDuplicateNames<
     ]
   : readonly []
 
-// The seed record `StateGroup.live` requires: one entry per member, keyed by the
-// member's name and typed to that member's value (so a missing or mistyped seed
-// is a compile error). Written against the group class, so call sites read
-// `GroupSeeds<typeof TodosStates>`.
 export type GroupSeeds<G extends AnyStateGroup> =
   G extends StateGroupClass<infer Members>
     ? { readonly [N in StateName<Members[number]>]: ValueForName<Members, N> }
     : never
 
-// Collapse a union of records into their intersection — merges every group's
-// seed record into one. (The classic contravariant-position trick.)
 type UnionToIntersection<U> = (U extends unknown ? (k: U) => void : never) extends (
   k: infer I,
 ) => void
   ? I
   : never
 
-/** The seed record for one tuple entry: a group's `GroupSeeds`, else nothing. */
 type EntrySeeds<G> = G extends AnyStateGroup ? GroupSeeds<G> : never
 
-/**
- * The optional seed overrides for a composition's whole `states` tuple, keyed by
- * member name and typed to each member's value. Every key is optional (seeds are
- * overrides over the authored initial). Tuple entries that aren't state groups
- * contribute no keys, so a partially-grouped `states` still types its groups.
- * Powers `seedScene` — a typo'd key or mistyped value is a compile error.
- */
 export type SeedsOf<St extends ReadonlyArray<unknown>> = Partial<UnionToIntersection<EntrySeeds<St[number]>>>
 
-/** Compose atomic States into a group provided (and addressed) as a unit. */
 export const make = <const Members extends ReadonlyArray<AnyState>>(
   ...members: Members & NoDuplicateNames<Members>
 ): StateGroupClass<Members> => {
-  // `byName` already de-dupes, so a smaller map than the member list means two
-  // members claimed one name — unaddressable, and a silent footgun on merge.
   const names = members.map((member) => member.manifest.name)
   const duplicate = Arr.findFirst(names, (name, index) =>
     Option.exists(
@@ -95,16 +66,6 @@ export const make = <const Members extends ReadonlyArray<AnyState>>(
   })
 }
 
-/**
- * Address a member by its tag — `StateGroup.select(TodosStates, 'feed')` —
- * yielding a `StateToken` for reads and calc inputs (still `yield*`-able).
- *
- * Data-first only (not `dual`): the member name's type depends on the group, and
- * a group is not `Pipeable`, so a data-last form would be both more verbose and
- * harder to type than the direct call. Effect reserves `dual` for operators on a
- * `Pipeable` self with an independent value arg (e.g. `ref.pipe(Ref.set(v))`);
- * this is not that shape.
- */
 export const select = <Members extends ReadonlyArray<AnyState>, N extends StateName<Members[number]>>(
   group: StateGroupClass<Members>,
   name: N,
@@ -117,18 +78,10 @@ export const select = <Members extends ReadonlyArray<AnyState>, N extends StateN
   return new StateToken(name, member.store)
 }
 
-/**
- * Allocate every member's store as one merged layer, each seeded from `seeds`
- * keyed by member name — `StateGroup.live(BoardStates, { board: { _tag: 'Idle' } })`.
- */
 export const live = <Members extends ReadonlyArray<AnyState>>(
   group: StateGroupClass<Members>,
   seeds: GroupSeeds<StateGroupClass<Members>>,
 ): Layer.Layer<StoresOf<Members>> => {
-  // Index the typed seed record by the member's runtime name — a genuine
-  // reflection boundary (string key into a mapped type). Each member's store
-  // layer is then merged; the union of stores is exactly `StoresOf<Members>`,
-  // which `reduce`'s single-layer accumulator can't express, so restate it.
   // oxlint-disable-next-line reform-rules/no-type-assertion -- reflection boundary: index a mapped seed type by runtime member name
   const seedRecord = seeds as Record<string, unknown>
   // oxlint-disable-next-line reform-rules/no-type-assertion -- union-of-stores Rout can't be expressed by reduce's single-layer accumulator