@0xbuff/throughline 0.0.0-stage → 0.0.2

package/dist/index.js

@@ -0,0 +1,1134 @@
+import { a as getAt, c as setAt, o as overlaps, s as parseTarget, t as describeFrame } from "./describe-ZC7v_r7z.js";
+// src/model.ts
+const VIEWS = [
+	"auto",
+	"text",
+	"number",
+	"array",
+	"stack",
+	"matrix",
+	"bits",
+	"record"
+];
+const GROUP_LAYOUTS = [
+	"row",
+	"column",
+	"tree"
+];
+var ProgramError = class extends Error {
+	diagnostics;
+	constructor(diagnostics) {
+		super(diagnostics.map(({ message, line, beat }) => `${line ? `Line ${line}: ` : beat !== void 0 ? `Step ${beat + 1}: ` : ""}${message}`).join("\n"));
+		this.diagnostics = diagnostics;
+		this.name = "ProgramError";
+	}
+};
+// src/limits.ts
+/** Fixed v1 safety ceilings, independent of machine speed or wall-clock timing. */
+const COMPILATION_LIMITS = Object.freeze({
+	sourceCharacters: 262144,
+	programUnits: 1e6,
+	traceUnits: 8e6,
+	entities: 200,
+	relations: 1e3,
+	steps: 2e3,
+	events: 1e4
+});
+/**
+* Account for expanded JSON, including repeated references. One unit per
+* UTF-16 code unit in strings/keys, eight per scalar/container. This is a
+* deterministic work/payload budget, not a claim about exact heap bytes.
+* Memoization makes shared immutable snapshots cheap to measure without
+* discounting their cost when serialized. Use a fresh budget for mutable data.
+*/
+function createBudget(name, limit) {
+	const sizes = /* @__PURE__ */ new WeakMap();
+	const visiting = /* @__PURE__ */ new WeakSet();
+	let total = 0;
+	const fail = (message) => {
+		throw new ProgramError([{ message: `${name}: ${message}` }]);
+	};
+	const check = (size) => {
+		if (size > limit) fail(`exceeds compilation limit (${limit} units).`);
+		return size;
+	};
+	const measure = (value, depth) => {
+		if (depth > 64) fail("JSON nesting exceeds the compilation limit.");
+		if (value === null || typeof value === "boolean") return 8;
+		if (typeof value === "string") return check(8 + value.length);
+		if (typeof value === "number" && Number.isFinite(value)) return 8;
+		if (typeof value !== "object" || value === null) return fail("expected finite JSON data.");
+		if (visiting.has(value)) fail("cyclic values are not JSON data.");
+		const cached = sizes.get(value);
+		if (cached !== void 0) return cached;
+		if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype) fail("expected plain JSON objects.");
+		visiting.add(value);
+		let size = 8;
+		if (Array.isArray(value)) for (const item of value) size = check(size + measure(item, depth + 1));
+		else for (const [key, item] of Object.entries(value)) if (item !== void 0) size = check(size + key.length + measure(item, depth + 1));
+		visiting.delete(value);
+		sizes.set(value, size);
+		return size;
+	};
+	return (value) => {
+		total = check(total + measure(value, 0));
+	};
+}
+function checkSourceSize(characters) {
+	if (characters > COMPILATION_LIMITS.sourceCharacters) throw new ProgramError([{ message: `Source exceeds compilation limit (${COMPILATION_LIMITS.sourceCharacters} characters).` }]);
+}
+// src/compiler.ts
+const owns = (object, key) => Object.hasOwn(object, key);
+const isValue = (value, depth = 0) => {
+	if (depth > 32) return false;
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every((item) => isValue(item, depth + 1));
+	return typeof value === "object" && value !== null && Object.getPrototypeOf(value) === Object.prototype && Object.values(value).every((item) => isValue(item, depth + 1));
+};
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const identifier = (value) => typeof value === "string" && /^[A-Za-z][\w-]*$/.test(value);
+function validateProgram(input) {
+	if (!record(input) || input.version !== 1 || !Array.isArray(input.entities) || !Array.isArray(input.relations) || !Array.isArray(input.beats)) throw new ProgramError([{ message: "Expected version: 1 and entities, relations, beats arrays." }]);
+	if (input.entities.length > COMPILATION_LIMITS.entities || input.relations.length > COMPILATION_LIMITS.relations || input.beats.length > COMPILATION_LIMITS.steps) throw new ProgramError([{ message: "Program exceeds limits (200 entities, 1000 relations, 2000 steps)." }]);
+	let eventCount = 0;
+	for (const beat of input.beats) {
+		if (record(beat) && Array.isArray(beat.events)) eventCount += beat.events.length;
+		if (eventCount > COMPILATION_LIMITS.events) throw new ProgramError([{ message: `Program exceeds ${COMPILATION_LIMITS.events} events.` }]);
+	}
+	createBudget("Program", COMPILATION_LIMITS.programUnits)(input);
+	const diagnostics = [];
+	if (input.groups !== void 0) {
+		if (!Array.isArray(input.groups) || input.groups.length > 200 || input.groups.some((group) => !record(group) || typeof group.name !== "string" || !GROUP_LAYOUTS.includes(group.layout))) diagnostics.push({ message: "Groups require a name and a row, column, or tree layout (at most 200)." });
+		else if (new Set(input.groups.map((group) => group.name)).size !== input.groups.length) diagnostics.push({ message: "Duplicate group name." });
+	}
+	const entities = /* @__PURE__ */ new Set();
+	const relations = /* @__PURE__ */ new Set();
+	for (const entity of input.entities) {
+		if (!record(entity) || !identifier(entity.id) || typeof entity.label !== "string" || !owns(entity, "value") || !isValue(entity.value) || entity.hidden !== void 0 && typeof entity.hidden !== "boolean" || entity.lane !== void 0 && typeof entity.lane !== "string" || entity.view !== void 0 && !VIEWS.includes(entity.view)) {
+			diagnostics.push({ message: `Each entity needs a valid id, label, JSON value, optional string lane, and optional view (${VIEWS.join(", ")}).` });
+			continue;
+		}
+		if (entities.has(entity.id)) diagnostics.push({ message: `Duplicate entity “${entity.id}”.` });
+		entities.add(entity.id);
+	}
+	for (const relation of input.relations) {
+		if (!record(relation) || !identifier(relation.id) || typeof relation.from !== "string" || typeof relation.to !== "string" || relation.hidden !== void 0 && typeof relation.hidden !== "boolean" || relation.label !== void 0 && typeof relation.label !== "string") {
+			diagnostics.push({ message: "Each relation needs an id, from, to, and optional string label." });
+			continue;
+		}
+		if (relations.has(relation.id)) diagnostics.push({ message: `Duplicate relation “${relation.id}”.` });
+		relations.add(relation.id);
+		if (!entities.has(relation.from) || !entities.has(relation.to)) diagnostics.push({ message: `Relation “${relation.id}” references an unknown entity.` });
+	}
+	input.beats.forEach((beat, index) => {
+		if (!record(beat) || typeof beat.label !== "string" || !Array.isArray(beat.events)) {
+			diagnostics.push({
+				message: "Each step needs a label and events array.",
+				beat: index
+			});
+			return;
+		}
+		const writes = [];
+		const visibility = /* @__PURE__ */ new Set();
+		for (const event of beat.events) {
+			const fail = (message) => diagnostics.push({
+				message,
+				beat: index,
+				line: record(event) && record(event.source) && Number.isInteger(event.source.line) ? Number(event.source.line) : void 0
+			});
+			if (!record(event)) {
+				fail("Expected an event object.");
+				continue;
+			}
+			if (event.op === "show" || event.op === "hide") {
+				const ids = event.kind === "node" ? entities : event.kind === "link" ? relations : null;
+				if (!ids || typeof event.id !== "string" || !ids.has(event.id)) fail(`Unknown ${String(event.kind)} “${String(event.id)}”.`);
+				const key = `${event.kind}:${event.id}`;
+				if (visibility.has(key)) fail(`Conflicting visibility for “${String(event.id)}” in one step.`);
+				visibility.add(key);
+			} else if (event.op === "set") {
+				const target = typeof event.target === "string" ? parseTarget(event.target) : null;
+				if (!target || !entities.has(target.id)) fail(`Unknown set target “${String(event.target)}”.`);
+				if (!owns(event, "value") || !isValue(event.value)) fail("set requires a finite JSON value.");
+				if (target) {
+					if (writes.some((write) => write.id === target.id && overlaps(write.path, target.path))) fail(`Conflicting writes to “${event.target}” in one step; split into separate steps.`);
+					writes.push(target);
+				}
+			} else if (event.op === "focus") {
+				if (!Array.isArray(event.targets) || event.targets.some((text) => {
+					const target = typeof text === "string" ? parseTarget(text) : null;
+					return !target || !entities.has(target.id);
+				})) fail("focus requires known entity ids, optionally with a position such as data[3].");
+			} else if (event.op === "send") {
+				if (typeof event.relation !== "string" || !relations.has(event.relation)) fail(`Unknown relation “${String(event.relation)}”.`);
+				if (owns(event, "value") && !isValue(event.value)) fail("send requires a finite JSON value.");
+			} else if (event.op === "note") {
+				if (typeof event.text !== "string") fail("note requires text.");
+			} else fail(`Unknown event operation “${String(event.op)}”.`);
+			if (event.source !== void 0 && (!record(event.source) || !Number.isInteger(event.source.line) || Number(event.source.line) < 1)) fail("Source line must be a positive integer.");
+		}
+		if (beat.source !== void 0 && (!record(beat.source) || !Number.isInteger(beat.source.line) || Number(beat.source.line) < 1)) diagnostics.push({
+			message: "Step source line must be a positive integer.",
+			beat: index
+		});
+	});
+	if (diagnostics.length) throw new ProgramError(diagnostics);
+}
+function reduceBeat(previous, events) {
+	const writes = /* @__PURE__ */ new Map();
+	const nodes = /* @__PURE__ */ new Map();
+	const links = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		if (event.op === "show" || event.op === "hide") (event.kind === "node" ? nodes : links).set(event.id, event.op === "hide");
+		if (event.op !== "set") continue;
+		const target = parseTarget(event.target);
+		if (!target) throw new Error(`Invalid target “${event.target}”.`);
+		writes.set(target.id, [...writes.get(target.id) ?? [], {
+			path: target.path,
+			value: event.value
+		}]);
+	}
+	const state = {
+		entities: previous.entities.map((entity) => {
+			const list = writes.get(entity.id);
+			return list || nodes.has(entity.id) ? {
+				...entity,
+				...nodes.has(entity.id) ? { hidden: nodes.get(entity.id) } : {},
+				value: list ? list.reduce((value, write) => setAt(value, write.path, write.value), entity.value) : entity.value
+			} : entity;
+		}),
+		relations: previous.relations.map((relation) => links.has(relation.id) ? {
+			...relation,
+			hidden: links.get(relation.id)
+		} : relation),
+		active: [...new Set(events.flatMap((event) => event.op === "focus" ? event.targets : event.op === "set" ? [event.target] : []))],
+		changed: events.flatMap((event) => event.op === "set" ? [event.target] : []),
+		transfers: events.flatMap((event) => event.op === "send" ? [{
+			relation: event.relation,
+			value: event.value
+		}] : []),
+		notes: events.flatMap((event) => event.op === "note" ? [event.text] : [])
+	};
+	for (const transfer of state.transfers) {
+		const relation = state.relations.find((candidate) => candidate.id === transfer.relation);
+		if (relation.hidden) throw new Error(`Cannot send along hidden link “${relation.id}”.`);
+		if (state.entities.some((entity) => entity.hidden && (entity.id === relation.from || entity.id === relation.to))) throw new Error(`Cannot send along “${relation.id}” with a hidden node.`);
+	}
+	return state;
+}
+function compileProgram(input) {
+	validateProgram(input);
+	const program = JSON.parse(JSON.stringify(input));
+	let state = {
+		entities: program.entities,
+		relations: program.relations,
+		active: [],
+		changed: [],
+		transfers: [],
+		notes: []
+	};
+	const frames = [{
+		index: 0,
+		label: "Initial state",
+		state,
+		events: []
+	}];
+	const account = createBudget("Trace", COMPILATION_LIMITS.traceUnits);
+	account({
+		version: 1,
+		groups: program.groups,
+		frames
+	});
+	program.beats.forEach((beat, index) => {
+		try {
+			state = reduceBeat(state, beat.events);
+			const frame = {
+				index: index + 1,
+				label: beat.label,
+				state,
+				events: beat.events,
+				source: beat.source
+			};
+			account(frame);
+			frames.push(frame);
+		} catch (error) {
+			throw new ProgramError([{
+				message: error instanceof Error ? error.message : String(error),
+				beat: index,
+				line: beat.source?.line
+			}]);
+		}
+	});
+	return {
+		version: 1,
+		frames,
+		...program.groups ? { groups: program.groups } : {}
+	};
+}
+// src/domains/lines.ts
+function sourceLine(ast, index = 0) {
+	return (ast.source?.line ?? 1) + index + 1;
+}
+/**
+* Non-empty, non-comment fence lines with fence line numbers (header is
+* line 1, first body line is line 2). Blank lines are retained by the parser so diagnostics refer to the
+* original source in every domain.
+*/
+function sourceLines(ast) {
+	if (ast.source && (!Number.isSafeInteger(ast.source.line) || ast.source.line < 1)) throw new ProgramError([{ message: "Source line must be a positive safe integer." }]);
+	checkSourceSize(ast.lines.reduce((size, line) => size + line.length + 1, ast.kind.length + 4));
+	const out = [];
+	ast.lines.forEach((raw, index) => {
+		const text = raw.trim();
+		if (!text || text.startsWith("#")) return;
+		out.push({
+			text,
+			line: sourceLine(ast, index)
+		});
+	});
+	return out;
+}
+// src/authoring.ts
+function parseProgram(ast) {
+	const program = {
+		version: 1,
+		entities: [],
+		relations: [],
+		beats: []
+	};
+	let beat;
+	sourceLines(ast).forEach(({ text, line }) => {
+		const source = { line };
+		const fail = (message) => {
+			throw new ProgramError([{
+				message,
+				line
+			}]);
+		};
+		const json = (value) => {
+			try {
+				return JSON.parse(value);
+			} catch {
+				return fail("Expected a JSON value (quote strings; arrays and objects are supported).");
+			}
+		};
+		const quoted = (value) => {
+			const parsed = json(value);
+			return typeof parsed === "string" ? parsed : fail("Expected a quoted label.");
+		};
+		const group = text.match(/^group\s+("(?:[^"\\]|\\.)*")\s+as\s+([a-z]+)$/);
+		if (group) {
+			if (beat) fail("Declare groups before the first step.");
+			if (!GROUP_LAYOUTS.includes(group[2])) fail(`Unknown group layout “${group[2]}”. Use ${GROUP_LAYOUTS.join(", ")}.`);
+			const name = quoted(group[1]);
+			program.groups ??= [];
+			if (program.groups.some((candidate) => candidate.name === name)) fail(`Duplicate group “${name}”.`);
+			program.groups.push({
+				name,
+				layout: group[2]
+			});
+			return;
+		}
+		const node = text.match(/^node\s+([\w-]+)\s+("(?:[^"\\]|\\.)*")(?:\s+in\s+("(?:[^"\\]|\\.)*"))?(?:\s+as\s+([a-z]+))?(\s+hidden)?(?:\s*=\s*(.+))?$/);
+		if (node) {
+			if (beat) fail("Declare nodes and links before the first step.");
+			if (node[4] && !VIEWS.includes(node[4])) fail(`Unknown view “${node[4]}”. Use ${VIEWS.join(", ")}.`);
+			program.entities.push({
+				id: node[1],
+				label: quoted(node[2]),
+				lane: node[3] ? quoted(node[3]) : void 0,
+				...node[4] ? { view: node[4] } : {},
+				...node[5] ? { hidden: true } : {},
+				value: node[6] ? json(node[6]) : null
+			});
+			return;
+		}
+		const link = text.match(/^link\s+([\w-]+)\s+([\w-]+)\s*->\s*([\w-]+)(?:\s+("(?:[^"\\]|\\.)*"))?(\s+hidden)?$/);
+		if (link) {
+			if (beat) fail("Declare nodes and links before the first step.");
+			program.relations.push({
+				id: link[1],
+				from: link[2],
+				to: link[3],
+				label: link[4] ? quoted(link[4]) : void 0,
+				...link[5] ? { hidden: true } : {}
+			});
+			return;
+		}
+		const step = text.match(/^step\s+("(?:[^"\\]|\\.)*")$/);
+		if (step) {
+			beat = {
+				label: quoted(step[1]),
+				events: [],
+				source
+			};
+			program.beats.push(beat);
+			return;
+		}
+		if (!beat) fail("Expected node, link, or step. Events must follow a step.");
+		const set = text.match(/^set\s+([^\s=]+)\s*=\s*(.+)$/);
+		const send = text.match(/^send\s+([\w-]+)(?:\s*=\s*(.+))?$/);
+		const focus = text.match(/^focus(?:\s+(.+))?$/);
+		const note = text.match(/^note\s+("(?:[^"\\]|\\.)*")$/);
+		const visibility = text.match(/^(show|hide)\s+(node|link)\s+([\w-]+)$/);
+		if (visibility) beat?.events.push({
+			op: visibility[1],
+			kind: visibility[2],
+			id: visibility[3],
+			source
+		});
+		else if (set) {
+			if (!parseTarget(set[1])) fail(`Invalid target “${set[1]}”. Use an id, optionally followed by [index] or .key.`);
+			beat?.events.push({
+				op: "set",
+				target: set[1],
+				value: json(set[2]),
+				source
+			});
+		} else if (send) beat?.events.push({
+			op: "send",
+			relation: send[1],
+			...send[2] ? { value: json(send[2]) } : {},
+			source
+		});
+		else if (focus) {
+			const targets = (focus[1] ?? "").split(/[\s,]+/).filter(Boolean);
+			const bad = targets.find((target) => !parseTarget(target));
+			if (bad) fail(`Invalid target “${bad}”. Use an id, optionally followed by [index] or .key.`);
+			beat?.events.push({
+				op: "focus",
+				targets,
+				source
+			});
+		} else if (note) beat?.events.push({
+			op: "note",
+			text: quoted(note[1]),
+			source
+		});
+		else fail("Unknown statement. Use node, link, step, set, focus, send, note, show, or hide.");
+	});
+	validateProgram(program);
+	return program;
+}
+// src/dsl.ts
+/**
+* Parse one thl block, optionally fenced with backticks or tildes. Fence
+* lengths/indentation follow CommonMark; document/container parsing belongs
+* to the host's Markdown parser, not a second parser inside the engine.
+*/
+function parseThl(src) {
+	checkSourceSize(src.length);
+	const lines = src.replace(/^\uFEFF/, "").split(/\r\n?|\n/);
+	const start = lines.findIndex((line) => line.trim() !== "");
+	if (start < 0) return null;
+	const first = lines[start];
+	const fence = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(first);
+	const header = (fence ? fence[2] : first).trim().split(/\s+/);
+	if (header[0] !== "thl") return null;
+	const line = start + 1;
+	if (header.length !== 2) throw new ProgramError([{
+		message: "Expected header: thl <domain>, without extra options.",
+		line
+	}]);
+	let end = lines.length;
+	if (fence) {
+		const marker = fence[1];
+		for (let index = start + 1; index < lines.length; index++) {
+			const close = /^ {0,3}(`{3,}|~{3,})[\t ]*$/.exec(lines[index]);
+			if (close?.[1][0] === marker[0] && close[1].length >= marker.length) {
+				end = index;
+				break;
+			}
+		}
+		const trailing = lines.findIndex((text, index) => index > end && text.trim() !== "");
+		if (trailing >= 0) throw new ProgramError([{
+			message: "Expected one Throughline block; found content after its closing fence.",
+			line: trailing + 1
+		}]);
+	}
+	return {
+		kind: header[1],
+		lines: lines.slice(start + 1, end),
+		source: { line }
+	};
+}
+// src/tracer.ts
+/** Detach caller-owned data before it becomes part of the recording. */
+function captureData(value) {
+	createBudget("Program", COMPILATION_LIMITS.programUnits)(value);
+	return JSON.parse(JSON.stringify(value));
+}
+function checkCount(name, count, maximum) {
+	if (count > maximum) throw new ProgramError([{ message: `Program exceeds ${maximum} ${name}.` }]);
+}
+/**
+* Computation adapter: run any ordinary algorithm and narrate it.
+* Values written in a step become visible together, exactly like authored steps.
+*/
+function tracer() {
+	const program = {
+		version: 1,
+		entities: [],
+		relations: [],
+		beats: []
+	};
+	let live = /* @__PURE__ */ new Map();
+	let eventCount = 0;
+	let recording = false;
+	const account = createBudget("Program", COMPILATION_LIMITS.programUnits);
+	const assertIdle = () => {
+		if (recording) throw new Error("Use the step writer while a step is open.");
+	};
+	const api = {
+		group(name, layout) {
+			assertIdle();
+			checkCount("groups", (program.groups?.length ?? 0) + 1, COMPILATION_LIMITS.entities);
+			const group = {
+				name,
+				layout
+			};
+			account(group);
+			program.groups ??= [];
+			program.groups.push(group);
+			return api;
+		},
+		node(id, label, value, options = {}) {
+			assertIdle();
+			checkCount("entities", program.entities.length + 1, COMPILATION_LIMITS.entities);
+			const entity = {
+				id,
+				label,
+				value: captureData(value),
+				...options.lane ? { lane: options.lane } : {},
+				...options.view ? { view: options.view } : {},
+				...options.hidden ? { hidden: true } : {}
+			};
+			account(entity);
+			program.entities.push(entity);
+			live.set(id, entity.value);
+			return api;
+		},
+		link(id, from, to, label, options = {}) {
+			assertIdle();
+			checkCount("relations", program.relations.length + 1, COMPILATION_LIMITS.relations);
+			const relation = {
+				id,
+				from,
+				to,
+				...label ? { label } : {},
+				...options.hidden ? { hidden: true } : {}
+			};
+			account(relation);
+			program.relations.push(relation);
+			return api;
+		},
+		/** Current value of a target as of the previous completed step. */
+		get(target) {
+			const parsed = parseTarget(target);
+			const value = parsed ? getAt(live.get(parsed.id), parsed.path) : void 0;
+			return value === void 0 ? void 0 : captureData(value);
+		},
+		step(label, body) {
+			assertIdle();
+			checkCount("steps", program.beats.length + 1, COMPILATION_LIMITS.steps);
+			const events = [];
+			const stepBudget = createBudget("Program step", COMPILATION_LIMITS.programUnits);
+			stepBudget({ label });
+			let open = true;
+			const append = (event) => {
+				if (!open) throw new Error("This step writer is closed.");
+				checkCount("events", eventCount + events.length + 1, COMPILATION_LIMITS.events);
+				stepBudget(event);
+				events.push(event);
+			};
+			recording = true;
+			try {
+				const result = body({
+					set: (target, value) => append({
+						op: "set",
+						target,
+						value: captureData(value)
+					}),
+					focus: (...targets) => append({
+						op: "focus",
+						targets
+					}),
+					send: (relation, value) => append({
+						op: "send",
+						relation,
+						...value === void 0 ? {} : { value: captureData(value) }
+					}),
+					note: (text) => append({
+						op: "note",
+						text
+					}),
+					show: (kind, id) => append({
+						op: "show",
+						kind,
+						id
+					}),
+					hide: (kind, id) => append({
+						op: "hide",
+						kind,
+						id
+					})
+				});
+				if (result !== null && typeof result === "object" && "then" in result && typeof result.then === "function") {
+					Promise.resolve(result).catch(() => {});
+					throw new Error("Step callbacks must be synchronous.");
+				}
+			} finally {
+				open = false;
+				recording = false;
+			}
+			const beat = {
+				label,
+				events
+			};
+			const pending = new Map(live);
+			for (const event of events) {
+				if (event.op !== "set") continue;
+				const parsed = parseTarget(event.target);
+				if (parsed && live.has(parsed.id)) pending.set(parsed.id, setAt(pending.get(parsed.id), parsed.path, event.value));
+			}
+			account(beat);
+			program.beats.push(beat);
+			live = pending;
+			eventCount += events.length;
+			return api;
+		},
+		program() {
+			return captureData(program);
+		}
+	};
+	return api;
+}
+// src/domains/binary.ts
+const BITS = /^[01]{1,16}$/;
+function parseBinary(ast) {
+	const found = /* @__PURE__ */ new Map();
+	for (const { text, line } of sourceLines(ast)) {
+		const entry = text.match(/^(a|b)\s*=\s*([01]+)\s*$/);
+		if (!entry?.[1] || !entry[2]) throw new ProgramError([{
+			message: "Expected a = <bits> or b = <bits>.",
+			line
+		}]);
+		const key = entry[1];
+		const digits = entry[2];
+		if (!BITS.test(digits)) throw new ProgramError([{
+			message: "Operands are 1–16 binary digits.",
+			line
+		}]);
+		if (found.has(key)) throw new ProgramError([{
+			message: `Duplicate operand "${key}".`,
+			line
+		}]);
+		found.set(key, digits);
+	}
+	const a = found.get("a");
+	const b = found.get("b");
+	if (!a || !b) throw new ProgramError([{
+		message: "Binary needs both a = <bits> and b = <bits>.",
+		line: sourceLine(ast)
+	}]);
+	return {
+		a,
+		b
+	};
+}
+function buildBinary({ a, b }) {
+	const t = tracer();
+	const n = Math.max(a.length, b.length);
+	const A = a.padStart(n, "0");
+	const B = b.padStart(n, "0");
+	t.node("a", "A", Number.parseInt(A, 2), {
+		lane: "Binary",
+		view: "bits"
+	});
+	t.node("b", "B", Number.parseInt(B, 2), {
+		lane: "Binary",
+		view: "bits"
+	});
+	t.node("sum", "Sum", Array(n + 1).fill("·"), {
+		lane: "Binary",
+		view: "array"
+	});
+	t.node("carry", "Carry", 0, {
+		lane: "Binary",
+		view: "number"
+	});
+	let carry = 0;
+	const sums = [];
+	for (let r = 0; r < n; r++) {
+		const x = Number(A[n - 1 - r]);
+		const y = Number(B[n - 1 - r]);
+		const total = x + y + carry;
+		const cin = carry;
+		const bit = total & 1;
+		carry = total >> 1;
+		sums.unshift(bit);
+		t.step(`bit ${r}`, (s) => {
+			s.focus(`a[${r}]`, `b[${r}]`, `sum[${n - r}]`, "carry");
+			s.set(`sum[${n - r}]`, bit);
+			s.set("carry", carry);
+			s.note(`bit ${r}: ${x} + ${y} + carry ${cin} = ${total}, so write ${bit} and carry ${carry}`);
+		});
+	}
+	const carryOut = carry;
+	const result = `${carryOut}${sums.join("")}`;
+	t.step("Result", (s) => {
+		s.focus("sum", "carry");
+		s.set("sum[0]", carryOut);
+		s.note(carryOut ? `The last carry becomes the top bit: ${A} + ${B} = ${result}` : `No final carry: ${A} + ${B} = ${result}`);
+	});
+	return t.program();
+}
+// src/domains/bindings.ts
+const NAME = "[A-Za-z][\\w-]*";
+const isHeapValue = (value) => Array.isArray(value) || typeof value === "object" && value !== null;
+const show = (value) => JSON.stringify(value) ?? "null";
+function parseBindings(ast) {
+	const ops = [];
+	const declared = /* @__PURE__ */ new Set();
+	const lines = sourceLines(ast);
+	if (lines.length > COMPILATION_LIMITS.steps) throw new ProgramError([{
+		message: `Bindings exceed ${COMPILATION_LIMITS.steps} steps.`,
+		line: lines[COMPILATION_LIMITS.steps].line
+	}]);
+	for (const { text, line } of lines) {
+		const fail = (message) => {
+			throw new ProgramError([{
+				message,
+				line
+			}]);
+		};
+		const json = (source) => {
+			try {
+				return JSON.parse(source);
+			} catch {
+				return fail("Expected a JSON value (quote strings).");
+			}
+		};
+		const bare = (source) => new RegExp(`^${NAME}$`).test(source) && !/^"(?:[^"\\]|\\.)*"$/.test(source) ? source : null;
+		const declare = text.match(new RegExp(`^(?:let|const)\\s+(${NAME})\\s*=\\s*(.+)$`));
+		if (declare) {
+			const name = declare[1] ?? "";
+			const rhs = (declare[2] ?? "").trim();
+			if (declared.has(name)) fail(`Duplicate variable "${name}".`);
+			const ref = bare(rhs);
+			if (ref) {
+				if (!declared.has(ref)) fail(`Unknown variable "${ref}".`);
+				declared.add(name);
+				ops.push({
+					kind: "declare",
+					name,
+					value: null,
+					from: ref,
+					line
+				});
+				continue;
+			}
+			declared.add(name);
+			ops.push({
+				kind: "declare",
+				name,
+				value: json(rhs),
+				line
+			});
+			continue;
+		}
+		const push = text.match(new RegExp(`^(${NAME})\\.push\\((.*)\\)$`));
+		if (push) {
+			const name = push[1] ?? "";
+			if (!declared.has(name)) fail(`Unknown variable "${name}".`);
+			let items;
+			try {
+				items = JSON.parse(`[${push[2] ?? ""}]`);
+			} catch {
+				throw new ProgramError([{
+					message: "Expected push arguments as JSON values.",
+					line
+				}]);
+			}
+			ops.push({
+				kind: "push",
+				name,
+				items,
+				line
+			});
+			continue;
+		}
+		const assign = text.match(new RegExp(`^(${NAME})\\s*=\\s*(.+)$`));
+		if (assign) {
+			const name = assign[1] ?? "";
+			if (!declared.has(name)) fail(`Unknown variable "${name}".`);
+			const rhs = (assign[2] ?? "").trim();
+			const ref = bare(rhs);
+			if (ref) {
+				if (!declared.has(ref)) fail(`Unknown variable "${ref}".`);
+				ops.push({
+					kind: "assign",
+					name,
+					value: null,
+					from: ref,
+					line
+				});
+				continue;
+			}
+			ops.push({
+				kind: "assign",
+				name,
+				value: json(rhs),
+				line
+			});
+			continue;
+		}
+		fail("Unknown statement. Use let <name> = <json>, <name> = <json|name>, or <name>.push(<json>).");
+	}
+	return { ops };
+}
+function buildBindings(params) {
+	const t = tracer();
+	t.group("Stack", "column").group("Heap", "column");
+	const vars = [];
+	const heapViews = /* @__PURE__ */ new Map();
+	const slot = /* @__PURE__ */ new Map();
+	const edges = [];
+	const edgeId = (from, to) => `ref_${from}_${to}`;
+	const alloc = (value) => {
+		const id = `o${heapViews.size + 1}`;
+		heapViews.set(id, Array.isArray(value) ? "array" : "record");
+		return id;
+	};
+	for (const op of params.ops) {
+		if (op.kind === "push") {
+			const target = slot.get(op.name);
+			if (!target || !("heap" in target)) throw new ProgramError([{
+				message: `Cannot push to "${op.name}": not an array.`,
+				line: op.line
+			}]);
+			continue;
+		}
+		if (!op.from) {
+			const value = op.value;
+			if (!vars.includes(op.name)) vars.push(op.name);
+			if (isHeapValue(value)) {
+				const heap = alloc(value);
+				slot.set(op.name, { heap });
+				edges.push({
+					id: edgeId(op.name, heap),
+					from: op.name,
+					to: heap
+				});
+			} else slot.set(op.name, { value });
+			continue;
+		}
+		if (!vars.includes(op.name)) vars.push(op.name);
+		const from = op.from;
+		const source = slot.get(from);
+		if (!source) throw new ProgramError([{
+			message: `Unknown variable "${from}".`,
+			line: op.line
+		}]);
+		if ("heap" in source) {
+			slot.set(op.name, { heap: source.heap });
+			edges.push({
+				id: edgeId(op.name, source.heap),
+				from: op.name,
+				to: source.heap
+			});
+		} else slot.set(op.name, { value: source.value });
+	}
+	for (const name of vars) t.node(name, name, null, {
+		lane: "Stack",
+		hidden: true
+	});
+	for (const [heap, view] of heapViews) t.node(heap, heap, null, {
+		lane: "Heap",
+		view,
+		hidden: true
+	});
+	const seen = /* @__PURE__ */ new Set();
+	for (const edge of edges) {
+		if (seen.has(edge.id)) continue;
+		seen.add(edge.id);
+		t.link(edge.id, edge.from, edge.to, "ref", { hidden: true });
+	}
+	const cur = /* @__PURE__ */ new Map();
+	const heapLive = /* @__PURE__ */ new Map();
+	let nextHeap = 0;
+	const shownPointers = /* @__PURE__ */ new Map();
+	const point = (s, name, heap) => {
+		const previous = shownPointers.get(name);
+		if (previous && previous !== heap) s.hide("link", edgeId(name, previous));
+		if (heap && previous !== heap) s.show("link", edgeId(name, heap));
+		if (heap) shownPointers.set(name, heap);
+		else shownPointers.delete(name);
+	};
+	const sharers = (heap, except) => [...cur.entries()].filter(([, binding]) => "heap" in binding && binding.heap === heap).map(([name]) => name).filter((name) => name !== except);
+	for (const op of params.ops) {
+		if (op.kind === "push") {
+			const binding = cur.get(op.name);
+			const heap = binding && "heap" in binding ? binding.heap : "";
+			const current = heapLive.get(heap);
+			if (!Array.isArray(current)) throw new ProgramError([{
+				message: `Cannot push to "${op.name}": not an array.`,
+				line: op.line
+			}]);
+			const next = [...current, ...op.items];
+			heapLive.set(heap, next);
+			const others = sharers(heap, op.name);
+			t.step(`${op.name}.push(${op.items.map(show).join(", ")})`, (s) => {
+				s.focus(op.name, heap, ...others);
+				s.set(heap, next);
+				s.note(others.length ? `push mutates the shared object, so ${others.join(", ")} see it too.` : `push appends to ${heap}.`);
+			});
+			continue;
+		}
+		if (!op.from) {
+			const label = op.kind === "declare" ? `let ${op.name} = ${show(op.value)}` : `${op.name} = ${show(op.value)}`;
+			if (isHeapValue(op.value)) {
+				nextHeap += 1;
+				const heap = `o${nextHeap}`;
+				const heapValue = op.value;
+				cur.set(op.name, { heap });
+				heapLive.set(heap, heapValue);
+				t.step(label, (s) => {
+					s.show("node", op.name);
+					s.show("node", heap);
+					point(s, op.name, heap);
+					s.focus(op.name);
+					s.set(op.name, heap);
+					s.set(heap, heapValue);
+					s.send(edgeId(op.name, heap), heapValue);
+					s.note(op.kind === "declare" ? `A new object lives on the heap. ${op.name} holds a reference to it.` : `Rebinding ${op.name} moves its arrow to a new object.`);
+				});
+			} else if (op.kind === "declare") {
+				const prim = op.value;
+				cur.set(op.name, { value: prim });
+				t.step(label, (s) => {
+					s.show("node", op.name);
+					s.focus(op.name);
+					s.set(op.name, prim);
+					s.note(`${op.name} is a primitive. The slot holds ${show(prim)} itself.`);
+				});
+			} else {
+				const prim = op.value;
+				cur.set(op.name, { value: prim });
+				t.step(label, (s) => {
+					point(s, op.name);
+					s.focus(op.name);
+					s.set(op.name, prim);
+					s.note(`Reassigning ${op.name} changes only ${op.name}.`);
+				});
+			}
+			continue;
+		}
+		const from = op.from;
+		const keyword = op.kind === "declare" ? "let " : "";
+		const source = cur.get(from);
+		if (source && "heap" in source) {
+			const heap = source.heap;
+			cur.set(op.name, { heap });
+			const heapValue = heapLive.get(heap) ?? null;
+			t.step(`${keyword}${op.name} = ${from}`, (s) => {
+				s.show("node", op.name);
+				point(s, op.name, heap);
+				s.focus(op.name, from);
+				s.set(op.name, heap);
+				s.send(edgeId(op.name, heap), heapValue);
+				s.note("Copying a reference copies the arrow, not the array. Two names, one object.");
+			});
+		} else {
+			const value = source && "value" in source ? source.value : null;
+			cur.set(op.name, { value });
+			t.step(`${keyword}${op.name} = ${from}`, (s) => {
+				s.show("node", op.name);
+				point(s, op.name);
+				s.focus(op.name, from);
+				s.set(op.name, value);
+				s.note(`${op.name} gets a copy of ${show(value)}. Two independent slots.`);
+			});
+		}
+	}
+	return t.program();
+}
+// src/domains/callstack.ts
+const fact = (k) => k <= 1 ? 1 : k * fact(k - 1);
+function parseCallstack(ast) {
+	const lines = sourceLines(ast);
+	const line = lines[0]?.line ?? sourceLine(ast);
+	if (lines.length !== 1) throw new ProgramError([{
+		message: "Callstack takes one line: fact <n>.",
+		line
+	}]);
+	const entry = lines[0]?.text.match(/^fact\s+(\d+)$/);
+	if (!entry || entry[1] === void 0) throw new ProgramError([{
+		message: "Expected fact <n>.",
+		line
+	}]);
+	const n = Number(entry[1]);
+	if (!Number.isInteger(n) || n < 1 || n > 6) throw new ProgramError([{
+		message: "Depth n is 1–6.",
+		line
+	}]);
+	return { n };
+}
+function buildCallstack({ n }) {
+	const t = tracer();
+	const slot = (k) => `slot${n - k + 1}`;
+	for (let i = 1; i <= n; i++) t.node(`slot${i}`, `frame ${i}`, null, { lane: "Call stack" });
+	t.node("returns", "Returns", Array(n).fill("·"), {
+		lane: "Returns",
+		view: "array"
+	});
+	for (let k = 1; k < n; k++) t.link(`calls${k}`, slot(k + 1), slot(k), "calls");
+	for (let k = 1; k <= n; k++) t.link(`ret${k}`, slot(k), "returns", "↩");
+	for (let k = n; k >= 1; k--) t.step(`call fact(${k})`, (s) => {
+		s.focus(slot(k));
+		s.set(slot(k), k === 1 ? "fact(1) · base case" : `fact(${k}) · waiting on fact(${k - 1})`);
+		if (k < n) s.send(`calls${k}`, `fact(${k})`);
+		s.note(k === n ? `fact(${n}) is called. Each call gets its own frame.` : k === 1 ? "Base case: n <= 1. fact(1) returns without another call." : `fact(${k}) can't finish yet — it needs fact(${k - 1}). A new frame is pushed.`);
+	});
+	for (let k = 1; k <= n; k++) {
+		const value = fact(k);
+		t.step(`return fact(${k})`, (s) => {
+			s.focus(slot(k), `returns[${k - 1}]`);
+			s.set(slot(k), null);
+			s.set(`returns[${k - 1}]`, value);
+			s.send(`ret${k}`, value);
+			s.note(k === 1 ? "fact(1) returns 1. Its frame is popped." : `fact(${k}) gets ${fact(k - 1)} back and returns ${k} × ${fact(k - 1)} = ${value}.`);
+		});
+	}
+	t.step("done", (s) => {
+		s.focus("returns");
+		s.note(`The stack is empty again. fact(${n}) = ${fact(n)}.`);
+	});
+	return t.program();
+}
+// src/domains/matrix.ts
+const parseGrid = (source, line) => {
+	let value;
+	try {
+		value = JSON.parse(source);
+	} catch {
+		throw new ProgramError([{
+			message: "Expected a JSON grid like [[1,2],[3,4]].",
+			line
+		}]);
+	}
+	if (!Array.isArray(value) || value.length < 1 || value.length > 4 || value.some((row) => !Array.isArray(row) || row.length < 1 || row.length > 4 || row.length !== value[0].length || row.some((cell) => typeof cell !== "number" || !Number.isFinite(cell)))) throw new ProgramError([{
+		message: "Grids are 1–4 rows of 1–4 finite numbers, all rows equal length.",
+		line
+	}]);
+	return value;
+};
+function parseMatrix(ast) {
+	const found = /* @__PURE__ */ new Map();
+	for (const { text, line } of sourceLines(ast)) {
+		const entry = text.match(/^(A|B)\s*=\s*(.+)$/);
+		if (!entry?.[1] || entry[2] === void 0) throw new ProgramError([{
+			message: "Expected A = <grid> or B = <grid>.",
+			line
+		}]);
+		if (found.has(entry[1])) throw new ProgramError([{
+			message: `Duplicate operand "${entry[1]}".`,
+			line
+		}]);
+		found.set(entry[1], {
+			grid: parseGrid(entry[2], line),
+			line
+		});
+	}
+	const a = found.get("A");
+	const b = found.get("B");
+	if (!a || !b) throw new ProgramError([{
+		message: "Matrix needs both A = <grid> and B = <grid>.",
+		line: sourceLine(ast)
+	}]);
+	if (a.grid[0]?.length !== b.grid.length) throw new ProgramError([{
+		message: `Inner dimensions mismatch: A has ${a.grid[0]?.length} columns but B has ${b.grid.length} rows.`,
+		line: b.line
+	}]);
+	return {
+		a: a.grid,
+		b: b.grid
+	};
+}
+function buildMatrix({ a, b }) {
+	const t = tracer();
+	t.group("Matrices", "row").group("Work", "row");
+	const rows = a.length;
+	const cols = b[0]?.length;
+	const inner = b.length;
+	t.node("A", "A", a, {
+		lane: "Matrices",
+		view: "matrix"
+	});
+	t.node("B", "B", b, {
+		lane: "Matrices",
+		view: "matrix"
+	});
+	t.node("C", "C = A × B", Array.from({ length: rows }, () => Array(cols).fill("·")), {
+		lane: "Matrices",
+		view: "matrix"
+	});
+	t.node("work", "Terms", [], {
+		lane: "Work",
+		view: "array"
+	});
+	t.link("readA", "A", "C", "row");
+	t.link("readB", "B", "C", "col");
+	for (let i = 0; i < rows; i++) for (let j = 0; j < cols; j++) {
+		const terms = Array.from({ length: inner }, (_, k) => a[i][k] * b[k][j]);
+		const total = terms.reduce((sum, term) => sum + term, 0);
+		const column = Array.from({ length: inner }, (_, k) => `B[${k}][${j}]`);
+		t.step(`C[${i}][${j}]`, (s) => {
+			s.focus(`A[${i}]`, `C[${i}][${j}]`, ...column);
+			s.set(`C[${i}][${j}]`, total);
+			s.set("work", terms);
+			s.send("readA", a[i]);
+			s.send("readB", b.map((row) => row[j]));
+			s.note(`C[${i}][${j}] = ${terms.join(" + ")} = ${total}. Row ${i} of A dot column ${j} of B.`);
+		});
+	}
+	return t.program();
+}
+// src/domains/registry.ts
+const SUPPORTED_DOMAINS = [
+	"flow",
+	"bindings",
+	"binary",
+	"matrix",
+	"callstack"
+];
+const COMPUTED = {
+	bindings: (ast) => buildBindings(checkParameters(parseBindings(ast))),
+	binary: (ast) => buildBinary(checkParameters(parseBinary(ast))),
+	matrix: (ast) => buildMatrix(checkParameters(parseMatrix(ast))),
+	callstack: (ast) => buildCallstack(checkParameters(parseCallstack(ast)))
+};
+/** Adapters may serialize labels before producing a Program. Guard their input first. */
+function checkParameters(parameters) {
+	createBudget("Program input", COMPILATION_LIMITS.programUnits)(parameters);
+	return parameters;
+}
+/** Compile any fenced thl block, routing on the info-string domain. */
+function compile(src) {
+	const ast = parseThl(src);
+	if (!ast) throw new ProgramError([{ message: "Expected a ```thl <domain> block." }]);
+	return compileAst(ast);
+}
+function compileAst(ast) {
+	if (ast.kind === "flow") return compileProgram(parseProgram(ast));
+	const build = Object.hasOwn(COMPUTED, ast.kind) ? COMPUTED[ast.kind] : void 0;
+	if (!build) throw new ProgramError([{
+		message: `Unknown domain "${ast.kind}". Use ${SUPPORTED_DOMAINS.join(", ")}.`,
+		line: ast.source?.line ?? 1
+	}]);
+	return compileProgram(build(ast));
+}
+export { COMPILATION_LIMITS, ProgramError, SUPPORTED_DOMAINS, compile, compileAst, compileProgram, describeFrame, parseProgram, parseThl, tracer, validateProgram };
+
+//# sourceMappingURL=index.js.map