@mantaq/traversal 0.1.2 → 0.3.0

package/dist/index.mjs

@@ -1,281 +1,463 @@
-import { Context } from "@mantaq/core";
+import { Context, isStateRef } from "@mantaq/core";
 import { Either } from "@mantaq/utils";
-//#region src/graph.ts
+// src/history.ts
+function entriesOfType(recordedEntries, options) {
+	return recordedEntries.filter((entry) => entry.type === options.type).map((entry) => entry.data);
+}
+/**
+* History records the runtime trace of an instrumented actor. A closure over
+* the entry list keeps the recorder mutable without exposing the raw array.
+*/
+function createHistory() {
+	const recordedEntries = [];
+	function append(entry) {
+		recordedEntries.push(entry);
+	}
+	function entries() {
+		return recordedEntries;
+	}
+	function stateVisits() {
+		return entriesOfType(recordedEntries, { type: "state_visit" });
+	}
+	function transitions() {
+		return entriesOfType(recordedEntries, { type: "transition" });
+	}
+	function effects() {
+		return entriesOfType(recordedEntries, { type: "effect" });
+	}
+	function sends() {
+		return entriesOfType(recordedEntries, { type: "send" });
+	}
+	function visitedStates() {
+		const visited = /* @__PURE__ */ new Set();
+		for (const visit of stateVisits()) visited.add(visit.stateName);
+		return visited;
+	}
+	function firedTransitions() {
+		const fired = /* @__PURE__ */ new Set();
+		for (const record of transitions()) fired.add(`${record.from}:${record.event}`);
+		return fired;
+	}
+	function reset() {
+		recordedEntries.length = 0;
+	}
+	return {
+		append,
+		entries,
+		stateVisits,
+		transitions,
+		effects,
+		sends,
+		visitedStates,
+		firedTransitions,
+		reset
+	};
+}
+// src/graph-ids.ts
 const INITIAL_NODE_ID = "__initial__";
-function collectActiveStates(snapshot, prefix, activeSet) {
-	if (!snapshot || !snapshot.path) return;
+/** Source of `onAny` edges: any non-final state of the machine (`region.*` inside a region). */
+const ANY_NODE_NAME = "*";
+function isAnyNode(id) {
+	return id === "*" || id.endsWith(`.*`);
+}
+function collectActiveStates(snapshot, options) {
+	if (!snapshot.path) return;
 	const currentName = snapshot.path[snapshot.path.length - 1];
 	if (!currentName) return;
-	const fullId = nodeId(prefix, currentName);
-	activeSet.add(fullId);
-	if (snapshot.regions && !snapshot.done && !snapshot.error) for (const [regionName, regionSnap] of Object.entries(snapshot.regions)) collectActiveStates(regionSnap, regionName, activeSet);
+	const fullId = nodeId({
+		prefix: options.prefix,
+		name: currentName
+	});
+	options.activeSet.add(fullId);
+	if (snapshot.regions && !snapshot.done && !snapshot.error) for (const [regionName, regionSnapshot] of Object.entries(snapshot.regions)) collectActiveStates(regionSnapshot, {
+		prefix: regionName,
+		activeSet: options.activeSet
+	});
 }
-function nodeId(prefix, name) {
-	return prefix ? `${prefix}.${name}` : name;
+function nodeId(identity) {
+	return identity.prefix ? `${identity.prefix}.${identity.name}` : identity.name;
 }
-function buildNodesFromStates(states, activeSet, pathPrefix) {
-	return states.map((stateRef) => {
-		const nid = nodeId(pathPrefix, stateRef.name);
-		return {
-			id: nid,
-			label: stateRef.name,
-			isActive: activeSet.has(nid),
-			isFinal: stateRef.isFinal
-		};
+function collectActorsFromSnapshot(snapshot) {
+	const activeSet = /* @__PURE__ */ new Set();
+	collectActiveStates(snapshot, {
+		prefix: "",
+		activeSet
 	});
+	return activeSet;
+}
+// src/is-handler-result.ts
+function isHandlerResult(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const candidate = value;
+	return (candidate.state === void 0 || typeof candidate.state === "object" && candidate.state !== null && typeof candidate.state.name === "string") && (candidate.emit === void 0 || Array.isArray(candidate.emit));
 }
-function invokeHandler(handler, eventId, context, actor) {
+// src/graph-edges.ts
+function invokeHandler(handler, options) {
 	return Either.from(() => {
 		const result = handler({
-			type: eventId,
+			type: options.eventId,
 			payload: {}
 		}, {
-			context: new Context(() => context, () => {}),
-			actor
+			context: Context({
+				get: () => options.context,
+				set: () => {}
+			}),
+			actor: options.actor
 		});
-		return {
-			targetName: result?.state?.name,
-			emitNames: result?.emit?.map((e) => e.type).filter((type) => Boolean(type)) ?? []
+		return isHandlerResult(result) ? {
+			targetName: result.state?.name,
+			emitNames: result.emit?.map((emitted) => emitted.type).filter((eventType) => Boolean(eventType)) ?? []
+		} : {
+			targetName: void 0,
+			emitNames: []
 		};
 	});
 }
-function upsertEdge(sink, traversal, eventId, handled) {
-	const undetermined = !handled.targetName;
-	const targetId = handled.targetName ? nodeId(traversal.pathPrefix, handled.targetName) : `${sink.sourceId}-undetermined-${eventId}`;
-	const edgeId = `${sink.sourceId}-${eventId}-${targetId}`;
-	const existing = sink.edgeMap.get(edgeId);
-	if (existing) existing.contexts.push(sink.ctxName);
-	else sink.edgeMap.set(edgeId, {
-		id: edgeId,
-		source: sink.sourceId,
-		target: targetId,
-		label: eventId,
-		isActive: traversal.activeSet.has(sink.sourceId),
-		isInternal: traversal.internalIds?.has(eventId),
-		isUndetermined: undetermined,
-		contexts: [sink.ctxName],
-		...handled.emitNames.length > 0 && { payload: { action: `emit(${handled.emitNames.join(", ")})` } }
+function probeAll(registration, pass) {
+	const probes = [];
+	for (const ctxName of pass.traversal.contextNames) {
+		const sampleContext = pass.traversal.contexts[ctxName];
+		if (sampleContext === void 0) continue;
+		const handled = Either.getRight(invokeHandler(registration.handler, {
+			eventId: registration.eventId,
+			context: sampleContext,
+			actor: pass.traversal.actor
+		}));
+		if (handled !== void 0) probes.push({
+			ctxName,
+			handled
+		});
+	}
+	return probes;
+}
+/**
+* One edge per declared target, a `stay` edge when `to` is empty, or one
+* undetermined edge when the actor carries no declaration. Probing only labels
+* edges: which sample contexts reach each target, and what it emits.
+*/
+function addRegistration(registration, pass) {
+	const probes = probeAll(registration, pass);
+	const declared = registration.declared ?? [];
+	const targets = declared.length > 0 ? declared : [void 0];
+	const undetermined = registration.declared === void 0;
+	for (const targetName of targets) {
+		const matching = undetermined ? probes : probes.filter((probe) => probe.handled.targetName === targetName);
+		const emitNames = [...new Set(matching.flatMap((probe) => probe.handled.emitNames))].sort();
+		const targetId = targetName ? nodeId({
+			prefix: pass.traversal.pathPrefix,
+			name: targetName
+		}) : pass.sourceId;
+		const suffix = targetName ? targetId : undetermined ? "undetermined" : "stay";
+		const edgeId = `${pass.sourceId}-${registration.eventId}-${suffix}`;
+		pass.edgeMap.set(edgeId, {
+			id: edgeId,
+			source: pass.sourceId,
+			target: targetId,
+			label: registration.eventId,
+			isActive: pass.isActive,
+			isInternal: pass.traversal.internalIds?.has(registration.eventId),
+			isUndetermined: undetermined,
+			isStay: !undetermined && targetName === void 0,
+			isDeclared: !undetermined,
+			contexts: matching.map((probe) => probe.ctxName),
+			...emitNames.length > 0 && { payload: { action: `emit(${emitNames.join(", ")})` } }
+		});
+	}
+}
+function registrations(handlers, declared) {
+	return Object.entries(handlers ?? {}).map(([eventId, handler]) => ({
+		eventId,
+		handler,
+		declared: declared?.[eventId]
+	}));
+}
+function stateEdges(edges) {
+	const sourceId = nodeId({
+		prefix: edges.traversal.pathPrefix,
+		name: edges.state.name
 	});
+	const pass = {
+		edgeMap: /* @__PURE__ */ new Map(),
+		sourceId,
+		isActive: edges.traversal.activeSet.has(sourceId),
+		traversal: edges.traversal
+	};
+	const own = registrations(edges.transitions[edges.state.name], edges.targets[edges.state.name]);
+	for (const registration of own) addRegistration(registration, pass);
+	return [...pass.edgeMap.values()];
+}
+/**
+* `onAny` edges leave one `*` source, once per target: "from any non-final
+* state". Expanding them per state would claim source/target pairs the code
+* never states. A state's own handler for the same event runs first; when it
+* stays, `onAny` may still transition, so both edges are kept.
+*/
+function anyEdges(edges) {
+	const prefix = edges.traversal.pathPrefix;
+	const pass = {
+		edgeMap: /* @__PURE__ */ new Map(),
+		sourceId: nodeId({
+			prefix,
+			name: "*"
+		}),
+		isActive: edges.states.some((state) => !state.isFinal && edges.traversal.activeSet.has(nodeId({
+			prefix,
+			name: state.name
+		}))),
+		traversal: edges.traversal
+	};
+	for (const registration of registrations(edges.transitions["Any"], edges.targets["Any"])) addRegistration(registration, pass);
+	return [...pass.edgeMap.values()];
+}
+function buildEdgesFromTransitions(edges) {
+	const scope = {
+		transitions: edges.transitions,
+		targets: edges.targets ?? {},
+		traversal: edges.traversal
+	};
+	return [...edges.states.flatMap((state) => stateEdges({
+		...scope,
+		state
+	})), ...anyEdges({
+		...scope,
+		states: edges.states
+	})];
 }
-function processStateTransitions(stateTransitions, pass) {
-	const stateTransitionedEvents = /* @__PURE__ */ new Set();
-	for (const [eventId, handler] of Object.entries(stateTransitions)) {
-		if (typeof handler !== "function") continue;
-		for (const ctxName of pass.traversal.contextNames) {
-			const sampleContext = pass.traversal.contexts[ctxName];
-			const handled = Either.getOrElse(invokeHandler(handler, eventId, sampleContext, pass.traversal.actor), () => ({
-				targetName: void 0,
-				emitNames: []
-			}));
-			if (handled.targetName) stateTransitionedEvents.add(eventId);
-			upsertEdge({
-				edgeMap: pass.edgeMap,
-				sourceId: pass.sourceId,
-				ctxName
-			}, pass.traversal, eventId, handled);
+// src/parse-graph.ts
+function parseStates(options) {
+	const states = options?.states;
+	if (!Array.isArray(states)) return [];
+	return states.filter((stateEntry) => typeof stateEntry === "object" && stateEntry !== null && typeof stateEntry.name === "string" && typeof stateEntry.isFinal === "boolean");
+}
+function parseTransitionMap(source) {
+	const dispatchMap = {};
+	if (typeof source !== "object" || source === null) return dispatchMap;
+	for (const [stateName, eventMap] of Object.entries(source)) {
+		if (typeof eventMap !== "object" || eventMap === null) continue;
+		for (const [eventType, handler] of Object.entries(eventMap)) {
+			if (typeof handler !== "function") continue;
+			(dispatchMap[stateName] ??= {})[eventType] = handler;
 		}
 	}
-	return stateTransitionedEvents;
-}
-function mergeAnyTransitions(anyTransitions, stateTransitionedEvents, pass) {
-	for (const [eventId, handler] of Object.entries(anyTransitions)) {
-		if (typeof handler !== "function") continue;
-		if (stateTransitionedEvents.has(eventId)) continue;
-		for (const ctxName of pass.traversal.contextNames) {
-			const sampleContext = pass.traversal.contexts[ctxName];
-			const handled = Either.getOrElse(invokeHandler(handler, eventId, sampleContext, pass.traversal.actor), () => ({
-				targetName: void 0,
-				emitNames: []
-			}));
-			upsertEdge({
-				edgeMap: pass.edgeMap,
-				sourceId: pass.sourceId,
-				ctxName
-			}, pass.traversal, eventId, handled);
+	return dispatchMap;
+}
+function parseTargetMap(source) {
+	const targetMap = {};
+	if (typeof source !== "object" || source === null) return targetMap;
+	for (const [stateName, eventMap] of Object.entries(source)) {
+		if (typeof eventMap !== "object" || eventMap === null) continue;
+		for (const [eventType, names] of Object.entries(eventMap)) {
+			if (!Array.isArray(names)) continue;
+			const declared = names.filter((name) => typeof name === "string");
+			(targetMap[stateName] ??= {})[eventType] = declared;
 		}
 	}
+	return targetMap;
 }
-function collectTransitionsForState(stateTransitions, anyTransitions, sourceId, traversal) {
-	const edgeMap = /* @__PURE__ */ new Map();
-	const pass = {
-		edgeMap,
-		sourceId,
-		traversal
-	};
-	const stateTransitionedEvents = stateTransitions ? processStateTransitions(stateTransitions, pass) : /* @__PURE__ */ new Set();
-	if (anyTransitions) mergeAnyTransitions(anyTransitions, stateTransitionedEvents, pass);
-	return edgeMap;
-}
-function buildEdgesFromTransitions(states, transitions, traversal) {
-	if (!transitions) return [];
-	const anyTransitions = transitions["Any"];
-	const edges = [];
-	for (const stateRef of states) {
-		const sourceId = nodeId(traversal.pathPrefix, stateRef.name);
-		const edgeMap = collectTransitionsForState(transitions[stateRef.name], anyTransitions, sourceId, traversal);
-		edges.push(...edgeMap.values());
+function parseInitialName(options) {
+	const initial = options?.initial;
+	if (initial === void 0 || initial === null) return void 0;
+	if (isStateRef(initial)) return initial.name;
+	const wrapped = initial;
+	return isStateRef(wrapped.state) ? wrapped.state.name : void 0;
+}
+function parseContextRecord(context) {
+	if (context === void 0 || context === null) return {};
+	return { ...context };
+}
+function parseInternalEventIds(options) {
+	const internal = options?.internal;
+	const eventIds = /* @__PURE__ */ new Set();
+	if (!Array.isArray(internal)) return eventIds;
+	for (const entry of internal) {
+		if (typeof entry !== "object" || entry === null || !("type" in entry)) continue;
+		const eventType = entry.type;
+		if (typeof eventType === "string") eventIds.add(eventType);
 	}
-	return edges;
+	return eventIds;
 }
-function addNodesForActor(actor, pathPrefix, activeSet) {
-	return buildNodesFromStates(actor.options?.states ?? [], activeSet, pathPrefix);
+// src/graph.ts
+function buildNodesFromStates(states, options) {
+	return states.map((stateEntry) => {
+		const graphId = nodeId({
+			prefix: options.pathPrefix,
+			name: stateEntry.name
+		});
+		return {
+			id: graphId,
+			label: stateEntry.name,
+			isActive: options.activeSet.has(graphId),
+			isFinal: stateEntry.isFinal
+		};
+	});
 }
-function addEdgesForActor(actor, traversal) {
-	return buildEdgesFromTransitions(actor.options?.states ?? [], actor.options?.transitions, traversal);
+function addNodesForActor(actor, layout) {
+	const nodes = buildNodesFromStates(parseStates(actor.options), {
+		activeSet: layout.activeSet,
+		pathPrefix: layout.pathPrefix
+	});
+	const anyTransitions = parseTransitionMap(actor.options?.transitions)["Any"];
+	if (anyTransitions !== void 0 && Object.keys(anyTransitions).length > 0) {
+		const id = nodeId({
+			prefix: layout.pathPrefix,
+			name: "*"
+		});
+		nodes.push({
+			id,
+			label: "any state",
+			isActive: false,
+			isFinal: false,
+			isAny: true
+		});
+	}
+	return nodes;
 }
-function recurseRegions(actor, traversal) {
+function addEdgesForActor(actor, layout) {
+	return buildEdgesFromTransitions({
+		states: parseStates(actor.options),
+		transitions: parseTransitionMap(actor.options?.transitions),
+		targets: parseTargetMap(actor.options?.targets),
+		traversal: layout.traversal
+	});
+}
+function recurseRegions(actor, layout) {
 	const nodes = [];
-	const edges = [];
+	const childEdges = [];
 	if (actor.regions) for (const [regionName, childActor] of Object.entries(actor.regions)) {
-		const child = buildForActor(childActor, {
-			...traversal,
-			pathPrefix: nodeId(traversal.pathPrefix, regionName)
-		});
+		const child = buildForActor(childActor, { traversal: {
+			...layout.traversal,
+			pathPrefix: nodeId({
+				prefix: layout.traversal.pathPrefix,
+				name: regionName
+			})
+		} });
 		nodes.push(...child.nodes);
-		edges.push(...child.edges);
+		childEdges.push(...child.edges);
 	}
 	return {
 		nodes,
-		edges
+		edges: childEdges
 	};
 }
-function addEffectSelfLoops(actor, pathPrefix, activeSet) {
-	const edges = [];
+function readEffect(entry) {
+	if (typeof entry !== "object" || entry === null) return [];
+	const name = Reflect.get(entry, "name");
+	if (typeof name !== "string") return [];
+	const sends = Reflect.get(entry, "sends");
+	return [{
+		name,
+		sends: Array.isArray(sends) ? sends.filter((type) => typeof type === "string") : null
+	}];
+}
+function addEffectSelfLoops(actor, layout) {
+	const selfLoops = [];
 	const effects = actor.options?.effects;
 	if (effects) {
-		for (const [stateName, fns] of Object.entries(effects)) if (Array.isArray(fns) && fns.length > 0) {
-			const sid = nodeId(pathPrefix, stateName);
-			edges.push({
-				id: `${sid}-effect:${stateName}-${sid}`,
-				source: sid,
-				target: sid,
+		for (const [stateName, effectFns] of Object.entries(effects)) if (Array.isArray(effectFns) && effectFns.length > 0) {
+			const loopId = nodeId({
+				prefix: layout.pathPrefix,
+				name: stateName
+			});
+			selfLoops.push({
+				id: `${loopId}-effect:${stateName}-${loopId}`,
+				source: loopId,
+				target: loopId,
 				label: `effect:${stateName}`,
-				isActive: activeSet.has(sid),
-				isInternal: true
+				isActive: layout.activeSet.has(loopId),
+				isInternal: true,
+				contexts: [],
+				effects: effectFns.flatMap((entry) => readEffect(entry))
 			});
 		}
 	}
-	return edges;
+	return selfLoops;
 }
-function buildForActor(actor, traversal) {
+function buildForActor(actor, layout) {
 	if (!actor) return {
 		nodes: [],
 		edges: []
 	};
-	const nodes = addNodesForActor(actor, traversal.pathPrefix, traversal.activeSet);
-	const edges = addEdgesForActor(actor, traversal);
-	const region = recurseRegions(actor, traversal);
+	const nodes = addNodesForActor(actor, {
+		pathPrefix: layout.traversal.pathPrefix,
+		activeSet: layout.traversal.activeSet
+	});
+	const actorEdges = addEdgesForActor(actor, { traversal: layout.traversal });
+	const region = recurseRegions(actor, { traversal: layout.traversal });
 	nodes.push(...region.nodes);
-	edges.push(...region.edges);
-	edges.push(...addEffectSelfLoops(actor, traversal.pathPrefix, traversal.activeSet));
+	actorEdges.push(...region.edges);
+	actorEdges.push(...addEffectSelfLoops(actor, {
+		pathPrefix: layout.traversal.pathPrefix,
+		activeSet: layout.traversal.activeSet
+	}));
 	return {
 		nodes,
-		edges
+		edges: actorEdges
 	};
 }
-function addInitialNode(actor, nodes, edges) {
-	const initialName = actor.options?.initial?.name;
+function addInitialNode(actor, layout) {
+	const initialName = parseInitialName(actor.options);
 	if (!initialName) return;
-	const initNodeId = nodeId("", INITIAL_NODE_ID);
-	const targetId = nodeId("", initialName);
-	nodes.push({
+	const initNodeId = INITIAL_NODE_ID;
+	const targetId = nodeId({
+		prefix: "",
+		name: initialName
+	});
+	layout.nodes.push({
 		id: initNodeId,
 		label: "",
 		isActive: false,
 		isFinal: false,
 		isInitial: true
 	});
-	edges.push({
+	layout.graphEdges.push({
 		id: `${initNodeId}->${targetId}`,
 		source: initNodeId,
 		target: targetId,
 		label: "",
-		isActive: true
+		isActive: true,
+		contexts: []
 	});
 }
-function collectActorsFromSnapshot(snapshot) {
-	const activeSet = /* @__PURE__ */ new Set();
-	collectActiveStates(snapshot, "", activeSet);
-	return activeSet;
-}
-function collectNamedContexts(options) {
-	return options?.sampleContexts ?? (options?.sampleContext ? { default: options.sampleContext } : void 0);
+function collectNamedContexts(named) {
+	return named?.sampleContexts ?? (named?.sampleContext ? { default: named.sampleContext } : void 0);
 }
 function buildGraph(actor, options) {
 	if (!actor) return {
 		nodes: [],
 		edges: []
 	};
-	return Either.match(Either.from(() => {
+	return Either.getOrElse(Either.from(() => {
 		const activeSet = collectActorsFromSnapshot(actor.snapshot());
-		const contexts = collectNamedContexts(options) ?? { default: { ...actor.context } };
-		const { nodes, edges } = buildForActor(actor, {
+		const contexts = collectNamedContexts(options) ?? { default: parseContextRecord(actor.context) };
+		const built = buildForActor(actor, { traversal: {
 			actor,
 			pathPrefix: "",
 			activeSet,
 			internalIds: options?.internalIds,
 			contexts,
 			contextNames: Object.keys(contexts)
+		} });
+		addInitialNode(actor, {
+			nodes: built.nodes,
+			graphEdges: built.edges
 		});
-		addInitialNode(actor, nodes, edges);
 		return {
-			nodes,
-			edges
+			nodes: built.nodes,
+			edges: built.edges
 		};
-	}), (error) => {
-		throw error;
-	}, (result) => result);
-}
-//#endregion
-//#region src/history.ts
-const entriesMap = /* @__PURE__ */ new WeakMap();
-function entriesOfType(entries, type) {
-	return entries.filter((e) => e.type === type).map((e) => e.data);
-}
-var History = class {
-	constructor() {
-		entriesMap.set(this, []);
-	}
-	append(entry) {
-		entriesMap.get(this).push(entry);
-	}
-	entries() {
-		return entriesMap.get(this);
-	}
-	stateVisits() {
-		return entriesOfType(entriesMap.get(this), "state_visit");
-	}
-	transitions() {
-		return entriesOfType(entriesMap.get(this), "transition");
-	}
-	effects() {
-		return entriesOfType(entriesMap.get(this), "effect");
-	}
-	sends() {
-		return entriesOfType(entriesMap.get(this), "send");
-	}
-	visitedStates() {
-		const result = /* @__PURE__ */ new Set();
-		for (const visit of this.stateVisits()) result.add(visit.stateName);
-		return result;
-	}
-	firedTransitions() {
-		const result = /* @__PURE__ */ new Set();
-		for (const t of this.transitions()) result.add(`${t.from}:${t.event}`);
-		return result;
-	}
-	reset() {
-		const arr = entriesMap.get(this);
-		arr.length = 0;
+	}), { onLeft: () => ({
+		nodes: [],
+		edges: []
+	}) });
+}
+// src/instrument.ts
+function wrapWithProxy(actor, wrapped) {
+	function forwardOn(event, options) {
+		return actor.on(event, options);
 	}
-};
-//#endregion
-//#region src/instrument.ts
-function wrapWithProxy(actor, history) {
-	const origSend = actor.send.bind(actor);
 	return {
 		get history() {
-			return history;
+			return wrapped.history;
 		},
 		get state() {
 			return actor.state;
@@ -293,181 +475,226 @@ function wrapWithProxy(actor, history) {
 			return actor.options;
 		},
 		send(event) {
-			trackSendEvent(history, event);
-			origSend(event);
+			trackSendEvent({
+				history: wrapped.history,
+				sentEvent: event
+			});
+			actor.send(event);
 		},
 		snapshot() {
 			return actor.snapshot();
 		},
-		on: actor.on.bind(actor),
+		on: forwardOn,
 		inject: actor.inject.bind(actor),
 		dispose: actor.dispose.bind(actor),
 		recover: actor.recover.bind(actor),
 		settled: actor.settled.bind(actor)
 	};
 }
-function recordTransition(history, rec) {
-	history.append({
+function recordTransition(recorder) {
+	recorder.history.append({
 		type: "transition",
 		data: {
-			from: rec.from,
-			event: rec.event,
-			to: rec.to,
-			timestamp: Date.now()
+			from: recorder.record.from,
+			event: recorder.record.event,
+			to: recorder.record.to
 		}
 	});
-	if (!rec.transitioned) return;
-	history.append({
+	if (!recorder.record.transitioned) return;
+	recorder.history.append({
 		type: "state_visit",
-		data: {
-			stateName: rec.to,
-			timestamp: Date.now()
-		}
+		data: { stateName: recorder.record.to }
 	});
-	if ((rec.effects[rec.to] ?? []).length > 0) history.append({
+	for (const effectName of recorder.record.effectNames) recorder.history.append({
 		type: "effect",
 		data: {
-			stateName: rec.to,
-			timestamp: Date.now()
+			stateName: recorder.record.to,
+			effectName
 		}
 	});
 }
-function trackSendEvent(history, event) {
-	const eventId = event?.type ?? "unknown";
-	history.append({
+function trackSendEvent(tracking) {
+	const eventType = typeof tracking.sentEvent === "object" && tracking.sentEvent !== null && "type" in tracking.sentEvent ? tracking.sentEvent.type : "unknown";
+	tracking.history.append({
 		type: "send",
-		data: {
-			event: eventId,
-			timestamp: Date.now()
-		}
+		data: { event: String(eventType) }
 	});
 }
+function prefixId(identity) {
+	return identity.prefix ? `${identity.prefix}.${identity.name}` : identity.name;
+}
 function instrument(actor) {
-	const history = new History();
-	history.append({
+	const history = createHistory();
+	const wrapped = wrapWithProxy(actor, { history });
+	attach(actor, {
+		history,
+		prefix: ""
+	});
+	return wrapped;
+}
+function attach(childActor, branch) {
+	branch.history.append({
 		type: "state_visit",
-		data: {
-			stateName: actor.state.name,
-			timestamp: Date.now()
-		}
+		data: { stateName: prefixId({
+			prefix: branch.prefix,
+			name: childActor.state.name
+		}) }
 	});
-	const wrapped = wrapWithProxy(actor, history);
-	const effectsByState = actor.options?.effects ?? {};
-	actor.on("transition", ({ event, from, to, transitioned }) => {
-		recordTransition(history, {
-			from,
-			to,
-			event: event.type,
-			transitioned,
-			effects: effectsByState
+	childActor.on("transition", { fn: ({ event, from, to, transitioned, effects }) => {
+		recordTransition({
+			history: branch.history,
+			record: {
+				from: prefixId({
+					prefix: branch.prefix,
+					name: from
+				}),
+				to: prefixId({
+					prefix: branch.prefix,
+					name: to
+				}),
+				event: event.type,
+				transitioned,
+				effectNames: effects
+			}
 		});
+	} });
+	for (const [regionName, regionChild] of Object.entries(childActor.regions ?? {})) attach(regionChild, {
+		history: branch.history,
+		prefix: prefixId({
+			prefix: branch.prefix,
+			name: regionName
+		})
 	});
-	return wrapped;
 }
-//#endregion
-//#region src/algorithms.ts
+// src/algorithms.ts
 function buildAdjacency(graph) {
-	const adj = {};
-	for (const node of graph.nodes) adj[node.id] = [];
-	for (const edge of graph.edges) if (adj[edge.source]) adj[edge.source].push({
+	const adjacency = {};
+	for (const node of graph.nodes) adjacency[node.id] = [];
+	for (const edge of graph.edges) if (adjacency[edge.source]) adjacency[edge.source].push({
 		target: edge.target,
 		label: edge.label
 	});
-	return adj;
+	return adjacency;
 }
-function bfsWalk(adj, start, visit) {
+function bfsWalk(adjacency, walk) {
 	const visited = {};
-	const queue = [start];
+	const queue = [walk.start];
 	while (queue.length > 0) {
 		const current = queue.shift();
-		if (visited[current]) continue;
+		if (current === void 0 || visited[current]) continue;
 		visited[current] = true;
-		if (visit(current)) break;
-		const neighbors = adj[current] || [];
-		for (let i = 0; i < neighbors.length; i++) {
-			const target = neighbors[i].target;
-			if (!visited[target]) queue.push(target);
-		}
+		if (walk.visit(current)) break;
+		for (const neighbor of adjacency[current] ?? []) if (!visited[neighbor.target]) queue.push(neighbor.target);
 	}
 	return visited;
 }
-function reachable(graph, fromId, toId) {
-	return bfsWalk(buildAdjacency(graph), fromId, (node) => node === toId)[toId] === true;
+function reachable(graph, endpoints) {
+	return bfsWalk(buildAdjacency(graph), {
+		start: endpoints.fromId,
+		visit: (nodeId) => nodeId === endpoints.toId
+	})[endpoints.toId] === true;
 }
-function allPaths(graph, fromId, toId) {
-	const adj = buildAdjacency(graph);
+function allPaths(graph, endpoints) {
+	const adjacency = buildAdjacency(graph);
 	const results = [];
 	const visited = {};
-	function dfs(current, path) {
-		if (current === toId) {
-			results.push(path.slice());
+	function dfs(cursor) {
+		if (cursor.nodeId === endpoints.toId) {
+			results.push(cursor.path.slice());
 			return;
 		}
-		if (visited[current]) return;
-		visited[current] = true;
-		const neighbors = adj[current] || [];
-		for (let i = 0; i < neighbors.length; i++) {
-			path.push(neighbors[i].target);
-			dfs(neighbors[i].target, path);
-			path.pop();
+		if (visited[cursor.nodeId]) return;
+		visited[cursor.nodeId] = true;
+		for (const neighbor of adjacency[cursor.nodeId] ?? []) {
+			cursor.path.push(neighbor.target);
+			dfs({
+				nodeId: neighbor.target,
+				path: cursor.path
+			});
+			cursor.path.pop();
 		}
-		delete visited[current];
+		delete visited[cursor.nodeId];
 	}
-	dfs(fromId, [fromId]);
+	dfs({
+		nodeId: endpoints.fromId,
+		path: [endpoints.fromId]
+	});
 	return results;
 }
 function findCycles(graph) {
-	const adj = buildAdjacency(graph);
+	const adjacency = buildAdjacency(graph);
 	const cycles = [];
+	const seen = /* @__PURE__ */ new Set();
 	const visited = {};
 	const inStack = {};
 	const path = [];
-	function dfs(node) {
-		if (inStack[node]) {
-			const cycleStart = path.indexOf(node);
-			if (cycleStart !== -1) cycles.push(path.slice(cycleStart).concat(node));
+	/**
+	* A cycle ends with its start node (e.g. the list a, b, a). The body is
+	* every element but the last. Rotate the body so it starts at the
+	* lexicographically smallest id, giving every rotation of a cycle the same
+	* canonical key.
+	*/
+	function rotateToMin(cycleNodes) {
+		const body = cycleNodes.slice(0, -1);
+		let minIndex = 0;
+		let minValue = body[0] ?? "";
+		for (const [index, candidate] of body.entries()) if (candidate < minValue) {
+			minValue = candidate;
+			minIndex = index;
+		}
+		return body.slice(minIndex).concat(body.slice(0, minIndex)).join(":");
+	}
+	function dfs(nodeId) {
+		if (inStack[nodeId]) {
+			const cycleStart = path.indexOf(nodeId);
+			if (cycleStart !== -1) {
+				const cycle = path.slice(cycleStart).concat(nodeId);
+				const key = rotateToMin(cycle);
+				if (!seen.has(key)) {
+					seen.add(key);
+					cycles.push(cycle);
+				}
+			}
 			return;
 		}
-		if (visited[node]) return;
-		visited[node] = true;
-		inStack[node] = true;
-		path.push(node);
-		const neighbors = adj[node] || [];
-		for (let i = 0; i < neighbors.length; i++) dfs(neighbors[i].target);
+		if (visited[nodeId]) return;
+		visited[nodeId] = true;
+		inStack[nodeId] = true;
+		path.push(nodeId);
+		for (const neighbor of adjacency[nodeId] ?? []) dfs(neighbor.target);
 		path.pop();
-		delete inStack[node];
+		delete inStack[nodeId];
+		delete visited[nodeId];
 	}
 	for (const node of graph.nodes) dfs(node.id);
 	return cycles;
 }
-function unreachableNodes(graph, fromId) {
-	const visited = bfsWalk(buildAdjacency(graph), fromId, () => false);
+function unreachableNodes(graph, options) {
+	const visited = bfsWalk(buildAdjacency(graph), {
+		start: options.fromId,
+		visit: () => false
+	});
 	const result = [];
 	for (const node of graph.nodes) if (!visited[node.id]) result.push(node.id);
 	return result;
 }
-function shortestPath(graph, fromId, toId) {
-	const adj = buildAdjacency(graph);
+function shortestPath(graph, endpoints) {
+	const adjacency = buildAdjacency(graph);
 	const visited = {};
 	const queue = [{
-		node: fromId,
-		path: [fromId]
+		node: endpoints.fromId,
+		path: [endpoints.fromId]
 	}];
 	while (queue.length > 0) {
-		const { node: current, path } = queue.shift();
-		if (current === toId) return path;
-		if (visited[current]) continue;
-		visited[current] = true;
-		const neighbors = adj[current] || [];
-		for (let i = 0; i < neighbors.length; i++) {
-			const target = neighbors[i].target;
-			if (!visited[target]) queue.push({
-				node: target,
-				path: path.concat(target)
-			});
-		}
+		const candidate = queue.shift();
+		if (candidate === void 0) break;
+		if (candidate.node === endpoints.toId) return candidate.path;
+		if (visited[candidate.node]) continue;
+		visited[candidate.node] = true;
+		for (const neighbor of adjacency[candidate.node] ?? []) if (!visited[neighbor.target]) queue.push({
+			node: neighbor.target,
+			path: candidate.path.concat(neighbor.target)
+		});
 	}
-	return null;
 }
-//#endregion
-export { History, INITIAL_NODE_ID, allPaths, buildGraph, collectActiveStates, findCycles, instrument, reachable, shortestPath, unreachableNodes };
+export { ANY_NODE_NAME, INITIAL_NODE_ID, allPaths, buildGraph, collectActiveStates, createHistory, findCycles, instrument, isAnyNode, parseContextRecord, parseInitialName, parseInternalEventIds, parseStates, parseTransitionMap, reachable, shortestPath, unreachableNodes };