@pibbl/core 0.0.1 → 0.0.3-alpha.85.1

package/dist/features/machines/runtime.js

@@ -0,0 +1,363 @@
+import { assertDirectSignalWriteAllowed, signal } from "../../lib/signals/graph.js";
+import { assignmentOf } from "./assign.js";
+const compiledMachines = /* @__PURE__ */ new WeakMap();
+function defineMachine(definition) {
+  compile(definition);
+  return definition;
+}
+function createMachine(definition, options) {
+  const compiled = compile(definition);
+  const input = options.input;
+  const context = typeof definition.context === "function" ? definition.context({ input }) : definition.context;
+  let currentContext = context;
+  let value = definition.initial;
+  let status = "not-started";
+  let error;
+  let activeEntry;
+  let entryGeneration = 0;
+  const initial = snapshot(value, currentContext, status, error);
+  const writableSnapshot = signal(initial, { debugName: "machine.snapshot" });
+  const publicSnapshot = writableSnapshot.asReadonly();
+  const queue = [];
+  let queueHead = 0;
+  let processing = false;
+  const actor = {
+    snapshot: publicSnapshot,
+    start() {
+      if (status !== "not-started") return;
+      assertDirectSignalWriteAllowed(writableSnapshot);
+      status = "active";
+      processing = true;
+      try {
+        runActions(stateDefinition().entry, void 0);
+        if (status !== "active") return;
+        publish();
+        startInvocations(void 0);
+      } catch (cause) {
+        fail(cause);
+      } finally {
+        processing = false;
+      }
+      drain();
+    },
+    send(event) {
+      if (status !== "active") return;
+      assertDirectSignalWriteAllowed(writableSnapshot);
+      queue.push({ kind: "event", event });
+      if (!processing) drain();
+    },
+    stop() {
+      if (status === "stopped" || status === "error") return;
+      assertDirectSignalWriteAllowed(writableSnapshot);
+      status = "stopped";
+      try {
+        cancelEntry();
+      } finally {
+        releaseQueue();
+        publish();
+      }
+    }
+  };
+  return actor;
+  function stateDefinition() {
+    const state = compiled.states.get(value);
+    if (!state) throw new Error(`Machine entered unknown state ${JSON.stringify(value)}.`);
+    return state.definition;
+  }
+  function drain() {
+    if (processing || status !== "active") return;
+    processing = true;
+    try {
+      while (status === "active" && queueHead < queue.length) {
+        const item = queue[queueHead];
+        queue[queueHead++] = void 0;
+        if (item.kind === "event") processEvent(item.event);
+        else processInvocation(item);
+      }
+    } catch (cause) {
+      fail(cause);
+    } finally {
+      processing = false;
+      if (queueHead === queue.length) releaseQueue();
+    }
+  }
+  function processEvent(event) {
+    const compiledState = compiled.states.get(value);
+    const local = compiledState.on;
+    const source = local.has(event.type) ? local.get(event.type) : compiled.on.get(event.type);
+    if (source === void 0) return;
+    const selected = selectTransition(source, event);
+    if (selected !== void 0) applyTransition(selected, event);
+  }
+  function processInvocation(item) {
+    if (!item.entry.active || activeEntry !== item.entry || status !== "active") return;
+    const source = item.kind === "done" ? item.invocation.onDone : item.invocation.onError;
+    if (source === void 0) {
+      if (item.kind === "error") fail(item.error);
+      return;
+    }
+    const event = item.kind === "done" ? { type: "@pibbl/machine.done", output: item.output } : { type: "@pibbl/machine.error", error: item.error };
+    const selected = selectTransition(
+      source,
+      event
+    );
+    if (selected !== void 0) applyTransition(selected, event);
+  }
+  function selectTransition(source, event) {
+    if (typeof source === "string") return { target: source };
+    const candidates = Array.isArray(source) ? source : void 0;
+    if (!candidates) {
+      const candidate = source;
+      return !candidate.guard || candidate.guard(actionContext(event)) ? candidate : void 0;
+    }
+    for (const candidate of candidates) {
+      if (!candidate.guard || candidate.guard(actionContext(event))) return candidate;
+    }
+    return void 0;
+  }
+  function applyTransition(transition, event) {
+    const target = transition.target ?? value;
+    const changesState = target !== value || transition.reenter === true;
+    if (changesState) {
+      cancelEntry();
+      runActions(stateDefinition().exit, event);
+      if (status !== "active") return;
+    }
+    const contextChanged = runActions(transition.actions, event);
+    if (status !== "active") return;
+    if (changesState) {
+      value = target;
+      runActions(stateDefinition().entry, event);
+    }
+    if (changesState || contextChanged) publish();
+    if (changesState) startInvocations(event);
+  }
+  function actionContext(event) {
+    return {
+      get context() {
+        return currentContext;
+      },
+      event,
+      input,
+      send: actor.send
+    };
+  }
+  function runActions(actions, event) {
+    if (actions === void 0) return false;
+    const list = Array.isArray(actions) ? actions : [actions];
+    let changed = false;
+    for (const action of list) {
+      const contextForAction = actionContext(event);
+      const assignment = assignmentOf(action);
+      if (assignment) {
+        const patch = assignment(contextForAction);
+        if (patch === null || typeof patch !== "object") throw new TypeError("assign() must return a context object patch.");
+        if (patchChangesContext(currentContext, patch)) {
+          currentContext = Object.assign({}, currentContext, patch);
+          changed = true;
+        }
+      } else {
+        action(contextForAction);
+      }
+      if (status !== "active") return changed;
+    }
+    return changed;
+  }
+  function startInvocations(event) {
+    const definitions = stateDefinition().invoke;
+    if (!definitions) return;
+    const entry = {
+      active: true,
+      generation: ++entryGeneration,
+      controllers: []
+    };
+    activeEntry = entry;
+    const list = Array.isArray(definitions) ? definitions : [definitions];
+    for (const invocation of list) {
+      startInvocation(entry, invocation, event);
+      if (status !== "active" || !entry.active || activeEntry !== entry) break;
+    }
+  }
+  function startInvocation(entry, invocation, event) {
+    const controller = new AbortController();
+    const owned = { controller, invocation, cleanup: void 0 };
+    entry.controllers.push(owned);
+    let returned;
+    try {
+      returned = invocation.task({
+        context: currentContext,
+        event,
+        input,
+        signal: controller.signal,
+        send(queuedEvent) {
+          if (status !== "active" || !entry.active || activeEntry !== entry || controller.signal.aborted) return;
+          actor.send(queuedEvent);
+        }
+      });
+    } catch (cause) {
+      queueInvocation({ kind: "error", entry, invocation, error: cause });
+      return;
+    }
+    if (typeof returned === "function") {
+      owned.cleanup = returned;
+    } else if (returned && typeof returned.then === "function") {
+      Promise.resolve(returned).then(
+        (output) => queueInvocation({ kind: "done", entry, invocation, output }),
+        (cause) => queueInvocation({ kind: "error", entry, invocation, error: cause })
+      );
+    }
+  }
+  function queueInvocation(item) {
+    if (status !== "active" || !item.entry.active || activeEntry !== item.entry) return;
+    queue.push(item);
+    if (!processing) drain();
+  }
+  function cancelEntry() {
+    const entry = activeEntry;
+    activeEntry = void 0;
+    if (!entry) return;
+    entry.active = false;
+    const failures = [];
+    for (const owned of entry.controllers) {
+      try {
+        owned.controller.abort();
+      } catch (cause) {
+        failures.push(cause);
+      }
+      const cleanup = owned.cleanup;
+      owned.cleanup = void 0;
+      if (cleanup) {
+        try {
+          cleanup();
+        } catch (cause) {
+          failures.push(cause);
+        }
+      }
+    }
+    entry.controllers.length = 0;
+    if (failures.length === 1) throw failures[0];
+    if (failures.length > 1) throw new AggregateError(failures, "Machine state task cleanup failed.");
+  }
+  function fail(cause) {
+    if (status === "error" || status === "stopped") return;
+    status = "error";
+    error = cause;
+    try {
+      cancelEntry();
+    } catch (cleanupCause) {
+      error = new AggregateError([cause, cleanupCause], "Machine failed while cleaning up a state task.");
+    }
+    releaseQueue();
+    publish();
+  }
+  function releaseQueue() {
+    for (let index = queueHead; index < queue.length; index++) queue[index] = void 0;
+    queue.length = 0;
+    queueHead = 0;
+  }
+  function publish() {
+    writableSnapshot.set(snapshot(value, currentContext, status, error));
+  }
+}
+function snapshot(value, context, status, error) {
+  return Object.freeze({ value, context, status, error, matches: (candidate) => candidate === value });
+}
+function patchChangesContext(context, patch) {
+  if (context === null || typeof context !== "object") return true;
+  for (const key of Reflect.ownKeys(patch)) {
+    if (!Object.is(context[key], patch[key])) return true;
+  }
+  return false;
+}
+function compile(definition) {
+  const known = compiledMachines.get(definition);
+  if (known) return known;
+  if (!definition || typeof definition !== "object") throw new TypeError("Machine definition must be an object.");
+  if (!definition.states || typeof definition.states !== "object") throw new TypeError("Machine definition requires a states object.");
+  if (!Object.prototype.hasOwnProperty.call(definition.states, definition.initial)) throw new RangeError(`Machine initial state ${JSON.stringify(definition.initial)} is not declared.`);
+  const names = new Set(Object.keys(definition.states));
+  const states = /* @__PURE__ */ new Map();
+  for (const [name, rawValue] of Object.entries(definition.states)) {
+    const raw = rawValue;
+    if (!raw || typeof raw !== "object") throw new TypeError(`Machine state ${JSON.stringify(name)} must be an object.`);
+    validateHandlers(raw.on, names, `state ${JSON.stringify(name)}`);
+    validateInvocations(raw.invoke, names, `state ${JSON.stringify(name)}`);
+    const normalized = normalizeState(raw);
+    states.set(name, { definition: normalized, on: new Map(Object.entries(normalized.on ?? {})) });
+  }
+  validateHandlers(definition.on, names, "machine");
+  const compiled = { states, on: normalizeHandlers(definition.on) };
+  compiledMachines.set(definition, compiled);
+  return compiled;
+}
+function normalizeState(state) {
+  const invocations = state.invoke === void 0 ? void 0 : Array.isArray(state.invoke) ? state.invoke.map((invocation) => normalizeInvocation(invocation)) : normalizeInvocation(state.invoke);
+  return Object.freeze({
+    entry: normalizeActions(state.entry),
+    exit: normalizeActions(state.exit),
+    invoke: invocations === void 0 ? void 0 : Object.freeze(Array.isArray(invocations) ? invocations : [invocations]),
+    on: Object.freeze(Object.fromEntries(normalizeHandlers(state.on)))
+  });
+}
+function normalizeHandlers(handlers) {
+  if (!handlers) return /* @__PURE__ */ new Map();
+  return new Map(Object.entries(handlers).map(([type, transition]) => [type, normalizeTransition(transition)]));
+}
+function normalizeInvocation(invocation) {
+  const source = invocation;
+  return Object.freeze({
+    id: source.id,
+    task: source.task,
+    onDone: normalizeTransition(source.onDone),
+    onError: normalizeTransition(source.onError)
+  });
+}
+function normalizeTransition(transition) {
+  if (transition === void 0 || typeof transition === "string") return transition;
+  if (Array.isArray(transition)) return Object.freeze(transition.map((candidate) => normalizeTransition(candidate)));
+  const source = transition;
+  return Object.freeze({
+    target: source.target,
+    guard: source.guard,
+    actions: normalizeActions(source.actions),
+    reenter: source.reenter
+  });
+}
+function normalizeActions(actions) {
+  return Array.isArray(actions) ? Object.freeze([...actions]) : actions;
+}
+function validateHandlers(handlers, names, label) {
+  if (handlers === void 0) return;
+  if (!handlers || typeof handlers !== "object") throw new TypeError(`Handlers for ${label} must be an object.`);
+  for (const transition of Object.values(handlers)) validateTransition(transition, names, label);
+}
+function validateInvocations(invocations, names, label) {
+  if (invocations === void 0) return;
+  const list = Array.isArray(invocations) ? invocations : [invocations];
+  for (const invocation of list) {
+    if (!invocation || typeof invocation !== "object" || typeof invocation.task !== "function") throw new TypeError(`Each invocation in ${label} requires a task function.`);
+    const typed = invocation;
+    validateTransition(typed.onDone, names, label);
+    validateTransition(typed.onError, names, label);
+  }
+}
+function validateTransition(transition, names, label) {
+  if (transition === void 0) return;
+  const list = Array.isArray(transition) ? transition : [transition];
+  for (const candidate of list) {
+    if (typeof candidate === "string") {
+      if (!names.has(candidate)) throw new RangeError(`Transition in ${label} targets undeclared state ${JSON.stringify(candidate)}.`);
+      continue;
+    }
+    if (!candidate || typeof candidate !== "object") throw new TypeError(`Transition in ${label} must be a state name or object.`);
+    const config = candidate;
+    if (config.target !== void 0 && (typeof config.target !== "string" || !names.has(config.target))) throw new RangeError(`Transition in ${label} targets an undeclared state.`);
+    if (config.guard !== void 0 && typeof config.guard !== "function") throw new TypeError(`Transition guard in ${label} must be a function.`);
+    if (config.actions !== void 0 && typeof config.actions !== "function" && (!Array.isArray(config.actions) || config.actions.some((action) => typeof action !== "function"))) throw new TypeError(`Transition actions in ${label} must be functions.`);
+  }
+}
+export {
+  createMachine,
+  defineMachine
+};
+//# sourceMappingURL=runtime.js.map

package/dist/features/machines/runtime.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/features/machines/runtime.ts"],
+  "sourcesContent": ["import { assertDirectSignalWriteAllowed, signal } from '../../lib/signals/graph.js';\nimport { assignmentOf } from './assign.js';\nimport type {\n  CreateMachineOptions,\n  MachineAction,\n  MachineActionContext,\n  MachineActions,\n  MachineActor,\n  MachineDefinition,\n  MachineEvent,\n  MachineInvocation,\n  MachineSnapshot,\n  MachineState,\n  MachineStatus,\n  MachineTaskDoneEvent,\n  MachineTaskErrorEvent,\n  MachineTransition,\n  MachineTransitionConfig,\n} from './types.js';\n\ninterface CompiledMachine {\n  readonly states: ReadonlyMap<string, CompiledState>;\n  readonly on: ReadonlyMap<string, unknown>;\n}\n\ninterface CompiledState {\n  readonly definition: MachineState<object, MachineEvent, unknown, string>;\n  readonly on: ReadonlyMap<string, unknown>;\n}\n\nconst compiledMachines = new WeakMap<object, CompiledMachine>();\n\n/**\n * Validates and records a reusable flat machine definition. Calling this function performs no\n * work and creates no actor; use {@link createMachine} or `useMachine` to execute it.\n * @param definition - Reusable machine behavior to validate and normalize.\n * @returns The supplied definition, suitable for actor creation.\n * @see {@link MachineDefinition}\n */\nexport function defineMachine<Context, Event extends MachineEvent, Input = undefined, State extends string = string>(\n  definition: MachineDefinition<Context, Event, Input, State>,\n): MachineDefinition<Context, Event, Input, State> {\n  compile(definition);\n  return definition;\n}\n\n/**\n * Creates an explicitly owned, initially idle machine actor. Call `start()` when ownership begins\n * and `stop()` when it ends. The actor has no renderer, scheduler, or animation dependency.\n * @param definition - Reusable behavior previously authored with {@link defineMachine}.\n * @param options - Immutable input supplied to this actor.\n * @returns An idle actor that owns no task until it starts.\n * @see {@link MachineActor}\n */\nexport function createMachine<Context, Event extends MachineEvent, Input, State extends string = string>(\n  definition: MachineDefinition<Context, Event, Input, State>,\n  options: CreateMachineOptions<Input>,\n): MachineActor<Context, Event, Input, State> {\n  const compiled = compile(definition);\n  const input = options.input;\n  const context = typeof definition.context === 'function'\n    ? (definition.context as (value: Readonly<{ input: Input }>) => Context)({ input })\n    : definition.context;\n  let currentContext = context;\n  let value = definition.initial;\n  let status: MachineStatus = 'not-started';\n  let error: unknown | undefined;\n  let activeEntry: StateEntry<Context, Event, Input, State> | undefined;\n  let entryGeneration = 0;\n  const initial = snapshot(value, currentContext, status, error);\n  const writableSnapshot = signal(initial, { debugName: 'machine.snapshot' });\n  const publicSnapshot = writableSnapshot.asReadonly();\n  const queue: QueueItem<Context, Event, Input, State>[] = [];\n  let queueHead = 0;\n  let processing = false;\n\n  const actor: MachineActor<Context, Event, Input, State> = {\n    snapshot: publicSnapshot,\n    start(): void {\n      if (status !== 'not-started') return;\n      assertDirectSignalWriteAllowed(writableSnapshot);\n      status = 'active';\n      // Entry actions may send events. Keep those queued until the initial entry has published\n      // and started its owned work, just like an ordinary transition.\n      processing = true;\n      try {\n        runActions(stateDefinition().entry as unknown as MachineActions<Context, Event, Input>, undefined);\n        if (status !== 'active') return;\n        publish();\n        startInvocations(undefined);\n      } catch (cause) {\n        fail(cause);\n      } finally {\n        processing = false;\n      }\n      drain();\n    },\n    send(event: Event): void {\n      if (status !== 'active') return;\n      assertDirectSignalWriteAllowed(writableSnapshot);\n      queue.push({ kind: 'event', event });\n      if (!processing) drain();\n    },\n    stop(): void {\n      if (status === 'stopped' || status === 'error') return;\n      assertDirectSignalWriteAllowed(writableSnapshot);\n      status = 'stopped';\n      try {\n        cancelEntry();\n      } finally {\n        releaseQueue();\n        publish();\n      }\n    },\n  };\n\n  return actor;\n\n  function stateDefinition(): MachineState<Context, Event, Input, State> {\n    const state = compiled.states.get(value);\n    if (!state) throw new Error(`Machine entered unknown state ${JSON.stringify(value)}.`);\n    return state.definition as unknown as MachineState<Context, Event, Input, State>;\n  }\n\n  function drain(): void {\n    if (processing || status !== 'active') return;\n    processing = true;\n    try {\n      while (status === 'active' && queueHead < queue.length) {\n        const item = queue[queueHead];\n        queue[queueHead++] = undefined as never;\n        if (item.kind === 'event') processEvent(item.event);\n        else processInvocation(item);\n      }\n    } catch (cause) {\n      fail(cause);\n    } finally {\n      processing = false;\n      if (queueHead === queue.length) releaseQueue();\n    }\n  }\n\n  function processEvent(event: Event): void {\n    const compiledState = compiled.states.get(value)!;\n    const local = compiledState.on;\n    // Local declaration intentionally shadows the machine fallback even if every guard rejects.\n    const source = local.has(event.type) ? local.get(event.type) : compiled.on.get(event.type);\n    if (source === undefined) return;\n    const selected = selectTransition(source as MachineTransition<Context, Event, Input, State, Event>, event);\n    if (selected !== undefined) applyTransition(selected, event);\n  }\n\n  function processInvocation(item: InvocationQueueItem<Context, Event, Input, State>): void {\n    if (!item.entry.active || activeEntry !== item.entry || status !== 'active') return;\n    const source = item.kind === 'done' ? item.invocation.onDone : item.invocation.onError;\n    if (source === undefined) {\n      if (item.kind === 'error') fail(item.error);\n      return;\n    }\n    const event = item.kind === 'done'\n      ? { type: '@pibbl/machine.done', output: item.output } as MachineTaskDoneEvent\n      : { type: '@pibbl/machine.error', error: item.error } as MachineTaskErrorEvent;\n    const selected = selectTransition<MachineEvent>(\n      source as unknown as MachineTransition<Context, MachineEvent, Input, State, Event>,\n      event,\n    );\n    if (selected !== undefined) applyTransition<MachineEvent>(selected, event);\n  }\n\n  function selectTransition<SelectedEvent extends MachineEvent>(\n    source: MachineTransition<Context, SelectedEvent, Input, State, Event>,\n    event: SelectedEvent,\n  ): MachineTransitionConfig<Context, SelectedEvent, Input, State, Event> | undefined {\n    if (typeof source === 'string') return { target: source };\n    const candidates = Array.isArray(source as unknown) ? source as readonly MachineTransitionConfig<Context, SelectedEvent, Input, State, Event>[] : undefined;\n    if (!candidates) {\n      const candidate = source as MachineTransitionConfig<Context, SelectedEvent, Input, State, Event>;\n      return !candidate.guard || candidate.guard(actionContext(event)) ? candidate : undefined;\n    }\n    for (const candidate of candidates) {\n      if (!candidate.guard || candidate.guard(actionContext(event))) return candidate;\n    }\n    return undefined;\n  }\n\n  function applyTransition<SelectedEvent extends MachineEvent>(\n    transition: MachineTransitionConfig<Context, SelectedEvent, Input, State, Event>,\n    event: SelectedEvent,\n  ): void {\n    const target = transition.target ?? value;\n    const changesState = target !== value || transition.reenter === true;\n    if (changesState) {\n      cancelEntry();\n      runActions(stateDefinition().exit, event as unknown as Event);\n      if (status !== 'active') return;\n    }\n    const contextChanged = runActions(transition.actions, event);\n    if (status !== 'active') return;\n    if (changesState) {\n      value = target;\n      runActions(stateDefinition().entry as unknown as MachineActions<Context, Event, Input>, event as unknown as Event);\n    }\n    // Empty handlers and no-op action handlers preserve snapshot identity.\n    if (changesState || contextChanged) publish();\n    if (changesState) startInvocations(event as unknown as Event);\n  }\n\n  function actionContext<SelectedEvent extends MachineEvent>(event: SelectedEvent | undefined): MachineActionContext<Context, SelectedEvent, Input, Event> {\n    return {\n      get context() { return currentContext; },\n      event: event as SelectedEvent,\n      input,\n      send: actor.send,\n    };\n  }\n\n  function runActions<SelectedEvent extends MachineEvent>(\n    actions: MachineAction<Context, SelectedEvent, Input, Event> | readonly MachineAction<Context, SelectedEvent, Input, Event>[] | undefined,\n    event: SelectedEvent | undefined,\n  ): boolean {\n    if (actions === undefined) return false;\n    const list = Array.isArray(actions) ? actions : [actions];\n    let changed = false;\n    for (const action of list) {\n      const contextForAction = actionContext(event);\n      const assignment = assignmentOf(action);\n      if (assignment) {\n        const patch = assignment(contextForAction as unknown as MachineActionContext<object, MachineEvent, unknown>);\n        if (patch === null || typeof patch !== 'object') throw new TypeError('assign() must return a context object patch.');\n        if (patchChangesContext(currentContext, patch)) {\n          currentContext = Object.assign({}, currentContext as object, patch) as Context;\n          changed = true;\n        }\n      } else {\n        action(contextForAction);\n      }\n      if (status !== 'active') return changed;\n    }\n    return changed;\n  }\n\n  function startInvocations(event: Event | undefined): void {\n    const definitions = stateDefinition().invoke;\n    if (!definitions) return;\n    const entry: StateEntry<Context, Event, Input, State> = {\n      active: true,\n      generation: ++entryGeneration,\n      controllers: [],\n    };\n    activeEntry = entry;\n    const list = Array.isArray(definitions) ? definitions : [definitions];\n    for (const invocation of list) {\n      startInvocation(entry, invocation, event);\n      if (status !== 'active' || !entry.active || activeEntry !== entry) break;\n    }\n  }\n\n  function startInvocation(\n    entry: StateEntry<Context, Event, Input, State>,\n    invocation: MachineInvocation<Context, Event, Input, State>,\n    event: Event | undefined,\n  ): void {\n    const controller = new AbortController();\n    const owned: OwnedInvocation<Context, Event, Input, State> = { controller, invocation, cleanup: undefined };\n    entry.controllers.push(owned);\n    let returned: void | (() => void) | Promise<unknown>;\n    try {\n      returned = invocation.task({\n        context: currentContext,\n        event,\n        input,\n        signal: controller.signal,\n        send(queuedEvent: Event): void {\n          if (status !== 'active' || !entry.active || activeEntry !== entry || controller.signal.aborted) return;\n          actor.send(queuedEvent);\n        },\n      });\n    } catch (cause) {\n      queueInvocation({ kind: 'error', entry, invocation, error: cause });\n      return;\n    }\n    if (typeof returned === 'function') {\n      owned.cleanup = returned;\n    } else if (returned && typeof (returned as Promise<unknown>).then === 'function') {\n      Promise.resolve(returned).then(\n        output => queueInvocation({ kind: 'done', entry, invocation, output }),\n        cause => queueInvocation({ kind: 'error', entry, invocation, error: cause }),\n      );\n    }\n  }\n\n  function queueInvocation(item: InvocationQueueItem<Context, Event, Input, State>): void {\n    if (status !== 'active' || !item.entry.active || activeEntry !== item.entry) return;\n    queue.push(item);\n    if (!processing) drain();\n  }\n\n  function cancelEntry(): void {\n    const entry = activeEntry;\n    activeEntry = undefined;\n    if (!entry) return;\n    entry.active = false;\n    const failures: unknown[] = [];\n    for (const owned of entry.controllers) {\n      try { owned.controller.abort(); } catch (cause) { failures.push(cause); }\n      const cleanup = owned.cleanup;\n      owned.cleanup = undefined;\n      if (cleanup) {\n        try { cleanup(); } catch (cause) { failures.push(cause); }\n      }\n    }\n    entry.controllers.length = 0;\n    if (failures.length === 1) throw failures[0];\n    if (failures.length > 1) throw new AggregateError(failures, 'Machine state task cleanup failed.');\n  }\n\n  function fail(cause: unknown): void {\n    if (status === 'error' || status === 'stopped') return;\n    status = 'error';\n    error = cause;\n    try { cancelEntry(); } catch (cleanupCause) { error = new AggregateError([cause, cleanupCause], 'Machine failed while cleaning up a state task.'); }\n    releaseQueue();\n    publish();\n  }\n\n  function releaseQueue(): void {\n    for (let index = queueHead; index < queue.length; index++) queue[index] = undefined as never;\n    queue.length = 0;\n    queueHead = 0;\n  }\n\n  function publish(): void {\n    writableSnapshot.set(snapshot(value, currentContext, status, error));\n  }\n}\n\nfunction snapshot<Context, State extends string>(\n  value: State,\n  context: Context,\n  status: MachineStatus,\n  error: unknown | undefined,\n): MachineSnapshot<Context, State> {\n  return Object.freeze({ value, context, status, error, matches: (candidate: State) => candidate === value });\n}\n\n/** Avoid replacing context or publishing a snapshot for an assignment that changes no own key. */\nfunction patchChangesContext(context: unknown, patch: object): boolean {\n  if (context === null || typeof context !== 'object') return true;\n  for (const key of Reflect.ownKeys(patch)) {\n    if (!Object.is((context as Record<PropertyKey, unknown>)[key], (patch as Record<PropertyKey, unknown>)[key])) return true;\n  }\n  return false;\n}\n\nfunction compile<Context, Event extends MachineEvent, Input, State extends string>(\n  definition: MachineDefinition<Context, Event, Input, State>,\n): CompiledMachine {\n  const known = compiledMachines.get(definition);\n  if (known) return known;\n  if (!definition || typeof definition !== 'object') throw new TypeError('Machine definition must be an object.');\n  if (!definition.states || typeof definition.states !== 'object') throw new TypeError('Machine definition requires a states object.');\n  if (!Object.prototype.hasOwnProperty.call(definition.states, definition.initial)) throw new RangeError(`Machine initial state ${JSON.stringify(definition.initial)} is not declared.`);\n  const names = new Set(Object.keys(definition.states));\n  const states = new Map<string, CompiledState>();\n  for (const [name, rawValue] of Object.entries(definition.states)) {\n    const raw = rawValue as MachineState<Context, Event, Input, State>;\n    if (!raw || typeof raw !== 'object') throw new TypeError(`Machine state ${JSON.stringify(name)} must be an object.`);\n    validateHandlers(raw.on, names, `state ${JSON.stringify(name)}`);\n    validateInvocations(raw.invoke, names, `state ${JSON.stringify(name)}`);\n    const normalized = normalizeState(raw);\n    states.set(name, { definition: normalized as unknown as MachineState<object, MachineEvent, unknown, string>, on: new Map(Object.entries(normalized.on ?? {})) });\n  }\n  validateHandlers(definition.on, names, 'machine');\n  const compiled: CompiledMachine = { states, on: normalizeHandlers(definition.on) };\n  compiledMachines.set(definition, compiled);\n  return compiled;\n}\n\nfunction normalizeState<Context, Event extends MachineEvent, Input, State extends string>(\n  state: MachineState<Context, Event, Input, State>,\n): MachineState<Context, Event, Input, State> {\n  const invocations = state.invoke === undefined ? undefined : (Array.isArray(state.invoke)\n    ? state.invoke.map(invocation => normalizeInvocation(invocation))\n    : normalizeInvocation(state.invoke));\n  return Object.freeze({\n    entry: normalizeActions(state.entry),\n    exit: normalizeActions(state.exit),\n    invoke: invocations === undefined ? undefined : Object.freeze(Array.isArray(invocations) ? invocations : [invocations]),\n    on: Object.freeze(Object.fromEntries(normalizeHandlers(state.on))),\n  }) as unknown as MachineState<Context, Event, Input, State>;\n}\n\nfunction normalizeHandlers(handlers: object | undefined): Map<string, unknown> {\n  if (!handlers) return new Map();\n  return new Map(Object.entries(handlers).map(([type, transition]) => [type, normalizeTransition(transition)]));\n}\n\nfunction normalizeInvocation(invocation: unknown): object {\n  const source = invocation as { id?: string; task: unknown; onDone?: unknown; onError?: unknown };\n  return Object.freeze({\n    id: source.id,\n    task: source.task,\n    onDone: normalizeTransition(source.onDone),\n    onError: normalizeTransition(source.onError),\n  });\n}\n\nfunction normalizeTransition(transition: unknown): unknown {\n  if (transition === undefined || typeof transition === 'string') return transition;\n  if (Array.isArray(transition)) return Object.freeze(transition.map(candidate => normalizeTransition(candidate)));\n  const source = transition as { target?: string; guard?: unknown; actions?: unknown; reenter?: boolean };\n  return Object.freeze({\n    target: source.target,\n    guard: source.guard,\n    actions: normalizeActions(source.actions),\n    reenter: source.reenter,\n  });\n}\n\nfunction normalizeActions(actions: unknown): unknown {\n  return Array.isArray(actions) ? Object.freeze([...actions]) : actions;\n}\n\nfunction validateHandlers(handlers: object | undefined, names: ReadonlySet<string>, label: string): void {\n  if (handlers === undefined) return;\n  if (!handlers || typeof handlers !== 'object') throw new TypeError(`Handlers for ${label} must be an object.`);\n  for (const transition of Object.values(handlers)) validateTransition(transition, names, label);\n}\n\nfunction validateInvocations(invocations: unknown, names: ReadonlySet<string>, label: string): void {\n  if (invocations === undefined) return;\n  const list = Array.isArray(invocations) ? invocations : [invocations];\n  for (const invocation of list) {\n    if (!invocation || typeof invocation !== 'object' || typeof (invocation as { task?: unknown }).task !== 'function') throw new TypeError(`Each invocation in ${label} requires a task function.`);\n    const typed = invocation as { onDone?: unknown; onError?: unknown };\n    validateTransition(typed.onDone, names, label);\n    validateTransition(typed.onError, names, label);\n  }\n}\n\nfunction validateTransition(transition: unknown, names: ReadonlySet<string>, label: string): void {\n  if (transition === undefined) return;\n  const list = Array.isArray(transition) ? transition : [transition];\n  for (const candidate of list) {\n    if (typeof candidate === 'string') {\n      if (!names.has(candidate)) throw new RangeError(`Transition in ${label} targets undeclared state ${JSON.stringify(candidate)}.`);\n      continue;\n    }\n    if (!candidate || typeof candidate !== 'object') throw new TypeError(`Transition in ${label} must be a state name or object.`);\n    const config = candidate as { target?: unknown; guard?: unknown; actions?: unknown };\n    if (config.target !== undefined && (typeof config.target !== 'string' || !names.has(config.target))) throw new RangeError(`Transition in ${label} targets an undeclared state.`);\n    if (config.guard !== undefined && typeof config.guard !== 'function') throw new TypeError(`Transition guard in ${label} must be a function.`);\n    if (config.actions !== undefined && typeof config.actions !== 'function' && (!Array.isArray(config.actions) || config.actions.some(action => typeof action !== 'function'))) throw new TypeError(`Transition actions in ${label} must be functions.`);\n  }\n}\n\ninterface StateEntry<Context, Event extends MachineEvent, Input, State extends string> {\n  active: boolean;\n  readonly generation: number;\n  readonly controllers: OwnedInvocation<Context, Event, Input, State>[];\n}\ninterface OwnedInvocation<Context, Event extends MachineEvent, Input, State extends string> {\n  readonly controller: AbortController;\n  readonly invocation: MachineInvocation<Context, Event, Input, State>;\n  cleanup: (() => void) | undefined;\n}\ntype EventQueueItem<Event extends MachineEvent> = { readonly kind: 'event'; readonly event: Event };\ntype InvocationQueueItem<Context, Event extends MachineEvent, Input, State extends string> =\n  | { readonly kind: 'done'; readonly entry: StateEntry<Context, Event, Input, State>; readonly invocation: MachineInvocation<Context, Event, Input, State>; readonly output: unknown }\n  | { readonly kind: 'error'; readonly entry: StateEntry<Context, Event, Input, State>; readonly invocation: MachineInvocation<Context, Event, Input, State>; readonly error: unknown };\ntype QueueItem<Context, Event extends MachineEvent, Input, State extends string> = EventQueueItem<Event> | InvocationQueueItem<Context, Event, Input, State>;\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/features/machines/types.d.ts

@@ -0,0 +1,164 @@
+import type { Signal } from '../../lib/signals/types.js';
+/** An event accepted by a machine. The `type` selects the active state's handler. @see {@link MachineDefinition} */
+export interface MachineEvent {
+    /** Stable event discriminator. */
+    readonly type: string;
+}
+/**
+ * Maps each event discriminator to its narrowed event shape.
+ * @property type - Handler selected for each event discriminator.
+ * @see {@link MachineTransition}
+ */
+export type MachineEventRoutes<Context, Event extends MachineEvent, Input, State extends string> = {
+    [type in Event['type']]?: MachineTransition<Context, Extract<Event, {
+        readonly type: type;
+    }>, Input, State, Event>;
+};
+/** Lifecycle state of a machine actor. @see {@link MachineActor} */
+export type MachineStatus = 'not-started' | 'active' | 'stopped' | 'error';
+/** Immutable state published by a running machine actor. @see {@link MachineActor} */
+export interface MachineSnapshot<Context, State extends string = string> {
+    /** Active flat state name. */
+    readonly value: State;
+    /** Application-owned immutable context for the active state. */
+    readonly context: Readonly<Context>;
+    /** Whether the actor may receive events. */
+    readonly status: MachineStatus;
+    /** Unexpected failure that stopped this actor, if any. */
+    readonly error: unknown | undefined;
+    /** Tests whether this flat machine currently occupies `state`.
+     * @param state - State name to compare with the active value.
+     * @returns True when this is the active state.
+     */
+    matches(state: State): boolean;
+}
+/** Cleanup called when a callback task's owning state exits or its actor stops. @see {@link MachineTask} */
+export type MachineTaskCleanup = () => void;
+/** Values given to state actions. Context reflects all preceding `assign` actions. @see {@link MachineAction} */
+export interface MachineActionContext<Context, Event extends MachineEvent | undefined, Input, SentEvent extends MachineEvent = MachineEvent> {
+    /** Context as it exists at this point in the transition. */
+    readonly context: Readonly<Context>;
+    /** Event which selected this transition. */
+    readonly event: Event;
+    /** Immutable actor input supplied at creation. */
+    readonly input: Input;
+    /** Queues an event after the current transition has completed.
+     * @param event - Event to process after the active transition.
+     */
+    send(event: SentEvent): void;
+}
+/** A synchronous effect run during entry, exit, or a transition. @see {@link MachineActionContext} */
+export type MachineAction<Context, Event extends MachineEvent | undefined, Input, SentEvent extends MachineEvent = MachineEvent> = {
+    /** Executes one synchronous effect.
+     * @param context - Current transition values.
+     */
+    action(context: MachineActionContext<Context, Event, Input, SentEvent>): void;
+}['action'];
+/** One action or actions run in source order. @see {@link MachineAction} */
+export type MachineActions<Context, Event extends MachineEvent | undefined, Input, SentEvent extends MachineEvent = MachineEvent> = MachineAction<Context, Event, Input, SentEvent> | readonly MachineAction<Context, Event, Input, SentEvent>[];
+/** Values supplied to a state-owned task when that state is entered. @see {@link MachineTask} */
+export interface MachineTaskContext<Context, Event extends MachineEvent, Input> {
+    /** Context captured when this particular task starts. */
+    readonly context: Readonly<Context>;
+    /** Event that entered this state, or undefined for the initial state. */
+    readonly event: Event | undefined;
+    /** Immutable actor input supplied at creation. */
+    readonly input: Input;
+    /** Aborted synchronously when the owning state exits. */
+    readonly signal: AbortSignal;
+    /** Queues an event after the current transition, without re-entering the actor.
+     * @param event - Event accepted by the owning actor.
+     */
+    send(event: Event): void;
+}
+/**
+ * Cancelable work owned by a state entry. Return a cleanup for subscriptions or a promise for
+ * finite work. A task is never started until its entry snapshot has been published.
+ * @param context - State-entry values and cancellation signal.
+ * @returns Optional cleanup or a promise for finite work.
+ * @see {@link MachineInvocation}
+ */
+export type MachineTask<Context, Event extends MachineEvent, Input, Output = unknown> = (context: MachineTaskContext<Context, Event, Input>) => void | MachineTaskCleanup | Promise<Output>;
+/** Completion data supplied to an invocation's `onDone` transition. @see {@link MachineInvocation} */
+export interface MachineTaskDoneEvent<Output = unknown> extends MachineEvent {
+    /** Internal completion discriminator. */ readonly type: '@pibbl/machine.done';
+    /** Value resolved by the task promise. */ readonly output: Output;
+}
+/** Failure data supplied to an invocation's `onError` transition. @see {@link MachineInvocation} */
+export interface MachineTaskErrorEvent extends MachineEvent {
+    /** Internal failure discriminator. */ readonly type: '@pibbl/machine.error';
+    /** Thrown or rejected task value. */ readonly error: unknown;
+}
+/** A transition selected by an invocation completion or failure. */
+/** State-owned task and optional completion transitions. @see {@link MachineTask} */
+export interface MachineInvocation<Context, Event extends MachineEvent, Input, State extends string> {
+    /** Optional diagnostic identity; IDs are local to one state entry. */
+    readonly id?: string;
+    /** Work started after this state's snapshot publishes. */
+    readonly task: MachineTask<Context, Event, Input>;
+    /** Transition selected if a promise resolves before cancellation. */
+    readonly onDone?: MachineTransition<Context, MachineTaskDoneEvent, Input, State, Event>;
+    /** Transition selected if a task throws or a promise rejects before cancellation. */
+    readonly onError?: MachineTransition<Context, MachineTaskErrorEvent, Input, State, Event>;
+}
+/** A conditional route considered in list order. @see {@link MachineTransition} */
+export interface MachineTransitionConfig<Context, Event extends MachineEvent, Input, State extends string, SentEvent extends MachineEvent = Event> {
+    /** Destination state. Omit to run actions without leaving the current state. */
+    readonly target?: State;
+    /** Only select this route when it returns true.
+     * @param context - Current transition values.
+     * @returns Whether this route may be selected.
+     */
+    readonly guard?: (context: MachineActionContext<Context, Event, Input, SentEvent>) => boolean;
+    /** Effects run after exit and before entry. */
+    readonly actions?: MachineActions<Context, Event, Input, SentEvent>;
+    /** Restarts entry work when targeting the already active state. */
+    readonly reenter?: boolean;
+}
+/** Shorthand state target, a configured route, or ordered guarded alternatives. @see {@link MachineTransitionConfig} */
+export type MachineTransition<Context, Event extends MachineEvent, Input, State extends string, SentEvent extends MachineEvent = Event> = State | MachineTransitionConfig<Context, Event, Input, State, SentEvent> | readonly MachineTransitionConfig<Context, Event, Input, State, SentEvent>[];
+/** One flat state definition. Local event handlers shadow machine-level handlers. @see {@link MachineDefinition} */
+export interface MachineState<Context, Event extends MachineEvent, Input, State extends string> {
+    /** Effects run whenever this state is entered. The initial entry receives `undefined` as event. */
+    readonly entry?: MachineActions<Context, Event | undefined, Input, Event>;
+    /** Effects run whenever this state is exited. */
+    readonly exit?: MachineActions<Context, Event, Input, Event>;
+    /** State-owned work, canceled before exit effects. */
+    readonly invoke?: MachineInvocation<Context, Event, Input, State> | readonly MachineInvocation<Context, Event, Input, State>[];
+    /** Event routes local to this state. Declaring an event consumes machine-level handling. */
+    readonly on?: MachineEventRoutes<Context, Event, Input, State>;
+}
+/** Declarative, reusable machine definition. Definitions create no actor or scheduled work. @see {@link MachineActor} */
+export interface MachineDefinition<Context, Event extends MachineEvent, Input = undefined, State extends string = string> {
+    /** State entered when an actor starts. */
+    readonly initial: State;
+    /** Initial context or a factory evaluated once for every actor.
+     * @param context - Input used to create this actor's context.
+     * @returns Initial context for the new actor.
+     */
+    readonly context: Context | ((context: Readonly<{
+        input: Input;
+    }>) => Context);
+    /** State table. This initial implementation supports flat states only. */
+    readonly states: Readonly<Record<State, MachineState<Context, Event, Input, State>>>;
+    /** Fallback routes for events not declared by the active state. */
+    readonly on?: MachineEventRoutes<Context, Event, Input, State>;
+}
+/** Options used to create an explicitly owned actor. @see {@link MachineActor} */
+export interface CreateMachineOptions<Input> {
+    /** Immutable application input available to context factories, actions, and tasks. */
+    readonly input: Input;
+}
+/** Explicitly owned machine execution. Call `start` before sending events and `stop` to release it. @see {@link MachineDefinition} */
+export interface MachineActor<Context, Event extends MachineEvent, _Input, State extends string = string> {
+    /** Readonly, synchronous signal for the current state and context. */
+    readonly snapshot: Signal<MachineSnapshot<Context, State>>;
+    /** Starts the initial state once. Starting an active or stopped actor does nothing. */
+    start(): void;
+    /** Queues an event. Events sent during actions run after the current transition.
+     * @param event - Event accepted by this actor.
+     */
+    send(event: Event): void;
+    /** Terminal, idempotent cleanup. Cancels every task owned by the active state. */
+    stop(): void;
+}

package/dist/features/physics/2d-geometry.d.ts

@@ -1,5 +1,5 @@
 import type { boundsOfShape2D, massProperties2D, transformShape2D } from "./lib/2d/shapes.js";
-import type { queryAabb2D, raycast2D } from "./2d.js";
+import type { findAabbMatch2D, raycastClosest2D } from "./2d.js";
 import type { raycastShape2D, shapeCastAgainstShape2D } from "./lib/2d/collision/casts.js";
 import type { PibblPhysicsCollisionEvent2D, PibblPhysicsQueryHit2D } from "./lib/2d/types.js";
 import type { PibblPhysicsContactInspection2D } from "./lib/2d/inspection-types.js";
@@ -36,7 +36,7 @@ export type PibblPhysicsTransform2D = PibblPhysicsPose2D;
  *
  * @see {@link PibblPhysicsVector2}
  * @see {@link boundsOfShape2D}
- * @see {@link queryAabb2D}
+ * @see {@link findAabbMatch2D}
  */
 export interface PibblPhysicsAabb2D {
     /** Lower bound of the coordinate or sampling interval. See {@link PibblPhysicsVector2}. */
@@ -49,7 +49,7 @@ export interface PibblPhysicsAabb2D {
  *
  * @see {@link PibblPhysicsVector2}
  * @see {@link raycastShape2D}
- * @see {@link raycast2D}
+ * @see {@link raycastClosest2D}
  */
 export interface PibblPhysicsRay2D {
     /** Origin of the transform or geometric query. See {@link PibblPhysicsVector2}. */