@playfast/reform 0.0.8 → 0.0.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform",
   "playbook": "./playbook",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "type": "module",
   "description": "The renderer-neutral core of the reform framework — typed, headless state, events, reducers, derived values, async/remote data, and compositions built on Effect.",
   "keywords": [

package/src/compose/composition.ts

@@ -4,21 +4,30 @@ import { type Manifest, definitionClass } from '../definition/definition'
 import { type Ctx } from '../internal/ctx'
 import type { Tracker } from '../internal/track'
 import { CurrentTracker } from '../internal/track'
-import { CurrentSlots, type SlotHost } from './host'
-import type { Node, SlotClass } from './slot'
+import type { SlotClass } from './slot'
+import type { Structure } from './structure'
 import type { UiClass, UiContract } from './ui'
 import { Props } from './props'
 
-/** Everything the host injects per render: the instance props, the dependency tracker, and slot bindings. */
+/**
+ * What a composition's logic returns for one frame: a serializable {@link Structure}
+ * value — its computed props, per-slot fills, and event triggers, all as DATA. A body
+ * never returns (nor evaluates) a React node, so the engine, the wire server, and the
+ * proof harness consume the frame without React; presentation resolves the contract's
+ * view separately, by name, on a host.
+ */
+export type Frame<C extends UiContract = UiContract> = Structure<C>
+
+/** Everything the host injects per render: the instance props and the dependency tracker. */
 export interface RenderEnv {
   readonly props: unknown
   readonly tracker: Tracker
-  readonly slots: SlotHost
 }
 
-/** A mounted composition: given a render environment, produces the current frame's node. */
+/** A mounted composition: given a render environment, produces the current frame —
+ *  a {@link Structure} value (see `Frame`). */
 export interface CompositionService {
-  readonly render: (env: RenderEnv) => Effect.Effect<Node, never, never>
+  readonly render: (env: RenderEnv) => Effect.Effect<Frame, never, never>
 }
 
 export interface CompositionConfig {
@@ -39,7 +48,20 @@ export interface CompositionConfig {
 
 type PropsOf<Config> = Config extends { props: Schema.Schema<infer P, any> } ? P : unknown
 
-export interface CompositionClass<out P, out C extends UiContract = UiContract> {
+/**
+ * The composition's state-group tuple, recovered from the `const`-inferred config
+ * so consumers can type its seeds. Erased to `readonly []` when no `states` are
+ * declared; entries that are not state groups contribute no seed keys (`SeedsOf`).
+ */
+type StatesOf<Config> = Config extends { states: infer S extends ReadonlyArray<unknown> }
+  ? S
+  : readonly []
+
+export interface CompositionClass<
+  out P,
+  out C extends UiContract = UiContract,
+  out S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
+> {
   new (): {}
   readonly manifest: Manifest & { readonly kind: 'Composition' } & CompositionConfig
   /** Phantom carrying the props type for `provide(slot, composition)` checks. */
@@ -51,6 +73,11 @@ export interface CompositionClass<out P, out C extends UiContract = UiContract>
    * invariant `impl` tag is never stored here, so no variance regression.
    */
   readonly Contract: C
+  /**
+   * Phantom carrying the state-group tuple, so `seedScene` can type a scene's
+   * seeds against the actual state members. Same erasure trick as `Contract`.
+   */
+  readonly States: S
   readonly tag: Context.Tag<CompositionService, CompositionService>
 }
 
@@ -66,12 +93,12 @@ export const make = <const Config extends CompositionConfig, C extends UiContrac
   // manifest still sees only the erased `{ manifest }` carrier (CompositionConfig),
   // so the manifest type — and its variance — is unchanged.
   config: Config & { readonly ui: UiClass<C> },
-): CompositionClass<PropsOf<Config>, C> => {
+): CompositionClass<PropsOf<Config>, C, StatesOf<Config>> => {
   const tag = Context.GenericTag<CompositionService, CompositionService>(
     `reform/composition/${name}`,
   )
   const manifest = { kind: 'Composition' as const, name, ...config }
-  return definitionClass<CompositionClass<PropsOf<Config>, C>>({ manifest, tag })
+  return definitionClass<CompositionClass<PropsOf<Config>, C, StatesOf<Config>>>({ manifest, tag })
 }
 
 /**
@@ -80,33 +107,40 @@ export const make = <const Config extends CompositionConfig, C extends UiContrac
  * host injects per render) surface as the Layer's `RIn`; the runtime runs the
  * body per render within the captured context.
  */
-export const live = <P, Eff extends YieldWrap<Effect.Effect<unknown, never, unknown>>>(
-  // `live` doesn't use the contract type; accept any composition.
-  composition: CompositionClass<P, any>,
-  body: () => Generator<Eff, Node, never>,
+export const live = <
+  P,
+  C extends UiContract,
+  Eff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
+>(
+  // The contract `C` is captured (not erased to `any`) so the body's returned
+  // `Structure` is checked against the composition's contract.
+  composition: CompositionClass<P, C>,
+  body: () => Generator<Eff, Frame<C>, never>,
 ): Layer.Layer<CompositionService, never, Exclude<Ctx<Eff>, Props>> => {
   const logic = Effect.gen(body)
   return Layer.effect(
     composition.tag,
     Effect.gen(function* () {
-      // Capture the build-time context (state stores, calc, ui, bus). `Props`,
-      // the tracker, and slots are injected per render below.
+      // Capture the build-time context (state stores, calc, ui, bus). `Props` and
+      // the tracker are injected per render below.
       const context = yield* Effect.context<Exclude<Ctx<Eff>, Props>>()
-      const render = (env: RenderEnv): Effect.Effect<Node, never, never> =>
-        // Total once fully provided: the body is synchronous, reads can't fail,
-        // and every requirement is now satisfied (D2). `Effect.gen` widens the
-        // error channel to `unknown` for a generic body, so we restate it.
+      const render = (env: RenderEnv): Effect.Effect<Frame, never, never> =>
+        // The per-render erasure seam: the body is total once fully provided (it is
+        // synchronous, reads can't fail, every requirement is now satisfied — D2) and
+        // its `Structure<C>` erases to the service's contract-agnostic `Frame`. `gen`
+        // widens the error channel to the body's inferred `E` for a generic body, so
+        // narrowing it (and the contract) back to the erased service type needs the
+        // `unknown` bridge — the one cast this render boundary has always required.
         logic.pipe(
           Effect.provideService(Props, env.props),
           Effect.provideService(CurrentTracker, env.tracker),
-          Effect.provideService(CurrentSlots, env.slots),
           Effect.provide(context),
-        ) as Effect.Effect<Node, never, never>
+        ) as unknown as Effect.Effect<Frame, never, never>
       return { render }
     }),
   )
 }
 
-/** Run a mounted composition for one frame, producing its node. */
-export const render = (service: CompositionService, env: RenderEnv): Effect.Effect<Node, never, never> =>
+/** Run a mounted composition for one frame, producing its `Frame` (a `Structure`). */
+export const render = (service: CompositionService, env: RenderEnv): Effect.Effect<Frame, never, never> =>
   service.render(env)

package/src/compose/host.ts

@@ -1,18 +1,12 @@
-import { Context } from 'effect'
 import type { Node } from './slot'
 
 /**
- * Binds a parent's slots to concrete child renderers. The host package
- * (`@reform/react`) builds one per composition instance from the manifest's
- * slot map; the `ui` read consults it so `<slots.Item .../>` renders the wired
- * child. Core stays renderer-neutral — it only defines this hole.
+ * A slot handle the host hands a presentation: BOTH renderable (call it / use as a
+ * component to place the keyed children) AND inspectable (`.props` — the array of
+ * per-child fill props the structure carried, one entry per mounted child). The
+ * structure host (`renderStructure`) populates `.props` from the fills. Plan 06.
  */
-export interface SlotHost {
-  slot(name: string): (props: unknown) => Node
+export interface SlotRenderer {
+  (props: unknown): Node
+  readonly props: ReadonlyArray<unknown>
 }
-
-const CurrentSlotsBase: Context.TagClass<CurrentSlots, 'reform/Slots', SlotHost> =
-  Context.Tag('reform/Slots')<CurrentSlots, SlotHost>()
-
-/** The active composition's slot bindings, provided per render by the host. */
-export class CurrentSlots extends CurrentSlotsBase {}

package/src/compose/structure.test.ts

@@ -0,0 +1,90 @@
+import { Schema as S } from 'effect'
+import { describe, expect, test } from 'vitest'
+import { Composition } from '../index'
+import { slot } from './slot'
+import { type Contract, ui } from './ui'
+import { absent, each, isStructure, mount, one, structureEquals, when } from './structure'
+
+type List = Contract<typeof ListUi>
+
+// A minimal parent/child contract pair: a list parent with one keyed slot, so the
+// type-level `mount` checks have a real contract to bind against. Row carries a
+// props schema so its external props (`Comp['Props']`) are `{ label: string }`,
+// which is what each fill is checked against.
+class RowUi extends ui('Row')<{ props: { label: string } }>() {}
+class Row extends Composition.make('Row', {
+  title: 'Row',
+  props: S.Struct({ label: S.String }),
+  ui: RowUi,
+}) {}
+class RowSlot extends slot('Row')<typeof Row>() {}
+
+class ListUi extends ui('List')<{
+  props: { total: number }
+  slots: { Row: RowSlot }
+}>() {}
+
+describe('structure combinators', () => {
+  test('each produces one keyed entry per item, props mapped', () => {
+    const fill = each([{ id: 'a' }, { id: 'b' }], { key: (t) => t.id, props: (t) => ({ label: t.id }) })
+    expect(fill).toEqual({
+      _tag: 'Each',
+      items: [
+        { key: 'a', props: { label: 'a' } },
+        { key: 'b', props: { label: 'b' } },
+      ],
+    })
+  })
+
+  test('one and absent / when', () => {
+    expect(one({ label: 'x' })).toEqual({ _tag: 'One', props: { label: 'x' } })
+    expect(absent).toEqual({ _tag: 'Absent' })
+    expect(when(true, one({ label: 'y' }))).toEqual({ _tag: 'One', props: { label: 'y' } })
+    expect(when(false, one({ label: 'y' }))).toEqual({ _tag: 'Absent' })
+  })
+
+  test('mount stamps the Structure brand; isStructure discriminates it from a node', () => {
+    const s = mount<List>({
+      props: { total: 2 },
+      slots: { Row: each([{ id: 'a' }], { key: (t) => t.id, props: (t) => ({ label: t.id }) }) },
+    })
+    expect(isStructure(s)).toBe(true)
+    expect(isStructure({ type: 'div' })).toBe(false)
+    expect(isStructure(null)).toBe(false)
+    expect(s.props).toEqual({ total: 2 })
+  })
+
+  test('structureEquals detects a two-frame fixpoint vs a change', () => {
+    const make = (label: string) =>
+      mount<List>({
+        props: { total: 1 },
+        slots: { Row: each([{ id: 'a' }], { key: (t) => t.id, props: () => ({ label }) }) },
+      })
+    expect(structureEquals(make('same'), make('same'))).toBe(true)
+    expect(structureEquals(make('a'), make('b'))).toBe(false)
+  })
+})
+
+// Type-level contract enforcement — never called; exists only so the negative
+// cases are typechecked. Each `@ts-expect-error` must sit on the line that errors.
+export const _typeChecks = (): void => {
+  mount<List>({
+    props: { total: 1 },
+    slots: {
+      // @ts-expect-error 'Nope' is not a declared slot of ListUi
+      Nope: one({ label: 'x' }),
+    },
+  })
+  mount<List>({
+    props: { total: 1 },
+    slots: {
+      // @ts-expect-error Row's child props are { label: string }, not { wrong: number }
+      Row: each([1], { key: () => 'k', props: () => ({ wrong: 1 }) }),
+    },
+  })
+  mount<List>({
+    // @ts-expect-error List's props are { total: number }, not { total: string }
+    props: { total: 'two' },
+    slots: { Row: absent },
+  })
+}

package/src/compose/structure.ts

@@ -0,0 +1,145 @@
+import type { SlotProps } from './slot'
+import type { EventsOf, UiContract } from './ui'
+
+/**
+ * Structure-as-data (the headless-structure keystone). A composition's logic
+ * body returns this *value* instead of a React node: pure, serializable data that
+ * describes — for this frame — the composition's own props and, per declared slot,
+ * how that slot is filled (a list / a singleton / absent). The engine, the wire
+ * server, and the proof harness consume this directly, so none of them needs to
+ * evaluate a view or import React to discover structure. Presentation (React)
+ * resolves a contract's markup separately, by name, on a host.
+ *
+ * `live` accepts BOTH a `Node` (legacy view body) and a `Structure` during the
+ * migration; hosts discriminate at runtime via {@link isStructure}.
+ */
+
+/** A list slot fill: one keyed entry per item. `key` is the SINGLE source of both
+ *  the wire `key` and the per-item `StateFamily` key — they can no longer drift. */
+export interface EachFill<P> {
+  readonly _tag: 'Each'
+  readonly items: ReadonlyArray<{ readonly key: string; readonly props: P }>
+}
+
+/** A singleton slot fill — the slot renders exactly one child with these props. */
+export interface OneFill<P> {
+  readonly _tag: 'One'
+  readonly props: P
+}
+
+/** A slot that renders nothing this frame (the data-driven analog of `cond && …`). */
+export interface AbsentFill {
+  readonly _tag: 'Absent'
+}
+
+/** How one declared slot is filled this frame, typed by the child's external props. */
+export type SlotFill<P> = EachFill<P> | OneFill<P> | AbsentFill
+
+/** The per-slot fill map a contract's structure carries — one fill per declared slot,
+ *  each typed by that child composition's external props (`SlotProps`). Empty when the
+ *  contract declares no slots. */
+export type StructureSlots<C extends UiContract> = C extends {
+  slots: infer S
+}
+  ? { readonly [K in keyof S]: SlotFill<SlotProps<S[K]>> }
+  : Record<never, never>
+
+/**
+ * The data a composition's logic returns for one frame: its computed props plus,
+ * for every declared slot, a fill description. Strict against the contract — props
+ * must match, and every declared slot must be filled (use {@link when} for
+ * conditional presence). Carries the child's contract per slot (via `SlotProps`),
+ * so consumers can select and descend into sub-compositions type-safely.
+ *
+ * `events` rides ON the structure: because a `mount(...)`-returning body never
+ * calls its view, the event triggers it acquired (`yield* Event.trigger(X)`) are
+ * no longer captured by a view's `CaptureSink` record — they must travel with the
+ * frame so hosts can register them (proof `actions`, the wire `TriggerRegistry`,
+ * the react presentation `events` arg). Triggers are functions, so `events` is NOT
+ * serializable and is intentionally excluded from {@link structureEquals}. Typed to
+ * the contract's event map; omit it (defaults to `{}`) when the contract has none.
+ */
+export interface Structure<C extends UiContract> {
+  readonly props: C['props']
+  readonly slots: StructureSlots<C>
+  readonly events?: EventsOf<C>
+}
+
+/** Runtime brand distinguishing a `Structure` value from a React `Node` (added by
+ *  {@link mount}; the authoring TYPE intentionally omits it so structure literals stay
+ *  plain). */
+export const StructureTypeId: unique symbol = Symbol.for('reform/Structure')
+export type StructureTypeId = typeof StructureTypeId
+
+/**
+ * Assemble a frame's structure, checked against the contract `C`. Identity at
+ * runtime apart from stamping the {@link StructureTypeId} brand; its real job is
+ * the compile-time contract check. `C` is recovered from the surrounding `live`
+ * body's return type (contextual typing), so call sites read `mount({ props, slots })`.
+ * A leaf composition (no declared slots) passes `slots: {}`. `events` defaults to an
+ * empty map when omitted, so a frame always carries an `events` record for hosts.
+ */
+export const mount = <C extends UiContract>(structure: Structure<C>): Structure<C> =>
+  Object.assign({ [StructureTypeId]: StructureTypeId, events: {} }, structure)
+
+/**
+ * A list slot fill. `key` derives the stable identity for BOTH the wire node and
+ * the per-item state family — passing the same id source to both is no longer
+ * possible to get wrong. `props` maps each item to the child's external props.
+ */
+export const each = <T, P>(
+  collection: Iterable<T>,
+  options: { readonly key: (item: T) => string; readonly props: (item: T) => P },
+): EachFill<P> => ({
+  _tag: 'Each',
+  items: Array.from(collection, (item) => ({ key: options.key(item), props: options.props(item) })),
+})
+
+/** A singleton slot fill — render one child with these external props. */
+export const one = <P>(props: P): OneFill<P> => ({ _tag: 'One', props })
+
+/** The shared empty fill — a slot that renders nothing this frame. */
+export const absent: AbsentFill = { _tag: 'Absent' }
+
+/** Conditional presence: the fill when `cond`, otherwise {@link absent}. */
+export const when = <F extends SlotFill<unknown>>(cond: boolean, fill: F): F | AbsentFill =>
+  cond ? fill : absent
+
+/** Whether a frame value is a `Structure` (vs a legacy React `Node`). The runtime
+ *  discriminator hosts use during the migration, replacing React's `isValidElement`. */
+export const isStructure = (frame: unknown): frame is Structure<UiContract> =>
+  typeof frame === 'object' && frame !== null && StructureTypeId in frame
+
+/** Whether a value is a plain record (not an array) — narrows for the deep compare
+ *  below without a cast. */
+const isRecord = (u: unknown): u is Record<string, unknown> =>
+  typeof u === 'object' && u !== null && !Array.isArray(u)
+
+/** Minimal structural deep-equality for serializable shapes (plain JSON — the
+ *  UI-contract guarantee). Avoids a heavyweight dep for the settle comparison. */
+const deepEquals = (a: unknown, b: unknown): boolean => {
+  if (Object.is(a, b)) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, index) => deepEquals(item, b[index]))
+  }
+  if (isRecord(a) && isRecord(b)) {
+    const aKeys = Object.keys(a)
+    const bKeys = Object.keys(b)
+    return (
+      aKeys.length === bKeys.length &&
+      aKeys.every(
+        (key) => Object.prototype.hasOwnProperty.call(b, key) && deepEquals(a[key], b[key]),
+      )
+    )
+  }
+  return false
+}
+
+/** Structural equality over two structures — props and every slot fill compared by
+ *  value. `events` is intentionally excluded: triggers are functions, freshly
+ *  acquired each render, so comparing them by identity would never match and would
+ *  break the settle fixpoint. The `StructureTypeId` brand is a symbol key, so
+ *  `Object.keys` skips it. Used by the proof/server settle loop to detect a
+ *  two-frame fixpoint. */
+export const structureEquals = (a: Structure<UiContract>, b: Structure<UiContract>): boolean =>
+  deepEquals(a.props, b.props) && deepEquals(a.slots, b.slots)

package/src/compose/ui.test.ts

@@ -1,8 +1,6 @@
 import { expect, test } from 'vitest'
-import { Effect, Schema as S } from 'effect'
-import { Ui, isUi, ui } from '../index'
-import { CaptureSink, type UiCapture } from '../internal/capture'
-import type { Trigger } from '../ui/trigger'
+import { Schema as S } from 'effect'
+import { isUi, ui } from '../index'
 
 // `ui` has two authoring forms with one source of truth each: the type-only form
 // (local, no schema) and the schema form (wired, the type is *derived*). Both are
@@ -34,29 +32,3 @@ test('schema `ui` with no events omits the events schema', () => {
   expect(S.isSchema(TitleUi.manifest.props)).toBe(true)
   expect(TitleUi.manifest.events).toBeUndefined()
 })
-
-test('a contract resolves its presentation and reports to a capturing sink', () => {
-  class CounterUi extends ui('Counter', {
-    props: S.Struct({ count: S.Number }),
-    events: { bump: S.Struct({ by: S.Number }) },
-  }) {}
-
-  const view = Ui.make(CounterUi, ({ count }) => `count:${count}`)
-  const records: UiCapture[] = []
-  const sink = { record: (capture: UiCapture): void => void records.push(capture) }
-
-  const logicView = Effect.runSync(
-    CounterUi.pipe(
-      Effect.provideService(CounterUi.impl, view),
-      Effect.provideService(CaptureSink, sink),
-    ),
-  )
-
-  const bump: Trigger<{ by: number }> = () => {}
-  const node = logicView({ count: 3 }, { bump })
-
-  expect(node).toBe('count:3')
-  expect(records).toHaveLength(1)
-  expect(records[0]?.name).toBe('Counter')
-  expect(records[0]?.props).toEqual({ count: 3 })
-})

package/src/compose/ui.ts

@@ -1,10 +1,7 @@
 import type { FunctionComponent } from 'react'
-import { Context, Effect, Option, type Schema } from 'effect'
-import { type Manifest, yieldableClass } from '../definition/definition'
-import { CaptureSink } from '../internal/capture'
-import { SlotRenderingUnavailable } from '../internal/errors'
+import { Context, type Schema } from 'effect'
+import { type Manifest, definitionClass } from '../definition/definition'
 import type { Trigger } from '../ui/trigger'
-import { CurrentSlots } from './host'
 import { type Node, type SlotClass, type SlotInstance, type SlotProps } from './slot'
 
 export interface UiContract {
@@ -14,7 +11,10 @@ export interface UiContract {
 }
 
 type PropsOf<C extends UiContract> = C['props']
-type EventsOf<C extends UiContract> = C extends { events: infer E } ? E : Record<never, never>
+/** The contract's event map (`{ [name]: Trigger<P> }`), or empty when it declares
+ *  none. Exported so a `Structure<C>` can type its optional `events` field to the
+ *  same map a composition body acquires. */
+export type EventsOf<C extends UiContract> = C extends { events: infer E } ? E : Record<never, never>
 // A slot is a React COMPONENT whose props are OPTIONAL (a `Partial`): a parent that
 // drives a child supplies them (`<slots.Item id=… />` / `createElement(slots.Item, {…})`),
 // but a placeholder render (the remote client, where the per-child props were captured
@@ -35,15 +35,18 @@ type SlotsOf<C extends UiContract> = C extends { slots: infer S }
       // child props are `any` the whole thing still collapses to `any` (`any & X = any`), keeping
       // the component assignable to a bare `(props: unknown) => Node` slot-renderer shape. An
       // outer intersection would leave a required-shape object that `unknown` can't satisfy.
+      //
+      // A slot handle is BOTH renderable (the `FunctionComponent` — places the keyed children)
+      // AND inspectable (`.props` — the array of per-child fill props the structure carried, one
+      // entry per mounted child, typed by the child contract). A presentation can read the fills
+      // (`slots.Item.props.length`, a header, layout decisions) and still render them
+      // (`<slots.Item/>`); it never DERIVES multiplicity — the engine already fixed it. Read-only.
       readonly [K in keyof S]: FunctionComponent<
         Partial<SlotProps<S[K]> & { readonly slotKey?: string }>
-      >
+      > & { readonly props: ReadonlyArray<SlotProps<S[K]>> }
     }
   : Record<never, never>
 
-/** What the composition logic calls: props + handlers in, a node out. Slots are bound by the renderer. */
-export type LogicView<C extends UiContract> = (props: PropsOf<C>, events?: EventsOf<C>) => Node
-
 /** What `.make` authors: the pure presentation. Slots are injected by the renderer. */
 export type ViewImpl<C extends UiContract> = (
   props: PropsOf<C>,
@@ -73,8 +76,9 @@ export interface WiredUiManifest extends UiManifest {
   readonly props: Schema.Schema<any, any>
 }
 
-export interface UiClass<C extends UiContract>
-  extends Effect.Effect<LogicView<C>, never, ViewImpl<C>> {
+// A branded, extendable class carrying the wire `manifest` + the DI `impl` tag. Not
+// yieldable: bodies return a `Structure`, and the host reads `impl` to resolve the view.
+export interface UiClass<C extends UiContract> {
   new (): {}
   readonly [UiTypeId]: UiTypeId
   readonly manifest: UiManifest
@@ -144,34 +148,9 @@ const buildUi = <C extends UiContract, M extends UiManifest>(
   manifest: M,
 ): UiClass<C> & { readonly manifest: M } => {
   const impl = Context.GenericTag<ViewImpl<C>, ViewImpl<C>>(`reform/ui/${name}`)
-  const read = Effect.gen(function* () {
-    const render = yield* impl
-    // Slots are bound by the host (`@reform/react`) per composition instance.
-    // Core has no renderer, so without a host every slot access throws.
-    const host = yield* Effect.serviceOption(CurrentSlots)
-    const slots = new Proxy({} as SlotsOf<C>, {
-      get(_t, key) {
-        if (Option.isNone(host)) {
-          throw new SlotRenderingUnavailable({ slot: String(key) })
-        }
-        return host.value.slot(String(key))
-      },
-    })
-    // A capturing host (proofs, the dev tool) reports each render's observable
-    // surface without replacing the presentation. Absent in production.
-    const sink = yield* Effect.serviceOption(CaptureSink)
-    return (props: PropsOf<C>, events?: EventsOf<C>) => {
-      if (Option.isSome(sink)) {
-        sink.value.record({
-          name,
-          props,
-          events: (events ?? {}) as Record<string, Trigger<unknown>>,
-        })
-      }
-      return render(props, slots, (events ?? {}) as EventsOf<C>)
-    }
-  })
-  return yieldableClass(read, {
+  // Extendable definition class (`class Counter extends ui('Counter', …) {}`); resolved
+  // by name on a host via `impl`, never yielded.
+  return definitionClass<UiClass<C> & { readonly manifest: M }>({
     [UiTypeId]: UiTypeId,
     manifest,
     impl,
@@ -179,9 +158,8 @@ const buildUi = <C extends UiContract, M extends UiManifest>(
 }
 
 /**
- * A renderer-neutral UI contract. The logic resolves it (`yield* TodoAppUi`) to
- * a `(props, events) => node` view with slots already bound; `.make` authors the
- * presentation. Core defines the contract; `@reform/react` does the rendering.
+ * A renderer-neutral UI contract: `.make` authors the presentation, a composition
+ * names it, and `@reform/react` resolves it to a view. Core defines the contract.
  *
  * Two authoring forms, one source of truth each:
  *

package/src/index.ts

@@ -56,8 +56,25 @@ export * as Composition from './compose/composition'
 export type {
   CompositionClass,
   CompositionService,
+  Frame,
   RenderEnv,
 } from './compose/composition'
+export {
+  absent,
+  each,
+  type EachFill,
+  isStructure,
+  mount,
+  one,
+  type OneFill,
+  type AbsentFill,
+  type SlotFill,
+  type Structure,
+  structureEquals,
+  type StructureSlots,
+  StructureTypeId,
+  when,
+} from './compose/structure'
 export { Props } from './compose/props'
 export {
   isSlot,
@@ -68,12 +85,11 @@ export {
   type SlotProps,
   SlotTypeId,
 } from './compose/slot'
-export { CurrentSlots, type SlotHost } from './compose/host'
+export { type SlotRenderer } from './compose/host'
 export * as Ui from './compose/ui'
 export {
   type DerivedContract,
   isUi,
-  type LogicView,
   type MadeView,
   ui,
   type UiClass,
@@ -151,7 +167,6 @@ export {
   FeatureLoadFailed,
   forceSync,
   InvalidProvideTarget,
-  SlotRenderingUnavailable,
   UnknownGroupState,
 } from './internal/errors'
 // Notification scheduler: hosts that need per-runtime isolation (concurrent SSR,

package/src/internal/capture.ts

@@ -10,6 +10,14 @@ export interface UiCapture {
   readonly name: string
   readonly props: unknown
   readonly events: Record<string, Trigger<unknown>>
+  /**
+   * The stable slot-fill key this render was mounted under (an `each` item's
+   * `key`, or a synthesized singleton key for a `one`). Present only on the
+   * structure path — the legacy Node path defers slot expansion to host
+   * components and has no fill key, so it is omitted there. Lets the proof
+   * facade select a child by key (`byKey`) instead of by render index.
+   */
+  readonly key?: string
 }
 
 /** Where captured renders are reported, when a capturing host is present. */

package/src/internal/errors.ts

@@ -19,18 +19,6 @@ type TaggedErrorClass<Tag extends string, A extends Record<string, unknown>> = n
 /** The fieldless variant — a `Data.TaggedError(tag)<{}>` constructor. */
 type EmptyTaggedErrorClass<Tag extends string> = new () => Cause.YieldableError & { readonly _tag: Tag }
 
-const SlotRenderingUnavailableBase: TaggedErrorClass<
-  'reform/SlotRenderingUnavailable',
-  { readonly slot: string }
-> = Data.TaggedError('reform/SlotRenderingUnavailable')<{ readonly slot: string }>
-
-/** A `<slots.X/>` was rendered without a render-target host to realize it. */
-export class SlotRenderingUnavailable extends SlotRenderingUnavailableBase {
-  override get message(): string {
-    return `reform: rendering slot '${this.slot}' requires @reform/react`
-  }
-}
-
 const InvalidProvideTargetBase: EmptyTaggedErrorClass<'reform/InvalidProvideTarget'> =
   Data.TaggedError('reform/InvalidProvideTarget')<{}>
 

package/src/scene/scene.ts

@@ -1,8 +1,10 @@
 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 { Bus, Tagged } from '../runtime/bus'
+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
@@ -23,27 +25,37 @@ import type { Bus, Tagged } from '../runtime/bus'
  */
 export type MountedServices = CompositionService | Bus
 
-export interface Scene<C extends UiContract = UiContract> {
+// 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 preserved for typed consumers. */
-  readonly composition: CompositionClass<unknown, C>
+  /** 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<Tagged>
+  readonly boot?: ReadonlyArray<BootEvent>
 }
 
 /**
  * Define a scene — `scene(TodoApp, { provide: [makeTestApp(client, seeds)] })`.
- * The composition's contract flows through `C`, so consumers stay typed.
+ * The composition's contract `C` and state tuple `S` flow through, so consumers
+ * (the facade, `seedScene`) stay typed.
  */
-export const scene = <C extends UiContract>(
-  composition: CompositionClass<unknown, C>,
+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<Tagged>
+    readonly boot?: ReadonlyArray<BootEvent>
   },
-): Scene<C> => ({
+): Scene<C, S> => ({
   kind: 'Scene',
   composition,
   provide: config.provide,
@@ -63,10 +75,10 @@ export const scene = <C extends UiContract>(
  * an invalid value silently falls back to the authored seed. `StateFamily`
  * entries are not covered.
  */
-export const seedScene = <C extends UiContract>(
-  base: Scene<C>,
-  seeds: Readonly<Record<string, unknown>>,
-): Scene<C> =>
+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)) }

package/src/scene/seedScene.test.ts

@@ -1,11 +1,11 @@
 import { Effect, Layer, ManagedRuntime, Schema as S } from 'effect'
 import { expect, test } from 'vitest'
 import {
-  type CaptureSinkApi,
-  CaptureSink,
   Composition,
   Engine,
   Event,
+  isStructure,
+  mount,
   provide,
   publish,
   Reducer,
@@ -18,13 +18,14 @@ import {
   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 CaptureSink.
+// composition's rendered props through the headless Structure.
 
 class CountState extends State.make('count', S.Number) {}
 class MiniStates extends StateGroup.make(CountState) {}
@@ -46,8 +47,7 @@ class Counter extends Composition.make('Counter', {
 }) {}
 const CounterLive = Composition.live(Counter, function* () {
   const count = yield* StateGroup.select(MiniStates, 'count')
-  const view = yield* CounterUi
-  return view({ count })
+  return mount({ props: { count }, slots: {} })
 })
 
 // The closed app layer a scene provides: views + logic + Engine, with the state
@@ -61,37 +61,44 @@ 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: () => {} },
-  slots: { slot: () => () => null },
 }
 
-// One ManagedRuntime per scene under test, with its own capture cell so two
-// runtimes in the same test (the no-leakage case) cannot bleed into each other.
-// Each `read` re-renders the root composition, repopulating the cell from the
-// stores that runtime actually built.
+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 captured: { count: number } = { count: -1 }
-  const sink: CaptureSinkApi = {
-    record: (capture) => {
-      const props = capture.props
-      if (
-        typeof props === 'object' &&
-        props !== null &&
-        'count' in props &&
-        typeof props.count === 'number'
-      ) {
-        captured.count = props.count
-      }
-    },
-  }
-  const layer = s.provide
-    .reduce((a, b) => Layer.merge(a, b))
-    .pipe(Layer.provideMerge(Layer.succeed(CaptureSink, sink)))
+  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.map(() => captured.count)),
+    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 }
 }
@@ -134,7 +141,7 @@ test('the live reducer drives the SAME overridden store', async () => {
 })
 
 test('an absent key leaves the authored seed in place', async () => {
-  const { runtime, read } = makeHarness(seedScene(CounterScene, { other: 1 }))
+  const { runtime, read } = makeHarness(overlayRawSeeds(CounterScene, { other: 1 }))
   try {
     expect(await runtime.runPromise(read)).toBe(1)
   } finally {
@@ -143,7 +150,7 @@ test('an absent key leaves the authored seed in place', async () => {
 })
 
 test('a schema-invalid override falls back to the authored seed', async () => {
-  const { runtime, read } = makeHarness(seedScene(CounterScene, { count: 'not-a-number' }))
+  const { runtime, read } = makeHarness(overlayRawSeeds(CounterScene, { count: 'not-a-number' }))
   try {
     expect(await runtime.runPromise(read)).toBe(1)
   } finally {

package/src/state/stateGroup.ts

@@ -51,6 +51,26 @@ export type GroupSeeds<G extends AnyStateGroup> =
     ? { 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>