@playfast/reform 0.0.7 → 0.0.9

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

package/{dist/feature/feature.d.ts → src/feature/feature.ts}

@@ -1,11 +1,19 @@
-import { type Context, Effect, Layer, type Scope } from 'effect';
-import { type Engine } from '../runtime/loop';
-import { type StoresOf } from '../internal/sources';
-import { FeatureLoadFailed } from '../internal/errors';
-import { type Manifest } from '../definition/definition';
-import { type CompositionClass } from '../compose/composition';
-import { type UiContract } from '../compose/ui';
-import { type Tagged } from '../runtime/bus';
+import { type Context, Effect, Layer, type Scope } from 'effect'
+import { type Engine } from '../runtime/loop'
+import { type StoresOf } from '../internal/sources'
+import { FeatureLoadFailed } from '../internal/errors'
+import { type Manifest, definitionClass } from '../definition/definition'
+import { type CompositionClass } from '../compose/composition'
+import { type UiContract } from '../compose/ui'
+import { publish, type Tagged } from '../runtime/bus'
+
+// A `Feature` is the unit of lazy code-split, ownership, reflection, and proof.
+// It splits on the seam Reform already has: definitions (manifests, schemas, the
+// composition class, placeholders) stay eager and reflectable; the heavy `.live`
+// layer loads on demand. The whole-app *shape* stays inspectable with no chunk
+// loaded. Everything here is additive — `provide(slot, Composition)` and eager
+// scenes are unchanged. See `LAZY.md` for the design rationale and variance proof.
+
 /**
  * The always-on engine services a feature builds against: the shared event `Bus`
  * plus the reducer/channel/procedure registries. Derived from the `Engine`
@@ -13,20 +21,18 @@ import { type Tagged } from '../runtime/bus';
  * these only as OPEN requirements (its `RIn`) and must never *provide* them — that
  * is what keeps the engine single and shared across every lazily-mounted feature.
  */
-export type EngineServices = Layer.Layer.Success<typeof Engine>;
+export type EngineServices = Layer.Layer.Success<typeof Engine>
+
 /**
  * A shared-state carrier a feature may declare in `requires`: a `State`,
  * `StateFamily`, `Calc`, or `AsyncCalc` (each carrying a `store` tag), or a
  * `StateGroup` (carrying `members`, each with its own `store`). Per the design,
  * a feature depends on shared state/calc only — never on another feature.
  */
-export type RequireCarrier = {
-    readonly store: Context.Tag<any, any>;
-} | {
-    readonly members: ReadonlyArray<{
-        readonly store: Context.Tag<any, any>;
-    }>;
-};
+export type RequireCarrier =
+  | { readonly store: Context.Tag<any, any> }
+  | { readonly members: ReadonlyArray<{ readonly store: Context.Tag<any, any> }> }
+
 /**
  * The Context services a `requires` tuple makes available to a feature layer: a
  * `StateGroup` contributes its members' stores (the shared `StoresOf`); every
@@ -37,12 +43,15 @@ export type RequireCarrier = {
  * is ordinary assignability — no `as`, no `infer` gymnastics in user code.
  */
 export type ProvidedBy<Requires extends ReadonlyArray<RequireCarrier>> = {
-    [I in keyof Requires]: Requires[I] extends {
-        readonly members: infer M extends ReadonlyArray<unknown>;
-    } ? StoresOf<M> : Requires[I] extends {
-        readonly store: Context.Tag<infer Svc, any>;
-    } ? Svc : never;
-}[number];
+  [I in keyof Requires]: Requires[I] extends {
+    readonly members: infer M extends ReadonlyArray<unknown>
+  }
+    ? StoresOf<M>
+    : Requires[I] extends { readonly store: Context.Tag<infer Svc, any> }
+      ? Svc
+      : never
+}[number]
+
 /**
  * A loaded feature's two artifacts. `requires` is the runtime-enumerable list the
  * editor reads (types are erased, so the carriers are kept as values); `layer` is
@@ -53,9 +62,10 @@ export type ProvidedBy<Requires extends ReadonlyArray<RequireCarrier>> = {
  * a feature's lazy half.
  */
 export interface FeatureModule<ROut, Requires extends ReadonlyArray<RequireCarrier>> {
-    readonly requires: Requires;
-    readonly layer: Layer.Layer<ROut, never, EngineServices | ProvidedBy<Requires>>;
+  readonly requires: Requires
+  readonly layer: Layer.Layer<ROut, never, EngineServices | ProvidedBy<Requires>>
 }
+
 /**
  * Publish a feature's lazy half: pair its `requires` (a runtime tuple of shared
  * carriers) with its `layer`. The covariant `RIn` bound does the checking — a
@@ -67,7 +77,11 @@ export interface FeatureModule<ROut, Requires extends ReadonlyArray<RequireCarri
  * be open `RIn`), structurally enforcing the liveness rule: a feature can never
  * bundle its own engine — it always shares the root's bus and registries.
  */
-export declare const featureModule: <const Requires extends ReadonlyArray<RequireCarrier>, ROut>(requires: Requires, layer: Layer.Layer<ROut, never, EngineServices | ProvidedBy<Requires>>) => FeatureModule<ROut, Requires>;
+export const featureModule = <const Requires extends ReadonlyArray<RequireCarrier>, ROut>(
+  requires: Requires,
+  layer: Layer.Layer<ROut, never, EngineServices | ProvidedBy<Requires>>,
+): FeatureModule<ROut, Requires> => ({ requires, layer })
+
 /**
  * Wrap a dynamic `import()` of a feature's `.live` module as an `Effect` — Reform
  * never exposes a Promise/`await` on the feature surface. The unavoidable thenable
@@ -75,14 +89,20 @@ export declare const featureModule: <const Requires extends ReadonlyArray<Requir
  * throw) surfaces as a typed `FeatureLoadFailed` the host hands to
  * `placeholder.failed`. The module's default export is its `FeatureModule`.
  */
-export declare const lazyImport: <M>(thunk: () => Promise<{
-    readonly default: M;
-}>) => Effect.Effect<M, FeatureLoadFailed>;
+export const lazyImport = <M>(
+  thunk: () => Promise<{ readonly default: M }>,
+): Effect.Effect<M, FeatureLoadFailed> =>
+  Effect.tryPromise({
+    try: thunk,
+    catch: (cause) => new FeatureLoadFailed({ cause }),
+  }).pipe(Effect.map((module) => module.default))
+
 /** The props the host injects into a lazy feature's `failed` placeholder. */
 export interface FailedProps {
-    readonly error: FeatureLoadFailed;
-    readonly retry: () => void;
+  readonly error: FeatureLoadFailed
+  readonly retry: () => void
 }
+
 /**
  * The reflectable shape of a feature: its strategy, the composition it mounts,
  * and (when lazy) its placeholder compositions — all as manifests, so the editor
@@ -90,21 +110,16 @@ export interface FailedProps {
  * runtime data and lives on the `FeatureBinding`, not here.
  */
 export interface FeatureManifest extends Manifest {
-    readonly kind: 'Feature';
-    readonly name: string;
-    readonly strategy: 'lazy' | 'default';
-    readonly composition: Manifest & {
-        readonly kind: 'Composition';
-    };
-    readonly placeholder?: {
-        readonly loading: Manifest & {
-            readonly kind: 'Composition';
-        };
-        readonly failed: Manifest & {
-            readonly kind: 'Composition';
-        };
-    };
+  readonly kind: 'Feature'
+  readonly name: string
+  readonly strategy: 'lazy' | 'default'
+  readonly composition: Manifest & { readonly kind: 'Composition' }
+  readonly placeholder?: {
+    readonly loading: Manifest & { readonly kind: 'Composition' }
+    readonly failed: Manifest & { readonly kind: 'Composition' }
+  }
 }
+
 /**
  * A feature's loaded artifacts with type params erased, for the renderer-neutral,
  * strategy-uniform host. The erasure is cast-free *into*: because `Layer`'s `ROut`
@@ -114,12 +129,14 @@ export interface FeatureManifest extends Manifest {
  * documented boundary cast there, mirroring `buildRuntime`).
  */
 export interface LoadedModule {
-    readonly requires: ReadonlyArray<RequireCarrier>;
-    readonly layer: Layer.Layer<never, never, unknown>;
+  readonly requires: ReadonlyArray<RequireCarrier>
+  readonly layer: Layer.Layer<never, never, unknown>
 }
+
 /** Nominal brand identifying the value a `provide(slot, Feature)` puts under a slot tag. */
-export declare const FeatureBindingTypeId: unique symbol;
-export type FeatureBindingTypeId = typeof FeatureBindingTypeId;
+export const FeatureBindingTypeId: unique symbol = Symbol.for('reform/FeatureBinding')
+export type FeatureBindingTypeId = typeof FeatureBindingTypeId
+
 /**
  * What `provide(slot, Feature)` binds under the slot tag — everything the host
  * needs to mount the feature, with types erased (the host is renderer-neutral and
@@ -130,19 +147,22 @@ export type FeatureBindingTypeId = typeof FeatureBindingTypeId;
  * each.
  */
 export interface FeatureBinding {
-    readonly [FeatureBindingTypeId]: FeatureBindingTypeId;
-    readonly manifest: FeatureManifest;
-    readonly composition: CompositionClass<unknown>;
-    readonly strategy: 'lazy' | 'default';
-    readonly load: Effect.Effect<LoadedModule, FeatureLoadFailed>;
-    readonly placeholder?: {
-        readonly loading: CompositionClass<unknown>;
-        readonly failed: CompositionClass<unknown>;
-    };
-    readonly boot: ReadonlyArray<Tagged>;
+  readonly [FeatureBindingTypeId]: FeatureBindingTypeId
+  readonly manifest: FeatureManifest
+  readonly composition: CompositionClass<unknown>
+  readonly strategy: 'lazy' | 'default'
+  readonly load: Effect.Effect<LoadedModule, FeatureLoadFailed>
+  readonly placeholder?: {
+    readonly loading: CompositionClass<unknown>
+    readonly failed: CompositionClass<unknown>
+  }
+  readonly boot: ReadonlyArray<Tagged>
 }
+
 /** Whether a slot's bound child is a lazy/eager feature (vs a plain composition). */
-export declare const isFeatureBinding: (u: unknown) => u is FeatureBinding;
+export const isFeatureBinding = (u: unknown): u is FeatureBinding =>
+  typeof u === 'object' && u !== null && FeatureBindingTypeId in u
+
 /**
  * A feature *definition*: a reflectable manifest (`kind: 'Feature'`) that carries
  * the eager half (composition + placeholders) and an Effect `load` for the heavy
@@ -150,25 +170,37 @@ export declare const isFeatureBinding: (u: unknown) => u is FeatureBinding;
  * shared-carrier tuple the loaded module declares. `load` is an `Effect`, never a
  * Promise — consumers `yield* Feature.load`.
  */
-export interface FeatureClass<P, C extends UiContract, ROut, Requires extends ReadonlyArray<RequireCarrier>> {
-    new (): {};
-    readonly manifest: FeatureManifest;
-    /** Phantom carrying the mounted composition's props type (for `provide` checks). */
-    readonly Props: P;
-    /** Phantom carrying the composition's UI contract (for typed reflection consumers). */
-    readonly Contract: C;
-    /** Phantom carrying the declared shared-carrier tuple. */
-    readonly Requires: Requires;
-    /** Load the feature's module — `yield* Feature.load` → its `FeatureModule`, or `FeatureLoadFailed`. */
-    readonly load: Effect.Effect<FeatureModule<ROut, Requires>, FeatureLoadFailed>;
-    /** The value `provide(slot, Feature)` binds under the slot tag. */
-    readonly binding: FeatureBinding;
-    /** The eagerly-available module — present only for `loadingStrategy: 'default'`. */
-    readonly eagerModule: FeatureModule<ROut, Requires> | undefined;
+export interface FeatureClass<
+  P,
+  C extends UiContract,
+  ROut,
+  Requires extends ReadonlyArray<RequireCarrier>,
+> {
+  new (): {}
+  readonly manifest: FeatureManifest
+  /** Phantom carrying the mounted composition's props type (for `provide` checks). */
+  readonly Props: P
+  /** Phantom carrying the composition's UI contract (for typed reflection consumers). */
+  readonly Contract: C
+  /** Phantom carrying the declared shared-carrier tuple. */
+  readonly Requires: Requires
+  /** Load the feature's module — `yield* Feature.load` → its `FeatureModule`, or `FeatureLoadFailed`. */
+  readonly load: Effect.Effect<FeatureModule<ROut, Requires>, FeatureLoadFailed>
+  /** The value `provide(slot, Feature)` binds under the slot tag. */
+  readonly binding: FeatureBinding
+  /** The eagerly-available module — present only for `loadingStrategy: 'default'`. */
+  readonly eagerModule: FeatureModule<ROut, Requires> | undefined
 }
-export type AnyFeature = FeatureClass<any, any, any, ReadonlyArray<RequireCarrier>>;
+
+export type AnyFeature = FeatureClass<any, any, any, ReadonlyArray<RequireCarrier>>
+
 /** Whether a value is a feature definition (its target shape in `provide(slot, Feature)`). */
-export declare const isFeature: (u: unknown) => u is AnyFeature;
+export const isFeature = (u: unknown): u is AnyFeature =>
+  (typeof u === 'function' || typeof u === 'object') &&
+  u !== null &&
+  'manifest' in u &&
+  (u as { readonly manifest: { readonly kind?: unknown } }).manifest?.kind === 'Feature'
+
 /**
  * The placeholders a lazy feature must ship — both eager compositions (their
  * `.live` is in the eager bundle, so they paint the load gap). `loading` receives
@@ -177,20 +209,28 @@ export declare const isFeature: (u: unknown) => u is AnyFeature;
  * are not schema-decoded inputs.
  */
 export interface Placeholders {
-    readonly loading: CompositionClass<any, UiContract>;
-    readonly failed: CompositionClass<any, UiContract>;
+  readonly loading: CompositionClass<any, UiContract>
+  readonly failed: CompositionClass<any, UiContract>
 }
+
 type FeatureConfig<P, C extends UiContract, ROut, Requires extends ReadonlyArray<RequireCarrier>> = {
-    readonly composition: CompositionClass<P, C>;
-    readonly boot?: ReadonlyArray<Tagged>;
-} & ({
-    readonly loadingStrategy?: 'default';
-    readonly module: FeatureModule<ROut, Requires>;
-} | {
-    readonly loadingStrategy: 'lazy';
-    readonly load: Effect.Effect<FeatureModule<ROut, Requires>, FeatureLoadFailed>;
-    readonly placeholder: Placeholders;
-});
+  readonly composition: CompositionClass<P, C>
+  readonly boot?: ReadonlyArray<Tagged>
+} & (
+  | {
+      // EAGER: the module is statically present and merged into the runtime at
+      // boot. No load gap, so no placeholder.
+      readonly loadingStrategy?: 'default'
+      readonly module: FeatureModule<ROut, Requires>
+    }
+  | {
+      // LAZY: the module loads on mount via an Effect. Placeholders required.
+      readonly loadingStrategy: 'lazy'
+      readonly load: Effect.Effect<FeatureModule<ROut, Requires>, FeatureLoadFailed>
+      readonly placeholder: Placeholders
+    }
+)
+
 /**
  * Define a feature. The whole-app shape (this manifest, the composition, the
  * placeholders) stays eager and reflectable; the `.live` layer in `module`/`load`
@@ -198,7 +238,41 @@ type FeatureConfig<P, C extends UiContract, ROut, Requires extends ReadonlyArray
  * the discriminated config *requires* `placeholder` — the compiler walks you to a
  * complete code-split feature.
  */
-export declare const make: <P, C extends UiContract, ROut, Requires extends ReadonlyArray<RequireCarrier>>(name: string, config: FeatureConfig<P, C, ROut, Requires>) => FeatureClass<P, C, ROut, Requires>;
+export const make = <P, C extends UiContract, ROut, Requires extends ReadonlyArray<RequireCarrier>>(
+  name: string,
+  config: FeatureConfig<P, C, ROut, Requires>,
+): FeatureClass<P, C, ROut, Requires> => {
+  const strategy: 'lazy' | 'default' = config.loadingStrategy ?? 'default'
+  const load: Effect.Effect<FeatureModule<ROut, Requires>, FeatureLoadFailed> =
+    'load' in config ? config.load : Effect.succeed(config.module)
+  const eagerModule = 'module' in config ? config.module : undefined
+  const placeholder = 'placeholder' in config ? config.placeholder : undefined
+
+  const manifest: FeatureManifest = {
+    kind: 'Feature',
+    name,
+    strategy,
+    composition: config.composition.manifest,
+    ...(placeholder
+      ? { placeholder: { loading: placeholder.loading.manifest, failed: placeholder.failed.manifest } }
+      : {}),
+  }
+
+  const binding: FeatureBinding = {
+    [FeatureBindingTypeId]: FeatureBindingTypeId,
+    manifest,
+    composition: config.composition,
+    strategy,
+    // The host is strategy-uniform: `default`'s `load` resolves immediately. The
+    // assignment to the erased `LoadedModule` needs no cast — see `LoadedModule`.
+    load,
+    ...(placeholder ? { placeholder: { loading: placeholder.loading, failed: placeholder.failed } } : {}),
+    boot: config.boot ?? [],
+  }
+
+  return definitionClass<FeatureClass<P, C, ROut, Requires>>({ manifest, load, binding, eagerModule })
+}
+
 /**
  * Mount a feature against a live engine. The renderer-neutral lifecycle, run on a
  * per-feature `Scope`: load the module (an Effect — lazy = dynamic import; default
@@ -215,6 +289,18 @@ export declare const make: <P, C extends UiContract, ROut, Requires extends Read
  * we re-attach the concrete `engineContext` it builds against. `R` is the engine
  * context's service set, supplied by the host.
  */
-export declare const mountFeature: <R>(binding: FeatureBinding, engineContext: Context.Context<R>) => Effect.Effect<Context.Context<unknown>, FeatureLoadFailed, Scope.Scope>;
-export {};
-//# sourceMappingURL=feature.d.ts.map
+export const mountFeature = <R>(
+  binding: FeatureBinding,
+  engineContext: Context.Context<R>,
+): Effect.Effect<Context.Context<unknown>, FeatureLoadFailed, Scope.Scope> =>
+  Effect.gen(function* () {
+    const { layer } = yield* binding.load
+    const featureLayer = layer as Layer.Layer<unknown, never, R>
+    const context = yield* Layer.build(
+      Layer.provideMerge(featureLayer, Layer.succeedContext(engineContext)),
+    )
+    yield* Effect.forEach(binding.boot, (event) => publish('High', event), { discard: true }).pipe(
+      Effect.provide(context),
+    )
+    return context
+  })