@playfast/reform 0.0.7 → 0.0.9

package/src/compose/structure.test.ts

@@ -0,0 +1,90 @@
+import { Schema as S } from 'effect'
+import { describe, expect, test } from 'vitest'
+import { Composition } from '../index'
+import { slot } from './slot'
+import { type Contract, ui } from './ui'
+import { absent, each, isStructure, mount, one, structureEquals, when } from './structure'
+
+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>() {}
+
+class ListUi extends ui('List')<{
+  props: { total: number }
+  slots: { Row: RowSlot }
+}>() {}
+
+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 }) })
+    expect(fill).toEqual({
+      _tag: 'Each',
+      items: [
+        { key: 'a', props: { label: 'a' } },
+        { key: 'b', props: { label: 'b' } },
+      ],
+    })
+  })
+
+  test('one and absent / when', () => {
+    expect(one({ label: 'x' })).toEqual({ _tag: 'One', props: { label: 'x' } })
+    expect(absent).toEqual({ _tag: 'Absent' })
+    expect(when(true, one({ label: 'y' }))).toEqual({ _tag: 'One', props: { label: 'y' } })
+    expect(when(false, one({ label: 'y' }))).toEqual({ _tag: 'Absent' })
+  })
+
+  test('mount stamps the Structure brand; isStructure discriminates it from a node', () => {
+    const s = mount<List>({
+      props: { total: 2 },
+      slots: { Row: each([{ id: 'a' }], { key: (t) => t.id, props: (t) => ({ label: t.id }) }) },
+    })
+    expect(isStructure(s)).toBe(true)
+    expect(isStructure({ type: 'div' })).toBe(false)
+    expect(isStructure(null)).toBe(false)
+    expect(s.props).toEqual({ total: 2 })
+  })
+
+  test('structureEquals detects a two-frame fixpoint vs a change', () => {
+    const make = (label: string) =>
+      mount<List>({
+        props: { total: 1 },
+        slots: { Row: each([{ id: 'a' }], { key: (t) => t.id, props: () => ({ label }) }) },
+      })
+    expect(structureEquals(make('same'), make('same'))).toBe(true)
+    expect(structureEquals(make('a'), make('b'))).toBe(false)
+  })
+})
+
+// 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 },
+    slots: {
+      // @ts-expect-error 'Nope' is not a declared slot of ListUi
+      Nope: one({ label: 'x' }),
+    },
+  })
+  mount<List>({
+    props: { total: 1 },
+    slots: {
+      // @ts-expect-error Row's child props are { label: string }, not { wrong: number }
+      Row: each([1], { key: () => 'k', props: () => ({ wrong: 1 }) }),
+    },
+  })
+  mount<List>({
+    // @ts-expect-error List's props are { total: number }, not { total: string }
+    props: { total: 'two' },
+    slots: { Row: absent },
+  })
+}

package/src/compose/structure.ts

@@ -0,0 +1,145 @@
+import type { SlotProps } from './slot'
+import type { EventsOf, UiContract } from './ui'
+
+/**
+ * Structure-as-data (the headless-structure keystone). A composition's logic
+ * body returns this *value* instead of a React node: pure, serializable data that
+ * describes — for this frame — the composition's own props and, per declared slot,
+ * how that slot is filled (a list / a singleton / absent). The engine, the wire
+ * server, and the proof harness consume this directly, so none of them needs to
+ * evaluate a view or import React to discover structure. Presentation (React)
+ * resolves a contract's markup separately, by name, on a host.
+ *
+ * `live` accepts BOTH a `Node` (legacy view body) and a `Structure` during the
+ * migration; hosts discriminate at runtime via {@link isStructure}.
+ */
+
+/** A list slot fill: one keyed entry per item. `key` is the SINGLE source of both
+ *  the wire `key` and the per-item `StateFamily` key — they can no longer drift. */
+export interface EachFill<P> {
+  readonly _tag: 'Each'
+  readonly items: ReadonlyArray<{ readonly key: string; readonly props: P }>
+}
+
+/** A singleton slot fill — the slot renders exactly one child with these props. */
+export interface OneFill<P> {
+  readonly _tag: 'One'
+  readonly props: P
+}
+
+/** A slot that renders nothing this frame (the data-driven analog of `cond && …`). */
+export interface AbsentFill {
+  readonly _tag: 'Absent'
+}
+
+/** How one declared slot is filled this frame, typed by the child's external props. */
+export type SlotFill<P> = EachFill<P> | OneFill<P> | AbsentFill
+
+/** The per-slot fill map a contract's structure carries — one fill per declared slot,
+ *  each typed by that child composition's external props (`SlotProps`). Empty when the
+ *  contract declares no slots. */
+export type StructureSlots<C extends UiContract> = C extends {
+  slots: infer S
+}
+  ? { readonly [K in keyof S]: SlotFill<SlotProps<S[K]>> }
+  : Record<never, never>
+
+/**
+ * The data a composition's logic returns for one frame: its computed props plus,
+ * for every declared slot, a fill description. Strict against the contract — props
+ * must match, and every declared slot must be filled (use {@link when} for
+ * conditional presence). Carries the child's contract per slot (via `SlotProps`),
+ * so consumers can select and descend into sub-compositions type-safely.
+ *
+ * `events` rides ON the structure: because a `mount(...)`-returning body never
+ * calls its view, the event triggers it acquired (`yield* Event.trigger(X)`) are
+ * no longer captured by a view's `CaptureSink` record — they must travel with the
+ * frame so hosts can register them (proof `actions`, the wire `TriggerRegistry`,
+ * the react presentation `events` arg). Triggers are functions, so `events` is NOT
+ * serializable and is intentionally excluded from {@link structureEquals}. Typed to
+ * the contract's event map; omit it (defaults to `{}`) when the contract has none.
+ */
+export interface Structure<C extends UiContract> {
+  readonly props: C['props']
+  readonly slots: StructureSlots<C>
+  readonly events?: EventsOf<C>
+}
+
+/** Runtime brand distinguishing a `Structure` value from a React `Node` (added by
+ *  {@link mount}; the authoring TYPE intentionally omits it so structure literals stay
+ *  plain). */
+export const StructureTypeId: unique symbol = Symbol.for('reform/Structure')
+export type StructureTypeId = typeof StructureTypeId
+
+/**
+ * Assemble a frame's structure, checked against the contract `C`. Identity at
+ * runtime apart from stamping the {@link StructureTypeId} brand; its real job is
+ * the compile-time contract check. `C` is recovered from the surrounding `live`
+ * body's return type (contextual typing), so call sites read `mount({ props, slots })`.
+ * A leaf composition (no declared slots) passes `slots: {}`. `events` defaults to an
+ * empty map when omitted, so a frame always carries an `events` record for hosts.
+ */
+export const mount = <C extends UiContract>(structure: Structure<C>): Structure<C> =>
+  Object.assign({ [StructureTypeId]: StructureTypeId, events: {} }, structure)
+
+/**
+ * A list slot fill. `key` derives the stable identity for BOTH the wire node and
+ * the per-item state family — passing the same id source to both is no longer
+ * possible to get wrong. `props` maps each item to the child's external props.
+ */
+export const each = <T, P>(
+  collection: Iterable<T>,
+  options: { readonly key: (item: T) => string; readonly props: (item: T) => P },
+): EachFill<P> => ({
+  _tag: 'Each',
+  items: Array.from(collection, (item) => ({ key: options.key(item), props: options.props(item) })),
+})
+
+/** A singleton slot fill — render one child with these external props. */
+export const one = <P>(props: P): OneFill<P> => ({ _tag: 'One', props })
+
+/** The shared empty fill — a slot that renders nothing this frame. */
+export const absent: AbsentFill = { _tag: 'Absent' }
+
+/** Conditional presence: the fill when `cond`, otherwise {@link absent}. */
+export const when = <F extends SlotFill<unknown>>(cond: boolean, fill: F): F | AbsentFill =>
+  cond ? fill : absent
+
+/** Whether a frame value is a `Structure` (vs a legacy React `Node`). The runtime
+ *  discriminator hosts use during the migration, replacing React's `isValidElement`. */
+export const isStructure = (frame: unknown): frame is Structure<UiContract> =>
+  typeof frame === 'object' && frame !== null && StructureTypeId in frame
+
+/** Whether a value is a plain record (not an array) — narrows for the deep compare
+ *  below without a cast. */
+const isRecord = (u: unknown): u is Record<string, unknown> =>
+  typeof u === 'object' && u !== null && !Array.isArray(u)
+
+/** Minimal structural deep-equality for serializable shapes (plain JSON — the
+ *  UI-contract guarantee). Avoids a heavyweight dep for the settle comparison. */
+const deepEquals = (a: unknown, b: unknown): boolean => {
+  if (Object.is(a, b)) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, index) => deepEquals(item, b[index]))
+  }
+  if (isRecord(a) && isRecord(b)) {
+    const aKeys = Object.keys(a)
+    const bKeys = Object.keys(b)
+    return (
+      aKeys.length === bKeys.length &&
+      aKeys.every(
+        (key) => Object.prototype.hasOwnProperty.call(b, key) && deepEquals(a[key], b[key]),
+      )
+    )
+  }
+  return false
+}
+
+/** Structural equality over two structures — props and every slot fill compared by
+ *  value. `events` is intentionally excluded: triggers are functions, freshly
+ *  acquired each render, so comparing them by identity would never match and would
+ *  break the settle fixpoint. The `StructureTypeId` brand is a symbol key, so
+ *  `Object.keys` skips it. Used by the proof/server settle loop to detect a
+ *  two-frame fixpoint. */
+export const structureEquals = (a: Structure<UiContract>, b: Structure<UiContract>): boolean =>
+  deepEquals(a.props, b.props) && deepEquals(a.slots, b.slots)

package/src/compose/ui.test.ts

@@ -0,0 +1,34 @@
+import { expect, test } from 'vitest'
+import { Schema as S } from 'effect'
+import { isUi, ui } from '../index'
+
+// `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()
+})

package/src/compose/ui.ts

@@ -0,0 +1,204 @@
+import type { FunctionComponent } from 'react'
+import { Context, type Schema } from 'effect'
+import { type Manifest, definitionClass } from '../definition/definition'
+import type { Trigger } from '../ui/trigger'
+import { type Node, type SlotClass, type SlotInstance, type SlotProps } from './slot'
+
+export interface UiContract {
+  props: unknown
+  slots?: Record<string, SlotInstance<any>>
+  events?: Record<string, Trigger<any>>
+}
+
+type PropsOf<C extends UiContract> = C['props']
+/** The contract's event map (`{ [name]: Trigger<P> }`), or empty when it declares
+ *  none. Exported so a `Structure<C>` can type its optional `events` field to the
+ *  same map a composition body acquires. */
+export type EventsOf<C extends UiContract> = C extends { events: infer E } ? E : Record<never, never>
+// A slot is a React COMPONENT whose props are OPTIONAL (a `Partial`): a parent that
+// drives a child supplies them (`<slots.Item id=… />` / `createElement(slots.Item, {…})`),
+// but a placeholder render (the remote client, where the per-child props were captured
+// server-side and the framework expands the children) omits them (`<slots.Item />`).
+// One `Ui.make` view thus serves both renderers. The child still reads its own
+// props/state — these are only the external props the parent feeds, advisory at the
+// slot boundary. Typing it as `FunctionComponent` makes both JSX and `createElement` work.
+//
+// `slotKey` is the universal KEYED-SLOT selector (see `WireNode.key`): for a LIST slot
+// invoked once per item (`<slots.Row slotKey={id} />`), the remote client renders only the
+// one wire child whose React `key` matches, instead of every child of that slot at every
+// call site (which duplicates the whole list under each call). It is framework-handled, not
+// forwarded to the child, so it is allowed on EVERY slot and never collides with a child's
+// own props. Omit it for singleton slots (`<slots.Create />`) — they render all children.
+type SlotsOf<C extends UiContract> = C extends { slots: infer S }
+  ? {
+      // `slotKey` goes INSIDE the `Partial<…>` (not intersected outside) so that when a slot's
+      // child props are `any` the whole thing still collapses to `any` (`any & X = any`), keeping
+      // the component assignable to a bare `(props: unknown) => Node` slot-renderer shape. An
+      // outer intersection would leave a required-shape object that `unknown` can't satisfy.
+      //
+      // A slot handle is BOTH renderable (the `FunctionComponent` — places the keyed children)
+      // AND inspectable (`.props` — the array of per-child fill props the structure carried, one
+      // entry per mounted child, typed by the child contract). A presentation can read the fills
+      // (`slots.Item.props.length`, a header, layout decisions) and still render them
+      // (`<slots.Item/>`); it never DERIVES multiplicity — the engine already fixed it. Read-only.
+      readonly [K in keyof S]: FunctionComponent<
+        Partial<SlotProps<S[K]> & { readonly slotKey?: string }>
+      > & { readonly props: ReadonlyArray<SlotProps<S[K]>> }
+    }
+  : Record<never, never>
+
+/** What `.make` authors: the pure presentation. Slots are injected by the renderer. */
+export type ViewImpl<C extends UiContract> = (
+  props: PropsOf<C>,
+  slots: SlotsOf<C>,
+  events: EventsOf<C>,
+) => Node
+
+/** Nominal brand identifying a UI contract at runtime (Effect's `TypeId` idiom). */
+export const UiTypeId: unique symbol = Symbol.for('reform/Ui')
+export type UiTypeId = typeof UiTypeId
+
+/**
+ * The reflectable descriptor a contract carries. The wire `props` / `events`
+ * schemas are present *only* on the schema (wired) form — the type-only form
+ * carries neither, so a local contract has no schema cost and no schema surface.
+ */
+export interface UiManifest extends Manifest {
+  readonly kind: 'Ui'
+  // `any` in the encoded/context slots is required by Schema's variance for
+  // branded/Class schemas; only the decoded type is ever read off these.
+  readonly props?: Schema.Schema<any, any>
+  readonly events?: Readonly<Record<string, Schema.Schema<any, any>>>
+}
+
+/** A `UiManifest` whose wire schema is present — the runtime brand of a remote-capable contract. */
+export interface WiredUiManifest extends UiManifest {
+  readonly props: Schema.Schema<any, any>
+}
+
+// A branded, extendable class carrying the wire `manifest` + the DI `impl` tag. Not
+// yieldable: bodies return a `Structure`, and the host reads `impl` to resolve the view.
+export interface UiClass<C extends UiContract> {
+  new (): {}
+  readonly [UiTypeId]: UiTypeId
+  readonly manifest: UiManifest
+  /** Internal DI tag the `Ui.make` presentation is provided under. */
+  readonly impl: Context.Tag<ViewImpl<C>, ViewImpl<C>>
+}
+
+/**
+ * Recover a contract's `UiContract` type from its `Ui` class — `Ui.Contract<typeof
+ * SomeUi>`. Lets a consumer (a proof, a reflection tool) name the contract derived
+ * from a wired `ui('X', {…})` without re-declaring it.
+ */
+export type Contract<U> = U extends UiClass<infer C> ? C : never
+
+/**
+ * A contract authored with wire schemas. Structurally a `UiClass<C>` whose
+ * manifest *carries* the schemas (`WiredUiManifest`), so it is the subtype the
+ * remote seam (`provideRemote`, the wire registry) demands while plain `provide`
+ * / `scene` / `Composition.make` keep accepting any `UiClass<C>`.
+ */
+export type WiredUi<C extends UiContract> = UiClass<C> & { readonly manifest: WiredUiManifest }
+
+/** The wire schemas a contract is authored from: props, a payload schema per event, and
+ *  (type-only) the slots the view fills. Slots carry no wire schema — the children that
+ *  fill them are their own contracts — but declaring them here threads typed slots into
+ *  the derived contract, so a WIRED contract can also have slots (e.g. a parent whose
+ *  props the client reads AND that renders slot children). */
+export interface WireSchemas {
+  readonly props: Schema.Schema<any, any>
+  readonly events?: Readonly<Record<string, Schema.Schema<any, any>>>
+  // Slots are declared with their slot CLASSES (`slot('X')<typeof Child>()`), the
+  // same values `Composition.make({ slots })` takes — NOT `SlotInstance`s. The
+  // contract's slot facade is derived from them below.
+  readonly slots?: Readonly<Record<string, SlotClass>>
+}
+
+type DerivedEvents<Sch extends WireSchemas> = Sch extends {
+  readonly events: infer E extends Record<string, Schema.Schema<any, any>>
+}
+  ? { readonly [K in keyof E]: Trigger<Schema.Schema.Type<E[K]>> }
+  : Record<never, never>
+
+type DerivedSlots<Sch extends WireSchemas> = Sch extends {
+  readonly slots: infer S extends Record<string, SlotClass>
+}
+  ? { readonly [K in keyof S]: InstanceType<S[K]> }
+  : Record<never, never>
+
+/**
+ * The `UiContract` a set of wire schemas denotes — props and event-payload
+ * *types* derived from the schemas via `Schema.Type`, plus any declared slots. The
+ * schema is the single source of truth; the contract type is inferred, never written
+ * a second time.
+ */
+export type DerivedContract<Sch extends WireSchemas> = {
+  readonly props: Schema.Schema.Type<Sch['props']>
+  readonly slots: DerivedSlots<Sch>
+  readonly events: DerivedEvents<Sch>
+}
+
+/** Whether a value is a UI contract — discriminates a `provide` target by brand. */
+export const isUi = (u: unknown): u is UiClass<UiContract> =>
+  (typeof u === 'function' || typeof u === 'object') && u !== null && UiTypeId in u
+
+const buildUi = <C extends UiContract, M extends UiManifest>(
+  name: string,
+  manifest: M,
+): UiClass<C> & { readonly manifest: M } => {
+  const impl = Context.GenericTag<ViewImpl<C>, ViewImpl<C>>(`reform/ui/${name}`)
+  // Extendable definition class (`class Counter extends ui('Counter', …) {}`); resolved
+  // by name on a host via `impl`, never yielded.
+  return definitionClass<UiClass<C> & { readonly manifest: M }>({
+    [UiTypeId]: UiTypeId,
+    manifest,
+    impl,
+  })
+}
+
+/**
+ * A renderer-neutral UI contract: `.make` authors the presentation, a composition
+ * names it, and `@reform/react` resolves it to a view. Core defines the contract.
+ *
+ * Two authoring forms, one source of truth each:
+ *
+ * - **Type-only (local):** `ui('Counter')<{ props: { count: number } }>()` — no
+ *   schema, no ceremony, exactly as before.
+ * - **Schema (wired):** `ui('Counter', { props: S.Struct({ count: S.Number }) })`
+ *   — the schema *is* the definition; the contract type is derived via
+ *   `Schema.Type` (never re-written), and the result is a `WiredUi` the remote
+ *   seam accepts. Make a local contract remote by rewriting this one line.
+ */
+export function ui(name: string): <C extends UiContract>() => UiClass<C>
+export function ui<const Sch extends WireSchemas>(name: string, schemas: Sch): WiredUi<DerivedContract<Sch>>
+export function ui(name: string, schemas?: WireSchemas): unknown {
+  if (schemas === undefined) {
+    return <C extends UiContract>(): UiClass<C> => buildUi<C, UiManifest>(name, { kind: 'Ui', name })
+  }
+  const eventFields = schemas.events === undefined ? {} : { events: schemas.events }
+  const manifest: WiredUiManifest = { kind: 'Ui', name, props: schemas.props, ...eventFields }
+  return buildUi<DerivedContract<WireSchemas>, WiredUiManifest>(name, manifest)
+}
+
+/** Brand under which a `Ui.make` view carries its own contract. */
+export const UiViewContract: unique symbol = Symbol.for('reform/ui/view-contract')
+export type UiViewContract = typeof UiViewContract
+
+/**
+ * A `Ui.make` view that carries its contract, so a consumer can recover the
+ * contract (its wire name + props schema) straight from the view — no separate
+ * registration call. This is what makes the remote client view-set
+ * (`remoteViews<AppContract>({ Some: SomeView, … })`) work with the very same
+ * `Ui.make` views the local renderer uses.
+ */
+export type MadeView<C extends UiContract> = ViewImpl<C> & { readonly [UiViewContract]: UiClass<C> }
+
+/**
+ * Author the pure presentation for a contract — `Ui.make(TodoAppUi, (props,
+ * slots, events) => node)`. The contract argument fixes the view's types AND is
+ * carried on the returned view (`MadeView`), so the same view is reusable as a
+ * remote client presentation. Wire the result with `provide(contract, view)`.
+ */
+export const make = <C extends UiContract>(contract: UiClass<C>, view: ViewImpl<C>): MadeView<C> =>
+  Object.assign(view, { [UiViewContract]: contract })

package/src/compose/ui.typecheck.ts

@@ -0,0 +1,56 @@
+// Type-level proofs enforced by `tsc --noEmit` over `src` (not a vitest file).
+// These guard the schema-first seam: the wired form is the single source of
+// truth (props/event types derived, never re-written), a wired contract is a
+// plain `UiClass` (so `provide` / `scene` / `Composition.make` accept it), and
+// the remote seam (`WiredUi`) rejects a type-only contract. If a guarantee
+// regresses, a `@ts-expect-error` goes unused or an assignment fails, and `tsc`
+// breaks.
+
+import { Schema as S } from 'effect'
+import {
+  type Contract,
+  type DerivedContract,
+  type MadeView,
+  make,
+  ui,
+  type UiClass,
+  type UiContract,
+  type WiredUi,
+} from './ui'
+
+declare function acceptsAny<C extends UiContract>(contract: UiClass<C>): void
+declare function acceptsWired<C extends UiContract>(contract: WiredUi<C>): void
+
+class LocalUi extends ui('Local')<{ props: { n: number } }>() {}
+const wiredSchemas: {
+  readonly props: S.Struct<{ n: typeof S.Number }>
+  readonly events: { readonly bump: S.Struct<{ by: typeof S.Number }> }
+} = {
+  props: S.Struct({ n: S.Number }),
+  events: { bump: S.Struct({ by: S.Number }) },
+}
+const WiredUiClassBase: WiredUi<DerivedContract<typeof wiredSchemas>> = ui('Wired', wiredSchemas)
+class WiredUiClass extends WiredUiClassBase {}
+
+// POSITIVE: both forms are a `UiClass` — plain wiring (provide/scene/Composition) accepts either.
+acceptsAny(LocalUi)
+acceptsAny(WiredUiClass)
+
+// POSITIVE: the schema form is a `WiredUi` — the remote seam accepts it.
+acceptsWired(WiredUiClass)
+
+// NEGATIVE: a type-only contract has no wire schema, so the remote seam rejects it.
+// @ts-expect-error -- LocalUi is `UiClass`, not `WiredUi`
+acceptsWired(LocalUi)
+
+// POSITIVE: props/event types are DERIVED from the schemas — authoring a presentation
+// against the wired contract sees `n: number` and `bump: Trigger<{ by: number }>`,
+// none of it written a second time.
+export const derivedView: MadeView<Contract<typeof WiredUiClass>> = make(
+  WiredUiClass,
+  ({ n }, _slots, { bump }) => {
+    const _n: number = n
+    bump({ by: _n })
+    return `${_n}`
+  },
+)

package/src/definition/definition.ts

@@ -0,0 +1,76 @@
+import { Effect } from 'effect'
+import { attachInspectable } from '../internal/inspect'
+
+/** A definition's `toJSON`: its reflectable manifest, else its raw statics. */
+const describe = (statics: object): unknown => (statics as { manifest?: unknown }).manifest ?? statics
+
+/**
+ * The reflectable descriptor every primitive carries (principle #6). The editor
+ * and proof packages read these without running any logic.
+ */
+export type Kind =
+  | 'State'
+  | 'StateGroup'
+  | 'StateFamily'
+  | 'Event'
+  | 'EventGroup'
+  | 'Reducer'
+  | 'Calc'
+  | 'CalcFamily'
+  | 'AsyncCalc'
+  | 'Resource'
+  | 'RemoteState'
+  | 'SyncedStore'
+  | 'Boundary'
+  | 'Procedure'
+  | 'Channel'
+  | 'Composition'
+  | 'Ui'
+  | 'Slot'
+  | 'Feature'
+
+export interface Manifest {
+  readonly kind: Kind
+  readonly name: string
+}
+
+/**
+ * Build a class whose *static* side is itself an Effect, so `yield* TheClass`
+ * runs `read` and returns its value (the same mechanism `Context.Tag` uses).
+ * Subclasses inherit the protocol through the prototype chain, so the user's
+ * `class FeedState extends State.make(...) {}` is yieldable too.
+ *
+ * `statics` (manifest, `.live`, tag, …) are attached as own properties
+ * and likewise inherited by the subclass.
+ */
+export const yieldableClass = <A, E, R, Statics extends object>(
+  read: Effect.Effect<A, E, R>,
+  statics: Statics,
+): { new (): {} } & Effect.Effect<A, E, R> & Statics => {
+  class Base {}
+  Object.setPrototypeOf(Base, read)
+  // `defineProperty` over `Reflect.ownKeys`, not `Object.assign` over
+  // `Object.entries`: a static can shadow a non-writable own property of the
+  // class function (notably `name`, which a `Source`-shaped definition like a
+  // Calc carries) and `assign` would throw on those; and `ownKeys` (unlike
+  // `entries`) carries symbol-keyed statics — the `TypeId` brands.
+  for (const key of Reflect.ownKeys(statics)) {
+    const value = (statics as Record<PropertyKey, unknown>)[key]
+    Object.defineProperty(Base, key, { value, writable: true, enumerable: true, configurable: true })
+  }
+  // Print like an Effect value (the manifest), not `[object Object]`.
+  attachInspectable(Base, () => describe(statics))
+  return Base as never
+}
+
+/**
+ * Build a *definition class*: an empty constructible carrying static marker data
+ * (manifest, tag, policy, members, …) that the editor and proof packages reflect
+ * on. Definition interfaces declare phantom, type-only fields — a composition's
+ * `Props`, a family instance's `Key` — that exist purely for inference and have
+ * no runtime value, so the assembled object cannot *structurally* satisfy the
+ * interface. The one assertion to `Class` lives here, documented, instead of a
+ * scattered `as never` / `as unknown as` at every `*.make`.
+ */
+export const definitionClass = <Class>(statics: object): Class =>
+  attachInspectable(Object.assign(class {}, statics), () => describe(statics)) as unknown as Class

package/src/event/event.test.ts

@@ -0,0 +1,23 @@
+import { expect, test } from 'vitest'
+import { Schema as S } from 'effect'
+import { Event } from '../index'
+
+// An event is a pure data fact: `Event.construct` builds the tagged value the
+// bus carries, and the class carries the reflectable `manifest` + `tag`.
+
+test('Event.construct builds the tagged value `{ _tag, ...payload }`', () => {
+  class Added extends Event.make('Added', S.Struct({ id: S.String })) {}
+  expect(Event.construct(Added, { id: 'x' })).toEqual({ _tag: 'Added', id: 'x' })
+})
+
+test('an event carries its reflectable manifest and tag', () => {
+  class Added extends Event.make('Added', S.Struct({ id: S.String })) {}
+  expect(Added.tag).toBe('Added')
+  expect(Added.manifest.kind).toBe('Event')
+  expect(Added.manifest.name).toBe('Added')
+})
+
+test('empty-payload events construct to just their tag', () => {
+  class Pinged extends Event.make('Pinged', S.Struct({})) {}
+  expect(Event.construct(Pinged, {})).toEqual({ _tag: 'Pinged' })
+})