@spinjs/components 0.1.0-preview.2 → 0.2.0-alpha.1

package/dist/runtime/directives/tpl.d.ts

@@ -0,0 +1,11 @@
+export declare function tpl<T extends Element>(html: string): () => T;
+export interface Rendered {
+  readonly node: Node;
+  update(): void;
+}
+export declare function view(parts: (() => void)[], nodes: readonly Node[]): Rendered;
+export interface ReactiveText {
+  readonly node: Text;
+  set(value: string): void;
+}
+export declare function text(initial?: string): ReactiveText;

package/dist/runtime/directives/tpl.js

@@ -0,0 +1,39 @@
+// src/runtime/directives/tpl.ts
+function tpl(html) {
+	let proto;
+	return () => {
+		if (proto === void 0) {
+			const t = document.createElement("template");
+			t.innerHTML = html;
+			proto = t.content.firstElementChild;
+		}
+		return proto.cloneNode(true);
+	};
+}
+function view(parts, nodes) {
+	const host = document.createDocumentFragment();
+	for (const n of nodes) host.appendChild(n);
+	const rendered = {
+		node: host,
+		update() {
+			const n = parts.length;
+			for (let i = 0; i < n; i++) parts[i]();
+		}
+	};
+	rendered.update();
+	return rendered;
+}
+function text(initial = "") {
+	const node = document.createTextNode(initial);
+	return {
+		node,
+		set(value) {
+			const next = String(value);
+			if (node.data === next) return;
+			node.data = next;
+		}
+	};
+}
+export { text, tpl, view };
+
+//# sourceMappingURL=tpl.js.map

package/dist/runtime/directives/use.d.ts

@@ -0,0 +1,13 @@
+export type Signal<T> = {
+  (): T;
+  (value: T): void;
+};
+export interface ActionResult<P = unknown> {
+  update?(param: P): void;
+  destroy?(): void;
+}
+export type ElementAction<P = unknown> = (node: Element, param: P) => ActionResult<P> | void;
+export declare function createAction<P>(fn: ElementAction<P>): ElementAction<P>;
+export declare function runAction<P>(node: Element, action: ElementAction<P> | null | undefined, paramThunk?: () => P): void;
+export type SlotLookup = (name: string) => Node[];
+export declare function on<E extends Event = Event>(el: EventTarget, event: string, handler: (e: E) => void): () => void;

package/dist/runtime/directives/use.js

@@ -0,0 +1,34 @@
+import { effect, own, untrack } from "../core/signal.js";
+// src/runtime/directives/use.ts
+function createAction(fn) {
+	return (node, param) => untrack(() => fn(node, param) ?? void 0);
+}
+function runAction(node, action, paramThunk) {
+	if (typeof action !== "function") return;
+	let result;
+	let started = false;
+	effect(() => {
+		const param = paramThunk === void 0 ? void 0 : paramThunk();
+		if (!started) {
+			started = true;
+			result = action(node, param) ?? void 0;
+		} else result?.update?.(param);
+	});
+	own(() => {
+		result?.destroy?.();
+	});
+}
+function on(el, event, handler) {
+	const wrapped = (e) => {
+		handler(e);
+	};
+	el.addEventListener(event, wrapped);
+	const stop = () => el.removeEventListener(event, wrapped);
+	try {
+		own(stop);
+	} catch {}
+	return stop;
+}
+export { createAction, on, runAction };
+
+//# sourceMappingURL=use.js.map

package/dist/runtime/index.d.ts

@@ -0,0 +1,101 @@
+import { OwnerScope, Signal, batch, computed, effect, own, scope, signal, trigger, untrack } from "./core/signal.js";
+import { AttributeParser, BuildContext, ElementSpec, attrParsers, define, scopeOf, uniqueId, writeProp } from "./scope/element.js";
+import { IdFn, focuser, ids, measurer } from "./component/ids.js";
+import { coerceBool, coerceInt, coerceJsonArray, coerceList, coerceObjectArrayItems, coerceString, defaultTwin, isRecord, resolveTwins } from "./props.js";
+import { DefinedComponent, authoredProps, defineComponent, pickCallback, textProp } from "./component/synthesize.js";
+import { clampValue, closestIndex, getNextStepValue, getPercentValue, getPreviousStepValue, getValuePercent, getValueRanges, isInteractive, round10, snapValueToStep } from "./math/numbers.js";
+import { AnyEvent, ApiOf, CommandDef, ComponentDef, EventDef, PartDef, PartView, PropParser, SlotDef, SlotView, SlotViewFor, ViewFor, dataAttr, isComposing } from "./component/define.js";
+import { Handle, ScopeTable, SpinController, consume, controllerOf, controllerView, createScopeTable, provideController } from "./scope/table.js";
+import { ElementAction, SlotLookup, createAction, on, runAction } from "./directives/use.js";
+import { Binding, Writable, bindAttr, bindChecked, bindDynamic, bindProp, bindText, bindValue, classOf, placeSlot, projectSlots } from "./directives/bind.js";
+import { BindForOptions, RenderedItem, bindFor } from "./directives/for.js";
+import { BindIfOptions, BranchRender, bindIf } from "./directives/if.js";
+import { ReactiveText, Rendered, text, tpl, view } from "./directives/tpl.js";
+import { AriaAutocomplete, AriaCurrent, AriaFragment, AriaHasPopup, AriaLive, AriaOrientation, AriaPartRef, AriaState, AriaTarget, AriaValue, ariaAutocomplete, ariaBusy, ariaControls, ariaCurrent, ariaDescribedBy, ariaDescription, ariaDisabled, ariaFlag, ariaHidden, ariaInvalid, ariaLabelledBy, ariaOrientation, ariaOwns, ariaPressed, ariaReadOnly, ariaRequired, ariaRoleDescription, ariaState, comboboxInput, disclosureTrigger, listSurface, liveRegion, optionRow, sliderThumb } from "./aria.js";
+import { matchBrace, skipQuoted } from "./syntax/braces.js";
+import { CodeToken, CodeTokenType, formatExampleHtml, tokenizeHtml } from "./syntax/display.js";
+import { expandVariantGroups } from "./syntax/expand-groups.js";
+import { ActionUse, Attr, AttrValue, ComponentIr, Diagnostic, ElementNode, EventBinding, ForNode, Node, ParseError, SpreadUse, TextNode } from "./syntax/ir.js";
+import { classAttrOf, classTokens, classTokensOf } from "./syntax/classes.js";
+import { ScriptCall, ScriptConsume, StrippedScript, extractScript, stripScript } from "./syntax/script-block.js";
+import { parse } from "./syntax/parse.js";
+import { LoaderActions, LoaderScope, load } from "./directives/load.js";
+import { bindActionProps, bindSpread } from "./directives/spread.js";
+import { Assign, AssignFor, Config, EventMap, EventName, EventNames, EventObject, EventOf, EventUnion, GuardFor, Machine, MachineSpec, Service, State, Transition, Transitions, createMachine, interpret } from "./machine/fsm/machine.js";
+/**
+ * The machine-def contract: what a `<name>.machine-def.ts` module provides.
+ *
+ * `machine` + `connect` are Zag's pair, opaque here — the runtime never
+ * imports Zag. `events` is the authored out-side: each CustomEvent name maps
+ * to the Zag callback prop that fires it and the detail mapper. The plugin
+ * codegen turns each entry into a machine prop that dispatches on `el`.
+ * A misspelled `on` never fires, so machine-defs annotate against this
+ * rather than widening to `unknown`.
+ */
+export interface MachineEventContract<TDetail = unknown> {
+  /** The Zag callback prop name, e.g. `onValueChange`. */
+  readonly on: string;
+  /**
+   * Maps Zag's callback payload to the event's `detail`. `any` in, typed
+   * out: Zag's payload shapes are per-machine and untyped at this seam,
+   * so the mapper narrows and the event carries the narrowed type.
+   */
+  readonly detail: (change: any) => TDetail;
+}
+export interface MachineDef {
+  /**
+   * Builds the bridge from scope props, the element root, and the machine
+   * id. Props arrive as a live reader (the element's prop store), never a
+   * snapshot. The returned api is what the markup spreads and what commands
+   * and element getters forward to.
+   */
+  readonly createBridge: (props: () => Record<string, unknown>, root: () => Element, id: string) => {
+    readonly api: object;
+    dispose(): void;
+  };
+  /**
+   * Imperative commands the host (or a controller) may call on the element:
+   * `el[name](...args)` forwards to `api[name]`. Declared, not reflected, so
+   * the element's surface is authored — no machine method can accidentally
+   * shadow a DOM API by being copied over.
+   */
+  readonly commands?: readonly string[];
+  /**
+   * Authored out-side: each CustomEvent name maps to a callback prop the
+   * bridge reports through and the detail mapper. The plugin codegen turns
+   * each entry into a machine prop that dispatches on `el`. A misspelled
+   * `on` never fires, so machine-defs annotate against this rather than
+   * widening to `unknown`.
+   */
+  readonly events?: Readonly<Record<string, MachineEventContract>>;
+}
+/**
+ * The platform-tier def: a thin layer over what the browser already does.
+ *
+ * Same slot as a MachineDef — markup `consume`s it the same way, commands
+ * install the same way, events map the same way, and the app-controller
+ * surface is identical. The difference is only who owns the state: here the
+ * platform does, and `attach` wires the native behavior to the declared
+ * commands and events. This is the progressive-enhancement tier: no machine,
+ * no bridge machinery, just the adapter that makes the platform's controller
+ * look like ours.
+ */
+export interface ControllerDef {
+  /** Wires the element's native behavior; returns the api markup spreads. */
+  attach(el: Element): object;
+  /** Commands the element installs, as with a machine def. */
+  readonly commands?: readonly string[];
+  /** Authored events, as with a machine def. */
+  readonly events?: Readonly<Record<string, MachineEventContract>>;
+}
+/**
+ * Build a platform-tier controller def that is also callable in `<script>`:
+ * the call typechecks the markup's binding (`const ctl = popover()`), while
+ * the compiler wires the live element through `attach(el)`.
+ */
+export declare function defineController<Api extends object>(def: ControllerDef & {
+  attach(el: Element): Api;
+}): ControllerDef & {
+  attach(el: Element): Api;
+} & (() => Api);
+export { type ActionUse, type AnyEvent, type ApiOf, type AriaAutocomplete, type AriaCurrent, type AriaFragment, type AriaHasPopup, type AriaLive, type AriaOrientation, type AriaPartRef, type AriaState, type AriaTarget, type AriaValue, type Assign, type AssignFor, type Attr, type AttrValue, type AttributeParser, type BindForOptions, type BindIfOptions, type Binding, type BranchRender, type BuildContext, type CodeToken, type CodeTokenType, type CommandDef, type ComponentDef, type ComponentIr, type Config, type DefinedComponent, type Diagnostic, type ElementAction, type ElementNode, type ElementSpec, type EventBinding, type EventDef, type EventMap, type EventName, type EventNames, type EventObject, type EventOf, type EventUnion, type ForNode, type GuardFor, type Handle, type IdFn, type LoaderActions, type LoaderScope, type Machine, type MachineSpec, type Node, type OwnerScope, ParseError, type PartDef, type PartView, type PropParser, type ReactiveText, type Rendered, type RenderedItem, type ScopeTable, type ScriptCall, type ScriptConsume, type Service, type Signal, type SlotDef, type SlotLookup, type SlotView, type SlotViewFor, type SpinController, type SpreadUse, type State, type StrippedScript, type TextNode, type Transition, type Transitions, type ViewFor, type Writable, ariaAutocomplete, ariaBusy, ariaControls, ariaCurrent, ariaDescribedBy, ariaDescription, ariaDisabled, ariaFlag, ariaHidden, ariaInvalid, ariaLabelledBy, ariaOrientation, ariaOwns, ariaPressed, ariaReadOnly, ariaRequired, ariaRoleDescription, ariaState, attrParsers, authoredProps, batch, bindActionProps, bindAttr, bindChecked, bindDynamic, bindFor, bindIf, bindProp, bindSpread, bindText, bindValue, clampValue, classAttrOf, classOf, classTokens, classTokensOf, closestIndex, coerceBool, coerceInt, coerceJsonArray, coerceList, coerceObjectArrayItems, coerceString, comboboxInput, computed, consume, controllerOf, controllerView, createAction, createMachine, createScopeTable, dataAttr, defaultTwin, define, defineComponent, disclosureTrigger, effect, expandVariantGroups, extractScript, focuser, formatExampleHtml, getNextStepValue, getPercentValue, getPreviousStepValue, getValuePercent, getValueRanges, ids, interpret, isComposing, isInteractive, isRecord, listSurface, liveRegion, load, matchBrace, measurer, on, optionRow, own, parse, pickCallback, placeSlot, projectSlots, provideController, resolveTwins, round10, runAction, scope, scopeOf, signal, skipQuoted, sliderThumb, snapValueToStep, stripScript, text, textProp, tokenizeHtml, tpl, trigger, uniqueId, untrack, view, writeProp };

package/dist/runtime/index.js

@@ -0,0 +1,40 @@
+import { batch, computed, effect, own, scope, signal, trigger, untrack } from "./core/signal.js";
+import { attrParsers, define, scopeOf, uniqueId, writeProp } from "./scope/element.js";
+import { focuser, ids, measurer } from "./component/ids.js";
+import { coerceBool, coerceInt, coerceJsonArray, coerceList, coerceObjectArrayItems, coerceString, defaultTwin, isRecord, resolveTwins } from "./props.js";
+import { authoredProps, defineComponent, pickCallback, textProp } from "./component/synthesize.js";
+import "./math/index.js";
+import { dataAttr, isComposing } from "./component/define.js";
+import { consume, controllerOf, controllerView, createScopeTable, provideController } from "./scope/table.js";
+import { createAction, on, runAction } from "./directives/use.js";
+import { bindAttr, bindChecked, bindDynamic, bindProp, bindText, bindValue, classOf, placeSlot, projectSlots } from "./directives/bind.js";
+import { bindFor } from "./directives/for.js";
+import { bindIf } from "./directives/if.js";
+import { text, tpl, view } from "./directives/tpl.js";
+import { ariaAutocomplete, ariaBusy, ariaControls, ariaCurrent, ariaDescribedBy, ariaDescription, ariaDisabled, ariaFlag, ariaHidden, ariaInvalid, ariaLabelledBy, ariaOrientation, ariaOwns, ariaPressed, ariaReadOnly, ariaRequired, ariaRoleDescription, ariaState, comboboxInput, disclosureTrigger, listSurface, liveRegion, optionRow, sliderThumb } from "./aria.js";
+import { matchBrace, skipQuoted } from "./syntax/braces.js";
+import { formatExampleHtml, tokenizeHtml } from "./syntax/display.js";
+import { expandVariantGroups } from "./syntax/expand-groups.js";
+import { classAttrOf, classTokens, classTokensOf } from "./syntax/classes.js";
+import { extractScript, stripScript } from "./syntax/script-block.js";
+import { ParseError } from "./syntax/ir.js";
+import { parse } from "./syntax/parse.js";
+import { load } from "./directives/load.js";
+import { bindActionProps, bindSpread } from "./directives/spread.js";
+import { clampValue, closestIndex, getNextStepValue, getPercentValue, getPreviousStepValue, getValuePercent, getValueRanges, isInteractive, round10, snapValueToStep } from "./math/numbers.js";
+import { createMachine, interpret } from "./machine/fsm/machine.js";
+// src/runtime/index.ts
+/**
+* Build a platform-tier controller def that is also callable in `<script>`:
+* the call typechecks the markup's binding (`const ctl = popover()`), while
+* the compiler wires the live element through `attach(el)`.
+*/
+function defineController(def) {
+	const callable = () => {
+		throw new Error("[spin] controller() is a <script> binding compiled by spin-components; the element wires attach(el)");
+	};
+	return Object.assign(callable, def);
+}
+export { ParseError, ariaAutocomplete, ariaBusy, ariaControls, ariaCurrent, ariaDescribedBy, ariaDescription, ariaDisabled, ariaFlag, ariaHidden, ariaInvalid, ariaLabelledBy, ariaOrientation, ariaOwns, ariaPressed, ariaReadOnly, ariaRequired, ariaRoleDescription, ariaState, attrParsers, authoredProps, batch, bindActionProps, bindAttr, bindChecked, bindDynamic, bindFor, bindIf, bindProp, bindSpread, bindText, bindValue, clampValue, classAttrOf, classOf, classTokens, classTokensOf, closestIndex, coerceBool, coerceInt, coerceJsonArray, coerceList, coerceObjectArrayItems, coerceString, comboboxInput, computed, consume, controllerOf, controllerView, createAction, createMachine, createScopeTable, dataAttr, defaultTwin, define, defineComponent, defineController, disclosureTrigger, effect, expandVariantGroups, extractScript, focuser, formatExampleHtml, getNextStepValue, getPercentValue, getPreviousStepValue, getValuePercent, getValueRanges, ids, interpret, isComposing, isInteractive, isRecord, listSurface, liveRegion, load, matchBrace, measurer, on, optionRow, own, parse, pickCallback, placeSlot, projectSlots, provideController, resolveTwins, round10, runAction, scope, scopeOf, signal, skipQuoted, sliderThumb, snapValueToStep, stripScript, text, textProp, tokenizeHtml, tpl, trigger, uniqueId, untrack, view, writeProp };
+
+//# sourceMappingURL=index.js.map

package/dist/runtime/machine/fsm/machine.d.ts

@@ -0,0 +1,192 @@
+/**
+ * The state machine core: a config-first FSM, forked from @xstate/fsm 2.1.0
+ * (MIT, © Stately, https://github.com/statelyai/xstate).
+ *
+ * The machine is HEADLESS: state, transitions, and its own arguments. It
+ * knows nothing about props, markup, or the DOM.
+ *
+ * Why fork rather than depend: the package is correct, tiny, MIT, and the
+ * last stable was published in 2023 — a frozen base is a solid foundation
+ * and a poor dependency. This fork adapts it to this runtime's needs and
+ * keeps the config shape agents and the studio know:
+ *
+ *   const machine = createMachine({
+ *     initial: "idle",
+ *     context: { value: [] },
+ *     states: {
+ *       idle: { on: {
+ *         TOGGLE: [
+ *           { cond: "isOpen", actions: [{ assign: "collapse" }] },
+ *           { actions: [{ assign: "expand" }] },
+ *         ],
+ *       } },
+ *     },
+ *   }, { conds: {...}, assigns: {...}, actions: {...} });
+ *
+ * Transition resolution is PURE (`machine.transition`), and `interpret`
+ * executes the resolved actions. The delta from upstream, all deliberate:
+ *
+ * 1. **Named conds and assigns.** `cond: "name"` resolves from
+ *    `implementations.conds`; `{ assign: "name" }` from
+ *    `implementations.assigns`. Upstream allows only inline functions, which
+ *    puts code inside the config — the config is meant to be data for the
+ *    studio's visualizer, test derivation, and agent authoring. Assigns are
+ *    pure context transforms, so naming them keeps the whole config
+ *    serializable with a lookup table of reviewed pure functions beside it.
+ * 2. **Per-field signals.** `interpret` backs `state.value` and each field of
+ *    `state.context` with an `alien-signals` signal updated inside `batch()`.
+ * 3. **No status enum beyond stopped.** Scope disposal owns teardown;
+ *    `stop()` is what `dispose()` calls.
+ */
+/** Any event object: a discriminant type plus any payload. */
+export type EventObject = {
+  type: string;
+} & Record<string, unknown>;
+/**
+ * The machine's events, as a MAP: one entry per event name, carrying that
+ * event's payload.
+ *
+ * The map is the contract with the outside, so the author writes it by hand
+ * — and the spec's `on` map is typed over it, so a transition's KEY
+ * narrows the event it receives.
+ */
+export type EventMap = object;
+/**
+ * The map's keys, as NAMES. A map is an interface, so it has no index
+ * signature — the names are extracted, not read off an index.
+ */
+export type EventNames<TMap extends EventMap> = Extract<keyof TMap, string>;
+/**
+ * The event a name names: its discriminant, plus the payload the map
+ * gives under that name.
+ */
+export type EventOf<TMap extends EventMap, TName extends EventNames<TMap>> = TName extends EventNames<TMap> ? {
+  readonly type: TName;
+} & TMap[TName & keyof TMap] : never;
+/** Every event of a map, as the union a service sends. */
+export type EventUnion<TMap extends EventMap> = { [TName in EventNames<TMap>]: EventOf<TMap, TName>; }[EventNames<TMap>];
+/** The name of an event of a map. */
+export type EventName<TMap extends EventMap> = EventNames<TMap>;
+/** The state a service holds: a value, the context, and what it matches. */
+export interface State<TContext extends object, TState extends string = string> {
+  readonly value: TState;
+  readonly context: TContext;
+  readonly matches: (value: string) => boolean;
+}
+/** A transition target: a state name, or a record with an optional target. */
+export type Transition<TContext extends object, TEvent, TState extends string = string> = TState | {
+  readonly target?: TState;
+  readonly cond?: (context: TContext, event: TEvent) => boolean;
+  readonly assign?: Assign<TContext, TEvent> | readonly Assign<TContext, TEvent>[];
+};
+/** A context write: a pure transform of the context. */
+export type Assign<TContext extends object, TEvent> = (context: TContext, event: TEvent) => Partial<TContext>;
+/** A context write narrowed to one or more event names of a map. */
+export type AssignFor<TContext extends object, TEventMap extends EventMap, TName extends EventNames<TEventMap> = EventNames<TEventMap>> = (context: TContext, event: EventOf<TEventMap, TName>) => Partial<TContext>;
+/** A transition guard narrowed to one or more event names of a map. */
+export type GuardFor<TContext extends object, TEventMap extends EventMap, TName extends EventNames<TEventMap> = EventNames<TEventMap>> = (context: TContext, event: EventOf<TEventMap, TName>) => boolean;
+/**
+ * The transitions of a map: each KEY narrows its own event.
+ *
+ * The author writes the event map once, and every transition reads its
+ * event through the narrowing its key gives.
+ */
+export type Transitions<TContext extends object, TEventMap extends EventMap, TState extends string = string> = { readonly [TName in EventNames<TEventMap>]?: Transition<TContext, EventOf<TEventMap, TName>, TState> | readonly Transition<TContext, EventOf<TEventMap, TName>, TState>[]; };
+/**
+ * A state's entry or exit: a context write, or the `{ assign }` form a
+ * spec writes when it names a shared body.
+ */
+export type Entry<TContext extends object, TEvent extends object> = Assign<TContext, TEvent> | {
+  readonly assign: Assign<TContext, TEvent>;
+};
+export interface Config<TContext extends object, TEventMap extends EventMap, TState extends string = string> {
+  readonly id?: string;
+  readonly initial: TState;
+  readonly context?: TContext;
+  /** Root-level handlers: candidates in every state. State-level handlers
+   * for the same event shadow these; everything else falls through here,
+   * which states "this event works everywhere" once instead of duplicating
+   * it across states. */
+  readonly on?: Transitions<TContext, TEventMap, TState>;
+  readonly states: Readonly<Record<string, {
+    readonly entry?: readonly Entry<TContext, EventUnion<TEventMap>>[];
+    readonly exit?: readonly Entry<TContext, EventUnion<TEventMap>>[];
+    readonly on?: Transitions<TContext, TEventMap, TState>;
+  }>>;
+}
+export type FieldsContract<TContext extends object, TEventMap extends EventMap> = { readonly [K in Extract<keyof TContext, string>]?: FieldContract<TEventMap>; } & Readonly<Record<string, FieldContract<TEventMap>>>;
+export interface Machine<TContext extends object, TEventMap extends EventMap, TState extends string = string> {
+  readonly config: Config<TContext, TEventMap, TState>;
+  /** The machine's contract with its hosts: the fields a host may write,
+   * and the event each write carries. */
+  readonly fields: FieldsContract<TContext, TEventMap>;
+  readonly initialState: State<TContext, TState>;
+  transition(state: TState | State<TContext, TState>, event: EventUnion<TEventMap>): State<TContext, TState>;
+}
+export interface Service<TContext extends object, TEventMap extends EventMap, TState extends string = string> {
+  send(event: EventUnion<TEventMap>): void;
+  /**
+   * Replace part of the context, the way a transition's assigns do: the
+   * context object is replaced, so subscribers see it. The seed uses
+   * this — it lands AFTER the entry actions, so a seed wins over an
+   * entry (the seed writes the value, the entry clears the highlight).
+   */
+  setContext(patch: Partial<TContext>): void;
+  /** Start (or restart) at an optional state, running that state's entry
+   * actions. This is how `defaultOpen`-style seeds work: the service's
+   * first state is not always the config's `initial`. */
+  start(state?: TState | State<TContext, TState>): Service<TContext, TEventMap, TState>;
+  stop(): Service<TContext, TEventMap, TState>;
+  readonly state: State<TContext, TState>;
+  readonly stopped: boolean;
+}
+/**
+ * The machine: one call, one object.
+ *
+ * The spec says what the machine IS (its context, its states, its
+ * transitions) and what it DOES (its context writes, its guards) — each
+ * bound to the event it answers, by the transition's KEY.
+ */
+export interface MachineSpec<TContext extends object, TEventMap extends EventMap, TState extends string = string> {
+  readonly id?: string;
+  /** The machine's own defaults. No prop reaches this: a machine does
+   * not know what a host is. */
+  readonly context: TContext;
+  readonly initial: NoInfer<TState>;
+  readonly on?: Transitions<TContext, TEventMap, NoInfer<TState>>;
+  readonly states: Readonly<Record<TState, {
+    readonly entry?: readonly Entry<TContext, EventUnion<TEventMap>>[];
+    readonly exit?: readonly Entry<TContext, EventUnion<TEventMap>>[];
+    readonly on?: Transitions<TContext, TEventMap, NoInfer<TState>>;
+  }>>;
+  /**
+   * The machine's contract with its hosts: the context fields a host may
+   * write, and the event each write carries.
+   *
+   * A field with an event is REPORTED: the host's write is an event, the
+   * machine decides, and the change reaches the host. A field without one
+   * is SILENT: the host's write lands in the field, and nothing reports.
+   *
+   * The machine owns this map. The element does not restate it, and a
+   * host cannot write a field the contract does not name.
+   */
+  readonly fields?: FieldsContract<TContext, TEventMap>;
+}
+/**
+ * One field of the machine's contract: how a host's write reaches it.
+ *
+ * - `event` — the write is REPORTED: the host's write is an event, the
+ *   machine decides, and the change reaches the host. The machine's
+ *   assign shapes the payload.
+ * - no `event` — the write is SILENT: it lands in the field, and nothing
+ *   reports. The framework shapes it with `parse`.
+ * - `parse` — the machine's own shaping of the field, for the silent
+ *   path. The same shaping the machine's `initial` applies to the
+ *   argument, so a host's write and the start agree.
+ */
+export interface FieldContract<TEventMap extends EventMap> {
+  readonly event?: EventUnion<TEventMap>["type"];
+  readonly parse?: (raw: unknown) => unknown;
+}
+export declare function createMachine<TContext extends object, TEventMap extends EventMap, TState extends string = string>(spec: MachineSpec<TContext, TEventMap, TState>): Machine<TContext, TEventMap, TState>;
+export declare function interpret<TContext extends object, TEventMap extends EventMap, TState extends string = string>(machine: Machine<TContext, TEventMap, TState>): Service<TContext, TEventMap, TState>;