@playfast/reform 0.0.7 → 0.0.8

package/src/channel/channel.ts

@@ -0,0 +1,269 @@
+import { Chunk, Context, type Duration, Effect, Layer, Match, Queue, Stream } from 'effect'
+import { type Manifest, definitionClass } from '../definition/definition'
+import { DuplicateRegistration } from '../internal/errors'
+import type { Tagged } from '../runtime/bus'
+
+/**
+ * How a channel schedules the procedure work routed to it. Channels generalize
+ * the old per-procedure `concurrency`: a named lane with one policy, shared by
+ * every procedure that declares it.
+ *
+ * - `merge`     run every routed event concurrently (the default).
+ * - `latest`    a new event cancels the in-flight run (switch).
+ * - `debounce`  collapse a burst, run only after `duration` of quiet.
+ * - `throttle`  rate-limit to `units` per `duration` (shape or enforce).
+ * - `exclusive` one run at a time across the whole channel (mutual exclusion).
+ */
+export type ChannelPolicy =
+  | { readonly _tag: 'merge' }
+  | { readonly _tag: 'latest' }
+  | { readonly _tag: 'debounce'; readonly duration: Duration.DurationInput }
+  | {
+      readonly _tag: 'throttle'
+      readonly units: number
+      readonly duration: Duration.DurationInput
+      readonly cost?: number
+      readonly burst?: number
+      readonly strategy?: 'enforce' | 'shape'
+    }
+  | { readonly _tag: 'exclusive' }
+
+/** The reflectable descriptor a channel carries. */
+export interface ChannelManifest extends Manifest {
+  readonly kind: 'Channel'
+}
+
+export interface ChannelClass {
+  new (): {}
+  readonly manifest: ChannelManifest
+  readonly policy: ChannelPolicy
+}
+
+export interface ChannelConfig {
+  readonly policy: ChannelPolicy
+}
+
+/**
+ * A registered procedure body, with its trigger events and the channel it runs
+ * on. `run`'s context (RPC clients, etc.) is already provided at registration
+ * (see `Procedure.live`), so the channel fiber can run it with no R.
+ */
+export interface ProcedureEntry {
+  /** The procedure's name — used only to warn on duplicate registration. */
+  readonly name: string
+  readonly channelName: string
+  readonly handles: ReadonlySet<string>
+  readonly run: (event: Tagged) => Effect.Effect<unknown, unknown, never>
+}
+
+/**
+ * Mutable collector procedures register into; channels read it to find their
+ * bodies. `byTag` indexes entries by trigger tag, so a channel routes an event
+ * to O(procedures handling it) rather than scanning every registered procedure.
+ */
+export interface ProcedureRegistry {
+  readonly entries: Array<ProcedureEntry>
+  readonly byTag: Map<string, Array<ProcedureEntry>>
+  /**
+   * Distinct channel names per event tag. The drain loop routes through this so
+   * it offers each event to each channel exactly once — not once per matching
+   * procedure, which would re-run every procedure on a shared channel per offer.
+   */
+  readonly channelsByTag: Map<string, Array<string>>
+  /**
+   * Procedures keyed by (channel, tag), so a channel's `runMatching` is a direct
+   * lookup instead of scanning `byTag` and re-filtering by channel per event.
+   */
+  readonly byChannelTag: Map<string, Map<string, Array<ProcedureEntry>>>
+  readonly register: (entry: ProcedureEntry) => void
+  /**
+   * Remove a previously-registered entry — the inverse of `register`, used when a
+   * lazy feature unmounts (scope close) so its procedures stop running and their
+   * index entries are reclaimed. Eager procedures (root scope) never call it.
+   */
+  readonly unregister: (entry: ProcedureEntry) => void
+}
+
+const ProceduresBase: Context.TagClass<Procedures, 'reform/Procedures', ProcedureRegistry> =
+  Context.Tag('reform/Procedures')<Procedures, ProcedureRegistry>()
+export class Procedures extends ProceduresBase {}
+
+/** Get a map entry, creating and inserting it on first access (avoids `let`). */
+const getOrCreate = <K, V>(map: Map<K, V>, key: K, make: () => V): V => {
+  const existing = map.get(key)
+  if (existing !== undefined) return existing
+  const created = make()
+  map.set(key, created)
+  return created
+}
+
+/** Drop an item from a `Map<K, Array>` bucket, pruning the key when it empties. */
+const dropFrom = <K, T>(map: Map<K, Array<T>>, key: K, item: T): void => {
+  const bucket = map.get(key)
+  if (bucket === undefined) return
+  const next = bucket.filter((value) => value !== item)
+  if (next.length === 0) map.delete(key)
+  else map.set(key, next)
+}
+
+const makeProcedureRegistry = (): ProcedureRegistry => {
+  const entries: Array<ProcedureEntry> = []
+  const byTag = new Map<string, Array<ProcedureEntry>>()
+  const channelsByTag = new Map<string, Array<string>>()
+  const byChannelTag = new Map<string, Map<string, Array<ProcedureEntry>>>()
+  return {
+    entries,
+    byTag,
+    channelsByTag,
+    byChannelTag,
+    register: (entry) => {
+      entries.push(entry)
+      for (const tag of entry.handles) {
+        getOrCreate(byTag, tag, () => []).push(entry)
+        const channels = getOrCreate(channelsByTag, tag, () => [])
+        if (!channels.includes(entry.channelName)) channels.push(entry.channelName)
+        getOrCreate(getOrCreate(byChannelTag, entry.channelName, () => new Map()), tag, () => []).push(
+          entry,
+        )
+      }
+    },
+    unregister: (entry) => {
+      const index = entries.indexOf(entry)
+      if (index >= 0) entries.splice(index, 1)
+      for (const tag of entry.handles) {
+        dropFrom(byTag, tag, entry)
+        const channelMap = byChannelTag.get(entry.channelName)
+        if (channelMap !== undefined) {
+          dropFrom(channelMap, tag, entry)
+          // If no procedure on this channel still handles the tag, drop the
+          // channel from `channelsByTag[tag]` so the loop stops offering to it.
+          if (channelMap.get(tag) === undefined) dropFrom(channelsByTag, tag, entry.channelName)
+          if (channelMap.size === 0) byChannelTag.delete(entry.channelName)
+        }
+      }
+    },
+  }
+}
+
+export const proceduresLayer: Layer.Layer<Procedures> = Layer.sync(Procedures, makeProcedureRegistry)
+
+/** A live channel: the single loop offers events here; the channel drives them. */
+export interface ChannelRuntime {
+  readonly name: string
+  /** The policy this channel was built with — used to reject a name clash. */
+  readonly policy: ChannelPolicy
+  readonly offer: (event: Tagged) => void
+}
+
+/** Registry of live channels, keyed by name. The single loop routes through it. */
+const ChannelsBase: Context.TagClass<
+  Channels,
+  'reform/Channels',
+  { readonly byName: Map<string, ChannelRuntime> }
+> = Context.Tag('reform/Channels')<Channels, { readonly byName: Map<string, ChannelRuntime> }>()
+export class Channels extends ChannelsBase {}
+
+export const channelsLayer: Layer.Layer<Channels> = Layer.sync(Channels, () => ({ byName: new Map() }))
+
+/**
+ * A scheduling lane for procedures. The *definition* (`Channel.make`) is a
+ * reflectable name + policy; the *implementation* (`Channel.live`) builds the
+ * queue + fiber that applies the policy. Procedures reference a channel by value
+ * and register into it; `Channel.live` is merged into the app once per channel.
+ */
+export const make = (name: string, config: ChannelConfig): ChannelClass =>
+  definitionClass<ChannelClass>({
+    manifest: { kind: 'Channel' as const, name } satisfies ChannelManifest,
+    policy: config.policy,
+  })
+
+/**
+ * Build and register the live machinery for a channel. Idempotent by name, so
+ * procedures sharing an `exclusive`/`latest` channel share one queue + fiber +
+ * semaphore (and therefore truly serialize / cancel across each other).
+ */
+export const live = (channel: ChannelClass): Layer.Layer<never, never, Channels | Procedures> =>
+  Layer.scopedDiscard(
+    Effect.gen(function* () {
+      const name = channel.manifest.name
+      const channels = yield* Channels
+      const existing = channels.byName.get(name)
+      if (existing !== undefined) {
+        // Idempotent for the *same* channel `.live`'d through several sub-layers
+        // (shared `exclusive`/`latest` lane). A *different* channel reusing the
+        // name is a silent footgun — the second policy would be dropped — so
+        // reject it loudly instead.
+        if (existing.policy !== channel.policy) {
+          throw new DuplicateRegistration({ kind: 'Channel', name })
+        }
+        return
+      }
+      const procedures = yield* Procedures
+      const queue = yield* Queue.unbounded<Tagged>()
+
+      // Run every procedure on THIS channel that handles the event. Read the live
+      // index each time so procedures registered later are still seen.
+      // A procedure is expected to model expected failures as events; a leaked
+      // defect (a bug in the body) is logged before being isolated, so one
+      // procedure's crash never tears down the channel fiber — but is observable.
+      const runMatching = (event: Tagged): Effect.Effect<void> =>
+        Effect.forEach(
+          procedures.byChannelTag.get(name)?.get(event._tag) ?? [],
+          (e) =>
+            e.run(event).pipe(
+              Effect.tapErrorCause((cause) =>
+                Effect.logError(`reform: procedure on channel '${name}' failed`, cause),
+              ),
+              Effect.catchAllCause(() => Effect.void),
+            ),
+          { discard: true, concurrency: 'unbounded' },
+        )
+
+      // Map the policy to its scheduling stream. `Match.exhaustive` makes a new
+      // policy variant a compile error, and each arm is a self-contained const.
+      const events = Stream.fromQueue(queue)
+      const driven: Stream.Stream<unknown> = Match.value(channel.policy).pipe(
+        Match.tag('merge', () => Stream.mapEffect(events, runMatching, { concurrency: 'unbounded' })),
+        Match.tag('latest', () =>
+          Stream.flatMap(events, (e) => Stream.fromEffect(runMatching(e)), { switch: true }),
+        ),
+        Match.tag('debounce', (policy) =>
+          events.pipe(
+            Stream.debounce(policy.duration),
+            Stream.mapEffect(runMatching, { concurrency: 'unbounded' }),
+          ),
+        ),
+        Match.tag('throttle', (policy) =>
+          events.pipe(
+            Stream.throttle({
+              cost: (chunk) => Chunk.size(chunk) * (policy.cost ?? 1),
+              units: policy.units,
+              duration: policy.duration,
+              ...(policy.burst !== undefined ? { burst: policy.burst } : {}),
+              strategy: policy.strategy ?? 'shape',
+            }),
+            Stream.mapEffect(runMatching, { concurrency: 'unbounded' }),
+          ),
+        ),
+        // `concurrency: 1` runs one event at a time AND in offer order — a true
+        // serialized lane. (An unbounded fork racing for a single semaphore permit
+        // would serialize but could reorder under contention.)
+        Match.tag('exclusive', () => Stream.mapEffect(events, runMatching, { concurrency: 1 })),
+        Match.exhaustive,
+      )
+
+      yield* Effect.forkScoped(Stream.runDrain(driven))
+      channels.byName.set(name, {
+        name,
+        policy: channel.policy,
+        offer: (event) => {
+          Queue.unsafeOffer(queue, event)
+        },
+      })
+      // On scope close (a lazy feature unmounting) remove the live channel so the
+      // loop stops routing to it; the drain fiber is already torn down by
+      // `forkScoped`. Eager channels live on the root scope, so this is a no-op
+      // until app dispose.
+      yield* Effect.addFinalizer(() => Effect.sync(() => channels.byName.delete(name)))
+    }),
+  )

package/src/compose/composition.ts

@@ -0,0 +1,112 @@
+import { Context, Effect, Layer, type Schema } from 'effect'
+import type { YieldWrap } from 'effect/Utils'
+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 { UiClass, UiContract } from './ui'
+import { Props } from './props'
+
+/** Everything the host injects per render: the instance props, the dependency tracker, and slot bindings. */
+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. */
+export interface CompositionService {
+  readonly render: (env: RenderEnv) => Effect.Effect<Node, never, never>
+}
+
+export interface CompositionConfig {
+  readonly title: string
+  readonly description?: string
+  // `any` in the encoded/context slots is required by Schema's variance for
+  // branded/Class schemas (e.g. `Todo`); only the decoded type `P` is used.
+  readonly props?: Schema.Schema<any, any>
+  readonly states?: ReadonlyArray<unknown>
+  readonly calcs?: ReadonlyArray<unknown>
+  readonly events?: ReadonlyArray<unknown>
+  readonly slots?: Record<string, SlotClass>
+  // The UI contract this composition resolves. Typed as a manifest carrier (not
+  // the full `UiClass`, whose invariant `impl` tag would force the contract type
+  // to leak here) so reflection — the dev tool, proofs — can read `ui.manifest`.
+  readonly ui: { readonly manifest: Manifest & { readonly kind: 'Ui' } }
+}
+
+type PropsOf<Config> = Config extends { props: Schema.Schema<infer P, any> } ? P : unknown
+
+export interface CompositionClass<out P, out C extends UiContract = UiContract> {
+  new (): {}
+  readonly manifest: Manifest & { readonly kind: 'Composition' } & CompositionConfig
+  /** Phantom carrying the props type for `provide(slot, composition)` checks. */
+  readonly Props: P
+  /**
+   * Phantom carrying the resolved UI contract (props + events + slots). It lets
+   * reflection consumers — proofs, the dev tool — recover the full contract from
+   * a composition value and stay fully typed. Covariant (output only); the
+   * invariant `impl` tag is never stored here, so no variance regression.
+   */
+  readonly Contract: C
+  readonly tag: Context.Tag<CompositionService, CompositionService>
+}
+
+/**
+ * A component's logic. The *definition* (`Composition.make`) is a reflectable
+ * manifest that doubles as a requirement/tag; the *implementation*
+ * (`Composition.live`) is the synchronous body, provided separately and
+ * checked against it.
+ */
+export const make = <const Config extends CompositionConfig, C extends UiContract>(
+  name: string,
+  // Constrain `ui` to the full `UiClass<C>` so `C` is inferred here; the stored
+  // 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> => {
+  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 })
+}
+
+/**
+ * Wire a composition's synchronous logic (D2): read state, acquire triggers,
+ * resolve the UI, return the view. Its requirements (minus `Props`, which the
+ * 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>,
+): 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.
+      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.
+        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>
+      return { render }
+    }),
+  )
+}
+
+/** Run a mounted composition for one frame, producing its node. */
+export const render = (service: CompositionService, env: RenderEnv): Effect.Effect<Node, never, never> =>
+  service.render(env)

package/{dist/compose/host.d.ts → src/compose/host.ts}

@@ -1,5 +1,6 @@
-import { Context } from 'effect';
-import type { Node } from './slot';
+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
@@ -7,11 +8,11 @@ import type { Node } from './slot';
  * child. Core stays renderer-neutral — it only defines this hole.
  */
 export interface SlotHost {
-    slot(name: string): (props: unknown) => Node;
+  slot(name: string): (props: unknown) => Node
 }
-declare const CurrentSlotsBase: Context.TagClass<CurrentSlots, 'reform/Slots', SlotHost>;
+
+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 declare class CurrentSlots extends CurrentSlotsBase {
-}
-export {};
-//# sourceMappingURL=host.d.ts.map
+export class CurrentSlots extends CurrentSlotsBase {}

package/{dist/compose/props.js → src/compose/props.ts}

@@ -1,4 +1,5 @@
-import { Context } from 'effect';
+import { Context } from 'effect'
+
 /**
  * The current composition instance's props. Bound per render by the runtime; a
  * composition body reads them with `const { todo } = yield* Props`.
@@ -6,7 +7,8 @@ import { Context } from 'effect';
  * (Per-instance typing of Props is DESIGN #26 — for now the value is opaque and
  * narrowed at the use site against the composition's declared props schema.)
  */
-const PropsBase = Context.Tag('reform/Props')();
-export class Props extends PropsBase {
-}
-//# sourceMappingURL=props.js.map
+const PropsBase: Context.TagClass<Props, 'reform/Props', any> = Context.Tag('reform/Props')<
+  Props,
+  any
+>()
+export class Props extends PropsBase {}

package/src/compose/provide.ts

@@ -0,0 +1,70 @@
+import { type Context, Layer } from 'effect'
+import { InvalidProvideTarget } from '../internal/errors'
+import type { CompositionClass } from './composition'
+import {
+  type EngineServices,
+  type FeatureClass,
+  isFeature,
+  type ProvidedBy,
+  type RequireCarrier,
+} from '../feature/feature'
+import { isSlot, type SlotChild, type SlotClass } from './slot'
+import { isUi, type UiClass, type UiContract, type ViewImpl } from './ui'
+
+/**
+ * Wire an implementation to a contract. Provides a `.make` presentation to a UI
+ * contract, a child composition into a parent's slot, or a `Feature` into a slot.
+ * The compose code never imports its implementations — they meet here.
+ */
+export function provide<C extends UiContract>(
+  contract: UiClass<C>,
+  view: ViewImpl<C>,
+): Layer.Layer<ViewImpl<C>>
+export function provide<Comp extends CompositionClass<any, any>>(
+  hole: SlotClass<Comp>,
+  composition: Comp,
+): Layer.Layer<CompositionClass<unknown>>
+/**
+ * Fill a slot with a feature. The slot's child composition type
+ * (`CompositionClass<P, C>`) must match the feature's mounted composition, so the
+ * facade/contract stays typed. The returned layer surfaces the feature's shared
+ * requirement (`EngineServices | ProvidedBy<Requires>`) as an open `RIn`, so the
+ * scene that wires it won't compile unless it provides the matching `Core` — even
+ * for a lazy feature whose own `.live` layer isn't built until mount.
+ */
+export function provide<
+  Comp extends CompositionClass<any, any>,
+  ROut,
+  Requires extends ReadonlyArray<RequireCarrier>,
+>(
+  hole: SlotClass<Comp>,
+  feature: FeatureClass<
+    Comp extends CompositionClass<infer P, any> ? P : never,
+    Comp extends CompositionClass<any, infer C> ? C : never,
+    ROut,
+    Requires
+  >,
+): Layer.Layer<SlotChild, never, EngineServices | ProvidedBy<Requires>>
+export function provide(target: unknown, impl: unknown): Layer.Layer<never, never, unknown> {
+  // Discriminate the target by its nominal brand, not by which DI-hole property
+  // happens to exist: a UI contract provides under its `impl` tag, a slot under
+  // its `tag`. Anything else is a wiring mistake. The overloads above pair
+  // `impl` with the chosen tag; this implementation sees both erased, so view
+  // the tag loosely (the one documented cast) to provide the service under it.
+  const tag = (isUi(target) ? target.impl : isSlot(target) ? target.tag : undefined) as
+    | Context.Tag<unknown, unknown>
+    | undefined
+  if (tag === undefined) throw new InvalidProvideTarget()
+  if (isFeature(impl)) {
+    const eager = impl.eagerModule
+    // Lazy: bind the `FeatureBinding`; the host drives load → mount, painting the
+    // placeholders. Default: bind the composition (so the existing `Compose` path
+    // renders it, no host, no flash) and merge the eager `.live` layer, whose `RIn`
+    // surfaces to the scene. Either way the overload's return type carries the
+    // shared `RIn`, so the scene still type-demands `Core`.
+    return eager === undefined
+      ? Layer.succeed(tag, impl.binding)
+      : Layer.merge(Layer.succeed(tag, impl.binding.composition), eager.layer)
+  }
+  return Layer.succeed(tag, impl)
+}

package/{dist/compose/slot.d.ts → src/compose/slot.ts}

@@ -1,17 +1,22 @@
-import { Context } from 'effect';
-import type { CompositionClass } from './composition';
-import type { FeatureBinding } from '../feature/feature';
-import type { Node } from '../ui/node';
-export type { Node };
+import { Context } from 'effect'
+import { definitionClass } from '../definition/definition'
+import type { CompositionClass } from './composition'
+import type { FeatureBinding } from '../feature/feature'
+import type { Node } from '../ui/node'
+
+export type { Node }
+
 /** Any composition, used where only the slot's structural role matters. */
-type AnyComposition = CompositionClass<any, any>;
+type AnyComposition = CompositionClass<any, any>
+
 /**
  * What a slot can be filled with: a plain child composition (the host renders it
  * directly), or a `FeatureBinding` from `provide(slot, Feature)` (the host drives
  * its lazy/eager mount lifecycle). The slot's DI tag holds one of these; the host
  * discriminates by the `FeatureBinding` brand.
  */
-export type SlotChild = CompositionClass<unknown> | FeatureBinding;
+export type SlotChild = CompositionClass<unknown> | FeatureBinding
+
 /**
  * Phantom instance shape: `ItemSlot` used as a *type* denotes this. It carries
  * the child *composition* type `Comp`, so the slot knows both the external props
@@ -20,8 +25,9 @@ export type SlotChild = CompositionClass<unknown> | FeatureBinding;
  * proof facade, drive.
  */
 export interface SlotInstance<Comp extends AnyComposition> {
-    readonly _slot: Comp;
+  readonly _slot: Comp
 }
+
 /**
  * A DI hole for a child composition. The parent declares
  * `slot('Item')<typeof TodoItem>()` and renders through it; the concrete child
@@ -32,18 +38,29 @@ export interface SlotInstance<Comp extends AnyComposition> {
  * by `provide`'s signature, not the (invariant) tag.
  */
 /** Nominal brand identifying a slot at runtime (Effect's `TypeId` idiom). */
-export declare const SlotTypeId: unique symbol;
-export type SlotTypeId = typeof SlotTypeId;
+export const SlotTypeId: unique symbol = Symbol.for('reform/Slot')
+export type SlotTypeId = typeof SlotTypeId
+
 export interface SlotClass<Comp extends AnyComposition = AnyComposition> {
-    new (): SlotInstance<Comp>;
-    readonly [SlotTypeId]: SlotTypeId;
-    readonly kind: 'Slot';
-    /** Internal DI tag the filling child (composition or feature binding) is provided under. */
-    readonly tag: Context.Tag<SlotChild, SlotChild>;
+  new (): SlotInstance<Comp>
+  readonly [SlotTypeId]: SlotTypeId
+  readonly kind: 'Slot'
+  /** Internal DI tag the filling child (composition or feature binding) is provided under. */
+  readonly tag: Context.Tag<SlotChild, SlotChild>
 }
+
 /** Whether a value is a slot — discriminates a `provide` target by brand. */
-export declare const isSlot: (u: unknown) => u is SlotClass;
+export const isSlot = (u: unknown): u is SlotClass =>
+  (typeof u === 'function' || typeof u === 'object') && u !== null && SlotTypeId in u
+
 /** The props a slot renders with — the child composition's external props. */
-export type SlotProps<S> = S extends SlotInstance<infer Comp> ? Comp['Props'] : never;
-export declare const slot: (name: string) => <Comp extends AnyComposition = AnyComposition>() => SlotClass<Comp>;
-//# sourceMappingURL=slot.d.ts.map
+export type SlotProps<S> = S extends SlotInstance<infer Comp> ? Comp['Props'] : never
+
+export const slot =
+  (name: string) =>
+  // Defaulted so a slot whose child carries no meaningful props/contract can be
+  // declared bare (`slot('Tree')()`); pass `typeof Child` to type the facade.
+  <Comp extends AnyComposition = AnyComposition>(): SlotClass<Comp> => {
+    const tag = Context.GenericTag<SlotChild, SlotChild>(`reform/slot/${name}`)
+    return definitionClass<SlotClass<Comp>>({ [SlotTypeId]: SlotTypeId, kind: 'Slot' as const, tag })
+  }

package/src/compose/ui.test.ts

@@ -0,0 +1,62 @@
+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'
+
+// `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
+// the same contract at runtime; only the wired form carries reflectable schemas.
+
+test('type-only `ui` carries no wire schema', () => {
+  class CounterUi extends ui('Counter')<{ props: { count: number } }>() {}
+  expect(CounterUi.manifest.kind).toBe('Ui')
+  expect(CounterUi.manifest.name).toBe('Counter')
+  expect(CounterUi.manifest.props).toBeUndefined()
+  expect(CounterUi.manifest.events).toBeUndefined()
+  expect(isUi(CounterUi)).toBe(true)
+})
+
+test('schema `ui` carries props and per-event wire schemas', () => {
+  class CounterUi extends ui('Counter', {
+    props: S.Struct({ count: S.Number }),
+    events: { bump: S.Struct({ by: S.Number }) },
+  }) {}
+  expect(CounterUi.manifest.kind).toBe('Ui')
+  expect(CounterUi.manifest.name).toBe('Counter')
+  expect(S.isSchema(CounterUi.manifest.props)).toBe(true)
+  expect(S.isSchema(CounterUi.manifest.events?.['bump'])).toBe(true)
+  expect(isUi(CounterUi)).toBe(true)
+})
+
+test('schema `ui` with no events omits the events schema', () => {
+  class TitleUi extends ui('Title', { props: S.Struct({ text: S.String }) }) {}
+  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 })
+})