@kyneta/machine 1.3.1 → 1.4.0

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+//#region src/machine.d.ts
 /** Dispatch a message into a running program. */
 type Dispatch<Msg> = (msg: Msg) => void;
 /** An effect is a continuation that may dispatch messages. */
@@ -15,9 +16,9 @@ type Effect<Msg> = (dispatch: Dispatch<Msg>) => void;
  *   the runtime is disposed.
  */
 type Program<Msg, Model, Fx = Effect<Msg>> = {
-    init: [Model, ...Fx[]];
-    update(msg: Msg, model: Model): [Model, ...Fx[]];
-    done?(model: Model): void;
+  init: [Model, ...Fx[]];
+  update(msg: Msg, model: Model): [Model, ...Fx[]];
+  done?(model: Model): void;
 };
 /** Dispose a running program — stops message processing and calls `done`. */
 type Disposer = () => void;
@@ -37,7 +38,8 @@ type Disposer = () => void;
  * after the current dispatch cycle completes (queue-based).
  */
 declare function runtime<Msg, Model>(program: Program<Msg, Model>, view?: (model: Model, dispatch: Dispatch<Msg>) => void): Disposer;
-
+//#endregion
+//#region src/observable.d.ts
 /**
  * A state transition event — from one model to another.
  *
@@ -45,9 +47,9 @@ declare function runtime<Msg, Model>(program: Program<Msg, Model>, view?: (model
  * transport packages re-export or alias it for their specific state types.
  */
 type StateTransition<S> = {
-    from: S;
-    to: S;
-    timestamp: number;
+  from: S;
+  to: S;
+  timestamp: number;
 };
 /**
  * Listener for state transitions.
@@ -61,40 +63,40 @@ type TransitionListener<S> = (transition: StateTransition<S>) => void;
  * matches the surface of the former `ClientStateMachine<S>`.
  */
 interface ObservableHandle<Msg, Model> {
-    /** Dispatch a message into the program. */
-    dispatch: Dispatch<Msg>;
-    /** Get the current model synchronously. */
-    getState(): Model;
-    /**
-     * Subscribe to state transitions.
-     *
-     * Transitions are delivered synchronously after each update.
-     * Returns an unsubscribe function.
-     */
-    subscribeToTransitions(listener: TransitionListener<Model>): () => void;
-    /**
-     * Wait for a specific state.
-     *
-     * Resolves immediately if the current state matches the predicate.
-     * Otherwise waits for a transition that matches.
-     */
-    waitForState(predicate: (state: Model) => boolean, options?: {
-        timeoutMs?: number;
-    }): Promise<Model>;
-    /**
-     * Wait for a specific status string on a model with a `status` discriminant.
-     *
-     * Convenience wrapper around `waitForState()`.
-     */
-    waitForStatus<S extends {
-        status: string;
-    }>(this: ObservableHandle<Msg, S>, status: S["status"], options?: {
-        timeoutMs?: number;
-    }): Promise<S>;
-    /**
-     * Dispose the program — stops dispatch and calls `program.done`.
-     */
-    dispose(): void;
+  /** Dispatch a message into the program. */
+  dispatch: Dispatch<Msg>;
+  /** Get the current model synchronously. */
+  getState(): Model;
+  /**
+   * Subscribe to state transitions.
+   *
+   * Transitions are delivered synchronously after each update.
+   * Returns an unsubscribe function.
+   */
+  subscribeToTransitions(listener: TransitionListener<Model>): () => void;
+  /**
+   * Wait for a specific state.
+   *
+   * Resolves immediately if the current state matches the predicate.
+   * Otherwise waits for a transition that matches.
+   */
+  waitForState(predicate: (state: Model) => boolean, options?: {
+    timeoutMs?: number;
+  }): Promise<Model>;
+  /**
+   * Wait for a specific status string on a model with a `status` discriminant.
+   *
+   * Convenience wrapper around `waitForState()`.
+   */
+  waitForStatus<S extends {
+    status: string;
+  }>(this: ObservableHandle<Msg, S>, status: S["status"], options?: {
+    timeoutMs?: number;
+  }): Promise<S>;
+  /**
+   * Dispose the program — stops dispatch and calls `program.done`.
+   */
+  dispose(): void;
 }
 /**
  * Run a program with data effects and state observation.
@@ -117,5 +119,6 @@ interface ObservableHandle<Msg, Model> {
  * @returns An observable handle for the running program.
  */
 declare function createObservableProgram<Msg, Model, Fx>(program: Program<Msg, Model, Fx>, executor: (effect: Fx, dispatch: Dispatch<Msg>) => void): ObservableHandle<Msg, Model>;
-
+//#endregion
 export { type Dispatch, type Disposer, type Effect, type ObservableHandle, type Program, type StateTransition, type TransitionListener, createObservableProgram, runtime };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/machine.ts","../src/observable.ts"],"mappings":";;KACY,QAAA,SAAiB,GAAA,EAAK,GAAA;;KAGtB,MAAA,SAAe,QAAA,EAAU,QAAA,CAAS,GAAA;;;;;;;AAA9C;;;;;;KAcY,OAAA,kBAAyB,MAAA,CAAO,GAAA;EAC1C,IAAA,GAAO,KAAA,KAAU,EAAA;EACjB,MAAA,CAAO,GAAA,EAAK,GAAA,EAAK,KAAA,EAAO,KAAA,IAAS,KAAA,KAAU,EAAA;EAC3C,IAAA,EAAM,KAAA,EAAO,KAAA;AAAA;;KAIH,QAAA;;;;;;;;;;;;;;;;iBAiBI,OAAA,YAAA,CACd,OAAA,EAAS,OAAA,CAAQ,GAAA,EAAK,KAAA,GACtB,IAAA,IAAQ,KAAA,EAAO,KAAA,EAAO,QAAA,EAAU,QAAA,CAAS,GAAA,aACxC,QAAA;;;AA5CH;;;;;;AAAA,KC8BY,eAAA;EACV,IAAA,EAAM,CAAA;EACN,EAAA,EAAI,CAAA;EACJ,SAAA;AAAA;;;;KAMU,kBAAA,OAAyB,UAAA,EAAY,eAAA,CAAgB,CAAA;;;;;ADtBjE;;;UCmCiB,gBAAA;EDnCoB;ECqCnC,QAAA,EAAU,QAAA,CAAS,GAAA;EDpCF;ECuCjB,QAAA,IAAY,KAAA;EDtCY;;;;;;EC8CxB,sBAAA,CAAuB,QAAA,EAAU,kBAAA,CAAmB,KAAA;EDhD7B;;;;;;ECwDvB,YAAA,CACE,SAAA,GAAY,KAAA,EAAO,KAAA,cACnB,OAAA;IAAY,SAAA;EAAA,IACX,OAAA,CAAQ,KAAA;EDzDJ;;;;;ECgEP,aAAA;IAA0B,MAAA;EAAA,GACxB,IAAA,EAAM,gBAAA,CAAiB,GAAA,EAAK,CAAA,GAC5B,MAAA,EAAQ,CAAA,YACR,OAAA;IAAY,SAAA;EAAA,IACX,OAAA,CAAQ,CAAA;ED/DD;;;ECoEV,OAAA;AAAA;ADnDF;;;;;;;;;;;;;;;;;;;;AAAA,iBC8EgB,uBAAA,gBAAA,CACd,OAAA,EAAS,OAAA,CAAQ,GAAA,EAAK,KAAA,EAAO,EAAA,GAC7B,QAAA,GAAW,MAAA,EAAQ,EAAA,EAAI,QAAA,EAAU,QAAA,CAAS,GAAA,aACzC,gBAAA,CAAiB,GAAA,EAAK,KAAA"}

package/dist/index.js

@@ -1,143 +1,158 @@
-// src/machine.ts
+//#region src/machine.ts
+/**
+* Run a program whose effects are `Effect<Msg>` closures.
+*
+* The runtime:
+* 1. Extracts `[model, ...effects]` from `program.init`.
+* 2. Executes each initial effect with `dispatch`.
+* 3. Calls `view(model, dispatch)` if provided.
+* 4. On `dispatch(msg)`: calls `update(msg, state)`, updates state,
+*    executes effects, calls `view`.
+* 5. Returns a `Disposer` that stops dispatch and calls `program.done`.
+*
+* Effects are executed synchronously in order. An effect may call
+* `dispatch` re-entrantly — the runtime processes re-entrant messages
+* after the current dispatch cycle completes (queue-based).
+*/
 function runtime(program, view) {
-  let state;
-  let isRunning = true;
-  const pending = [];
-  let isDispatching = false;
-  function dispatch(msg) {
-    if (!isRunning) return;
-    pending.push(msg);
-    if (isDispatching) return;
-    isDispatching = true;
-    try {
-      while (pending.length > 0) {
-        const next = pending.shift();
-        const [newModel, ...effects] = program.update(next, state);
-        state = newModel;
-        for (const effect of effects) {
-          effect(dispatch);
-        }
-        if (view) view(state, dispatch);
-      }
-    } finally {
-      isDispatching = false;
-    }
-  }
-  const [initialModel, ...initialEffects] = program.init;
-  state = initialModel;
-  for (const effect of initialEffects) {
-    effect(dispatch);
-  }
-  if (view) view(state, dispatch);
-  return () => {
-    if (!isRunning) return;
-    isRunning = false;
-    program.done?.(state);
-  };
+	let state;
+	let isRunning = true;
+	const pending = [];
+	let isDispatching = false;
+	function dispatch(msg) {
+		if (!isRunning) return;
+		pending.push(msg);
+		if (isDispatching) return;
+		isDispatching = true;
+		try {
+			while (pending.length > 0) {
+				const next = pending.shift();
+				const [newModel, ...effects] = program.update(next, state);
+				state = newModel;
+				for (const effect of effects) effect(dispatch);
+				if (view) view(state, dispatch);
+			}
+		} finally {
+			isDispatching = false;
+		}
+	}
+	const [initialModel, ...initialEffects] = program.init;
+	state = initialModel;
+	for (const effect of initialEffects) effect(dispatch);
+	if (view) view(state, dispatch);
+	return () => {
+		if (!isRunning) return;
+		isRunning = false;
+		program.done?.(state);
+	};
 }
-
-// src/observable.ts
+//#endregion
+//#region src/observable.ts
+/**
+* Run a program with data effects and state observation.
+*
+* Like `runtime()`, but instead of executing closure effects directly,
+* it delegates to a custom `executor` for each data effect. This enables
+* programs whose effects are inspectable data types (not opaque closures).
+*
+* The runtime:
+* 1. Extracts `[model, ...effects]` from `program.init`.
+* 2. Executes each initial effect via `executor(effect, dispatch)`.
+* 3. On `dispatch(msg)`: calls `update(msg, state)`, updates state,
+*    notifies transition listeners, executes effects.
+* 4. Re-entrant dispatch (effect calls dispatch) is queued and processed
+*    after the current dispatch cycle completes.
+* 5. `dispose()` stops dispatch and calls `program.done`.
+*
+* @param program - The program algebra: init, update, done.
+* @param executor - Interprets data effects as I/O.
+* @returns An observable handle for the running program.
+*/
 function createObservableProgram(program, executor) {
-  let state;
-  let isRunning = true;
-  const pending = [];
-  let isDispatching = false;
-  const listeners = /* @__PURE__ */ new Set();
-  function notifyTransition(from, to) {
-    if (from === to) return;
-    const transition = {
-      from,
-      to,
-      timestamp: Date.now()
-    };
-    for (const listener of listeners) {
-      try {
-        listener(transition);
-      } catch {
-      }
-    }
-  }
-  function dispatch(msg) {
-    if (!isRunning) return;
-    pending.push(msg);
-    if (isDispatching) return;
-    isDispatching = true;
-    try {
-      while (pending.length > 0) {
-        const next = pending.shift();
-        const prev = state;
-        const [newModel, ...effects] = program.update(next, state);
-        state = newModel;
-        notifyTransition(prev, state);
-        for (const effect of effects) {
-          executor(effect, dispatch);
-        }
-      }
-    } finally {
-      isDispatching = false;
-    }
-  }
-  function getState() {
-    return state;
-  }
-  function subscribeToTransitions(listener) {
-    listeners.add(listener);
-    return () => {
-      listeners.delete(listener);
-    };
-  }
-  function waitForState(predicate, options) {
-    if (predicate(state)) {
-      return Promise.resolve(state);
-    }
-    return new Promise((resolve, reject) => {
-      let timeoutId;
-      const unsubscribe = subscribeToTransitions((transition) => {
-        if (predicate(transition.to)) {
-          cleanup();
-          resolve(transition.to);
-        }
-      });
-      const cleanup = () => {
-        unsubscribe();
-        if (timeoutId !== void 0) {
-          clearTimeout(timeoutId);
-        }
-      };
-      if (options?.timeoutMs !== void 0) {
-        timeoutId = setTimeout(() => {
-          cleanup();
-          reject(
-            new Error(`Timeout waiting for state after ${options.timeoutMs}ms`)
-          );
-        }, options.timeoutMs);
-      }
-    });
-  }
-  function waitForStatus(status, options) {
-    return this.waitForState((s) => s.status === status, options);
-  }
-  function dispose() {
-    if (!isRunning) return;
-    isRunning = false;
-    program.done?.(state);
-  }
-  const [initialModel, ...initialEffects] = program.init;
-  state = initialModel;
-  for (const effect of initialEffects) {
-    executor(effect, dispatch);
-  }
-  return {
-    dispatch,
-    getState,
-    subscribeToTransitions,
-    waitForState,
-    waitForStatus,
-    dispose
-  };
+	let state;
+	let isRunning = true;
+	const pending = [];
+	let isDispatching = false;
+	const listeners = /* @__PURE__ */ new Set();
+	function notifyTransition(from, to) {
+		if (from === to) return;
+		const transition = {
+			from,
+			to,
+			timestamp: Date.now()
+		};
+		for (const listener of listeners) try {
+			listener(transition);
+		} catch {}
+	}
+	function dispatch(msg) {
+		if (!isRunning) return;
+		pending.push(msg);
+		if (isDispatching) return;
+		isDispatching = true;
+		try {
+			while (pending.length > 0) {
+				const next = pending.shift();
+				const prev = state;
+				const [newModel, ...effects] = program.update(next, state);
+				state = newModel;
+				notifyTransition(prev, state);
+				for (const effect of effects) executor(effect, dispatch);
+			}
+		} finally {
+			isDispatching = false;
+		}
+	}
+	function getState() {
+		return state;
+	}
+	function subscribeToTransitions(listener) {
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+		};
+	}
+	function waitForState(predicate, options) {
+		if (predicate(state)) return Promise.resolve(state);
+		return new Promise((resolve, reject) => {
+			let timeoutId;
+			const unsubscribe = subscribeToTransitions((transition) => {
+				if (predicate(transition.to)) {
+					cleanup();
+					resolve(transition.to);
+				}
+			});
+			const cleanup = () => {
+				unsubscribe();
+				if (timeoutId !== void 0) clearTimeout(timeoutId);
+			};
+			if (options?.timeoutMs !== void 0) timeoutId = setTimeout(() => {
+				cleanup();
+				reject(/* @__PURE__ */ new Error(`Timeout waiting for state after ${options.timeoutMs}ms`));
+			}, options.timeoutMs);
+		});
+	}
+	function waitForStatus(status, options) {
+		return this.waitForState((s) => s.status === status, options);
+	}
+	function dispose() {
+		if (!isRunning) return;
+		isRunning = false;
+		program.done?.(state);
+	}
+	const [initialModel, ...initialEffects] = program.init;
+	state = initialModel;
+	for (const effect of initialEffects) executor(effect, dispatch);
+	return {
+		dispatch,
+		getState,
+		subscribeToTransitions,
+		waitForState,
+		waitForStatus,
+		dispose
+	};
 }
-export {
-  createObservableProgram,
-  runtime
-};
+//#endregion
+export { createObservableProgram, runtime };
+
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/machine.ts","../src/observable.ts"],"sourcesContent":["/** Dispatch a message into a running program. */\nexport type Dispatch<Msg> = (msg: Msg) => void\n\n/** An effect is a continuation that may dispatch messages. */\nexport type Effect<Msg> = (dispatch: Dispatch<Msg>) => void\n\n/**\n * A Mealy machine — pure state transitions with effect outputs.\n *\n * `Fx` defaults to `Effect<Msg>` (closure effects) but can be any\n * data type for programs with custom effect executors.\n *\n * - `init`: initial state and zero or more effects to execute at startup.\n * - `update`: pure transition — given a message and the current state,\n *   return the new state and zero or more effects.\n * - `done`: optional teardown hook, called with the final state when\n *   the runtime is disposed.\n */\nexport type Program<Msg, Model, Fx = Effect<Msg>> = {\n  init: [Model, ...Fx[]]\n  update(msg: Msg, model: Model): [Model, ...Fx[]]\n  done?(model: Model): void\n}\n\n/** Dispose a running program — stops message processing and calls `done`. */\nexport type Disposer = () => void\n\n/**\n * Run a program whose effects are `Effect<Msg>` closures.\n *\n * The runtime:\n * 1. Extracts `[model, ...effects]` from `program.init`.\n * 2. Executes each initial effect with `dispatch`.\n * 3. Calls `view(model, dispatch)` if provided.\n * 4. On `dispatch(msg)`: calls `update(msg, state)`, updates state,\n *    executes effects, calls `view`.\n * 5. Returns a `Disposer` that stops dispatch and calls `program.done`.\n *\n * Effects are executed synchronously in order. An effect may call\n * `dispatch` re-entrantly — the runtime processes re-entrant messages\n * after the current dispatch cycle completes (queue-based).\n */\nexport function runtime<Msg, Model>(\n  program: Program<Msg, Model>,\n  view?: (model: Model, dispatch: Dispatch<Msg>) => void,\n): Disposer {\n  let state: Model\n  let isRunning = true\n  const pending: Msg[] = []\n  let isDispatching = false\n\n  function dispatch(msg: Msg): void {\n    if (!isRunning) return\n\n    pending.push(msg)\n    if (isDispatching) return\n\n    isDispatching = true\n    try {\n      while (pending.length > 0) {\n        const next = pending.shift()!\n        const [newModel, ...effects] = program.update(next, state)\n        state = newModel\n        for (const effect of effects) {\n          effect(dispatch)\n        }\n        if (view) view(state, dispatch)\n      }\n    } finally {\n      isDispatching = false\n    }\n  }\n\n  // Initialize\n  const [initialModel, ...initialEffects] = program.init\n  state = initialModel\n  for (const effect of initialEffects) {\n    effect(dispatch)\n  }\n  if (view) view(state, dispatch)\n\n  // Return disposer\n  return () => {\n    if (!isRunning) return\n    isRunning = false\n    program.done?.(state)\n  }\n}\n","// observable — data-effect runtime with state observation.\n//\n// createObservableProgram() is the data-effect counterpart to runtime().\n// Where runtime() executes closure effects (Effect<Msg>), this function\n// accepts a custom executor for data effects (Fx). It also provides\n// state observation: subscribeToTransitions, waitForState, waitForStatus.\n//\n// This subsumes ClientStateMachine's observation API and the peer program's\n// hand-rolled dispatch loop. Transition delivery is synchronous — the\n// listener fires after each update. The microtask-batched delivery from\n// ClientStateMachine is unnecessary complexity that no consumer depends on.\n\nimport type { Dispatch, Program } from \"./machine.js\"\n\n// ---------------------------------------------------------------------------\n// Ambient declarations for timer APIs (not in lib: [\"ESNext\"])\n// ---------------------------------------------------------------------------\n\ndeclare function setTimeout(callback: () => void, ms: number): unknown\ndeclare function clearTimeout(id: unknown): void\n\n// ---------------------------------------------------------------------------\n// Observation types\n// ---------------------------------------------------------------------------\n\n/**\n * A state transition event — from one model to another.\n *\n * Generic over the model type. This is the machine-level primitive;\n * transport packages re-export or alias it for their specific state types.\n */\nexport type StateTransition<S> = {\n  from: S\n  to: S\n  timestamp: number\n}\n\n/**\n * Listener for state transitions.\n */\nexport type TransitionListener<S> = (transition: StateTransition<S>) => void\n\n// ---------------------------------------------------------------------------\n// ObservableHandle\n// ---------------------------------------------------------------------------\n\n/**\n * Handle for a running observable program.\n *\n * Provides dispatch, state access, transition observation, and disposal.\n * The observation API (`subscribeToTransitions`, `waitForState`, `waitForStatus`)\n * matches the surface of the former `ClientStateMachine<S>`.\n */\nexport interface ObservableHandle<Msg, Model> {\n  /** Dispatch a message into the program. */\n  dispatch: Dispatch<Msg>\n\n  /** Get the current model synchronously. */\n  getState(): Model\n\n  /**\n   * Subscribe to state transitions.\n   *\n   * Transitions are delivered synchronously after each update.\n   * Returns an unsubscribe function.\n   */\n  subscribeToTransitions(listener: TransitionListener<Model>): () => void\n\n  /**\n   * Wait for a specific state.\n   *\n   * Resolves immediately if the current state matches the predicate.\n   * Otherwise waits for a transition that matches.\n   */\n  waitForState(\n    predicate: (state: Model) => boolean,\n    options?: { timeoutMs?: number },\n  ): Promise<Model>\n\n  /**\n   * Wait for a specific status string on a model with a `status` discriminant.\n   *\n   * Convenience wrapper around `waitForState()`.\n   */\n  waitForStatus<S extends { status: string }>(\n    this: ObservableHandle<Msg, S>,\n    status: S[\"status\"],\n    options?: { timeoutMs?: number },\n  ): Promise<S>\n\n  /**\n   * Dispose the program — stops dispatch and calls `program.done`.\n   */\n  dispose(): void\n}\n\n// ---------------------------------------------------------------------------\n// createObservableProgram\n// ---------------------------------------------------------------------------\n\n/**\n * Run a program with data effects and state observation.\n *\n * Like `runtime()`, but instead of executing closure effects directly,\n * it delegates to a custom `executor` for each data effect. This enables\n * programs whose effects are inspectable data types (not opaque closures).\n *\n * The runtime:\n * 1. Extracts `[model, ...effects]` from `program.init`.\n * 2. Executes each initial effect via `executor(effect, dispatch)`.\n * 3. On `dispatch(msg)`: calls `update(msg, state)`, updates state,\n *    notifies transition listeners, executes effects.\n * 4. Re-entrant dispatch (effect calls dispatch) is queued and processed\n *    after the current dispatch cycle completes.\n * 5. `dispose()` stops dispatch and calls `program.done`.\n *\n * @param program - The program algebra: init, update, done.\n * @param executor - Interprets data effects as I/O.\n * @returns An observable handle for the running program.\n */\nexport function createObservableProgram<Msg, Model, Fx>(\n  program: Program<Msg, Model, Fx>,\n  executor: (effect: Fx, dispatch: Dispatch<Msg>) => void,\n): ObservableHandle<Msg, Model> {\n  let state: Model\n  let isRunning = true\n  const pending: Msg[] = []\n  let isDispatching = false\n  const listeners = new Set<TransitionListener<Model>>()\n\n  // --------------------------------------------------------------------------\n  // Transition notification\n  // --------------------------------------------------------------------------\n\n  function notifyTransition(from: Model, to: Model): void {\n    if (from === to) return\n\n    const transition: StateTransition<Model> = {\n      from,\n      to,\n      timestamp: Date.now(),\n    }\n\n    for (const listener of listeners) {\n      try {\n        listener(transition)\n      } catch {\n        // Swallow listener errors — observers must not break dispatch.\n      }\n    }\n  }\n\n  // --------------------------------------------------------------------------\n  // Dispatch\n  // --------------------------------------------------------------------------\n\n  function dispatch(msg: Msg): void {\n    if (!isRunning) return\n\n    pending.push(msg)\n    if (isDispatching) return\n\n    isDispatching = true\n    try {\n      while (pending.length > 0) {\n        const next = pending.shift()!\n        const prev = state\n        const [newModel, ...effects] = program.update(next, state)\n        state = newModel\n        notifyTransition(prev, state)\n        for (const effect of effects) {\n          executor(effect, dispatch)\n        }\n      }\n    } finally {\n      isDispatching = false\n    }\n  }\n\n  // --------------------------------------------------------------------------\n  // Observation\n  // --------------------------------------------------------------------------\n\n  function getState(): Model {\n    return state\n  }\n\n  function subscribeToTransitions(\n    listener: TransitionListener<Model>,\n  ): () => void {\n    listeners.add(listener)\n    return () => {\n      listeners.delete(listener)\n    }\n  }\n\n  function waitForState(\n    predicate: (state: Model) => boolean,\n    options?: { timeoutMs?: number },\n  ): Promise<Model> {\n    // Resolve immediately if already matching\n    if (predicate(state)) {\n      return Promise.resolve(state)\n    }\n\n    return new Promise((resolve, reject) => {\n      let timeoutId: unknown\n\n      const unsubscribe = subscribeToTransitions(transition => {\n        if (predicate(transition.to)) {\n          cleanup()\n          resolve(transition.to)\n        }\n      })\n\n      const cleanup = () => {\n        unsubscribe()\n        if (timeoutId !== undefined) {\n          clearTimeout(timeoutId)\n        }\n      }\n\n      if (options?.timeoutMs !== undefined) {\n        timeoutId = setTimeout(() => {\n          cleanup()\n          reject(\n            new Error(`Timeout waiting for state after ${options.timeoutMs}ms`),\n          )\n        }, options.timeoutMs)\n      }\n    })\n  }\n\n  function waitForStatus<S extends { status: string }>(\n    this: ObservableHandle<Msg, S>,\n    status: S[\"status\"],\n    options?: { timeoutMs?: number },\n  ): Promise<S> {\n    return this.waitForState((s: S) => s.status === status, options)\n  }\n\n  function dispose(): void {\n    if (!isRunning) return\n    isRunning = false\n    program.done?.(state)\n  }\n\n  // --------------------------------------------------------------------------\n  // Initialize\n  // --------------------------------------------------------------------------\n\n  const [initialModel, ...initialEffects] = program.init\n  state = initialModel\n  for (const effect of initialEffects) {\n    executor(effect, dispatch)\n  }\n\n  // --------------------------------------------------------------------------\n  // Return handle\n  // --------------------------------------------------------------------------\n\n  return {\n    dispatch,\n    getState,\n    subscribeToTransitions,\n    waitForState,\n    waitForStatus,\n    dispose,\n  }\n}\n"],"mappings":";AA0CO,SAAS,QACd,SACA,MACU;AACV,MAAI;AACJ,MAAI,YAAY;AAChB,QAAM,UAAiB,CAAC;AACxB,MAAI,gBAAgB;AAEpB,WAAS,SAAS,KAAgB;AAChC,QAAI,CAAC,UAAW;AAEhB,YAAQ,KAAK,GAAG;AAChB,QAAI,cAAe;AAEnB,oBAAgB;AAChB,QAAI;AACF,aAAO,QAAQ,SAAS,GAAG;AACzB,cAAM,OAAO,QAAQ,MAAM;AAC3B,cAAM,CAAC,UAAU,GAAG,OAAO,IAAI,QAAQ,OAAO,MAAM,KAAK;AACzD,gBAAQ;AACR,mBAAW,UAAU,SAAS;AAC5B,iBAAO,QAAQ;AAAA,QACjB;AACA,YAAI,KAAM,MAAK,OAAO,QAAQ;AAAA,MAChC;AAAA,IACF,UAAE;AACA,sBAAgB;AAAA,IAClB;AAAA,EACF;AAGA,QAAM,CAAC,cAAc,GAAG,cAAc,IAAI,QAAQ;AAClD,UAAQ;AACR,aAAW,UAAU,gBAAgB;AACnC,WAAO,QAAQ;AAAA,EACjB;AACA,MAAI,KAAM,MAAK,OAAO,QAAQ;AAG9B,SAAO,MAAM;AACX,QAAI,CAAC,UAAW;AAChB,gBAAY;AACZ,YAAQ,OAAO,KAAK;AAAA,EACtB;AACF;;;ACiCO,SAAS,wBACd,SACA,UAC8B;AAC9B,MAAI;AACJ,MAAI,YAAY;AAChB,QAAM,UAAiB,CAAC;AACxB,MAAI,gBAAgB;AACpB,QAAM,YAAY,oBAAI,IAA+B;AAMrD,WAAS,iBAAiB,MAAa,IAAiB;AACtD,QAAI,SAAS,GAAI;AAEjB,UAAM,aAAqC;AAAA,MACzC;AAAA,MACA;AAAA,MACA,WAAW,KAAK,IAAI;AAAA,IACtB;AAEA,eAAW,YAAY,WAAW;AAChC,UAAI;AACF,iBAAS,UAAU;AAAA,MACrB,QAAQ;AAAA,MAER;AAAA,IACF;AAAA,EACF;AAMA,WAAS,SAAS,KAAgB;AAChC,QAAI,CAAC,UAAW;AAEhB,YAAQ,KAAK,GAAG;AAChB,QAAI,cAAe;AAEnB,oBAAgB;AAChB,QAAI;AACF,aAAO,QAAQ,SAAS,GAAG;AACzB,cAAM,OAAO,QAAQ,MAAM;AAC3B,cAAM,OAAO;AACb,cAAM,CAAC,UAAU,GAAG,OAAO,IAAI,QAAQ,OAAO,MAAM,KAAK;AACzD,gBAAQ;AACR,yBAAiB,MAAM,KAAK;AAC5B,mBAAW,UAAU,SAAS;AAC5B,mBAAS,QAAQ,QAAQ;AAAA,QAC3B;AAAA,MACF;AAAA,IACF,UAAE;AACA,sBAAgB;AAAA,IAClB;AAAA,EACF;AAMA,WAAS,WAAkB;AACzB,WAAO;AAAA,EACT;AAEA,WAAS,uBACP,UACY;AACZ,cAAU,IAAI,QAAQ;AACtB,WAAO,MAAM;AACX,gBAAU,OAAO,QAAQ;AAAA,IAC3B;AAAA,EACF;AAEA,WAAS,aACP,WACA,SACgB;AAEhB,QAAI,UAAU,KAAK,GAAG;AACpB,aAAO,QAAQ,QAAQ,KAAK;AAAA,IAC9B;AAEA,WAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAI;AAEJ,YAAM,cAAc,uBAAuB,gBAAc;AACvD,YAAI,UAAU,WAAW,EAAE,GAAG;AAC5B,kBAAQ;AACR,kBAAQ,WAAW,EAAE;AAAA,QACvB;AAAA,MACF,CAAC;AAED,YAAM,UAAU,MAAM;AACpB,oBAAY;AACZ,YAAI,cAAc,QAAW;AAC3B,uBAAa,SAAS;AAAA,QACxB;AAAA,MACF;AAEA,UAAI,SAAS,cAAc,QAAW;AACpC,oBAAY,WAAW,MAAM;AAC3B,kBAAQ;AACR;AAAA,YACE,IAAI,MAAM,mCAAmC,QAAQ,SAAS,IAAI;AAAA,UACpE;AAAA,QACF,GAAG,QAAQ,SAAS;AAAA,MACtB;AAAA,IACF,CAAC;AAAA,EACH;AAEA,WAAS,cAEP,QACA,SACY;AACZ,WAAO,KAAK,aAAa,CAAC,MAAS,EAAE,WAAW,QAAQ,OAAO;AAAA,EACjE;AAEA,WAAS,UAAgB;AACvB,QAAI,CAAC,UAAW;AAChB,gBAAY;AACZ,YAAQ,OAAO,KAAK;AAAA,EACtB;AAMA,QAAM,CAAC,cAAc,GAAG,cAAc,IAAI,QAAQ;AAClD,UAAQ;AACR,aAAW,UAAU,gBAAgB;AACnC,aAAS,QAAQ,QAAQ;AAAA,EAC3B;AAMA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;","names":[]}
+{"version":3,"file":"index.js","names":[],"sources":["../src/machine.ts","../src/observable.ts"],"sourcesContent":["/** Dispatch a message into a running program. */\nexport type Dispatch<Msg> = (msg: Msg) => void\n\n/** An effect is a continuation that may dispatch messages. */\nexport type Effect<Msg> = (dispatch: Dispatch<Msg>) => void\n\n/**\n * A Mealy machine — pure state transitions with effect outputs.\n *\n * `Fx` defaults to `Effect<Msg>` (closure effects) but can be any\n * data type for programs with custom effect executors.\n *\n * - `init`: initial state and zero or more effects to execute at startup.\n * - `update`: pure transition — given a message and the current state,\n *   return the new state and zero or more effects.\n * - `done`: optional teardown hook, called with the final state when\n *   the runtime is disposed.\n */\nexport type Program<Msg, Model, Fx = Effect<Msg>> = {\n  init: [Model, ...Fx[]]\n  update(msg: Msg, model: Model): [Model, ...Fx[]]\n  done?(model: Model): void\n}\n\n/** Dispose a running program — stops message processing and calls `done`. */\nexport type Disposer = () => void\n\n/**\n * Run a program whose effects are `Effect<Msg>` closures.\n *\n * The runtime:\n * 1. Extracts `[model, ...effects]` from `program.init`.\n * 2. Executes each initial effect with `dispatch`.\n * 3. Calls `view(model, dispatch)` if provided.\n * 4. On `dispatch(msg)`: calls `update(msg, state)`, updates state,\n *    executes effects, calls `view`.\n * 5. Returns a `Disposer` that stops dispatch and calls `program.done`.\n *\n * Effects are executed synchronously in order. An effect may call\n * `dispatch` re-entrantly — the runtime processes re-entrant messages\n * after the current dispatch cycle completes (queue-based).\n */\nexport function runtime<Msg, Model>(\n  program: Program<Msg, Model>,\n  view?: (model: Model, dispatch: Dispatch<Msg>) => void,\n): Disposer {\n  let state: Model\n  let isRunning = true\n  const pending: Msg[] = []\n  let isDispatching = false\n\n  function dispatch(msg: Msg): void {\n    if (!isRunning) return\n\n    pending.push(msg)\n    if (isDispatching) return\n\n    isDispatching = true\n    try {\n      while (pending.length > 0) {\n        const next = pending.shift()!\n        const [newModel, ...effects] = program.update(next, state)\n        state = newModel\n        for (const effect of effects) {\n          effect(dispatch)\n        }\n        if (view) view(state, dispatch)\n      }\n    } finally {\n      isDispatching = false\n    }\n  }\n\n  // Initialize\n  const [initialModel, ...initialEffects] = program.init\n  state = initialModel\n  for (const effect of initialEffects) {\n    effect(dispatch)\n  }\n  if (view) view(state, dispatch)\n\n  // Return disposer\n  return () => {\n    if (!isRunning) return\n    isRunning = false\n    program.done?.(state)\n  }\n}\n","// observable — data-effect runtime with state observation.\n//\n// createObservableProgram() is the data-effect counterpart to runtime().\n// Where runtime() executes closure effects (Effect<Msg>), this function\n// accepts a custom executor for data effects (Fx). It also provides\n// state observation: subscribeToTransitions, waitForState, waitForStatus.\n//\n// This subsumes ClientStateMachine's observation API and the peer program's\n// hand-rolled dispatch loop. Transition delivery is synchronous — the\n// listener fires after each update. The microtask-batched delivery from\n// ClientStateMachine is unnecessary complexity that no consumer depends on.\n\nimport type { Dispatch, Program } from \"./machine.js\"\n\n// ---------------------------------------------------------------------------\n// Ambient declarations for timer APIs (not in lib: [\"ESNext\"])\n// ---------------------------------------------------------------------------\n\ndeclare function setTimeout(callback: () => void, ms: number): unknown\ndeclare function clearTimeout(id: unknown): void\n\n// ---------------------------------------------------------------------------\n// Observation types\n// ---------------------------------------------------------------------------\n\n/**\n * A state transition event — from one model to another.\n *\n * Generic over the model type. This is the machine-level primitive;\n * transport packages re-export or alias it for their specific state types.\n */\nexport type StateTransition<S> = {\n  from: S\n  to: S\n  timestamp: number\n}\n\n/**\n * Listener for state transitions.\n */\nexport type TransitionListener<S> = (transition: StateTransition<S>) => void\n\n// ---------------------------------------------------------------------------\n// ObservableHandle\n// ---------------------------------------------------------------------------\n\n/**\n * Handle for a running observable program.\n *\n * Provides dispatch, state access, transition observation, and disposal.\n * The observation API (`subscribeToTransitions`, `waitForState`, `waitForStatus`)\n * matches the surface of the former `ClientStateMachine<S>`.\n */\nexport interface ObservableHandle<Msg, Model> {\n  /** Dispatch a message into the program. */\n  dispatch: Dispatch<Msg>\n\n  /** Get the current model synchronously. */\n  getState(): Model\n\n  /**\n   * Subscribe to state transitions.\n   *\n   * Transitions are delivered synchronously after each update.\n   * Returns an unsubscribe function.\n   */\n  subscribeToTransitions(listener: TransitionListener<Model>): () => void\n\n  /**\n   * Wait for a specific state.\n   *\n   * Resolves immediately if the current state matches the predicate.\n   * Otherwise waits for a transition that matches.\n   */\n  waitForState(\n    predicate: (state: Model) => boolean,\n    options?: { timeoutMs?: number },\n  ): Promise<Model>\n\n  /**\n   * Wait for a specific status string on a model with a `status` discriminant.\n   *\n   * Convenience wrapper around `waitForState()`.\n   */\n  waitForStatus<S extends { status: string }>(\n    this: ObservableHandle<Msg, S>,\n    status: S[\"status\"],\n    options?: { timeoutMs?: number },\n  ): Promise<S>\n\n  /**\n   * Dispose the program — stops dispatch and calls `program.done`.\n   */\n  dispose(): void\n}\n\n// ---------------------------------------------------------------------------\n// createObservableProgram\n// ---------------------------------------------------------------------------\n\n/**\n * Run a program with data effects and state observation.\n *\n * Like `runtime()`, but instead of executing closure effects directly,\n * it delegates to a custom `executor` for each data effect. This enables\n * programs whose effects are inspectable data types (not opaque closures).\n *\n * The runtime:\n * 1. Extracts `[model, ...effects]` from `program.init`.\n * 2. Executes each initial effect via `executor(effect, dispatch)`.\n * 3. On `dispatch(msg)`: calls `update(msg, state)`, updates state,\n *    notifies transition listeners, executes effects.\n * 4. Re-entrant dispatch (effect calls dispatch) is queued and processed\n *    after the current dispatch cycle completes.\n * 5. `dispose()` stops dispatch and calls `program.done`.\n *\n * @param program - The program algebra: init, update, done.\n * @param executor - Interprets data effects as I/O.\n * @returns An observable handle for the running program.\n */\nexport function createObservableProgram<Msg, Model, Fx>(\n  program: Program<Msg, Model, Fx>,\n  executor: (effect: Fx, dispatch: Dispatch<Msg>) => void,\n): ObservableHandle<Msg, Model> {\n  let state: Model\n  let isRunning = true\n  const pending: Msg[] = []\n  let isDispatching = false\n  const listeners = new Set<TransitionListener<Model>>()\n\n  // --------------------------------------------------------------------------\n  // Transition notification\n  // --------------------------------------------------------------------------\n\n  function notifyTransition(from: Model, to: Model): void {\n    if (from === to) return\n\n    const transition: StateTransition<Model> = {\n      from,\n      to,\n      timestamp: Date.now(),\n    }\n\n    for (const listener of listeners) {\n      try {\n        listener(transition)\n      } catch {\n        // Swallow listener errors — observers must not break dispatch.\n      }\n    }\n  }\n\n  // --------------------------------------------------------------------------\n  // Dispatch\n  // --------------------------------------------------------------------------\n\n  function dispatch(msg: Msg): void {\n    if (!isRunning) return\n\n    pending.push(msg)\n    if (isDispatching) return\n\n    isDispatching = true\n    try {\n      while (pending.length > 0) {\n        const next = pending.shift()!\n        const prev = state\n        const [newModel, ...effects] = program.update(next, state)\n        state = newModel\n        notifyTransition(prev, state)\n        for (const effect of effects) {\n          executor(effect, dispatch)\n        }\n      }\n    } finally {\n      isDispatching = false\n    }\n  }\n\n  // --------------------------------------------------------------------------\n  // Observation\n  // --------------------------------------------------------------------------\n\n  function getState(): Model {\n    return state\n  }\n\n  function subscribeToTransitions(\n    listener: TransitionListener<Model>,\n  ): () => void {\n    listeners.add(listener)\n    return () => {\n      listeners.delete(listener)\n    }\n  }\n\n  function waitForState(\n    predicate: (state: Model) => boolean,\n    options?: { timeoutMs?: number },\n  ): Promise<Model> {\n    // Resolve immediately if already matching\n    if (predicate(state)) {\n      return Promise.resolve(state)\n    }\n\n    return new Promise((resolve, reject) => {\n      let timeoutId: unknown\n\n      const unsubscribe = subscribeToTransitions(transition => {\n        if (predicate(transition.to)) {\n          cleanup()\n          resolve(transition.to)\n        }\n      })\n\n      const cleanup = () => {\n        unsubscribe()\n        if (timeoutId !== undefined) {\n          clearTimeout(timeoutId)\n        }\n      }\n\n      if (options?.timeoutMs !== undefined) {\n        timeoutId = setTimeout(() => {\n          cleanup()\n          reject(\n            new Error(`Timeout waiting for state after ${options.timeoutMs}ms`),\n          )\n        }, options.timeoutMs)\n      }\n    })\n  }\n\n  function waitForStatus<S extends { status: string }>(\n    this: ObservableHandle<Msg, S>,\n    status: S[\"status\"],\n    options?: { timeoutMs?: number },\n  ): Promise<S> {\n    return this.waitForState((s: S) => s.status === status, options)\n  }\n\n  function dispose(): void {\n    if (!isRunning) return\n    isRunning = false\n    program.done?.(state)\n  }\n\n  // --------------------------------------------------------------------------\n  // Initialize\n  // --------------------------------------------------------------------------\n\n  const [initialModel, ...initialEffects] = program.init\n  state = initialModel\n  for (const effect of initialEffects) {\n    executor(effect, dispatch)\n  }\n\n  // --------------------------------------------------------------------------\n  // Return handle\n  // --------------------------------------------------------------------------\n\n  return {\n    dispatch,\n    getState,\n    subscribeToTransitions,\n    waitForState,\n    waitForStatus,\n    dispose,\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA0CA,SAAgB,QACd,SACA,MACU;CACV,IAAI;CACJ,IAAI,YAAY;CAChB,MAAM,UAAiB,EAAE;CACzB,IAAI,gBAAgB;CAEpB,SAAS,SAAS,KAAgB;AAChC,MAAI,CAAC,UAAW;AAEhB,UAAQ,KAAK,IAAI;AACjB,MAAI,cAAe;AAEnB,kBAAgB;AAChB,MAAI;AACF,UAAO,QAAQ,SAAS,GAAG;IACzB,MAAM,OAAO,QAAQ,OAAO;IAC5B,MAAM,CAAC,UAAU,GAAG,WAAW,QAAQ,OAAO,MAAM,MAAM;AAC1D,YAAQ;AACR,SAAK,MAAM,UAAU,QACnB,QAAO,SAAS;AAElB,QAAI,KAAM,MAAK,OAAO,SAAS;;YAEzB;AACR,mBAAgB;;;CAKpB,MAAM,CAAC,cAAc,GAAG,kBAAkB,QAAQ;AAClD,SAAQ;AACR,MAAK,MAAM,UAAU,eACnB,QAAO,SAAS;AAElB,KAAI,KAAM,MAAK,OAAO,SAAS;AAG/B,cAAa;AACX,MAAI,CAAC,UAAW;AAChB,cAAY;AACZ,UAAQ,OAAO,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;ACmCzB,SAAgB,wBACd,SACA,UAC8B;CAC9B,IAAI;CACJ,IAAI,YAAY;CAChB,MAAM,UAAiB,EAAE;CACzB,IAAI,gBAAgB;CACpB,MAAM,4BAAY,IAAI,KAAgC;CAMtD,SAAS,iBAAiB,MAAa,IAAiB;AACtD,MAAI,SAAS,GAAI;EAEjB,MAAM,aAAqC;GACzC;GACA;GACA,WAAW,KAAK,KAAK;GACtB;AAED,OAAK,MAAM,YAAY,UACrB,KAAI;AACF,YAAS,WAAW;UACd;;CAUZ,SAAS,SAAS,KAAgB;AAChC,MAAI,CAAC,UAAW;AAEhB,UAAQ,KAAK,IAAI;AACjB,MAAI,cAAe;AAEnB,kBAAgB;AAChB,MAAI;AACF,UAAO,QAAQ,SAAS,GAAG;IACzB,MAAM,OAAO,QAAQ,OAAO;IAC5B,MAAM,OAAO;IACb,MAAM,CAAC,UAAU,GAAG,WAAW,QAAQ,OAAO,MAAM,MAAM;AAC1D,YAAQ;AACR,qBAAiB,MAAM,MAAM;AAC7B,SAAK,MAAM,UAAU,QACnB,UAAS,QAAQ,SAAS;;YAGtB;AACR,mBAAgB;;;CAQpB,SAAS,WAAkB;AACzB,SAAO;;CAGT,SAAS,uBACP,UACY;AACZ,YAAU,IAAI,SAAS;AACvB,eAAa;AACX,aAAU,OAAO,SAAS;;;CAI9B,SAAS,aACP,WACA,SACgB;AAEhB,MAAI,UAAU,MAAM,CAClB,QAAO,QAAQ,QAAQ,MAAM;AAG/B,SAAO,IAAI,SAAS,SAAS,WAAW;GACtC,IAAI;GAEJ,MAAM,cAAc,wBAAuB,eAAc;AACvD,QAAI,UAAU,WAAW,GAAG,EAAE;AAC5B,cAAS;AACT,aAAQ,WAAW,GAAG;;KAExB;GAEF,MAAM,gBAAgB;AACpB,iBAAa;AACb,QAAI,cAAc,KAAA,EAChB,cAAa,UAAU;;AAI3B,OAAI,SAAS,cAAc,KAAA,EACzB,aAAY,iBAAiB;AAC3B,aAAS;AACT,2BACE,IAAI,MAAM,mCAAmC,QAAQ,UAAU,IAAI,CACpE;MACA,QAAQ,UAAU;IAEvB;;CAGJ,SAAS,cAEP,QACA,SACY;AACZ,SAAO,KAAK,cAAc,MAAS,EAAE,WAAW,QAAQ,QAAQ;;CAGlE,SAAS,UAAgB;AACvB,MAAI,CAAC,UAAW;AAChB,cAAY;AACZ,UAAQ,OAAO,MAAM;;CAOvB,MAAM,CAAC,cAAc,GAAG,kBAAkB,QAAQ;AAClD,SAAQ;AACR,MAAK,MAAM,UAAU,eACnB,UAAS,QAAQ,SAAS;AAO5B,QAAO;EACL;EACA;EACA;EACA;EACA;EACA;EACD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kyneta/machine",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "Universal Mealy machine algebra — Program, Effect, Dispatch, runtime",
   "author": "Duane Johnson",
   "license": "MIT",
@@ -30,12 +30,12 @@
     "./src/*": "./src/*"
   },
   "devDependencies": {
-    "tsup": "^8.5.0",
+    "tsdown": "^0.21.9",
     "typescript": "^5.9.2",
     "vitest": "^4.0.17"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "test": "verify logic",
     "verify": "verify"
   }