@playfast/reform 0.0.5 → 0.0.8

package/src/compose/ui.ts

@@ -1,10 +1,11 @@
-import { Context, Effect, Option } from 'effect'
+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 type { Trigger } from '../ui/trigger'
 import { CurrentSlots } from './host'
-import { type Node, type SlotInstance, type SlotProps } from './slot'
+import { type Node, type SlotClass, type SlotInstance, type SlotProps } from './slot'
 
 export interface UiContract {
   props: unknown
@@ -14,8 +15,30 @@ export interface UiContract {
 
 type PropsOf<C extends UiContract> = C['props']
 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
+// server-side and the framework expands the children) omits them (`<slots.Item />`).
+// One `Ui.make` view thus serves both renderers. The child still reads its own
+// props/state — these are only the external props the parent feeds, advisory at the
+// slot boundary. Typing it as `FunctionComponent` makes both JSX and `createElement` work.
+//
+// `slotKey` is the universal KEYED-SLOT selector (see `WireNode.key`): for a LIST slot
+// invoked once per item (`<slots.Row slotKey={id} />`), the remote client renders only the
+// one wire child whose React `key` matches, instead of every child of that slot at every
+// call site (which duplicates the whole list under each call). It is framework-handled, not
+// forwarded to the child, so it is allowed on EVERY slot and never collides with a child's
+// own props. Omit it for singleton slots (`<slots.Create />`) — they render all children.
 type SlotsOf<C extends UiContract> = C extends { slots: infer S }
-  ? { readonly [K in keyof S]: (props: SlotProps<S[K]>) => Node }
+  ? {
+      // `slotKey` goes INSIDE the `Partial<…>` (not intersected outside) so that when a slot'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.
+      readonly [K in keyof S]: FunctionComponent<
+        Partial<SlotProps<S[K]> & { readonly slotKey?: string }>
+      >
+    }
   : Record<never, never>
 
 /** What the composition logic calls: props + handlers in, a node out. Slots are bound by the renderer. */
@@ -32,66 +55,172 @@ export type ViewImpl<C extends UiContract> = (
 export const UiTypeId: unique symbol = Symbol.for('reform/Ui')
 export type UiTypeId = typeof UiTypeId
 
+/**
+ * The reflectable descriptor a contract carries. The wire `props` / `events`
+ * schemas are present *only* on the schema (wired) form — the type-only form
+ * carries neither, so a local contract has no schema cost and no schema surface.
+ */
+export interface UiManifest extends Manifest {
+  readonly kind: 'Ui'
+  // `any` in the encoded/context slots is required by Schema's variance for
+  // branded/Class schemas; only the decoded type is ever read off these.
+  readonly props?: Schema.Schema<any, any>
+  readonly events?: Readonly<Record<string, Schema.Schema<any, any>>>
+}
+
+/** A `UiManifest` whose wire schema is present — the runtime brand of a remote-capable contract. */
+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>> {
   new (): {}
   readonly [UiTypeId]: UiTypeId
-  readonly manifest: Manifest & { readonly kind: 'Ui' }
+  readonly manifest: UiManifest
   /** Internal DI tag the `Ui.make` presentation is provided under. */
   readonly impl: Context.Tag<ViewImpl<C>, ViewImpl<C>>
 }
 
+/**
+ * Recover a contract's `UiContract` type from its `Ui` class — `Ui.Contract<typeof
+ * SomeUi>`. Lets a consumer (a proof, a reflection tool) name the contract derived
+ * from a wired `ui('X', {…})` without re-declaring it.
+ */
+export type Contract<U> = U extends UiClass<infer C> ? C : never
+
+/**
+ * A contract authored with wire schemas. Structurally a `UiClass<C>` whose
+ * manifest *carries* the schemas (`WiredUiManifest`), so it is the subtype the
+ * remote seam (`provideRemote`, the wire registry) demands while plain `provide`
+ * / `scene` / `Composition.make` keep accepting any `UiClass<C>`.
+ */
+export type WiredUi<C extends UiContract> = UiClass<C> & { readonly manifest: WiredUiManifest }
+
+/** The wire schemas a contract is authored from: props, a payload schema per event, and
+ *  (type-only) the slots the view fills. Slots carry no wire schema — the children that
+ *  fill them are their own contracts — but declaring them here threads typed slots into
+ *  the derived contract, so a WIRED contract can also have slots (e.g. a parent whose
+ *  props the client reads AND that renders slot children). */
+export interface WireSchemas {
+  readonly props: Schema.Schema<any, any>
+  readonly events?: Readonly<Record<string, Schema.Schema<any, any>>>
+  // Slots are declared with their slot CLASSES (`slot('X')<typeof Child>()`), the
+  // same values `Composition.make({ slots })` takes — NOT `SlotInstance`s. The
+  // contract's slot facade is derived from them below.
+  readonly slots?: Readonly<Record<string, SlotClass>>
+}
+
+type DerivedEvents<Sch extends WireSchemas> = Sch extends {
+  readonly events: infer E extends Record<string, Schema.Schema<any, any>>
+}
+  ? { readonly [K in keyof E]: Trigger<Schema.Schema.Type<E[K]>> }
+  : Record<never, never>
+
+type DerivedSlots<Sch extends WireSchemas> = Sch extends {
+  readonly slots: infer S extends Record<string, SlotClass>
+}
+  ? { readonly [K in keyof S]: InstanceType<S[K]> }
+  : Record<never, never>
+
+/**
+ * The `UiContract` a set of wire schemas denotes — props and event-payload
+ * *types* derived from the schemas via `Schema.Type`, plus any declared slots. The
+ * schema is the single source of truth; the contract type is inferred, never written
+ * a second time.
+ */
+export type DerivedContract<Sch extends WireSchemas> = {
+  readonly props: Schema.Schema.Type<Sch['props']>
+  readonly slots: DerivedSlots<Sch>
+  readonly events: DerivedEvents<Sch>
+}
+
 /** Whether a value is a UI contract — discriminates a `provide` target by brand. */
 export const isUi = (u: unknown): u is UiClass<UiContract> =>
   (typeof u === 'function' || typeof u === 'object') && u !== null && UiTypeId in u
 
+const buildUi = <C extends UiContract, M extends UiManifest>(
+  name: string,
+  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, {
+    [UiTypeId]: UiTypeId,
+    manifest,
+    impl,
+  })
+}
+
 /**
  * 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.
+ *
+ * Two authoring forms, one source of truth each:
+ *
+ * - **Type-only (local):** `ui('Counter')<{ props: { count: number } }>()` — no
+ *   schema, no ceremony, exactly as before.
+ * - **Schema (wired):** `ui('Counter', { props: S.Struct({ count: S.Number }) })`
+ *   — the schema *is* the definition; the contract type is derived via
+ *   `Schema.Type` (never re-written), and the result is a `WiredUi` the remote
+ *   seam accepts. Make a local contract remote by rewriting this one line.
  */
-export const ui =
-  (name: string) =>
-  <C extends UiContract>(): UiClass<C> => {
-    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, {
-      [UiTypeId]: UiTypeId,
-      manifest: { kind: 'Ui' as const, name },
-      impl,
-    })
+export function ui(name: string): <C extends UiContract>() => UiClass<C>
+export function ui<const Sch extends WireSchemas>(name: string, schemas: Sch): WiredUi<DerivedContract<Sch>>
+export function ui(name: string, schemas?: WireSchemas): unknown {
+  if (schemas === undefined) {
+    return <C extends UiContract>(): UiClass<C> => buildUi<C, UiManifest>(name, { kind: 'Ui', name })
   }
+  const eventFields = schemas.events === undefined ? {} : { events: schemas.events }
+  const manifest: WiredUiManifest = { kind: 'Ui', name, props: schemas.props, ...eventFields }
+  return buildUi<DerivedContract<WireSchemas>, WiredUiManifest>(name, manifest)
+}
+
+/** Brand under which a `Ui.make` view carries its own contract. */
+export const UiViewContract: unique symbol = Symbol.for('reform/ui/view-contract')
+export type UiViewContract = typeof UiViewContract
+
+/**
+ * A `Ui.make` view that carries its contract, so a consumer can recover the
+ * contract (its wire name + props schema) straight from the view — no separate
+ * registration call. This is what makes the remote client view-set
+ * (`remoteViews<AppContract>({ Some: SomeView, … })`) work with the very same
+ * `Ui.make` views the local renderer uses.
+ */
+export type MadeView<C extends UiContract> = ViewImpl<C> & { readonly [UiViewContract]: UiClass<C> }
 
 /**
  * Author the pure presentation for a contract — `Ui.make(TodoAppUi, (props,
- * slots, events) => node)`. The contract argument fixes the view's types; wire
- * the result with `provide(contract, view)`.
+ * slots, events) => node)`. The contract argument fixes the view's types AND is
+ * carried on the returned view (`MadeView`), so the same view is reusable as a
+ * remote client presentation. Wire the result with `provide(contract, view)`.
  */
-export const make = <C extends UiContract>(_contract: UiClass<C>, view: ViewImpl<C>): ViewImpl<C> =>
-  view
+export const make = <C extends UiContract>(contract: UiClass<C>, view: ViewImpl<C>): MadeView<C> =>
+  Object.assign(view, { [UiViewContract]: contract })

package/src/compose/ui.typecheck.ts

@@ -0,0 +1,56 @@
+// Type-level proofs enforced by `tsc --noEmit` over `src` (not a vitest file).
+// These guard the schema-first seam: the wired form is the single source of
+// truth (props/event types derived, never re-written), a wired contract is a
+// plain `UiClass` (so `provide` / `scene` / `Composition.make` accept it), and
+// the remote seam (`WiredUi`) rejects a type-only contract. If a guarantee
+// regresses, a `@ts-expect-error` goes unused or an assignment fails, and `tsc`
+// breaks.
+
+import { Schema as S } from 'effect'
+import {
+  type Contract,
+  type DerivedContract,
+  type MadeView,
+  make,
+  ui,
+  type UiClass,
+  type UiContract,
+  type WiredUi,
+} from './ui'
+
+declare function acceptsAny<C extends UiContract>(contract: UiClass<C>): void
+declare function acceptsWired<C extends UiContract>(contract: WiredUi<C>): void
+
+class LocalUi extends ui('Local')<{ props: { n: number } }>() {}
+const wiredSchemas: {
+  readonly props: S.Struct<{ n: typeof S.Number }>
+  readonly events: { readonly bump: S.Struct<{ by: typeof S.Number }> }
+} = {
+  props: S.Struct({ n: S.Number }),
+  events: { bump: S.Struct({ by: S.Number }) },
+}
+const WiredUiClassBase: WiredUi<DerivedContract<typeof wiredSchemas>> = ui('Wired', wiredSchemas)
+class WiredUiClass extends WiredUiClassBase {}
+
+// POSITIVE: both forms are a `UiClass` — plain wiring (provide/scene/Composition) accepts either.
+acceptsAny(LocalUi)
+acceptsAny(WiredUiClass)
+
+// POSITIVE: the schema form is a `WiredUi` — the remote seam accepts it.
+acceptsWired(WiredUiClass)
+
+// NEGATIVE: a type-only contract has no wire schema, so the remote seam rejects it.
+// @ts-expect-error -- LocalUi is `UiClass`, not `WiredUi`
+acceptsWired(LocalUi)
+
+// POSITIVE: props/event types are DERIVED from the schemas — authoring a presentation
+// against the wired contract sees `n: number` and `bump: Trigger<{ by: number }>`,
+// none of it written a second time.
+export const derivedView: MadeView<Contract<typeof WiredUiClass>> = make(
+  WiredUiClass,
+  ({ n }, _slots, { bump }) => {
+    const _n: number = n
+    bump({ by: _n })
+    return `${_n}`
+  },
+)

package/src/definition/definition.ts

@@ -18,7 +18,9 @@ export type Kind =
   | 'Calc'
   | 'CalcFamily'
   | 'AsyncCalc'
+  | 'Resource'
   | 'RemoteState'
+  | 'SyncedStore'
   | 'Boundary'
   | 'Procedure'
   | 'Channel'

package/src/event/event.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from 'vitest'
+import { Schema as S } from 'effect'
+import { Event } from '../index'
+
+// An event is a pure data fact: `Event.construct` builds the tagged value the
+// bus carries, and the class carries the reflectable `manifest` + `tag`.
+
+test('Event.construct builds the tagged value `{ _tag, ...payload }`', () => {
+  class Added extends Event.make('Added', S.Struct({ id: S.String })) {}
+  expect(Event.construct(Added, { id: 'x' })).toEqual({ _tag: 'Added', id: 'x' })
+})
+
+test('an event carries its reflectable manifest and tag', () => {
+  class Added extends Event.make('Added', S.Struct({ id: S.String })) {}
+  expect(Added.tag).toBe('Added')
+  expect(Added.manifest.kind).toBe('Event')
+  expect(Added.manifest.name).toBe('Added')
+})
+
+test('empty-payload events construct to just their tag', () => {
+  class Pinged extends Event.make('Pinged', S.Struct({})) {}
+  expect(Event.construct(Pinged, {})).toEqual({ _tag: 'Pinged' })
+})

package/src/feature/feature.mount.test.ts

@@ -0,0 +1,82 @@
+import { type Cause, Duration, Effect, Exit, Layer, ManagedRuntime, Scope } from 'effect'
+import { Schema as S } from 'effect'
+import { expect, test } from 'vitest'
+import * as Composition from '../compose/composition'
+import { ui } from '../compose/ui'
+import * as Event from '../event/event'
+import * as Reducer from '../reducer/reducer'
+import * as State from '../state/state'
+import { publish } from '../runtime/bus'
+import { Engine, Reducers } from '../runtime/loop'
+import * as Feature from './feature'
+import { type EngineServices, featureModule, mountFeature } from './feature'
+
+// A self-contained feature: a Count state + a reducer that folds Tick. The base
+// seeds Count; the logic provides the reducer over it and leaves the engine
+// (Reducers registry) OPEN, so `mountFeature` builds it against the live engine.
+class Tick extends Event.make('Tick', S.Struct({})) {}
+class Count extends State.make('count', S.Number) {}
+class CountReducer extends Reducer.make('CountReducer', { states: [Count], events: [Tick] }) {}
+
+const mod = featureModule(
+  [],
+  Reducer.live(CountReducer, (n) => n + 1).pipe(Layer.provideMerge(State.live(Count, 0))),
+)
+
+// A trivial composition to hang the feature off (definitions only).
+class CtrUi extends ui('CtrUi')<{ props: {}; events: {} }>() {}
+class CtrComp extends Composition.make('CtrComp', { title: 'Counter', ui: CtrUi }) {}
+
+class CounterFeature extends Feature.make('counter', {
+  composition: CtrComp,
+  module: mod,
+  boot: [Event.construct(Tick, {})],
+}) {}
+
+// Poll a read until it satisfies a predicate (the loop drains on a forked fiber).
+const waitUntil = <A, R>(
+  read: Effect.Effect<A, never, R>,
+  pred: (a: A) => boolean,
+): Effect.Effect<A, Cause.TimeoutException, R> =>
+  Effect.flatMap(read, (a) =>
+    pred(a)
+      ? Effect.succeed(a)
+      : Effect.flatMap(Effect.sleep(Duration.millis(1)), () => waitUntil(read, pred)),
+  ).pipe(Effect.timeout(Duration.seconds(2)))
+
+test('a mounted feature registers on the shared loop, boots, and folds dispatched events', async () => {
+  const runtime = ManagedRuntime.make(Engine)
+  try {
+    await runtime.runPromise(
+      Effect.gen(function* () {
+        const engineContext = yield* Effect.context<EngineServices>()
+        const reducers = yield* Reducers
+        const baseline = reducers.entries.length
+
+        const scope = yield* Scope.make()
+        const ctx = yield* mountFeature(CounterFeature.binding, engineContext).pipe(
+          Effect.provideService(Scope.Scope, scope),
+        )
+        // Registered into the SHARED registry.
+        expect(reducers.entries.length).toBe(baseline + 1)
+
+        // boot dispatched Tick → Count folds to 1 on the shared loop.
+        const booted = yield* waitUntil(Count.pipe(Effect.provide(ctx)), (n) => n === 1)
+        expect(booted).toBe(1)
+
+        // A further dispatch on the shared bus folds again → 2.
+        yield* publish('High', Event.construct(Tick, {}))
+        const folded = yield* waitUntil(Count.pipe(Effect.provide(ctx)), (n) => n === 2)
+        expect(folded).toBe(2)
+
+        // Unmount: closing the feature scope unregisters its reducer — the entry is
+        // reclaimed, not left folding onto an orphaned store.
+        yield* Scope.close(scope, Exit.succeed(undefined))
+        expect(reducers.entries.length).toBe(baseline)
+        expect(reducers.byTag.get('Tick')).toBeUndefined()
+      }),
+    )
+  } finally {
+    await runtime.dispose()
+  }
+})

package/src/feature/feature.test.ts

@@ -0,0 +1,60 @@
+import { Effect, Layer } from 'effect'
+import { expect, test } from 'vitest'
+import * as Composition from '../compose/composition'
+import { ui } from '../compose/ui'
+import * as Feature from './feature'
+import { featureModule, isFeature, isFeatureBinding, lazyImport } from './feature'
+
+// Minimal composition surface to hang features off — definitions only, no logic.
+class TestUi extends ui('TestUi')<{ props: {}; events: {} }>() {}
+class TestComp extends Composition.make('TestComp', { title: 'Test', ui: TestUi }) {}
+class FailComp extends Composition.make('FailComp', { title: 'Fail', ui: TestUi }) {}
+
+// A trivial loaded module: empty layer, no shared requirements.
+const mod = featureModule([], Layer.empty)
+
+class LazyFeature extends Feature.make('lazyFeature', {
+  loadingStrategy: 'lazy',
+  composition: TestComp,
+  load: lazyImport(() => Promise.resolve({ default: mod })),
+  placeholder: { loading: TestComp, failed: FailComp },
+}) {}
+
+class EagerFeature extends Feature.make('eagerFeature', {
+  composition: TestComp,
+  module: mod,
+}) {}
+
+test('a lazy feature reflects as a Feature manifest with placeholders, no chunk loaded', () => {
+  expect(LazyFeature.manifest.kind).toBe('Feature')
+  expect(LazyFeature.manifest.name).toBe('lazyFeature')
+  expect(LazyFeature.manifest.strategy).toBe('lazy')
+  expect(LazyFeature.manifest.composition.name).toBe('TestComp')
+  expect(LazyFeature.manifest.placeholder?.loading.name).toBe('TestComp')
+  expect(LazyFeature.manifest.placeholder?.failed.name).toBe('FailComp')
+  expect(LazyFeature.eagerModule).toBeUndefined()
+})
+
+test('an eager feature reflects as default strategy with its module available', () => {
+  expect(EagerFeature.manifest.strategy).toBe('default')
+  expect(EagerFeature.manifest.placeholder).toBeUndefined()
+  expect(EagerFeature.eagerModule).toBe(mod)
+})
+
+test('isFeature / isFeatureBinding discriminate', () => {
+  expect(isFeature(LazyFeature)).toBe(true)
+  expect(isFeature(TestComp)).toBe(false)
+  expect(isFeature(null)).toBe(false)
+  expect(isFeatureBinding(LazyFeature.binding)).toBe(true)
+  expect(isFeatureBinding(TestComp)).toBe(false)
+})
+
+test('load is an Effect (not a thenable) that yields the module and its requires', async () => {
+  // No `.then` on `load` — it is an Effect, run on the Effect runtime.
+  expect(typeof (LazyFeature.load as { then?: unknown }).then).toBe('undefined')
+  const loaded = await Effect.runPromise(LazyFeature.load)
+  expect(loaded.requires).toEqual([])
+  expect(loaded).toBe(mod)
+  // default strategy resolves immediately to its module.
+  expect(await Effect.runPromise(EagerFeature.load)).toBe(mod)
+})

package/src/feature/feature.typecheck.ts

@@ -0,0 +1,108 @@
+// Type-level proofs enforced by `tsc --noEmit` over `src` (not a vitest file).
+// These guard the cast-free seam: if a guarantee regresses, a `@ts-expect-error`
+// goes unused or an assignment fails, and `tsc` breaks.
+
+import { Layer, Schema as S } from 'effect'
+import type { Store } from '../internal/store'
+import * as Composition from '../compose/composition'
+import { provide } from '../compose/provide'
+import { type SlotChild, type SlotClass, slot } from '../compose/slot'
+import { type Contract, type UiClass, ui } from '../compose/ui'
+import * as State from '../state/state'
+import * as StateGroup from '../state/stateGroup'
+import { type EngineServices, type FeatureModule, featureModule, lazyImport } from './feature'
+import * as Feature from './feature'
+
+const FeedStateBase: State.StateClass<'feed', string> = State.make('feed', S.String)
+class FeedState extends FeedStateBase {}
+const FilterStateBase: State.StateClass<'filter', string> = State.make('filter', S.String)
+class FilterState extends FilterStateBase {}
+const TodosStatesBase: StateGroup.StateGroupClass<readonly [typeof FeedState, typeof FilterState]> =
+  StateGroup.make(FeedState, FilterState)
+class TodosStates extends TodosStatesBase {}
+
+// --- featureModule: the covariant-RIn bound (cast-free requirement honesty) ---
+
+// A feature layer that reads FeedState's store and the shared engine — nothing else.
+declare const readsFeed: Layer.Layer<{ readonly _out: true }, never, Store<string> | EngineServices>
+
+// POSITIVE: declaring the State it reads in `requires` covers the read — compiles.
+export const okState: FeatureModule<{ readonly _out: true }, readonly [typeof FeedState]> =
+  featureModule([FeedState], readsFeed)
+
+// POSITIVE: a StateGroup contributes its members' stores via `ProvidedBy` — compiles.
+export const okGroup: FeatureModule<{ readonly _out: true }, readonly [typeof TodosStates]> =
+  featureModule([TodosStates], readsFeed)
+
+// NEGATIVE: empty `requires` provides only the engine, not Store<string>; covariant
+// `RIn` makes the layer unassignable to the declared bound.
+export const badEmpty: FeatureModule<{ readonly _out: true }, readonly []> =
+  // @ts-expect-error feature layer reads a store it does not declare in `requires`
+  featureModule([], readsFeed)
+
+// --- provide(slot, Feature): RIn surfacing + composition match ---
+
+const AppUiBase: UiClass<{ props: { readonly a: string }; events: {} }> = ui('AppUi')<{
+  props: { readonly a: string }
+  events: {}
+}>()
+class AppUi extends AppUiBase {}
+const AppCompBase: Composition.CompositionClass<{ readonly a: string }, Contract<typeof AppUi>> =
+  Composition.make('AppComp', {
+    title: 'App',
+    props: S.Struct({ a: S.String }),
+    ui: AppUi,
+  })
+class AppComp extends AppCompBase {}
+const AppSlotBase: SlotClass<typeof AppComp> = slot('App')<typeof AppComp>()
+class AppSlot extends AppSlotBase {}
+
+const AppFeatureBase: Feature.FeatureClass<
+  { readonly a: string },
+  Contract<typeof AppUi>,
+  never,
+  readonly []
+> = Feature.make('appFeature', {
+  loadingStrategy: 'lazy',
+  composition: AppComp,
+  load: lazyImport(() => Promise.resolve({ default: featureModule([], Layer.empty) })),
+  placeholder: { loading: AppComp, failed: AppComp },
+})
+class AppFeature extends AppFeatureBase {}
+
+// POSITIVE: the wired layer's open `RIn` is exactly `EngineServices` (requires=[]),
+// so a scene must provide `Core` — surfaced cast-free by the overload.
+export const wired: Layer.Layer<SlotChild, never, EngineServices> = provide(AppSlot, AppFeature)
+
+// A feature over a DIFFERENT contract must not fill `AppSlot`.
+const OtherUiBase: UiClass<{ props: { readonly n: number }; events: {} }> = ui('OtherUi')<{
+  props: { readonly n: number }
+  events: {}
+}>()
+class OtherUi extends OtherUiBase {}
+const OtherCompBase: Composition.CompositionClass<{ readonly n: number }, Contract<typeof OtherUi>> =
+  Composition.make('OtherComp', {
+    title: 'Other',
+    props: S.Struct({ n: S.Number }),
+    ui: OtherUi,
+  })
+class OtherComp extends OtherCompBase {}
+const OtherFeatureBase: Feature.FeatureClass<
+  { readonly n: number },
+  Contract<typeof OtherUi>,
+  never,
+  readonly []
+> = Feature.make('otherFeature', {
+  loadingStrategy: 'lazy',
+  composition: OtherComp,
+  load: lazyImport(() => Promise.resolve({ default: featureModule([], Layer.empty) })),
+  placeholder: { loading: OtherComp, failed: OtherComp },
+})
+class OtherFeature extends OtherFeatureBase {}
+
+// NEGATIVE: OtherFeature's composition props don't match AppSlot's child composition.
+// @ts-expect-error feature composition does not match the slot's child type
+export const mismatched: Layer.Layer<SlotChild, never, EngineServices> = provide(
+  AppSlot,
+  OtherFeature,
+)