@playfast/reform 1.0.1 → 1.2.0

package/src/compose/composition.ts

@@ -1,165 +1,389 @@
-import { Context, Effect, Layer, type Schema } from 'effect'
+import { Context, Effect, GlobalValue, Layer, MutableRef, Option, Schema, Scope } from 'effect'
+import type { AST } from 'effect/SchemaAST'
 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 type { SlotClass } from './slot'
+import { type PropsId, type PropsTag, propsTag } from './props'
+import type { AnySlot, AnySlotInstance, SlotClass, SlotInstance } from './slot'
 import type { Structure } from './structure'
-import type { UiClass, UiContract } from './ui'
-import { Props } from './props'
-
-/**
- * What a composition's logic returns for one frame: a serializable {@link Structure}
- * value — its computed props, per-slot fills, and event triggers, all as DATA. A body
- * never returns (nor evaluates) a React node, so the engine, the wire server, and the
- * proof harness consume the frame without React; presentation resolves the contract's
- * view separately, by name, on a host.
- */
+import type { UiClass, UiContract, UiReflection } from './ui'
+
 export type Frame<C extends UiContract = UiContract> = Structure<C>
 
-/** Everything the host injects per render: the instance props and the dependency tracker. */
-export interface RenderEnv {
-  readonly props: unknown
+export interface RenderEnv<out P = unknown> {
+  readonly props: P
   readonly tracker: Tracker
 }
 
-/** A mounted composition: given a render environment, produces the current frame —
- *  a {@link Structure} value (see `Frame`). */
-export interface CompositionService {
-  readonly render: (env: RenderEnv) => Effect.Effect<Frame, never, never>
+export type CompositionActivation = Layer.Layer<never, never, never>
+
+export interface CompositionService<in out P = unknown, out C extends UiContract = UiContract> {
+  readonly render: (env: RenderEnv<P>) => Effect.Effect<Frame<C>, never, never>
+  readonly activation: (props: P) => Option.Option<CompositionActivation>
+}
+
+export const CompositionIdTypeId: unique symbol = Symbol.for('reform/CompositionId')
+export type CompositionIdTypeId = typeof CompositionIdTypeId
+
+export interface CompositionId<
+  out N extends string,
+  out Identity = unknown,
+  out RequiredSlots = unknown,
+> {
+  readonly [CompositionIdTypeId]: {
+    readonly name: N
+    readonly identity: Identity
+    readonly requiredSlots: RequiredSlots
+  }
+}
+
+type IsExact<Left, Right> = [Left] extends [Right] ? ([Right] extends [Left] ? true : false) : false
+
+type IsExactCompositionId<Service, N extends string, Identity> = Service extends {
+  readonly [CompositionIdTypeId]: {
+    readonly name: infer ServiceName extends string
+    readonly identity: infer ServiceIdentity
+  }
+}
+  ? IsExact<ServiceName, N> extends true
+    ? IsExact<ServiceIdentity, Identity>
+    : false
+  : false
+
+type IsAny<T> = 0 extends 1 & T ? true : false
+
+export type HasExactCompositionId<Services, N extends string, Identity> =
+  IsAny<Services> extends true
+    ? false
+    : true extends IsExactCompositionId<Services, N, Identity>
+      ? true
+      : false
+
+export type CompositionTag<
+  N extends string,
+  P,
+  C extends UiContract,
+  Identity = unknown,
+> = Context.Tag<CompositionId<N, Identity, RequiredSlotIdentities<C>>, CompositionService<P, C>>
+
+export type SlotClassesOf<C extends UiContract> = C extends {
+  readonly slots: infer Slots extends Record<string, AnySlotInstance>
+}
+  ? {
+      readonly [K in keyof Slots]: Slots[K] extends SlotInstance<
+        infer Child,
+        infer SlotName,
+        infer SlotIdentity
+      >
+        ? SlotClass<Child, SlotName, SlotIdentity>
+        : never
+    }
+  : Readonly<Record<PropertyKey, never>>
+
+type RequiredSlotIdentity<Slot> =
+  Slot extends SlotInstance<infer _Target, infer _Name, infer Identity> ? Identity : never
+
+export type RequiredSlotIdentities<C extends UiContract> = C extends {
+  readonly slots: infer Slots extends Record<string, AnySlotInstance>
+}
+  ? RequiredSlotIdentity<Slots[keyof Slots]>
+  : never
+
+type CompositionSlots<C extends UiContract> = C extends {
+  readonly slots: infer Slots extends Record<string, AnySlotInstance>
+}
+  ? [Slots[keyof Slots]] extends [never]
+    ? {}
+    : { readonly slots: SlotClassesOf<C> }
+  : {}
+
+export type CompositionManifest<
+  C extends UiContract = UiContract,
+  N extends string = string,
+> = Manifest &
+  Omit<CompositionConfig, 'slots' | 'ui'> &
+  CompositionSlots<C> & {
+    readonly kind: 'Composition'
+    readonly name: N
+    readonly ui: UiReflection<C>
+  }
+
+export interface CompositionInstance<out Identity = unknown> {
+  readonly _compositionIdentity: Identity
+}
+
+export interface CompositionReflection<
+  out P = unknown,
+  out C extends UiContract = UiContract,
+  out S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
+  out N extends string = string,
+  out Identity = unknown,
+> {
+  new (): CompositionInstance<Identity>
+  readonly manifest: CompositionManifest<C, N>
+  readonly Props: P
+  readonly Contract: C
+  readonly States: S
+  readonly parseProps: (input: unknown) => Option.Option<P>
+}
+
+export interface CompositionPropsReceiver<in P> {
+  readonly acceptsProps: (props: P) => void
+}
+
+export type CompositionCapture<Result> = <
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+>(
+  composition: CompositionClass<P, C, S, N, Identity>,
+) => Result
+
+export interface AnyComposition extends CompositionReflection {
+  readonly capture: <Result>(visit: CompositionCapture<Result>) => Result
+}
+
+interface CompositionSchema {
+  readonly ast: AST
 }
 
-// Reflectable manifest/config carrier: only `title` + `ui` are required, and the
-// optional members drive `Config extends { props: … }` / `{ states: … }` inference
-// (PropsOf/StatesOf) plus the ergonomic `Composition.make({ title, ui })` form, so
-// they cannot become `Option<T>` (would break inference and every call site) or be
-// renamed `ExternalApi` (would break external importers of `CompositionConfig`).
-export interface CompositionConfig {
+type GeneratorContext<Eff> = [Eff] extends [never]
+  ? never
+  : [Eff] extends [YieldWrap<Effect.Effect<infer _Success, infer _Error, infer R>>]
+    ? R
+    : never
+
+// Property presence drives Config conditional inference; Option would erase it.
+interface CompositionConfigOptionalFields {
+  readonly description: string
+  readonly props: CompositionSchema
+  readonly states: ReadonlyArray<unknown>
+  readonly calcs: ReadonlyArray<unknown>
+  readonly events: ReadonlyArray<unknown>
+  readonly slots: Record<string, AnySlot>
+}
+
+export interface CompositionConfig extends Partial<CompositionConfigOptionalFields> {
   readonly title: string
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
-  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.
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- drives `Config extends { props: … }` inference (PropsOf)
-  readonly props?: Schema.Schema<any, any>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- drives `Config extends { states: … }` inference (StatesOf)
-  readonly states?: ReadonlyArray<unknown>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
-  readonly calcs?: ReadonlyArray<unknown>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
-  readonly events?: ReadonlyArray<unknown>
-  // oxlint-disable-next-line reform-rules/no-optional-fields -- optional config field on a reflectable manifest carrier (see note above)
-  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
-
-/**
- * The composition's state-group tuple, recovered from the `const`-inferred config
- * so consumers can type its seeds. Erased to `readonly []` when no `states` are
- * declared; entries that are not state groups contribute no seed keys (`SeedsOf`).
- */
-type StatesOf<Config> = Config extends { states: infer S extends ReadonlyArray<unknown> }
+  readonly ui: UiReflection
+}
+
+type PropsOf<Config> = Config extends { props: infer PropsSchema }
+  ? PropsSchema extends Schema.Schema<infer P, infer _Encoded, infer _Context>
+    ? P
+    : unknown
+  : unknown
+
+type EncodedPropsOf<Config> = Config extends { props: infer PropsSchema }
+  ? PropsSchema extends Schema.Schema<infer _Props, infer Encoded, infer _Context>
+    ? Encoded
+    : unknown
+  : unknown
+
+type StatesOf<Config> = Config extends {
+  states: infer S extends ReadonlyArray<unknown>
+}
   ? S
   : readonly []
 
 export interface CompositionClass<
-  out P,
-  out C extends UiContract = UiContract,
+  in out P,
+  in out C extends UiContract = UiContract,
   out S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
-> {
-  new (): {}
-  readonly manifest: Manifest & { readonly kind: 'Composition' } & CompositionConfig
-  /** Phantom carrying the props type for `provide(slot, composition)` checks. */
+  in out N extends string = string,
+  in out Identity = unknown,
+>
+  extends CompositionReflection<P, C, S, N, Identity>, CompositionPropsReceiver<P> {
   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
-  /**
-   * Phantom carrying the state-group tuple, so `seedScene` can type a scene's
-   * seeds against the actual state members. Same erasure trick as `Contract`.
-   */
   readonly States: S
-  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.
- */
-/** The contract-carrying overlay on a composition config — keeps `C` inferable at
- *  the `Composition.make` call site while the stored manifest sees only the erased
- *  `{ manifest }` carrier. */
-interface UiCarrier<C extends UiContract> {
-  readonly ui: UiClass<C>
-}
-
-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 & UiCarrier<C>,
-): CompositionClass<PropsOf<Config>, C, StatesOf<Config>> => {
-  const tag = Context.GenericTag<CompositionService, CompositionService>(
-    `reform/composition/${name}`,
-  )
-  const manifest = { kind: 'Composition' as const, name, ...config }
-  return definitionClass<CompositionClass<PropsOf<Config>, C, StatesOf<Config>>>({ manifest, tag })
+  readonly identity: symbol
+  readonly props: PropsTag<P>
+  readonly tag: CompositionTag<N, P, C, Identity>
+  readonly capture: <Result>(visit: CompositionCapture<Result>) => Result
+}
+
+type CompositionDefinitionStatics<
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+> = Pick<
+  CompositionClass<P, C, S, N, Identity>,
+  'manifest' | 'identity' | 'props' | 'parseProps' | 'acceptsProps' | 'tag' | 'capture'
+>
+
+interface UiCarrier<C extends UiContract, UiName extends string> {
+  readonly ui: UiClass<C, UiName>
+}
+
+type ContractSlots<C extends UiContract> = CompositionSlots<C>
+
+type ContextFreeProps<Config> = Config extends {
+  readonly props: infer PropsSchema
+}
+  ? PropsSchema extends Schema.Schema<infer _P, infer _Encoded, infer Context>
+    ? [Context] extends [never]
+      ? unknown
+      : { readonly propsSchemaMustNotRequireServices: never }
+    : unknown
+  : unknown
+
+const compositionDefinitionSequence: MutableRef.MutableRef<number> = GlobalValue.globalValue(
+  Symbol.for('reform/CompositionDefinitionSequence'),
+  () => MutableRef.make(0),
+)
+
+const nextCompositionTagKey = (name: string): string =>
+  `reform/composition/${name}/${MutableRef.incrementAndGet(compositionDefinitionSequence)}`
+
+export const make =
+  <
+    const N extends string,
+    const Config extends CompositionConfig,
+    C extends UiContract,
+    const UiName extends string,
+  >(
+    name: N,
+    config: Config & UiCarrier<C, UiName> & ContractSlots<C> & ContextFreeProps<Config>,
+  ) =>
+  <Self>(): CompositionClass<PropsOf<Config>, C, StatesOf<Config>, N, Self> => {
+    const identity = Symbol(name)
+    const props = propsTag<PropsOf<Config>>()
+    const propsSchema = Schema.make<PropsOf<Config>, EncodedPropsOf<Config>>(
+      config.props?.ast ?? Schema.Unknown.ast,
+    )
+    const parseProps: (input: unknown) => Option.Option<PropsOf<Config>> =
+      Schema.decodeUnknownOption(propsSchema)
+    const tag = Context.GenericTag<
+      CompositionId<N, Self, RequiredSlotIdentities<C>>,
+      CompositionService<PropsOf<Config>, C>
+    >(nextCompositionTagKey(name))
+    const manifest = {
+      kind: 'Composition',
+      name,
+      ...config,
+    } satisfies CompositionManifest<C, N>
+    const composition = definitionClass<
+      CompositionClass<PropsOf<Config>, C, StatesOf<Config>, N, Self>
+    >({
+      manifest,
+      identity,
+      props,
+      parseProps,
+      acceptsProps: () => undefined,
+      tag,
+      capture: <Result>(visit: CompositionCapture<Result>): Result => visit(composition),
+    } satisfies CompositionDefinitionStatics<PropsOf<Config>, C, StatesOf<Config>, N, Self>)
+    return composition
+  }
+
+type CompositionLayerInput<Eff> = Exclude<Exclude<GeneratorContext<Eff>, PropsId>, CurrentTracker>
+
+type CompositionActivationLayerInput<Eff> = Exclude<
+  Exclude<GeneratorContext<Eff>, PropsId>,
+  Scope.Scope
+>
+
+export interface ScopedCompositionLiveConfig<
+  C extends UiContract,
+  RenderEff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
+  ActivationEff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
+> {
+  readonly render: () => Generator<RenderEff, Frame<C>, never>
+  readonly activate: () => Generator<ActivationEff, void, never>
 }
 
-/**
- * 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,
   C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
   Eff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
 >(
-  // The contract `C` is captured (not erased to `any`) so the body's returned
-  // `Structure` is checked against the composition's contract.
-  composition: CompositionClass<P, C>,
+  composition: CompositionClass<P, C, S, N, Identity>,
   body: () => Generator<Eff, Frame<C>, never>,
-): Layer.Layer<CompositionService, never, Exclude<Ctx<Eff>, Props>> => {
-  const logic = Effect.gen(body)
+): Layer.Layer<
+  CompositionId<N, Identity, RequiredSlotIdentities<C>>,
+  never,
+  CompositionLayerInput<Eff>
+> => {
+  const logic: Effect.Effect<Frame<C>, never, GeneratorContext<Eff>> = Effect.gen(body).pipe(
+    Effect.orDie,
+  )
   return Layer.effect(
     composition.tag,
     Effect.gen(function* () {
-      // Capture the build-time context (state stores, calc, ui, bus). `Props` and
-      // the tracker are injected per render below.
-      const context = yield* Effect.context<Exclude<Ctx<Eff>, Props>>()
-      const render = (env: RenderEnv): Effect.Effect<Frame, never, never> =>
-        // The per-render erasure seam: the body is total once fully provided (it is
-        // synchronous, reads can't fail, every requirement is now satisfied — D2) and
-        // its `Structure<C>` erases to the service's contract-agnostic `Frame`. `gen`
-        // widens the error channel to the body's inferred `E` for a generic body, so
-        // narrowing it (and the contract) back to the erased service type needs the
-        // `unknown` bridge — the one cast this render boundary has always required.
-        // oxlint-disable-next-line reform-rules/no-type-assertion -- the one documented render-boundary erasure: a fully-provided generic body's Structure<C> narrowed back to the contract-agnostic Frame service type
-        logic.pipe(
-          Effect.provideService(Props, env.props),
+      const context = yield* Effect.context<CompositionLayerInput<Eff>>()
+      const render = (env: RenderEnv<P>): Effect.Effect<Frame<C>, never, never> => {
+        return logic.pipe(
+          Effect.provideService(composition.props, env.props),
           Effect.provideService(CurrentTracker, env.tracker),
           Effect.provide(context),
-        ) as unknown as Effect.Effect<Frame, never, never>
-      return { render }
+        )
+      }
+      return { render, activation: () => Option.none() }
     }),
   )
 }
 
-/** Run a mounted composition for one frame, producing its `Frame` (a `Structure`). */
-export const render = (service: CompositionService, env: RenderEnv): Effect.Effect<Frame, never, never> =>
-  service.render(env)
+export const liveScoped = <
+  P,
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  N extends string,
+  Identity,
+  RenderEff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
+  ActivationEff extends YieldWrap<Effect.Effect<unknown, never, unknown>>,
+>(
+  composition: CompositionClass<P, C, S, N, Identity>,
+  config: ScopedCompositionLiveConfig<C, RenderEff, ActivationEff>,
+): Layer.Layer<
+  CompositionId<N, Identity, RequiredSlotIdentities<C>>,
+  never,
+  CompositionLayerInput<RenderEff> | CompositionActivationLayerInput<ActivationEff>
+> => {
+  const renderLogic: Effect.Effect<Frame<C>, never, GeneratorContext<RenderEff>> = Effect.gen(
+    config.render,
+  ).pipe(Effect.orDie)
+  const activationLogic: Effect.Effect<void, never, GeneratorContext<ActivationEff>> = Effect.gen(
+    config.activate,
+  ).pipe(Effect.orDie)
+
+  return Layer.effect(
+    composition.tag,
+    Effect.gen(function* () {
+      const renderContext = yield* Effect.context<CompositionLayerInput<RenderEff>>()
+      const activationContext =
+        yield* Effect.context<CompositionActivationLayerInput<ActivationEff>>()
+      const render = (env: RenderEnv<P>): Effect.Effect<Frame<C>, never, never> =>
+        renderLogic.pipe(
+          Effect.provideService(composition.props, env.props),
+          Effect.provideService(CurrentTracker, env.tracker),
+          Effect.provide(renderContext),
+        )
+      const activation = (props: P): Option.Option<CompositionActivation> => {
+        const scoped = Layer.scopedDiscard(
+          activationLogic.pipe(Effect.provideService(composition.props, props)),
+        )
+        return Option.some(scoped.pipe(Layer.provide(Layer.succeedContext(activationContext))))
+      }
+      return { render, activation }
+    }),
+  )
+}
+
+export const render = <P, C extends UiContract>(
+  service: CompositionService<P, C>,
+  env: RenderEnv<P>,
+): Effect.Effect<Frame<C>, never, never> => service.render(env)
+
+export const activation = <P, C extends UiContract>(
+  service: CompositionService<P, C>,
+  props: P,
+): Option.Option<CompositionActivation> => service.activation(props)

package/src/compose/host.ts

@@ -1,11 +1,5 @@
 import type { Node } from './slot'
 
-/**
- * A slot handle the host hands a presentation: BOTH renderable (call it / use as a
- * component to place the keyed children) AND inspectable (`.props` — the array of
- * per-child fill props the structure carried, one entry per mounted child). The
- * structure host (`renderStructure`) populates `.props` from the fills. Plan 06.
- */
 export interface SlotRenderer {
   (props: unknown): Node
   readonly props: ReadonlyArray<unknown>

package/src/compose/props.ts

@@ -1,14 +1,15 @@
 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`.
- *
- * (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.TagClass<Props, 'reform/Props', any> = Context.Tag('reform/Props')<
-  Props,
-  any
->()
-export class Props extends PropsBase {}
+export const PropsIdTypeId: unique symbol = Symbol.for('reform/PropsId')
+export type PropsIdTypeId = typeof PropsIdTypeId
+
+export interface PropsId {
+  readonly [PropsIdTypeId]: PropsIdTypeId
+}
+
+export type PropsTag<P> = Context.Tag<PropsId, P>
+
+export const propsTag = <P>(): PropsTag<P> => Context.GenericTag<PropsId, P>('reform/Props')
+
+// Unknown keeps the compatibility reader from leaking untyped props.
+export const Props: PropsTag<unknown> = propsTag<unknown>()