@playfast/reform 0.0.7 → 0.0.9

package/src/scene/scene.ts

@@ -0,0 +1,88 @@
+import { Layer } from 'effect'
+import type { CompositionClass, CompositionService } from '../compose/composition'
+import type { UiContract } from '../compose/ui'
+import type { EventOf } from '../event/event'
+import { CurrentSeedOverrides } from '../internal/seeds'
+import type { SeedsOf } from '../state/stateGroup'
+import type { Bus } from '../runtime/bus'
+
+// A scene is a VALUE — a composition plus the closed wiring that runs it: the
+// layers that supply its logic/views (each seeding its own live state) and the
+// boot events to dispatch once the runtime is live. Nothing self-registers on
+// import. A scene is the single handle every consumer takes instead of a bare
+// composition: the react host renders it, a proof runs against it, and the dev
+// tool previews it — all from the same closed `provide`.
+//
+// There is no seeded-`state` dict: variation (Default/Empty/Errored) comes from
+// providing different closed layers, exactly as production wiring does. The
+// composition's contract `C` is preserved (not erased to `unknown`) so a proof's
+// facade stays fully typed from `scene.composition`.
+
+/**
+ * The services a built reform runtime exposes to its host: every composition's
+ * logic and the event `Bus`. A scene's `provide` must close to these (a fully
+ * wired app layer provides far more; this is the subset hosts read directly).
+ */
+export type MountedServices = CompositionService | Bus
+
+// A scene's boot list holds CONSTRUCTED events (`Event.construct(E, payload)`),
+// not bare tagged objects — a lightweight nudge toward the real builder. It is
+// not a guarantee the event is handled by the wiring (reform carries no
+// type-level union of handled tags), only that it came from an event definition.
+type BootEvent = EventOf<string, unknown>
+
+export interface Scene<
+  C extends UiContract = UiContract,
+  S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
+> {
+  readonly kind: 'Scene'
+  /** The composition to run, with its contract + states preserved for typed consumers. */
+  readonly composition: CompositionClass<unknown, C, S>
+  /** Closed wiring (logic + views), each layer seeding its own live state. */
+  readonly provide: ReadonlyArray<Layer.Layer<MountedServices, never, never>>
+  /** Events dispatched once the runtime is live (e.g. `RequestedTodos`). */
+  readonly boot?: ReadonlyArray<BootEvent>
+}
+
+/**
+ * Define a scene — `scene(TodoApp, { provide: [makeTestApp(client, seeds)] })`.
+ * The composition's contract `C` and state tuple `S` flow through, so consumers
+ * (the facade, `seedScene`) stay typed.
+ */
+export const scene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
+  composition: CompositionClass<unknown, C, S>,
+  config: {
+    readonly provide: ReadonlyArray<Layer.Layer<MountedServices, never, never>>
+    readonly boot?: ReadonlyArray<BootEvent>
+  },
+): Scene<C, S> => ({
+  kind: 'Scene',
+  composition,
+  provide: config.provide,
+  ...(config.boot !== undefined ? { boot: config.boot } : {}),
+})
+
+/**
+ * Overlay seed values onto a CLOSED scene — the tooling/test seam (dev-tool
+ * inspector overrides, proofs). Scenes stay closed for authors: this does not
+ * reopen `provide`, it wraps each layer with `Layer.locally(CurrentSeedOverrides,
+ * seeds)` so `State.live` boots matching stores from the override instead of
+ * the authored seed.
+ *
+ * Keys are state MEMBER NAMES as reflected in `manifest.states` (e.g. `count`),
+ * not group names. If two groups in one scene share a member name, both receive
+ * the override (documented limitation). Values are schema-validated at build:
+ * an invalid value silently falls back to the authored seed. `StateFamily`
+ * entries are not covered.
+ */
+export const seedScene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
+  base: Scene<C, S>,
+  seeds: SeedsOf<S>,
+): Scene<C, S> =>
+  Object.keys(seeds).length === 0
+    ? base
+    : { ...base, provide: base.provide.map(Layer.locally(CurrentSeedOverrides, seeds)) }
+
+/** Reflection guard: is this exported value a scene? */
+export const isScene = (v: unknown): v is Scene =>
+  typeof v === 'object' && v !== null && (v as { readonly kind?: unknown }).kind === 'Scene'

package/src/scene/seedScene.test.ts

@@ -0,0 +1,176 @@
+import { Effect, Layer, ManagedRuntime, Schema as S } from 'effect'
+import { expect, test } from 'vitest'
+import {
+  Composition,
+  Engine,
+  Event,
+  isStructure,
+  mount,
+  provide,
+  publish,
+  Reducer,
+  type RenderEnv,
+  type Scene,
+  scene,
+  seedScene,
+  State,
+  StateGroup,
+  Ui,
+  ui,
+} 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 MiniStates extends StateGroup.make(CountState) {}
+
+class Bumped extends Event.make('Bumped', S.Struct({})) {}
+
+class BumpReducer extends Reducer.make('BumpReducer', {
+  states: [CountState],
+  events: [Bumped],
+}) {}
+const BumpReducerLive = Reducer.live(BumpReducer, (n) => n + 1)
+
+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 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 => ({
+  ...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' &&
+  props !== null &&
+  '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 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 isCountProps(frame.props)
+          ? Effect.succeed(frame.props.count)
+          : Effect.dieMessage('Counter Structure props must include numeric count')
+      }),
+    ),
+  )
+  return { runtime, 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,
+  rounds = 1000,
+): Effect.Effect<A, never, 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()
+  }
+})

package/src/state/state.ts

@@ -0,0 +1,94 @@
+import { Context, Effect, FiberRef, Layer, Option, Schema } from 'effect'
+import { type Manifest, yieldableClass } from '../definition/definition'
+import { resolveScheduler } from '../internal/scheduler'
+import { CurrentSeedOverrides } from '../internal/seeds'
+import { claimStateTag } from '../internal/stateRegistry'
+import { makeStore, type Store } from '../internal/store'
+import { readTracked } from '../internal/track'
+
+export interface StateOptions {
+  readonly title?: string
+  readonly description?: string
+}
+
+export interface StateManifest<N extends string, A> extends Manifest {
+  readonly kind: 'State'
+  readonly name: N
+  readonly schema: Schema.Schema<A, any>
+  readonly title?: string
+  readonly description?: string
+}
+
+export interface StateClass<out N extends string, in out A> extends Effect.Effect<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 StateValue<S> = S extends StateClass<string, infer A> ? A : never
+export type StateName<S> = S extends StateClass<infer N, any> ? 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>,
+  options: StateOptions = {},
+): StateClass<N, A> => {
+  const identifier = `reform/state/${name}`
+  claimStateTag(identifier)
+  const store = Context.GenericTag<Store<A>, Store<A>>(identifier)
+  const manifest: StateManifest<N, A> = {
+    kind: 'State',
+    name,
+    schema,
+    ...(options.title !== undefined ? { title: options.title } : {}),
+    ...(options.description !== undefined ? { description: options.description } : {}),
+  }
+  const read = Effect.flatMap(store, readTracked)
+  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>,
+): Effect.Effect<StateValue<S>> =>
+  Effect.map(FiberRef.get(CurrentSeedOverrides), (overrides) =>
+    state.manifest.name in overrides
+      ? Option.getOrElse(
+          Schema.decodeUnknownOption(state.manifest.schema)(overrides[state.manifest.name]),
+          () => initial,
+        )
+      : 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>,
+): Layer.Layer<Store<StateValue<S>>> =>
+  Layer.effect(
+    state.store,
+    Effect.zipWith(resolveScheduler, resolveSeed(state, initial), (scheduler, seed) =>
+      makeStore(seed, scheduler),
+    ),
+  )

package/src/state/stateFamily.test.ts

@@ -0,0 +1,138 @@
+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", () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  const TestLayer = StateFamily.live(Items, 0)
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+    const a = family.at('a')
+    const b = family.at('b')
+    const aWakes = { n: 0 }
+    const bWakes = { n: 0 }
+    a.subscribe(() => {
+      aWakes.n += 1
+    })
+    b.subscribe(() => {
+      bWakes.n += 1
+    })
+
+    a.set(1)
+    yield* tick
+    expect(aWakes.n).toBe(1)
+    expect(bWakes.n).toBe(0)
+    expect(b.get()).toBe(0)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('at(key) returns the same store each call, so subscriptions are stable', () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  const TestLayer = StateFamily.live(Items, 0)
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+    expect(family.at('k')).toBe(family.at('k'))
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('forget(key) drops the store; re-reading the key reseeds it', () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  const TestLayer = StateFamily.live(Items, 0)
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+    const first = family.at('k')
+    first.set(42)
+    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)
+  }).pipe(Effect.provide(TestLayer))
+})
+
+it.live('evictWhenUnused drops a key once its last subscriber leaves', () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  const TestLayer = StateFamily.live(Items, 0, { evictWhenUnused: true })
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+    const store = family.at('k')
+    const offA = store.subscribe(() => {})
+    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))
+})
+
+it.live('evictWhenUnused: a same-tick re-subscribe cancels eviction', () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  const TestLayer = StateFamily.live(Items, 0, { evictWhenUnused: true })
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+    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
+    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))
+})
+
+it.live('a family reducer fold returning Tombstone evicts the key', () => {
+  class Items extends StateFamily.make('items', S.String, S.Number) {}
+  class Bumped extends Event.make('Bumped', S.Struct({ id: S.String })) {}
+  class Removed extends Event.make('Removed', S.Struct({ id: S.String })) {}
+  class ItemsReducer extends Reducer.make('ItemsReducer', {
+    family: Items,
+    keyOf: (event) => event.id,
+    events: [Bumped, Removed],
+  }) {}
+  const ItemsLive = Reducer.live(ItemsReducer, (n, event) =>
+    event._tag === 'Removed' ? StateFamily.Tombstone : n + 1,
+  )
+
+  const TestLayer = ItemsLive.pipe(
+    Layer.provideMerge(Layer.mergeAll(StateFamily.live(Items, 0), Engine)),
+  )
+
+  return Effect.gen(function* () {
+    const family = yield* Items.store
+
+    yield* publish('High', Event.construct(Bumped, { id: 'a' }))
+    yield* Effect.sleep(Duration.millis(5))
+    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')
+    expect(after).not.toBe(before)
+    expect(after.get()).toBe(0)
+  }).pipe(Effect.provide(TestLayer))
+})

package/src/state/stateFamily.ts

@@ -0,0 +1,174 @@
+import { Context, Effect, Layer, type Schema } from 'effect'
+import { type Manifest, definitionClass } from '../definition/definition'
+import { resolveScheduler, type Scheduler } from '../internal/scheduler'
+import { claimStateTag } from '../internal/stateRegistry'
+import { makeStore, type Store } from '../internal/store'
+import { readTracked } from '../internal/track'
+
+/**
+ * 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 FamilyOptions {
+  /**
+   * 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
+}
+
+const makeFamilyStore = <K, V>(
+  seed: (key: K) => V,
+  scheduler: Scheduler,
+  options: FamilyOptions = {},
+): 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>()
+
+  // 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) => {
+      subscribers.set(key, (subscribers.get(key) ?? 0) + 1)
+      const off = store.subscribe(listener)
+      const released = { done: false }
+      return () => {
+        if (released.done) return
+        released.done = true
+        off()
+        const remaining = (subscribers.get(key) ?? 1) - 1
+        if (remaining > 0) {
+          subscribers.set(key, remaining)
+          return
+        }
+        subscribers.delete(key)
+        queueMicrotask(() => {
+          if ((subscribers.get(key) ?? 0) === 0) entries.delete(key)
+        })
+      }
+    },
+  })
+
+  return {
+    at: (key) => {
+      const existing = entries.get(key)
+      if (existing !== undefined) return existing
+      const base = makeStore(seed(key), scheduler)
+      const created = evictWhenUnused ? refCounted(key, base) : base
+      entries.set(key, created)
+      return created
+    },
+    forget: (key) => {
+      entries.delete(key)
+      subscribers.delete(key)
+    },
+    clear: () => {
+      entries.clear()
+      subscribers.clear()
+    },
+    size: () => entries.size,
+  }
+}
+
+export interface StateFamilyManifest<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 title?: string
+  readonly description?: string
+}
+
+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
+
+/**
+ * Normalized keyed state: one logical State per key, backed by a single family
+ * store. Scales with the collection without re-rendering unrelated entries.
+ */
+export const make = <const N extends string, K, V>(
+  name: N,
+  key: Schema.Schema<K, any>,
+  value: Schema.Schema<V, any>,
+  options: { readonly title?: string; readonly description?: string } = {},
+): StateFamilyClass<N, K, V> => {
+  const identifier = `reform/family/${name}`
+  claimStateTag(identifier)
+  const store = Context.GenericTag<FamilyStore<K, V>, FamilyStore<K, V>>(identifier)
+  const manifest: StateFamilyManifest<N, K, V> = {
+    kind: 'StateFamily',
+    name,
+    key,
+    value,
+    ...(options.title !== undefined ? { title: options.title } : {}),
+    ...(options.description !== undefined ? { description: options.description } : {}),
+  }
+  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, (fs) => readTracked(fs.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),
+  options: FamilyOptions = {},
+): Layer.Layer<FamilyStore<K, V>> => {
+  const seed: (key: K) => V = typeof initial === 'function' ? (initial as (key: K) => V) : () => initial
+  return Layer.effect(
+    family.store,
+    Effect.map(resolveScheduler, (scheduler) => makeFamilyStore<K, V>(seed, scheduler, options)),
+  )
+}