@playfast/reform 1.0.1 → 1.1.1

package/src/index.ts

@@ -1,239 +1,255 @@
-// Reform core — the renderer-neutral primitives and runtime.
-// Definitions (`X.make`) are separate from implementations (`.live`)
-// throughout, and nothing self-registers on import (principle #1, #6).
+export * as State from "./state/state";
+export * as StateGroup from "./state/stateGroup";
+export * as StateFamily from "./state/stateFamily";
+export { StateToken } from "./state/token";
+export type { AnySource, Source } from "./state/token";
 
-export * as State from './state/state'
-export * as StateGroup from './state/stateGroup'
-export * as StateFamily from './state/stateFamily'
-export { StateToken } from './state/token'
-export type { AnySource, Source } from './state/token'
+export * as Event from "./event/event";
+// TS2742: plain type export so declaration emit can name EventOf
+export type { EventOf } from "./event/event";
+export * as EventGroup from "./event/eventGroup";
 
-export * as Event from './event/event'
-// Direct type re-export alongside the namespace (TS2742 nameability): inferred
-// types of layers built over intent/event unions reference `EventOf`, and the
-// declaration emitter can only name it through a plain export.
-export type { EventOf } from './event/event'
-export * as EventGroup from './event/eventGroup'
-
-export * as Reducer from './reducer/reducer'
-export * as Calc from './calc/calc'
-export * as CalcFamily from './calc/calcFamily'
-export * as AsyncCalc from './calc/asyncCalc'
-export { composeCalcs } from './calc/compose'
-// The inputs-object/key/store types appearing in `AsyncCalc.live` /
-// `RemoteState.live` signatures, exported so app code can annotate
-// query-swapping helpers and layer types without re-spelling them.
-export type { InputsObject, InputStores, InvalidateBy } from './internal/sources'
-export {
-  AsyncData,
-  type AsyncError,
-  type AsyncIdle,
-  type AsyncLoading,
-  type AsyncSuccess,
-} from './calc/asyncData'
-// The flat, data-oriented query value (`data`/`error`/`isFetching`/`isStale`) an
-// `AsyncCalc` is driven by; `toAsyncData` projects it onto the matchable arms.
-export { isLoading, type QueryState, toAsyncData } from './calc/queryState'
-// Optional host seams an `AsyncCalc` consults — persistence and lifecycle signals.
-// Concrete implementations live in edge packages (e.g. `@playfast/reform-query-browser`).
-export {
-  noopQueryStore,
-  QueryStore,
-  type QueryStoreApi,
-  resolveQueryStore,
-} from './internal/queryStore'
-export {
-  noopQueryEvents,
-  QueryEvents,
-  type QueryEventsApi,
-  resolveQueryEvents,
-} from './internal/queryEvents'
-export * as RemoteState from './remote/remoteState'
-// Direct type re-exports alongside the namespace (TS2742 nameability): an app
-// layer's inferred type references these (`Store<ReadonlyArray<PendingIntent<…>>>`),
-// and the declaration emitter can only name them through a plain export.
-export type { FailedIntent, PendingIntent, RemoteStateClass } from './remote/remoteState'
-export * as SyncedStore from './synced/syncedStore'
-// Direct type re-export alongside the namespace (TS2742 nameability): adapters
-// (e.g. `@playfast/reform-db`) annotate the source handed to `SyncedStore.live`.
-export type { SyncedSource, SyncedStoreClass } from './synced/syncedStore'
-export * as Boundary from './boundary/boundary'
-// Direct type re-exports alongside the namespace (same TS2742 nameability
-// reason as the RemoteState types above): app code annotates props with these.
+export * as Reducer from "./reducer/reducer";
+export * as Calc from "./calc/calc";
+export * as CalcFamily from "./calc/calcFamily";
+export * as AsyncCalc from "./calc/asyncCalc";
+export { composeCalcs } from "./calc/compose";
+export type {
+	InputsObject,
+	InputStores,
+	InvalidateBy,
+} from "./internal/sources";
+export {
+	AsyncData,
+	type AsyncError,
+	type AsyncIdle,
+	type AsyncLoading,
+	type AsyncSuccess,
+} from "./calc/asyncData";
+export { isLoading, type QueryState, toAsyncData } from "./calc/queryState";
+export {
+	noopQueryStore,
+	QueryStore,
+	type QueryStoreApi,
+	resolveQueryStore,
+} from "./internal/queryStore";
+export {
+	noopQueryEvents,
+	QueryEvents,
+	type QueryEventsApi,
+	resolveQueryEvents,
+} from "./internal/queryEvents";
+export * as RemoteState from "./remote/remoteState";
+// TS2742: plain type exports so declaration emit can name pending/failed types
+export type {
+	FailedIntent,
+	PendingIntent,
+	RemoteStateClass,
+	RemoteStateSettled,
+} from "./remote/remoteState";
+export * as SyncedStore from "./synced/syncedStore";
+// TS2742: plain type export for SyncedSource nameability
+export type { SyncedSource, SyncedStoreClass } from "./synced/syncedStore";
+export * as Boundary from "./boundary/boundary";
+// TS2742: plain type exports for Boundary* nameability
 export type {
-  BoundaryErrored,
-  BoundaryPending,
-  BoundaryReady,
-  BoundaryState,
-} from './boundary/boundary'
-export * as Procedure from './procedure/procedure'
-export * as Channel from './channel/channel'
+	BoundaryErrored,
+	BoundaryPending,
+	BoundaryReady,
+	BoundaryState,
+} from "./boundary/boundary";
+export * as Procedure from "./procedure/procedure";
+export * as Channel from "./channel/channel";
+export * as Namespace from "./namespace/namespace";
+export type { FeatureNamespace } from "./namespace/namespace";
 
-export * as Composition from './compose/composition'
+export * as Composition from "./compose/composition";
 export type {
-  CompositionClass,
-  CompositionService,
-  Frame,
-  RenderEnv,
-} from './compose/composition'
-export {
-  absent,
-  each,
-  type EachFill,
-  isStructure,
-  mount,
-  one,
-  type OneFill,
-  type AbsentFill,
-  type SlotFill,
-  type Structure,
-  structureEquals,
-  type StructureSlots,
-  StructureTypeId,
-  when,
-} from './compose/structure'
-export { Props } from './compose/props'
-export {
-  isSlot,
-  type Node,
-  slot,
-  type SlotClass,
-  type SlotInstance,
-  type SlotProps,
-  SlotTypeId,
-} from './compose/slot'
-export { type SlotRenderer } from './compose/host'
-export * as Ui from './compose/ui'
-export {
-  type DerivedContract,
-  isUi,
-  type MadeView,
-  ui,
-  type UiClass,
-  type UiContract,
-  type UiManifest,
-  UiTypeId,
-  UiViewContract,
-  type ViewImpl,
-  type WireSchemas,
-  type WiredUi,
-  type WiredUiManifest,
-} from './compose/ui'
-export { provide } from './compose/provide'
-export type { Trigger } from './ui/trigger'
+	CompositionClass,
+	CompositionService,
+	Frame,
+	RenderEnv,
+} from "./compose/composition";
+export {
+	absent,
+	each,
+	type EachFill,
+	isStructure,
+	mount,
+	one,
+	type OneFill,
+	type AbsentFill,
+	type SlotFill,
+	type Structure,
+	structureEquals,
+	type StructureSlots,
+	StructureTypeId,
+	when,
+} from "./compose/structure";
+export { Props } from "./compose/props";
+export {
+	isSlot,
+	type Node,
+	slot,
+	type SlotClass,
+	type SlotInstance,
+	type SlotProps,
+	SlotTypeId,
+} from "./compose/slot";
+export { type SlotRenderer } from "./compose/host";
+export * as Ui from "./compose/ui";
+export {
+	type DerivedContract,
+	isUi,
+	type MadeView,
+	ui,
+	type UiClass,
+	type UiContract,
+	type UiManifest,
+	UiTypeId,
+	UiViewContract,
+	type ViewImpl,
+	type WireSchemas,
+	type WiredUi,
+	type WiredUiManifest,
+} from "./compose/ui";
+export { provide } from "./compose/provide";
+export type { Trigger } from "./ui/trigger";
 
-// Wire: the serializable rendered-tree model + pure diff/apply the remote
-// transport sends over the wire and the client folds back. See REMOTE_UI.md §3.
-export * as Wire from './wire/tree'
-export type { WireNode, WirePatch, WireProp, WireTree } from './wire/tree'
+export * as Wire from "./wire/tree";
+export type { WireNode, WirePatch, WireProp, WireTree } from "./wire/tree";
 
-// Triggers: the server-side handle registry bridging client trigger invocations
-// back to live triggers, decoding payloads via the event schema. See REMOTE_UI.md §4.
-export * as Triggers from './wire/triggers'
-export {
-  TriggerRegistry,
-  type TriggerHandle,
-  type TriggerRegistryApi,
-  UnknownTrigger,
-} from './wire/triggers'
+export * as Triggers from "./wire/triggers";
+export {
+	TriggerRegistry,
+	type TriggerHandle,
+	type TriggerRegistryApi,
+	UnknownTrigger,
+} from "./wire/triggers";
 
-// Feature: the lazy/eager code-split unit. Definitions stay eager and reflectable;
-// the heavy `.live` layer loads on demand (an Effect, never a Promise). See LAZY.md.
-export * as Feature from './feature/feature'
-export {
-  type EngineServices,
-  type FailedProps,
-  type FeatureBinding,
-  FeatureBindingTypeId,
-  type FeatureClass,
-  type FeatureManifest,
-  featureModule,
-  type FeatureModule,
-  isFeature,
-  isFeatureBinding,
-  lazyImport,
-  type LoadedModule,
-  mountFeature,
-  type Placeholders,
-  type ProvidedBy,
-  type RequireCarrier,
-} from './feature/feature'
-export { type SlotChild } from './compose/slot'
+export * as Feature from "./feature/feature";
+export {
+	type EngineServices,
+	type FailedProps,
+	type FeatureBinding,
+	FeatureBindingTypeId,
+	type FeatureClass,
+	type FeatureRequirement,
+	type FeatureManifest,
+	featureModule,
+	featureModuleFromInput,
+	FeatureInput,
+	type FeatureModule,
+	type EagerFeatureClass,
+	isFeature,
+	isFeatureBinding,
+	lazyImport,
+	type LazyFeatureClass,
+	type LoadedModule,
+	mountFeature,
+	type Placeholders,
+	type ProvidedBy,
+	type RequireCarrier,
+} from "./feature/feature";
+export { type SlotChild } from "./compose/slot";
 
-// A scene bundles a composition with the closed wiring that runs it — the single
-// handle the react host, proofs, and the dev tool all consume.
-export {
-  isScene,
-  type MountedServices,
-  profiledScene,
-  type Scene,
-  scene,
-  sceneInstrumentation,
-  seedScene,
-} from './scene/scene'
-export type { SeedsOf } from './state/stateGroup'
+export {
+	isScene,
+	type MountedServices,
+	profiledScene,
+	type Scene,
+	type FeatureSceneConfig,
+	featureScene,
+	scene,
+	sceneInstrumentation,
+	seedScene,
+} from "./scene/scene";
+export type { SeedsOf } from "./state/stateGroup";
 
-// Runtime surface for hosts (`@reform/react`) and headless tests.
-export { Bus, busLayer, type Envelope, type Priority, publish, type Tagged } from './runtime/bus'
-// The renderer-neutral scene runtime: hosts layer their lifecycle on top;
-// headless tests/proofs/drive scripts consume it directly.
-export {
-  type AppRuntime,
-  type FeatureMountHandlers,
-  makeAppRuntime,
-  type RuntimeHandle,
-} from './runtime/appRuntime'
-export { Engine, type ReducerEntry, Reducers, reducersLayer } from './runtime/loop'
-// The profiler SPI: synchronous hooks the engine calls on its hot paths, plus
-// the FiberRef seam `@playfast/reform-profiler` writes through (`profiledScene`).
-export {
-  CurrentInstrumentation,
-  type Instrumentation,
-  noopInstrumentation,
-  resolveInstrumentation,
-  type SpanEnd,
-} from './runtime/instrumentation'
-// The runtime-wide registry of live query handles. `AsyncCalc.invalidate` /
-// `AsyncCalc.refetch` and provider layers act on a query by name through it.
-export { Queries, queriesLayer, type QueryHandle, type QueryRegistry } from './runtime/queries'
-export {
-  type ChannelClass,
-  type ChannelPolicy,
-  type ChannelRuntime,
-  Channels,
-  channelsLayer,
-  type ProcedureEntry,
-  Procedures,
-  proceduresLayer,
-} from './channel/channel'
-export { CurrentTracker, type Subscribable, type Tracker } from './internal/track'
-export { CaptureSink, type CaptureSinkApi, type UiCapture } from './internal/capture'
-export {
-  AsyncReducer,
-  AsyncSceneLayer,
-  DuplicateRegistration,
-  FeatureLoadFailed,
-  forceSync,
-  InvalidProvideTarget,
-  UnknownGroupState,
-} from './internal/errors'
-// Notification scheduler: hosts that need per-runtime isolation (concurrent SSR,
-// multiple mounted roots) provide `Notifications` upstream of their state layers;
-// everything else coalesces on the process-wide default.
-export {
-  defaultScheduler,
-  makeScheduler,
-  Notifications,
-  notificationsLayer,
-  resolveScheduler,
-  type Scheduler,
-} from './internal/scheduler'
-export { makeStore, type Store } from './internal/store'
-export type { FamilyStore } from './state/stateFamily'
-// Primitive-authoring toolkit — exported for first-party companion packages
-// (e.g. `@playfast/reform-db`, `@playfast/reform-resource`) that build their own
-// first-class `Source`s which must participate in dependency tracking and
-// reflection exactly like a `Calc`.
-export { type Kind, type Manifest, yieldableClass } from './definition/definition'
-export { readTracked } from './internal/track'
-export { sameKey, wireSources, type WiredSources } from './internal/sources'
+export {
+	Bus,
+	busLayer,
+	type Envelope,
+	type Priority,
+	publish,
+	type Tagged,
+} from "./runtime/bus";
+export {
+	type AppRuntime,
+	type FeatureMountHandlers,
+	makeAppRuntime,
+	type RuntimeHandle,
+} from "./runtime/appRuntime";
+export {
+	Engine,
+	type ReducerEntry,
+	Reducers,
+	reducersLayer,
+} from "./runtime/loop";
+export {
+	CurrentEventBudget,
+	defaultEventBudget,
+	type EventBudget,
+	type ReformOptions,
+	resolveEventBudget,
+} from "./runtime/eventBudget";
+export {
+	CurrentInstrumentation,
+	type Instrumentation,
+	noopInstrumentation,
+	resolveInstrumentation,
+	type SpanEnd,
+} from "./runtime/instrumentation";
+export {
+	Queries,
+	queriesLayer,
+	type QueryHandle,
+	type QueryRegistry,
+} from "./runtime/queries";
+export {
+	type ChannelClass,
+	type ChannelPolicy,
+	type ChannelRuntime,
+	Channels,
+	channelsLayer,
+	type ProcedureEntry,
+	Procedures,
+	proceduresLayer,
+} from "./channel/channel";
+export {
+	CurrentTracker,
+	type Subscribable,
+	type Tracker,
+} from "./internal/track";
+export {
+	CaptureSink,
+	type CaptureSinkApi,
+	type UiCapture,
+} from "./internal/capture";
+export {
+	AsyncReducer,
+	AsyncSceneLayer,
+	DuplicateRegistration,
+	EventLoopOverflow,
+	FeatureLoadFailed,
+	forceSync,
+	InvalidProvideTarget,
+	UnknownGroupState,
+} from "./internal/errors";
+export {
+	defaultScheduler,
+	makeScheduler,
+	Notifications,
+	notificationsLayer,
+	resolveScheduler,
+	type Scheduler,
+} from "./internal/scheduler";
+export { makeStore, type Store } from "./internal/store";
+export type { FamilyStore } from "./state/stateFamily";
+export {
+	type Kind,
+	type Manifest,
+	yieldableClass,
+} from "./definition/definition";
+export { readTracked } from "./internal/track";
+export { sameKey, wireSources, type WiredSources } from "./internal/sources";

package/src/internal/capture.ts

@@ -1,38 +1,18 @@
 import { Context } from 'effect'
 import type { Trigger } from '../ui/trigger'
 
-/**
- * A single rendered UI node's observable surface: which contract rendered, the
- * props it received, and the event triggers it was handed. This is exactly what
- * a headless inspector (the proof facade, the dev tool) needs — no DOM, no JSX.
- */
 export interface UiCapture {
   readonly name: string
   readonly props: unknown
   readonly events: Record<string, Trigger<unknown>>
-  /**
-   * The stable slot-fill key this render was mounted under (an `each` item's
-   * `key`, or a synthesized singleton key for a `one`). Present only on the
-   * structure path — the legacy Node path defers slot expansion to host
-   * components and has no fill key, so it is omitted there. Lets the proof
-   * facade select a child by key (`byKey`) instead of by render index.
-   */
   // oxlint-disable-next-line reform-rules/no-optional-fields -- omitted (not Option-none) on the legacy Node path; built in compose/structure.ts and read by the proof package, both outside this batch
   readonly key?: string
 }
 
-/** Where captured renders are reported, when a capturing host is present. */
 export interface CaptureSinkApi {
   record(capture: UiCapture): void
 }
 
-/**
- * An OPTIONAL service. Core's `ui` read consults it via `serviceOption`: when a
- * capturing host provides it (proofs, the dev tool), every resolved view reports
- * its `(props, events)` before rendering, giving a faithful tree without
- * replacing any presentation. Production never provides it, so nothing is
- * recorded and there is no cost beyond one `serviceOption` lookup per render.
- */
 const CaptureSinkBase: Context.TagClass<CaptureSink, 'reform/internal/CaptureSink', CaptureSinkApi> =
   Context.Tag('reform/internal/CaptureSink')<CaptureSink, CaptureSinkApi>()
 

package/src/internal/ctx.ts

@@ -1,16 +1,9 @@
 import type { Effect } from 'effect'
 import type { YieldWrap } from 'effect/Utils'
+import type { AnyValue } from './variance'
 
-/**
- * The context (`R`) a generator body requires, recovered from the effects it
- * yields. Shared by `Composition.live` and `Procedure.live`, whose bodies are
- * both `Generator`s whose requirements must surface as their layer's `RIn`.
- *
- * A body that never yields (`Eff = never`) requires nothing — guard that case
- * first, or `infer R` resolves to `unknown` and leaks into the layer's `RIn`.
- */
 export type Ctx<Eff> = [Eff] extends [never]
   ? never
-  : [Eff] extends [YieldWrap<Effect.Effect<any, any, infer R>>]
+  : [Eff] extends [YieldWrap<Effect.Effect<AnyValue, AnyValue, infer R>>]
     ? R
     : never

package/src/internal/env.ts

@@ -0,0 +1,9 @@
+declare const process:
+  | { readonly env: { readonly NODE_ENV: string | undefined } }
+  | undefined
+
+export const isDev: boolean =
+  typeof process === 'undefined' ||
+  typeof process.env === 'undefined' ||
+  // oxlint-disable-next-line reform-rules/no-process-env -- must stay a static member expression so bundlers substitute it and DCE dev-only branches; Config resolves at runtime and cannot
+  process.env.NODE_ENV !== 'production'

package/src/internal/errors.test.ts

@@ -2,15 +2,9 @@ import { expect, it } from '@effect/vitest'
 import { Context, Effect, Layer, ManagedRuntime } from 'effect'
 import { AsyncSceneLayer, forceSync } from '../index'
 
-// `forceSync` is the sync-build boundary: reform materialises a scene's layer graph
-// with `runSync` so the first frame renders synchronously (D2). A layer whose acquire
-// suspends makes that `runSync` throw Effect's opaque `AsyncFiberException`; the
-// boundary translates it into `AsyncSceneLayer`, which names the cause and the fix.
-
 class Thing extends Context.Tag('test/Thing')<Thing, number>() {}
 
 it('translates an async layer build into AsyncSceneLayer', () => {
-  // A layer whose acquire suspends — exactly what a consumer trips on.
   const asyncLayer = Layer.effect(Thing, Effect.as(Effect.sleep('1 millis'), 1))
   const runtime = ManagedRuntime.make(asyncLayer)
   expect(() => forceSync(() => runtime.runSync(Effect.context<Thing>()))).toThrow(AsyncSceneLayer)