@playfast/reform 1.0.1 → 1.2.0

package/src/compose/provide.ts

@@ -1,74 +1,201 @@
-import { type Context, Layer } from 'effect'
+import { Context, Effect, Layer, Predicate } from 'effect'
 import { InvalidProvideTarget } from '../internal/errors'
-import type { CompositionClass } from './composition'
 import {
+  type AnyFeatureBinding,
   type EngineServices,
-  type FeatureClass,
+  type FeatureBinding,
+  type FeatureRequirement,
   isFeature,
-  type ProvidedBy,
-  type RequireCarrier,
+  tree,
 } from '../feature/feature'
-import { isSlot, type SlotChild, type SlotClass } from './slot'
-import { isUi, type UiClass, type UiContract, type ViewImpl } from './ui'
+import type {
+  AnyComposition,
+  CompositionClass,
+  CompositionId,
+  RequiredSlotIdentities,
+} from './composition'
+import type {
+  AnyFeatureGraphSummary,
+  CompositionChildSummary,
+  ExactServiceExclude,
+  FeatureSummaryOpenServices,
+  FeatureSummarySupportOpenServices,
+} from '../graph/closure'
+import {
+  type AnyFeatureSlotTarget,
+  type AnySlot,
+  isSlot,
+  type SlotClass,
+  type SlotService,
+  type SlotTarget,
+} from './slot'
+import {
+  type CallableView,
+  type Contract,
+  type AnyUi,
+  isUi,
+  type UiName,
+  type UiContract,
+  type UiService,
+  type ViewImpl,
+} from './ui'
+
+type TargetOfSlotClass<Slot extends AnySlot> = InstanceType<Slot>['_slot']
+type NameOfSlotClass<Slot extends AnySlot> = InstanceType<Slot>['_slotName']
+type IdentityOfSlotClass<Slot extends AnySlot> = InstanceType<Slot>['_slotIdentity']
+type FeatureTargetOfSlotClass<Slot extends AnySlot> =
+  TargetOfSlotClass<Slot> extends AnyFeatureSlotTarget ? TargetOfSlotClass<Slot> : never
+
+type CompositionIdentityOf<Composition extends AnyComposition> =
+  InstanceType<Composition>['_compositionIdentity']
 
-/**
- * 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>,
+// Preserve exact residual inputs that Layer.provideMerge's union subtraction hides.
+export const provideMergeExact =
+  <Provided, ProviderError, ProviderInput>(
+    provider: Layer.Layer<Provided, ProviderError, ProviderInput>,
+  ) =>
+  <Output, Error, Input>(
+    consumer: Layer.Layer<Output, Error, Input>,
+  ): Layer.Layer<
+    Provided | Output,
+    ProviderError | Error,
+    ProviderInput | Exclude<Input, Provided> | ExactServiceExclude<Input, Provided>
+  > =>
+    Layer.merge(
+      Layer.provideMerge(provider)(consumer),
+      Layer.effectDiscard(Effect.context<ExactServiceExclude<Input, Provided>>()),
+    )
+
+const compositionSlotLayer = <
+  Target extends SlotTarget,
+  SlotName extends string,
+  SlotIdentity,
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  CompositionName extends string,
+  CompositionIdentity,
+>(
+  slotDefinition: SlotClass<Target, SlotName, SlotIdentity>,
+  composition: CompositionClass<P, C, S, CompositionName, CompositionIdentity>,
+): Layer.Layer<SlotService<SlotName, SlotIdentity, CompositionChildSummary<CompositionIdentity>>> =>
+  Layer.succeed(
+    Context.GenericTag<
+      SlotService<SlotName, SlotIdentity, CompositionChildSummary<CompositionIdentity>>,
+      AnyComposition
+    >(slotDefinition.tag.key),
+    composition,
+  )
+
+export const provideExisting = <
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  CompositionName extends string,
+  CompositionIdentity,
+  SlotName extends string,
+  SlotIdentity,
+>(
+  hole: SlotClass<
+    CompositionClass<P, C, S, CompositionName, CompositionIdentity>,
+    SlotName,
+    SlotIdentity
+  >,
+  composition: NoInfer<CompositionClass<P, C, S, CompositionName, CompositionIdentity>>,
+): Layer.Layer<
+  SlotService<SlotName, SlotIdentity, CompositionChildSummary<CompositionIdentity>>,
+  never,
+  CompositionId<CompositionName, CompositionIdentity, RequiredSlotIdentities<C>>
+> =>
+  Layer.effect(
+    Context.GenericTag<
+      SlotService<SlotName, SlotIdentity, CompositionChildSummary<CompositionIdentity>>,
+      CompositionClass<P, C, S, CompositionName, CompositionIdentity>
+    >(hole.tag.key),
+    Effect.as(composition.tag, composition),
+  )
+
+const featureSlotLayer = <
+  Target extends SlotTarget,
+  SlotName extends string,
+  SlotIdentity,
+  Summary extends AnyFeatureGraphSummary,
   ROut,
-  Requires extends ReadonlyArray<RequireCarrier>,
+  DirectRequires extends ReadonlyArray<FeatureRequirement>,
 >(
-  hole: SlotClass<Comp>,
-  feature: FeatureClass<
-    Comp extends CompositionClass<infer P, any> ? P : never,
-    Comp extends CompositionClass<any, infer C> ? C : never,
-    ROut,
-    Requires
+  slotDefinition: SlotClass<Target, SlotName, SlotIdentity>,
+  binding: FeatureBinding<Summary, ROut, DirectRequires>,
+): Layer.Layer<SlotService<SlotName, SlotIdentity, Summary>> =>
+  Layer.succeed(
+    Context.GenericTag<SlotService<SlotName, SlotIdentity, Summary>, AnyFeatureBinding>(
+      slotDefinition.tag.key,
+    ),
+    binding,
+  )
+
+const isComposition = (candidate: unknown): candidate is AnyComposition =>
+  (typeof candidate === 'function' || typeof candidate === 'object') &&
+  candidate !== null &&
+  Predicate.hasProperty(candidate, 'manifest') &&
+  Predicate.isRecord(candidate.manifest) &&
+  candidate.manifest['kind'] === 'Composition' &&
+  Predicate.hasProperty(candidate, 'capture') &&
+  typeof candidate.capture === 'function'
+
+const isCallableView = (candidate: unknown): candidate is CallableView =>
+  typeof candidate === 'function'
+
+export function provide<U extends AnyUi>(
+  contract: U,
+  view: ViewImpl<Contract<U>>,
+): Layer.Layer<UiService<UiName<U>>>
+export function provide<Comp extends AnyComposition, N extends string, Identity>(
+  hole: SlotClass<Comp, N, Identity>,
+  composition: NoInfer<Comp>,
+): Layer.Layer<SlotService<N, Identity, CompositionChildSummary<CompositionIdentityOf<Comp>>>>
+export function provide<Slot extends AnySlot>(
+  hole: Slot,
+  feature: NoInfer<FeatureTargetOfSlotClass<Slot>>,
+): Layer.Layer<
+  SlotService<
+    NameOfSlotClass<Slot>,
+    IdentityOfSlotClass<Slot>,
+    FeatureTargetOfSlotClass<Slot>['summary']
   >,
-): Layer.Layer<SlotChild, never, EngineServices | ProvidedBy<Requires>>
-// oxlint-disable-next-line reform-rules/no-multiple-primitive-params -- erased implementation signature of the 2-arg overloaded `provide`; the typed public API is the overloads above
-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.
-  // oxlint-disable-next-line reform-rules/no-type-assertion -- erased DI tag widening at the provide seam (Context.Tag is invariant); overloads pair impl with the right tag
-  const tag = (isUi(target) ? target.impl : isSlot(target) ? target.tag : undefined) as
-    | Context.Tag<unknown, unknown>
-    | undefined
-  if (tag === undefined) {
-    return Layer.die(new InvalidProvideTarget())
+  never,
+  | EngineServices
+  | FeatureSummaryOpenServices<FeatureTargetOfSlotClass<Slot>['summary']>
+  | FeatureSummarySupportOpenServices<FeatureTargetOfSlotClass<Slot>['summary']>
+>
+export function provide(...args: readonly [target: unknown, implementation: unknown]): unknown {
+  const [target, implementation] = args
+  if (isUi(target)) {
+    if (!isCallableView(implementation)) {
+      return Layer.die(new InvalidProvideTarget())
+    }
+    return target.capture<unknown>((contract) => Layer.succeed(contract.provider, implementation))
   }
-  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)
+  if (!isSlot(target)) {
+    return Layer.die(new InvalidProvideTarget())
   }
-  return Layer.succeed(tag, impl)
+  return target.capture<unknown>((slotDefinition) => {
+    if (isFeature(implementation)) {
+      const native = tree<typeof implementation>(implementation.token)
+      return native.binding.capture<unknown>((featureBinding) => {
+        // Lazy features merge only eager support; default features merge their live module.
+        const eager = native.eagerModule ?? native.supportModule
+        const binding = featureSlotLayer(slotDefinition, featureBinding)
+        if (eager === undefined) {
+          return binding
+        }
+        return eager.capture<unknown>((module) => Layer.merge(binding, module.layer))
+      })
+    }
+    if (!isComposition(implementation)) {
+      return Layer.die(new InvalidProvideTarget())
+    }
+    return implementation.capture<unknown>((composition) =>
+      compositionSlotLayer(slotDefinition, composition),
+    )
+  })
 }

package/src/compose/slot.ts

@@ -1,68 +1,177 @@
-import { Context } from 'effect'
-import { definitionClass } from '../definition/definition'
-import type { CompositionClass } from './composition'
-import type { FeatureBinding } from '../feature/feature'
+import { Context, GlobalValue, MutableRef } from 'effect'
+import { type Manifest, definitionClass } from '../definition/definition'
+import type { AnyFeatureBinding, ProvideableFeature } from '../feature/feature'
+import type {
+  AnyFeatureGraphSummary,
+  FeatureSummaryCompositionIdentity,
+  FeatureSummaryCompositionProps,
+  FeatureSummaryContract,
+  FeatureSummaryMountProps,
+  FeatureSummaryName,
+  FeatureSummaryStates,
+  FeatureSummaryIdentity,
+  SlotBindingSummary,
+} from '../graph/closure'
 import type { Node } from '../ui/node'
+import type { AnyComposition, CompositionClass } from './composition'
 
 export type { Node }
 
-/** Any composition, used where only the slot's structural role matters. */
-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
-
-/**
- * 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
- * the parent renders it with (`Comp['Props']`) and the child's full UI contract
- * (`Comp['Contract']` — props + events + slots) that reflection consumers, the
- * proof facade, drive.
- */
-export interface SlotInstance<Comp extends AnyComposition> {
-  readonly _slot: Comp
+export type { AnyComposition } from './composition'
+
+type AnyProvideableFeature = ProvideableFeature<unknown, AnyFeatureGraphSummary>
+
+export type FeatureSlotTarget<Feature extends AnyProvideableFeature> = ProvideableFeature<
+  FeatureSummaryIdentity<Feature['summary']>,
+  Feature['summary']
+>
+
+export type AnyFeatureSlotTarget = FeatureSlotTarget<AnyProvideableFeature>
+
+export type SlotTarget = AnyComposition | AnyFeatureSlotTarget
+
+export type CompositionOfSlotTarget<Target extends SlotTarget> = Target extends AnyComposition
+  ? Target
+  : Target extends AnyFeatureSlotTarget
+    ? CompositionClass<
+        FeatureSummaryCompositionProps<Target['summary']>,
+        FeatureSummaryContract<Target['summary']>,
+        FeatureSummaryStates<Target['summary']>,
+        FeatureSummaryName<Target['summary']>,
+        FeatureSummaryCompositionIdentity<Target['summary']>
+      >
+    : never
+
+export type PropsOfSlotTarget<Target extends SlotTarget> = Target extends AnyComposition
+  ? Target['Props']
+  : Target extends AnyFeatureSlotTarget
+    ? FeatureSummaryMountProps<Target['summary']>
+    : never
+
+export type ContractOfSlotTarget<Target extends SlotTarget> = Target extends AnyComposition
+  ? Target['Contract']
+  : Target extends AnyFeatureSlotTarget
+    ? FeatureSummaryContract<Target['summary']>
+    : never
+
+export type SlotChild<Target extends SlotTarget> = Target extends AnyComposition
+  ? Target | (AnyFeatureBinding & { readonly composition: Target })
+  : Target extends AnyFeatureSlotTarget
+    ? AnyFeatureBinding & {
+        readonly summary: Target['summary']
+      }
+    : never
+
+export type AnySlotChild = AnyComposition | AnyFeatureBinding
+
+export interface AnySlotInstance {
+  readonly _slot: SlotTarget
+  readonly _slotName: string
+  readonly _slotIdentity: unknown
+}
+
+export interface SlotInstance<
+  Target extends SlotTarget,
+  N extends string,
+  Identity,
+> extends AnySlotInstance {
+  readonly _slot: Target
+  readonly _slotName: N
+  readonly _slotIdentity: Identity
 }
 
-/**
- * A DI hole for a child composition. The parent declares
- * `slot('Item')<typeof TodoItem>()` and renders through it; the concrete child
- * is wired with `provide(Item, TodoItem)`, so the parent never imports the
- * child's *implementation* (the `typeof` is a type-only reference to the
- * definition). `Comp` lives only in the phantom instance (so `SlotClass` is
- * covariant and a `{ Item: ItemSlot }` map is well-typed); the match is enforced
- * by `provide`'s signature, not the (invariant) tag.
- */
-/** Nominal brand identifying a slot at runtime (Effect's `TypeId` idiom). */
 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
+export const SlotServiceTypeId: unique symbol = Symbol.for('reform/SlotService')
+export type SlotServiceTypeId = typeof SlotServiceTypeId
+
+export interface SlotService<
+  N extends string,
+  Identity = unknown,
+  out Binding extends SlotBindingSummary = SlotBindingSummary,
+> {
+  readonly [SlotServiceTypeId]: {
+    readonly name: N
+    readonly identity: Identity
+    readonly binding: Binding
+  }
+}
+
+export interface SlotManifest<N extends string = string> extends Manifest {
   readonly kind: 'Slot'
-  /** Internal DI tag the filling child (composition or feature binding) is provided under. */
-  readonly tag: Context.Tag<SlotChild, SlotChild>
+  readonly name: N
+}
+
+export type SlotCapture<Result> = <Target extends SlotTarget, N extends string, Identity>(
+  slotDefinition: SlotClass<Target, N, Identity>,
+) => Result
+
+export interface AnySlot {
+  new (): AnySlotInstance
+  readonly [SlotTypeId]: SlotTypeId
+  readonly manifest: SlotManifest
+  readonly identity: symbol
+  readonly capture: <Result>(visit: SlotCapture<Result>) => Result
+}
+
+export interface SlotClass<Target extends SlotTarget, N extends string, Identity> {
+  new (): SlotInstance<Target, N, Identity>
+  readonly [SlotTypeId]: SlotTypeId
+  readonly manifest: SlotManifest<N>
+  readonly identity: symbol
+  readonly capture: <Result>(visit: SlotCapture<Result>) => Result
+  readonly tag: Context.Tag<SlotService<N, Identity>, SlotChild<Target>>
+  // Same runtime key, widened only after provide's typed overloads validate the child.
+  readonly provider: Context.Tag<SlotService<N, Identity>, AnySlotChild>
 }
 
-/** Whether a value is a slot — discriminates a `provide` target by brand. */
-export const isSlot = (candidate: unknown): candidate is SlotClass =>
+export const isSlot = (candidate: unknown): candidate is AnySlot =>
   (typeof candidate === 'function' || typeof candidate === 'object') &&
   candidate !== null &&
   SlotTypeId in candidate
 
-/** 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 type TargetOfSlot<S> =
+  S extends SlotInstance<infer Target, infer _N, infer _Identity> ? Target : never
+
+export type SlotProps<S> =
+  S extends SlotInstance<infer Target, infer _N, infer _Identity>
+    ? PropsOfSlotTarget<Target>
+    : never
+
+export type SlotComposition<S> =
+  S extends SlotInstance<infer Target, infer _N, infer _Identity>
+    ? CompositionOfSlotTarget<Target>
+    : never
+
+export type SlotContract<S> =
+  S extends SlotInstance<infer Target, infer _N, infer _Identity>
+    ? ContractOfSlotTarget<Target>
+    : never
+
+const slotDefinitionSequence: MutableRef.MutableRef<number> = GlobalValue.globalValue(
+  Symbol.for('reform/SlotDefinitionSequence'),
+  () => MutableRef.make(0),
+)
+
+const nextSlotTagKey = (name: string): string =>
+  `reform/slot/${name}/${MutableRef.incrementAndGet(slotDefinitionSequence)}`
 
 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 })
+  <const N extends string>(name: N) =>
+  <Self, Target extends SlotTarget = AnyComposition>(): SlotClass<Target, N, Self> => {
+    const key = nextSlotTagKey(name)
+    const identity = Symbol(name)
+    const tag = Context.GenericTag<SlotService<N, Self>, SlotChild<Target>>(key)
+    const provider = Context.GenericTag<SlotService<N, Self>, AnySlotChild>(key)
+    const manifest: SlotManifest<N> = { kind: 'Slot', name }
+    const slotDefinition: SlotClass<Target, N, Self> = definitionClass<SlotClass<Target, N, Self>>({
+      [SlotTypeId]: SlotTypeId,
+      manifest,
+      identity,
+      tag,
+      provider,
+      capture: <Result>(visit: SlotCapture<Result>): Result => visit(slotDefinition),
+    })
+    return slotDefinition
   }

package/src/compose/structure.test.ts

@@ -7,17 +7,13 @@ import { absent, each, isStructure, mount, one, structureEquals, when } from './
 
 type List = Contract<typeof ListUi>
 
-// A minimal parent/child contract pair: a list parent with one keyed slot, so the
-// type-level `mount` checks have a real contract to bind against. Row carries a
-// props schema so its external props (`Comp['Props']`) are `{ label: string }`,
-// which is what each fill is checked against.
 class RowUi extends ui('Row')<{ props: { label: string } }>() {}
 class Row extends Composition.make('Row', {
   title: 'Row',
   props: S.Struct({ label: S.String }),
   ui: RowUi,
-}) {}
-class RowSlot extends slot('Row')<typeof Row>() {}
+})<Row>() {}
+class RowSlot extends slot('Row')<RowSlot, typeof Row>() {}
 
 class ListUi extends ui('List')<{
   props: { total: number }
@@ -26,7 +22,10 @@ class ListUi extends ui('List')<{
 
 describe('structure combinators', () => {
   test('each produces one keyed entry per item, props mapped', () => {
-    const fill = each([{ id: 'a' }, { id: 'b' }], { key: (t) => t.id, props: (t) => ({ label: t.id }) })
+    const fill = each([{ id: 'a' }, { id: 'b' }], {
+      key: (t) => t.id,
+      props: (t) => ({ label: t.id }),
+    })
     expect(fill).toEqual({
       _tag: 'Each',
       items: [
@@ -65,8 +64,6 @@ describe('structure combinators', () => {
   })
 })
 
-// Type-level contract enforcement — never called; exists only so the negative
-// cases are typechecked. Each `@ts-expect-error` must sit on the line that errors.
 export const _typeChecks = (): void => {
   mount<List>({
     props: { total: 1 },