@playfast/reform 0.0.7 → 0.0.8

package/src/compose/ui.ts

@@ -0,0 +1,226 @@
+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 SlotClass, type SlotInstance, type SlotProps } from './slot'
+
+export interface UiContract {
+  props: unknown
+  slots?: Record<string, SlotInstance<any>>
+  events?: Record<string, Trigger<any>>
+}
+
+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 }
+  ? {
+      // `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. */
+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>,
+  slots: SlotsOf<C>,
+  events: EventsOf<C>,
+) => Node
+
+/** Nominal brand identifying a UI contract at runtime (Effect's `TypeId` idiom). */
+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: 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 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 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>): 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

@@ -0,0 +1,76 @@
+import { Effect } from 'effect'
+import { attachInspectable } from '../internal/inspect'
+
+/** A definition's `toJSON`: its reflectable manifest, else its raw statics. */
+const describe = (statics: object): unknown => (statics as { manifest?: unknown }).manifest ?? statics
+
+/**
+ * The reflectable descriptor every primitive carries (principle #6). The editor
+ * and proof packages read these without running any logic.
+ */
+export type Kind =
+  | 'State'
+  | 'StateGroup'
+  | 'StateFamily'
+  | 'Event'
+  | 'EventGroup'
+  | 'Reducer'
+  | 'Calc'
+  | 'CalcFamily'
+  | 'AsyncCalc'
+  | 'Resource'
+  | 'RemoteState'
+  | 'SyncedStore'
+  | 'Boundary'
+  | 'Procedure'
+  | 'Channel'
+  | 'Composition'
+  | 'Ui'
+  | 'Slot'
+  | 'Feature'
+
+export interface Manifest {
+  readonly kind: Kind
+  readonly name: string
+}
+
+/**
+ * Build a class whose *static* side is itself an Effect, so `yield* TheClass`
+ * runs `read` and returns its value (the same mechanism `Context.Tag` uses).
+ * Subclasses inherit the protocol through the prototype chain, so the user's
+ * `class FeedState extends State.make(...) {}` is yieldable too.
+ *
+ * `statics` (manifest, `.live`, tag, …) are attached as own properties
+ * and likewise inherited by the subclass.
+ */
+export const yieldableClass = <A, E, R, Statics extends object>(
+  read: Effect.Effect<A, E, R>,
+  statics: Statics,
+): { new (): {} } & Effect.Effect<A, E, R> & Statics => {
+  class Base {}
+  Object.setPrototypeOf(Base, read)
+  // `defineProperty` over `Reflect.ownKeys`, not `Object.assign` over
+  // `Object.entries`: a static can shadow a non-writable own property of the
+  // class function (notably `name`, which a `Source`-shaped definition like a
+  // Calc carries) and `assign` would throw on those; and `ownKeys` (unlike
+  // `entries`) carries symbol-keyed statics — the `TypeId` brands.
+  for (const key of Reflect.ownKeys(statics)) {
+    const value = (statics as Record<PropertyKey, unknown>)[key]
+    Object.defineProperty(Base, key, { value, writable: true, enumerable: true, configurable: true })
+  }
+  // Print like an Effect value (the manifest), not `[object Object]`.
+  attachInspectable(Base, () => describe(statics))
+  return Base as never
+}
+
+/**
+ * Build a *definition class*: an empty constructible carrying static marker data
+ * (manifest, tag, policy, members, …) that the editor and proof packages reflect
+ * on. Definition interfaces declare phantom, type-only fields — a composition's
+ * `Props`, a family instance's `Key` — that exist purely for inference and have
+ * no runtime value, so the assembled object cannot *structurally* satisfy the
+ * interface. The one assertion to `Class` lives here, documented, instead of a
+ * scattered `as never` / `as unknown as` at every `*.make`.
+ */
+export const definitionClass = <Class>(statics: object): Class =>
+  attachInspectable(Object.assign(class {}, statics), () => describe(statics)) as unknown as Class

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/event/event.ts

@@ -0,0 +1,65 @@
+import { Effect, PubSub, Runtime, type Schema } from 'effect'
+import { type Manifest, definitionClass } from '../definition/definition'
+import { Bus, publish, type Tagged } from '../runtime/bus'
+import type { Trigger } from '../ui/trigger'
+
+/** The dispatched value of an event: `{ _tag, ...payload }`, matched with `Match.tags`. */
+export type EventOf<N extends string, P> = Tagged & { readonly _tag: N } & P
+
+export interface EventManifest<N extends string, P> extends Manifest {
+  readonly kind: 'Event'
+  readonly name: N
+  readonly schema: Schema.Schema<P, any>
+}
+
+export interface EventClass<out N extends string, in out P> {
+  new (): {}
+  readonly manifest: EventManifest<N, P>
+  readonly tag: N
+  /** Carrier for `Event.construct` — builds the tagged value `{ _tag, ...payload }`. */
+  readonly build: (payload: P) => EventOf<N, P>
+  /** Carrier for `Event.trigger` — the UI callback effect (High priority). */
+  readonly trigger: Effect.Effect<Trigger<P>, never, Bus>
+}
+
+export type AnyEvent = EventClass<string, any>
+export type EventType<E> = E extends EventClass<infer N, infer P> ? EventOf<N, P> : never
+
+/** A pure data fact. Events depend on nothing — only reducers tie them to state. */
+export const make = <const N extends string, P>(
+  name: N,
+  schema: Schema.Schema<P, any>,
+): EventClass<N, P> => {
+  const build = (payload: P): EventOf<N, P> => ({ _tag: name, ...payload })
+  const trigger = Effect.gen(function* () {
+    const bus = yield* Bus
+    const runtime = yield* Effect.runtime<never>()
+    // Dispatch synchronously: on the unbounded bus `publish` only enqueues and
+    // returns, so `runSync` never suspends and no fiber is forked per UI event.
+    // The drain loop still folds reducers on its own fiber — publish is pure offer.
+    return (payload: P) => {
+      Runtime.runSync(runtime)(PubSub.publish(bus, { priority: 'High', event: build(payload) }))
+    }
+  })
+  return definitionClass<EventClass<N, P>>({
+    manifest: { kind: 'Event' as const, name, schema },
+    tag: name,
+    build,
+    trigger,
+  })
+}
+
+/** Construct the tagged value for an event (used for `boot` events). */
+export const construct = <N extends string, P>(event: EventClass<N, P>, payload: P): EventOf<N, P> =>
+  event.build(payload)
+
+/** Dispatch as a follow-up (Normal priority) from a procedure/effect. */
+export const dispatch = <N extends string, P>(
+  event: EventClass<N, P>,
+  payload: P,
+): Effect.Effect<void, never, Bus> => publish('Normal', event.build(payload))
+
+/** A callback for the UI that dispatches at High priority via the runtime. */
+export const trigger = <N extends string, P>(
+  event: EventClass<N, P>,
+): Effect.Effect<Trigger<P>, never, Bus> => event.trigger

package/src/event/eventGroup.ts

@@ -0,0 +1,14 @@
+import { definitionClass } from '../definition/definition'
+import type { AnyEvent } from './event'
+
+export interface EventGroupClass<Members extends ReadonlyArray<AnyEvent>> {
+  new (): {}
+  readonly kind: 'EventGroup'
+  readonly members: Members
+}
+
+/** Compose events into a group, the same variadic shape as `StateGroup`/`RpcGroup`. */
+export const make = <const Members extends ReadonlyArray<AnyEvent>>(
+  ...members: Members
+): EventGroupClass<Members> =>
+  definitionClass<EventGroupClass<Members>>({ kind: 'EventGroup' as const, members })

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)
+})