@menapo/machine 0.0.0-stage → 0.1.0

package/dist/index.js

@@ -0,0 +1,582 @@
+import { i as suggest, n as checkParts, r as fail, t as checkKeys } from "./dev-BAz6e3W-.js";
+import { a as start, d as CHECK, f as DEV, l as track, o as derivedClass, p as dev, r as run, s as storeClass, u as bit } from "./instance-BM2UqeXW.js";
+import { a as release, c as own, i as activate, n as wireParallel, o as BOUND, r as wireHistory, s as bind, t as DONE } from "./chart-BWjU2VF4.js";
+import { t as inspect } from "./inspect-BmyLUhcy.js";
+//#region src/core/bindable.ts
+/**
+* `bindable`: a prop the owner may control or leave to the machine (D9, as
+* spike S2 refined it). One transition serves both modes:
+*
+* - uncontrolled, the machine moves or stores the value and tells the owner
+*   through `on…Change`;
+* - controlled, a transition that would change the value runs its actions
+*   when the event is handled and asks the owner; only the move waits. When
+*   the owner's new value arrives, the machine takes the waiting transition's
+*   target, and the target's entry sees the event that asked. Props that do
+*   not grant it drop it (a veto); an owner that changes the value unasked
+*   moves the machine to the matching state.
+*
+* All of it lives here and reaches the core only through the
+* {@link Control} a `bindable()` value carries, so an app that never imports
+* `bindable` ships none of it.
+*/
+/** What entry actions see when the owner moves a bound boolean unasked. */
+const PROPS = { type: "machine.props" };
+/**
+* A controlled-or-uncontrolled prop: `open: bindable(false, { states: {
+* true: "open", false: "closed" } })` gives the owner `open`, `defaultOpen`
+* and `onOpenChange`; `value: bindable("")` is data that actions write as
+* `props.value = next`.
+*/
+const bindable = (value, options) => ({
+	[BOUND]: control,
+	value,
+	...options
+});
+const capital = (name) => name[0].toUpperCase() + name.slice(1);
+/** True when leaf `at` is inside `state`. */
+function inside(at, state) {
+	for (; at; at = at.up) if (at === state) return true;
+	return false;
+}
+const bounds = (machine) => machine.bd;
+const control = {
+	bind(machine, prop, name, bindable, proto) {
+		const { states, changed } = bindable;
+		const find = (path) => {
+			const state = machine.ss.find((s) => s.path === path);
+			if (CHECK && !state) fail("UNKNOWN_TARGET", machine.name, `bindable "${name}" names state "${path}", which does not exist; use a path from the root: ${machine.ss.map((s) => `"${s.path}"`).join(", ")}.`);
+			return state;
+		};
+		if (CHECK && changed !== void 0 && !machine.handled.has(changed)) {
+			const handled = [...machine.handled];
+			fail("UNKNOWN_EVENT", machine.name, `bindable "${name}" sends "${changed}" when the owner changes it, but no state handles it${suggest(changed, handled) || "."} Handle it in a state's \`on\`, or name an event one does.`);
+		}
+		const b = {
+			prop,
+			name,
+			bit: bit(1 + machine.nm.length - machine.pn.length + prop),
+			default: `default${capital(name)}`,
+			change: `on${capital(name)}Change`,
+			yes: states && find(states.true),
+			no: states && find(states.false),
+			changed
+		};
+		bounds(machine).push(b);
+		Object.defineProperty(proto, name, {
+			get() {
+				const instance = this.i;
+				track(b.bit);
+				const given = instance.o[name];
+				if (given !== void 0) return given;
+				if (!b.yes) return this.v[prop];
+				track(1);
+				return inside(instance.s, b.yes);
+			},
+			set(value) {
+				const owner = this.i.o;
+				if (DEV) {
+					if (b.yes) fail("BOUND_WRITE", machine.name, `props.${name} follows the state; move to "${b.yes.path}" or "${b.no.path}" instead of writing it.`);
+					if (!dev.acting) fail("CONTEXT_WRITE", machine.name, `props.${name} was written outside an action. Write it in a transition's \`do\`, \`entry\` or \`exit\`, and send an event from here instead.`);
+				}
+				const controlled = owner[name] !== void 0;
+				if ((controlled ? owner[name] : this.v[prop]) === value) return;
+				if (!controlled) {
+					this.v[prop] = value;
+					this.m |= b.bit;
+				}
+				owner[b.change]?.(value);
+			}
+		});
+	},
+	initial(instance, leaf) {
+		const owner = instance.o;
+		for (const b of bounds(instance.M)) {
+			const given = owner[b.name] !== void 0 ? owner[b.name] : owner[b.default];
+			if (given === void 0) continue;
+			if (!b.yes) instance.props.v[b.prop] = given;
+			else if (!!given !== inside(leaf, b.yes)) leaf = (given ? b.yes : b.no).lf;
+		}
+		return leaf;
+	},
+	hold(instance, rule) {
+		for (const b of bounds(instance.M)) {
+			if (!b.yes || instance.o[b.name] === void 0) continue;
+			const next = inside(rule.to.lf, b.yes);
+			if (inside(instance.s, b.yes) === next) continue;
+			run(rule.do, instance);
+			instance.p = {
+				to: rule.to,
+				event: instance.event,
+				b
+			};
+			instance.o[b.change]?.(next);
+			return true;
+		}
+		return false;
+	},
+	moved(instance, from) {
+		for (const b of bounds(instance.M)) {
+			if (!b.yes || instance.o[b.name] !== void 0) continue;
+			const now = inside(instance.s, b.yes);
+			if (now !== inside(from, b.yes)) {
+				instance.props.m |= b.bit;
+				instance.o[b.change]?.(now);
+			}
+		}
+	},
+	own(instance, previous) {
+		for (const b of bounds(instance.M)) {
+			const value = instance.o[b.name];
+			if (value !== previous[b.name]) {
+				instance.props.m |= b.bit;
+				if (b.changed && value !== void 0) instance.dispatch({
+					type: b.changed,
+					value
+				});
+			}
+			if (!b.yes) continue;
+			const pending = instance.p?.b === b ? instance.p : void 0;
+			if (pending) instance.p = void 0;
+			if (value === void 0 || !!value === inside(instance.s, b.yes)) continue;
+			if (pending && inside(pending.to.lf, b.yes) === !!value) {
+				instance.event = pending.event;
+				instance.move(pending.to, void 0);
+			} else {
+				instance.event = PROPS;
+				instance.move(value ? b.yes : b.no, void 0);
+			}
+		}
+	}
+};
+//#endregion
+//#region src/core/machine.ts
+/**
+* `defineMachine`: the config normalised once into tables (PLAN §5.2).
+* Each state becomes a record linked to its parent, numbered depth first
+* (so an ancestor's index is below its descendants'), with the leaf it
+* settles in when entered, its entry/exit/effect lists, `after` timers,
+* `always` rules and one `Map` from event name to what it does, its
+* ancestors' rules folded in after its own (D20).
+*/
+const STATE_KEYS = [
+	"initial",
+	"states",
+	"on",
+	"entry",
+	"exit",
+	"effect",
+	"after",
+	"always",
+	"type",
+	"done"
+];
+const MACHINE_KEYS = [
+	"name",
+	"context",
+	"props",
+	"events",
+	"derived",
+	"actions",
+	"guards",
+	"effects",
+	"initial",
+	"states",
+	"on",
+	"parts",
+	"expose"
+];
+const RULE_KEYS = [
+	"to",
+	"if",
+	"do"
+];
+const list = (value) => value === void 0 || Array.isArray(value) ? value : [value];
+const NOTHING = /* @__PURE__ */ new Map();
+/** Config → tables: what `defineMachine` does at runtime, and the plugin at build time ({@link prepared}). */
+function normalise(config) {
+	const name = CHECK ? config.name ?? "machine" : "";
+	const byPath = /* @__PURE__ */ new Map();
+	const states = [];
+	const root = {
+		i: -1,
+		path: ""
+	};
+	/** The raw config of `root`, then of each state. */
+	const raws = [config];
+	if (CHECK) checkKeys(config, MACHINE_KEYS, name, "the machine");
+	const where = (from) => from === root ? "the machine" : `"${from.path}"`;
+	const below = (up, key) => up === root ? key : `${up.path}.${key}`;
+	/** Dev only: the state and target being resolved, for `find`'s message; set before each call. */
+	let asked = [root, ""];
+	const find = (path) => {
+		const found = byPath.get(path);
+		if (CHECK && !found && asked[1] !== void 0) {
+			const [from, target] = asked;
+			const last = (p) => p.slice(p.lastIndexOf(".") + 1);
+			fail("UNKNOWN_TARGET", name, `${where(from)} → "${target}" does not exist${suggest(last(path), [...byPath.keys()].map(last)) || `; the states are ${[...byPath.keys()].map((p) => `"${p}"`).join(", ")}.`}`);
+		}
+		return found;
+	};
+	/**
+	* Named implementations (D8), in one map: the types keep each kind's
+	* names apart, and development rejects a name used in the wrong kind or
+	* declared in two.
+	*/
+	const named = {
+		...config.actions,
+		...config.guards,
+		...config.effects
+	};
+	if (CHECK) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const kind of [
+			"actions",
+			"guards",
+			"effects"
+		]) for (const key of Object.keys(config[kind] ?? {})) {
+			if (seen.has(key)) fail("NAME_CLASH", name, `"${key}" is declared in \`${kind}\` and in another of \`actions\`, \`guards\` and \`effects\`; give each its own name.`);
+			seen.add(key);
+		}
+	}
+	/** Functions as written, or the ones they name. */
+	const fns = (value) => value && list(value).map((f) => typeof f === "string" ? named[f] : f);
+	/** Dev only: each name in `value` is one of `config[kind]`. */
+	const known = (value, kind, from) => {
+		for (const f of list(value) ?? []) if (typeof f !== "function" && !config[kind]?.[f]) fail("UNKNOWN_NAME", name, `${where(from)} names "${String(f)}", which is not in \`${kind}\`${suggest(String(f), Object.keys(config[kind] ?? {})) || "."} Declare it in \`${kind}\`, or write the function in place.`);
+	};
+	/** Numbers `up`'s children depth first, then sets the leaf entering `up` settles in. */
+	const walk = (up, raw) => {
+		const children = raw.states;
+		if (children) {
+			for (const key of Object.keys(children)) {
+				const child = children[key];
+				const state = {
+					i: states.length,
+					path: below(up, key),
+					up,
+					fi: child.type === "final"
+				};
+				if (CHECK) {
+					if (/[.#]/.test(key)) fail("STATE_NAME", name, `state "${key}" has a "." or "#" in its name; targets use them as separators, so rename it.`);
+					checkKeys(child, STATE_KEYS, name, `state "${state.path}"`);
+					const type = child.type;
+					if (type !== void 0 && type !== "final" && typeof type !== "object") fail("BAD_TYPE", name, `"${state.path}" has \`type: ${JSON.stringify(type)}\`; a state's type is "final", or \`parallel\` imported from @menapo/machine (\`type: parallel\`).`);
+				}
+				byPath.set(state.path, state);
+				states.push(state);
+				raws.push(child);
+				walk(state, child);
+			}
+			if (CHECK && raw.initial === void 0 && typeof raw.type !== "object") fail("NO_INITIAL", name, `${up === root ? "the machine has no" : `"${up.path}" has child states but no`} \`initial\`; name one of: ${Object.keys(children).join(", ")}.`);
+		}
+		if (CHECK) asked = [up, raw.initial];
+		up.lf = children ? find(below(up, raw.initial))?.lf : up;
+	};
+	walk(root, config);
+	/** `#path` from the root, `.child` below `from`, else a sibling of `from` or of its nearest ancestor that has one. */
+	const resolve = (target, from) => {
+		if (CHECK) asked = [from, target];
+		if (target[0] === "#") return find(target.slice(1));
+		if (target[0] === ".") return find(below(from, target.slice(1)));
+		for (let up = from.up; up && up !== root; up = up.up) {
+			const found = byPath.get(`${up.path}.${target}`);
+			if (found) return found;
+		}
+		return find(target);
+	};
+	const rules = (transitions, from) => list(transitions).map((item) => {
+		if (CHECK && (typeof item !== "object" || item === null) && typeof item !== "string" && typeof item !== "function") fail("BAD_TRANSITION", name, `${where(from)} has a transition that is ${String(item)}; write a target name, an action, or { to, if, do }.`);
+		const rule = typeof item === "string" ? { to: item } : typeof item === "function" ? { do: item } : item;
+		if (CHECK) {
+			checkKeys(rule, RULE_KEYS, name, `a transition in ${where(from)}`);
+			known(rule.if, "guards", from);
+			known(rule.do, "actions", from);
+			if (rule.to === "") resolve("", from);
+		}
+		return {
+			to: rule.to && resolve(rule.to, from),
+			if: rule.if && fns(rule.if)[0],
+			do: fns(rule.do)
+		};
+	});
+	const handled = /* @__PURE__ */ new Set();
+	[root, ...states].forEach((state, k) => {
+		const raw = raws[k];
+		const up = state.up;
+		const inherited = up?.on ?? NOTHING;
+		let on = state.fi ? NOTHING : inherited;
+		if (raw.on && !state.fi) {
+			const folded = on = new Map(inherited);
+			for (const type of Object.keys(raw.on)) {
+				if (CHECK) {
+					const declared = config.events;
+					if (declared && !(type in declared)) fail("UNKNOWN_EVENT", name, `${where(state)} handles "${type}", which is not in \`events\`${suggest(type, Object.keys(declared)) || "."} Declare it in \`events\`.`);
+					handled.add(type);
+				}
+				const mine = rules(raw.on[type], state);
+				const outer = inherited.get(type);
+				folded.set(type, {
+					ev: outer?.ev ?? { type },
+					ru: outer ? mine.concat(outer.ru) : mine
+				});
+			}
+		}
+		if (CHECK) {
+			if (raw.done && raw.type?.kind !== "parallel") fail("DONE_KEY", name, `${where(state)} has \`done\`, which is taken when every region of a parallel state is final; give the state \`type: parallel\`, or use \`always\`.`);
+		}
+		if (CHECK && state.fi) {
+			const region = up !== root && (raws[up.up.i + 1]?.type)?.kind;
+			if (up !== root && region !== "parallel") fail("FINAL_STATE", name, `"${state.path}" is final but not top-level; a final state ends the machine at the top level, or a region of a parallel state, so move it or drop \`type: "final"\`.`);
+			for (const key of [
+				"states",
+				"on",
+				"effect",
+				"after",
+				"always"
+			]) if (raw[key]) fail("FINAL_STATE", name, `final state "${state.path}" has \`${key}\`, but the machine stops there; move it to another state.`);
+		}
+		const always = raw.always && rules(raw.always, state);
+		const after = raw.after;
+		state.on = on;
+		if (CHECK) {
+			known(raw.entry, "actions", state);
+			known(raw.exit, "actions", state);
+			known(raw.effect, "effects", state);
+		}
+		state.en = fns(raw.entry);
+		state.ex = fns(raw.exit);
+		state.ef = fns(raw.effect);
+		state.af = after && Object.keys(after).map((ms) => {
+			if (CHECK && !(Number(ms) >= 0)) fail("BAD_DELAY", name, `"${state.path}" has \`after: { ${ms}: … }\`; a delay is a number of milliseconds.`);
+			return [+ms, rules(after[ms], state)];
+		});
+		state.al = always && up?.al ? always.concat(up.al) : always || up?.al;
+	});
+	if (CHECK) checkParts(config, name, handled);
+	const context = config.context ?? {};
+	const fields = Object.keys(context);
+	const defaults = Object.values(context);
+	if (CHECK) {
+		for (const value of defaults) if (Array.isArray(value) || Object.getPrototypeOf(value ?? 0) === Object.prototype) Object.freeze(value);
+	}
+	const props = config.props ?? {};
+	const propNames = Object.keys(props);
+	const Props = propNames.length ? storeClass(propNames, 1 + fields.length, false) : void 0;
+	const derived = config.derived;
+	const tables = {
+		ss: states,
+		i0: root.lf,
+		df: defaults,
+		C: fields.length ? storeClass(fields, 1, true) : void 0,
+		pn: propNames,
+		pd: [],
+		Q: Props,
+		pl: [],
+		nm: fields.concat(propNames),
+		D: derived && derivedClass(Object.keys(derived), Object.values(derived)),
+		k: void 0,
+		bd: [],
+		c: config,
+		r: normalise,
+		A: activate,
+		X: release,
+		P: own
+	};
+	if (CHECK) Object.assign(tables, {
+		name,
+		handled
+	});
+	bind(tables, props);
+	for (const raw of raws) raw.type?.f?.(tables, raws, rules);
+	return tables;
+}
+/**
+* Defines a machine (PLAN §4.1): states, transitions, context, props and
+* events in one object, normalised once into tables. Context, props,
+* events, derived values, named implementations and the state tree are
+* inferred from it.
+*/
+const defineMachine = normalise;
+/**
+* The machine with some of its named `actions`, `guards` and `effects`
+* replaced (D8), for tests or reuse; `machine` itself is unchanged. Each
+* function is typed from the machine, as the ones it replaces.
+*/
+function provide(machine, implementations) {
+	const tables = machine;
+	const config = { ...tables.c };
+	for (const kind of [
+		"actions",
+		"guards",
+		"effects"
+	]) {
+		const given = implementations[kind];
+		if (DEV && given) {
+			for (const key of Object.keys(given)) if (!(key in (config[kind] ?? {}))) fail("UNKNOWN_NAME", config.name ?? "machine", `provide() was given ${kind}.${key}, which the machine does not declare${suggest(key, Object.keys(config[kind] ?? {})) || "."} Declare it in the machine's \`${kind}\` first.`);
+		}
+		config[kind] = {
+			...config[kind],
+			...given
+		};
+	}
+	return tables.r(config);
+}
+/** Declares an event's data in `events` (D7): `ADD: payload<{ by: number }>()`. */
+const payload = () => null;
+//#endregion
+//#region src/features/marks.ts
+/** The feature's mark on a raw state config, if it has one. */
+const markOf = (raw) => typeof raw?.type === "object" ? raw.type : void 0;
+//#endregion
+//#region src/features/history.ts
+/**
+* `history()` (PLAN §4.9): a pseudo-state that stands for where its parent
+* was when last exited. A transition to it enters that again: the parent's
+* active child (shallow, its own initial states below it) or its active
+* leaves (`history("deep")`); before the parent was ever exited, the
+* parent's initial state. It is never active itself.
+*
+* Its mark carries what prepares a machine's tables, which the normaliser
+* calls when it meets the mark: each history state is marked (`h`: deep or
+* not) and checked; `resume.ts` wires them. Importing it has no effect. A
+* machine with parallel states leaves both to `parallel`'s configurations,
+* which read the same marker and the same records. A compiled machine (M7)
+* has its tables prepared at build time, so it ships `resume.ts` alone.
+*/
+/** The machines whose history states are prepared. */
+const done = /* @__PURE__ */ new WeakSet();
+/** Prepares a machine's history states, then wires them: what the marks carry. */
+const prepare$1 = (tables, raws) => {
+	if (done.has(tables) || raws.some((raw) => markOf(raw)?.kind === "parallel")) return;
+	done.add(tables);
+	tables.ss.forEach((state, k) => {
+		const mark = markOf(raws[k + 1]);
+		if (mark?.kind !== "history") return;
+		const parent = state.up;
+		if (CHECK) {
+			if (parent.i < 0) fail("HISTORY", tables.name, `"${state.path}" is a history state of the machine itself, which is never exited; put it inside the state whose history it keeps.`);
+			if (`${parent.path}.${raws[parent.i + 1].initial}` === state.path) fail("HISTORY", tables.name, `"${parent.path}" starts in its history state "${state.path}"; make another state its \`initial\`.`);
+		}
+		state.h = !!mark.deep;
+	});
+	wireHistory(tables);
+};
+const SHALLOW = /* @__PURE__ */ Object.freeze({
+	kind: "history",
+	deep: false,
+	f: prepare$1
+});
+const DEEP = /* @__PURE__ */ Object.freeze({
+	kind: "history",
+	deep: true,
+	f: prepare$1
+});
+/**
+* A history pseudo-state: `resume: history()` returns to the child its
+* parent was last in, `history("deep")` to the very states inside it.
+*/
+const history = (type) => ({ type: type === "deep" ? DEEP : SHALLOW });
+//#endregion
+//#region src/features/job.ts
+/**
+* Starts `run(signal)` for the state whose effect calls it and returns the
+* cleanup that cancels it. `view` is the effect's view; `done` and
+* `error` name events the machine declares.
+*/
+function job(view, run, events) {
+	const controller = new AbortController();
+	let live = true;
+	const send = view.send;
+	const tell = (type, payload) => {
+		if (live && type) send(type, payload);
+	};
+	const work = run(controller.signal);
+	let stop;
+	if (typeof work === "function") stop = work;
+	else if (work && typeof work.stop === "function") {
+		const child = work;
+		stop = () => child.stop();
+		child.done.then(() => tell(events?.done, { data: child.context }));
+	} else if (work) work.then((data) => tell(events?.done, { data }), (error) => {
+		if (!live) return;
+		if (!events?.error) throw error;
+		tell(events.error, { error });
+	});
+	return (() => {
+		live = false;
+		controller.abort();
+		stop?.();
+	});
+}
+//#endregion
+//#region src/features/parallel.ts
+/**
+* `type: parallel` (PLAN §4.9, D12): a state whose children, its regions,
+* are all active at once. Only a machine that declares one ships this
+* module: `parallel` is imported to be written, and the mark carries what
+* prepares the machine's tables for the configurations of `chart.ts` (the
+* regions, initial children and subtrees of each state, the state that
+* declares each rule, a parallel state's `done`) and wires them, which the
+* normaliser calls when it meets the mark. Importing it has no effect.
+* A compiled machine (M7) has its tables prepared at build time, so it ships
+* `chart.ts` without this module.
+*/
+/** Prepares a machine with parallel states, then wires it: what the mark carries. */
+const prepare = (tables, raws, rules) => {
+	const states = tables.ss;
+	const root = states[0].up;
+	if (root.k) return;
+	const all = [root, ...states];
+	const byPath = new Map(states.map((s) => [s.path, s]));
+	for (const s of all) {
+		const k = s.i + 1;
+		const mark = markOf(raws[k]);
+		const first = raws[k].initial;
+		s.k = [];
+		s.hs = [];
+		s.p = mark?.kind === "parallel";
+		s.h = mark?.kind === "history" ? !!mark.deep : void 0;
+		s.n = first === void 0 ? void 0 : byPath.get(s === root ? first : `${s.path}.${first}`);
+		for (let up = s; up; up = up.up) up.e = s.i;
+		if (s.up) (s.h === void 0 ? s.up.k : s.up.hs).push(s);
+	}
+	if (CHECK) {
+		for (const s of states) if (s.h !== void 0 && s.up.n === s) fail("HISTORY", tables.name, `"${s.up.path}" starts in its history state "${s.path}"; make another state its \`initial\`.`);
+		if (tables.bd.some((b) => b.yes)) fail("PARALLEL", tables.name, "a bindable prop follows states (`bindable(…, { states })`) in a machine with parallel states, which is not supported yet; bind the value to data and move with events.");
+	}
+	/** Marks the first `count` rules of `list` as declared by `s`. */
+	const own = (list, count, s) => {
+		for (let k = 0; k < count; k++) list[k].s = s;
+	};
+	for (const s of all) {
+		for (const [type, handler] of s.on) {
+			const outer = s.up?.on.get(type);
+			if (outer !== handler) own(handler.ru, handler.ru.length - (outer?.ru.length ?? 0), s);
+		}
+		if (s.al && s.al !== s.up?.al) own(s.al, s.al.length - (s.up?.al?.length ?? 0), s);
+		for (const [, list] of s.af ?? []) own(list, list.length, s);
+		const done = raws[s.i + 1]?.done;
+		if (done && s.p) {
+			const list = rules(done, s);
+			own(list, list.length, s);
+			s.dn = {
+				rules: list,
+				event: { type: DONE.type }
+			};
+		}
+	}
+	wireParallel(tables);
+};
+/** Marks a state whose regions are all active at once: `editor: { type: parallel, states: { … } }`. */
+const parallel = /* @__PURE__ */ Object.freeze({
+	kind: "parallel",
+	f: prepare
+});
+//#endregion
+//#region src/parts/use.ts
+function useMachine() {
+	throw new Error("[machine:NO_PLUGIN] useMachine is resolved per framework by the Vite plugin; add machine() from @menapo/machine/vite to the Vite config's plugins. With it, reach useMachine from a module the plugin transforms (a script, a .vue or .svelte file), by import, re-export or import(), not through an object passed around.");
+}
+//#endregion
+export { bindable, defineMachine, history, inspect, job, parallel, payload, provide, start, useMachine };

package/dist/inspect-BmyLUhcy.js

@@ -0,0 +1,74 @@
+import { i as setHook } from "./instance-BM2UqeXW.js";
+//#region src/inspect.ts
+/**
+* `inspect` (PLAN D17, §5.8): how DevTools and `/test` watch machines. Each
+* event an instance takes becomes one step once it is handled: the event,
+* the state after it, and the context fields and props it changed, with
+* their new values.
+*
+* A step's changes are found by comparing each field with its value after
+* the previous step, so a queued event that changes a field again reports it
+* too. Only the last values are kept, never a snapshot per event (§9): with
+* context changed in place, snapshots would cost memory on every event and
+* still not make time travel safe.
+*
+* This module is the only one that sets the core's hook, so a bundle that
+* never imports `inspect` (every production build: DevTools add it in dev
+* only) drops the hook's calls along with it.
+*/
+const PROPS = { type: "machine.props" };
+let open = /* @__PURE__ */ new WeakMap();
+const watchers = /* @__PURE__ */ new Set();
+/** Context fields, then props, as the instance reads them (a controlled prop is the owner's). */
+function values(instance) {
+	const { nm: names, pn: propNames } = instance.M;
+	const fields = names.length - propNames.length;
+	const context = instance.context;
+	const props = instance.props;
+	return names.map((name, n) => (n < fields ? context : props)[name]);
+}
+function close(instance, record) {
+	const event = record.event;
+	if (!event) return;
+	record.event = void 0;
+	const now = values(instance);
+	const changed = {};
+	now.forEach((value, n) => {
+		if (!Object.is(value, record.values[n])) changed[instance.M.nm[n]] = value;
+	});
+	record.values = now;
+	const step = {
+		instance,
+		event,
+		state: instance.s.path,
+		changed
+	};
+	for (const watch of watchers) watch(step);
+}
+/** The hook: an event begins (`null`: owner props), or, with none, the instance is done. */
+function observe(instance, event) {
+	let record = open.get(instance);
+	if (!record) open.set(instance, record = {
+		values: values(instance),
+		event: void 0
+	});
+	else close(instance, record);
+	if (event !== void 0) record.event = event ?? PROPS;
+}
+/**
+* Calls `watch` with a {@link Step} for every event any instance takes from
+* now on, in order. Returns the function that stops watching.
+*/
+function inspect(watch) {
+	watchers.add(watch);
+	setHook(observe);
+	return () => {
+		watchers.delete(watch);
+		if (!watchers.size) {
+			setHook(void 0);
+			open = /* @__PURE__ */ new WeakMap();
+		}
+	};
+}
+//#endregion
+export { values as n, inspect as t };

package/dist/inspect-C3qosuCm.d.ts

@@ -0,0 +1,22 @@
+import { g as Instance, n as AnyEvent } from "./types-Bk8svtO6.js";
+//#region src/inspect.d.ts
+/** One event an instance took, once handled. */
+interface Step {
+  readonly instance: Instance;
+  /**
+   * `machine.start` first, `machine.after` for a timer, `machine.props` for
+   * new owner props; otherwise the event as sent.
+   */
+  readonly event: AnyEvent;
+  /** The active path after it. */
+  readonly state: string;
+  /** The context fields and props it changed, with their new values. */
+  readonly changed: Readonly<Record<string, unknown>>;
+}
+/**
+ * Calls `watch` with a {@link Step} for every event any instance takes from
+ * now on, in order. Returns the function that stops watching.
+ */
+declare function inspect(watch: (step: Step) => void): () => void;
+//#endregion
+export { inspect as n, Step as t };