@ai-gui/core 0.2.0 → 0.4.0

package/dist/index.js

@@ -215,6 +215,261 @@ function sanitizeHtml(html, options = {}) {
 	return DOMPurify.sanitize(html);
 }
 
+//#endregion
+//#region src/debug-events.ts
+const DEFAULT_MAX_STRING_LENGTH = 2048;
+const DEFAULT_MAX_DEPTH = 8;
+const DEFAULT_MAX_NODES = 1e3;
+const SENSITIVE_KEY_PARTS = [
+	"authorization",
+	"auth",
+	"accesstoken",
+	"refreshtoken",
+	"clientsecret",
+	"credentials",
+	"cookie",
+	"setcookie",
+	"proxyauthorization",
+	"password",
+	"passwd",
+	"apikey",
+	"secret",
+	"token"
+];
+var DebugEmitter = class {
+	enabled;
+	source;
+	limits;
+	listeners = new Set();
+	sequence = 0;
+	constructor(source, options = {}) {
+		this.source = source;
+		this.enabled = options.debug === true;
+		this.limits = {
+			maxStringLength: positiveInteger(options.maxStringLength, DEFAULT_MAX_STRING_LENGTH, "maxStringLength"),
+			maxDepth: positiveInteger(options.maxDepth, DEFAULT_MAX_DEPTH, "maxDepth"),
+			maxNodes: positiveInteger(options.maxNodes, DEFAULT_MAX_NODES, "maxNodes"),
+			redact: options.redact
+		};
+		if (this.enabled && options.onDebugEvent) this.listeners.add(options.onDebugEvent);
+	}
+	get active() {
+		return this.enabled && this.listeners.size > 0;
+	}
+	get available() {
+		return this.enabled;
+	}
+	subscribe(listener) {
+		if (!this.enabled) return () => {};
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	emit(type, data = {}) {
+		if (!this.active) return;
+		const event = Object.freeze({
+			type,
+			source: this.source,
+			timestamp: Date.now(),
+			sequence: ++this.sequence,
+			data: safeDebugValue(data, this.limits)
+		});
+		for (const listener of this.listeners) try {
+			listener(event);
+		} catch {}
+	}
+};
+function safeDebugValue(value, options = {}) {
+	const maxStringLength = positiveInteger(options.maxStringLength, DEFAULT_MAX_STRING_LENGTH, "maxStringLength");
+	const maxDepth = positiveInteger(options.maxDepth, DEFAULT_MAX_DEPTH, "maxDepth");
+	const maxNodes = positiveInteger(options.maxNodes, DEFAULT_MAX_NODES, "maxNodes");
+	const seen = new WeakSet();
+	let nodes = 0;
+	const visit = (input, key = "", path = [], depth = 0) => {
+		if (++nodes > maxNodes) return "[MAX_NODES]";
+		if (isSensitiveKey(key) || options.redact?.({
+			key,
+			path,
+			value: input
+		})) return "[REDACTED]";
+		if (typeof input === "string") return limitString(redactText(input), maxStringLength);
+		if (input === null || typeof input === "boolean") return input;
+		if (typeof input === "number") return Number.isFinite(input) ? input : String(input);
+		if (typeof input === "bigint" || typeof input === "symbol" || typeof input === "function" || typeof input === "undefined") return String(input);
+		if (input instanceof Error) return {
+			name: limitString(input.name || "Error", maxStringLength),
+			message: limitString(redactText(input.message), maxStringLength)
+		};
+		if (depth >= maxDepth) return "[MAX_DEPTH]";
+		if (seen.has(input)) return "[CIRCULAR]";
+		seen.add(input);
+		try {
+			if (Array.isArray(input)) return input.map((item, index) => visit(item, "", [...path, index], depth + 1));
+			const output = {};
+			for (const [childKey, child] of Object.entries(input)) output[childKey] = visit(child, childKey, [...path, childKey], depth + 1);
+			return output;
+		} finally {
+			seen.delete(input);
+		}
+	};
+	return visit(value);
+}
+function isSensitiveKey(key) {
+	const normalized = key.toLowerCase().replace(/[^a-z0-9]/g, "");
+	return normalized !== "" && SENSITIVE_KEY_PARTS.some((part) => normalized.includes(part));
+}
+function redactText(value) {
+	return value.replace(/\bBearer\s+[^\s,;]+/gi, "Bearer [REDACTED]").replace(/([?&](?:access[_-]?token|refresh[_-]?token|client[_-]?secret|api[_-]?key|password|passwd|token|secret)=)[^&#\s]*/gi, "$1[REDACTED]").replace(/\b((?:access[_-]?token|refresh[_-]?token|client[_-]?secret|api[_-]?key|password|passwd|token|secret)\s*[:=]\s*)[^\s,;]+/gi, "$1[REDACTED]");
+}
+function limitString(value, maxLength) {
+	if (value.includes("[REDACTED]") && maxLength < 20) return `[REDACTED][TRUNCATED length=${value.length}]`;
+	return value.length > maxLength ? `${value.slice(0, maxLength)}[TRUNCATED length=${value.length}]` : value;
+}
+function positiveInteger(value, fallback, name) {
+	if (value === void 0) return fallback;
+	if (!Number.isSafeInteger(value) || value <= 0) throw new TypeError(`${name} must be a positive integer`);
+	return value;
+}
+
+//#endregion
+//#region src/json-schema.ts
+/** Small, dependency-free validator for the JSON Schema subset used by AIGUI definitions. */
+function validateJSONSchema(schema, value) {
+	const issues = [];
+	validate(schema, value, "$", issues);
+	return {
+		valid: issues.length === 0,
+		issues
+	};
+}
+function validate(schema, value, path, issues) {
+	if (Object.hasOwn(schema, "const") && !jsonEqual(value, schema.const)) {
+		issues.push(`${path} must equal ${describeJSONValue(schema.const)}`);
+		return;
+	}
+	if (schema.enum && !schema.enum.some((candidate) => jsonEqual(candidate, value))) {
+		issues.push(`${path} must be one of the allowed values`);
+		return;
+	}
+	if (schema.type === "object") {
+		if (!isJSONObject(value)) {
+			issues.push(`${path} must be an object`);
+			return;
+		}
+		for (const required of schema.required ?? []) if (!Object.hasOwn(value, required)) issues.push(`${path}.${required} is required`);
+		for (const [key, childSchema] of Object.entries(schema.properties ?? {})) if (Object.hasOwn(value, key)) validate(childSchema, value[key], `${path}.${key}`, issues);
+		if (schema.additionalProperties === false) {
+			const allowed = new Set(Object.keys(schema.properties ?? {}));
+			for (const key of Object.keys(value)) if (!allowed.has(key)) issues.push(`${path}.${key} is not allowed`);
+		} else if (typeof schema.additionalProperties === "object" && schema.additionalProperties !== null) {
+			const allowed = new Set(Object.keys(schema.properties ?? {}));
+			for (const key of Object.keys(value)) if (!allowed.has(key)) validate(schema.additionalProperties, value[key], `${path}.${key}`, issues);
+		}
+		return;
+	}
+	if (schema.type === "array") {
+		if (!Array.isArray(value)) {
+			issues.push(`${path} must be an array`);
+			return;
+		}
+		if (schema.minItems !== void 0 && value.length < schema.minItems) issues.push(`${path} must contain at least ${schema.minItems} items`);
+		if (schema.maxItems !== void 0 && value.length > schema.maxItems) issues.push(`${path} must contain at most ${schema.maxItems} items`);
+		if (schema.items) value.forEach((item, index) => validate(schema.items, item, `${path}[${index}]`, issues));
+		return;
+	}
+	if (schema.type === "string") {
+		if (typeof value !== "string") {
+			issues.push(`${path} must be a string`);
+			return;
+		}
+		if (schema.minLength !== void 0 && value.length < schema.minLength) issues.push(`${path} must contain at least ${schema.minLength} characters`);
+		if (schema.maxLength !== void 0 && value.length > schema.maxLength) issues.push(`${path} must contain at most ${schema.maxLength} characters`);
+		if (schema.pattern !== void 0) try {
+			if (!new RegExp(schema.pattern).test(value)) issues.push(`${path} must match ${schema.pattern}`);
+		} catch {
+			issues.push(`${path} has an invalid schema pattern`);
+		}
+		return;
+	}
+	if (schema.type === "number" || schema.type === "integer") {
+		if (typeof value !== "number" || !Number.isFinite(value) || schema.type === "integer" && !Number.isInteger(value)) {
+			issues.push(`${path} must be ${schema.type === "integer" ? "an integer" : "a number"}`);
+			return;
+		}
+		if (schema.minimum !== void 0 && value < schema.minimum) issues.push(`${path} must be at least ${schema.minimum}`);
+		if (schema.maximum !== void 0 && value > schema.maximum) issues.push(`${path} must be at most ${schema.maximum}`);
+		return;
+	}
+	if (schema.type === "boolean" && typeof value !== "boolean") issues.push(`${path} must be a boolean`);
+	if (schema.type === "null" && value !== null) issues.push(`${path} must be null`);
+}
+function isJSONObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return false;
+	if (Object.getOwnPropertySymbols(value).length > 0) return false;
+	return Object.values(Object.getOwnPropertyDescriptors(value)).every((descriptor) => descriptor.enumerable && "value" in descriptor);
+}
+function jsonEqual(left, right) {
+	return compareJSON(left, right, new WeakSet(), new WeakSet());
+}
+function compareJSON(left, right, leftPath, rightPath) {
+	if (left === null || right === null) return left === right;
+	if (typeof left !== typeof right) return false;
+	if (typeof left === "string" || typeof left === "boolean") return left === right;
+	if (typeof left === "number") return Number.isFinite(left) && Number.isFinite(right) && left === right;
+	if (typeof left !== "object" || typeof right !== "object") return false;
+	if (leftPath.has(left) || rightPath.has(right)) return false;
+	const leftArray = Array.isArray(left);
+	if (leftArray !== Array.isArray(right)) return false;
+	if (leftArray) {
+		if (!isJSONArray(left) || !isJSONArray(right)) return false;
+	} else if (!isJSONObject(left) || !isJSONObject(right)) return false;
+	leftPath.add(left);
+	rightPath.add(right);
+	try {
+		if (leftArray) {
+			const rightArray = right;
+			if (left.length !== rightArray.length) return false;
+			for (let index = 0; index < left.length; index++) if (!compareJSON(left[index], rightArray[index], leftPath, rightPath)) return false;
+			return true;
+		}
+		const leftRecord = left;
+		const rightRecord = right;
+		const leftKeys = Object.keys(leftRecord);
+		const rightKeys = Object.keys(rightRecord);
+		if (leftKeys.length !== rightKeys.length) return false;
+		for (const key of leftKeys) {
+			if (!Object.hasOwn(rightRecord, key)) return false;
+			if (!compareJSON(leftRecord[key], rightRecord[key], leftPath, rightPath)) return false;
+		}
+		return true;
+	} finally {
+		leftPath.delete(left);
+		rightPath.delete(right);
+	}
+}
+function describeJSONValue(value) {
+	try {
+		const serialized = JSON.stringify(value);
+		return serialized === void 0 ? "a valid JSON value" : serialized;
+	} catch {
+		return "a valid JSON value";
+	}
+}
+function isJSONArray(value) {
+	if (Object.getOwnPropertySymbols(value).length > 0) return false;
+	const descriptors = Object.getOwnPropertyDescriptors(value);
+	for (const [key, descriptor] of Object.entries(descriptors)) {
+		if (key === "length") continue;
+		if (!isArrayIndex(key) || !descriptor.enumerable || !("value" in descriptor)) return false;
+	}
+	return Object.keys(value).length === value.length;
+}
+function isArrayIndex(key) {
+	const index = Number(key);
+	return Number.isInteger(index) && index >= 0 && index < 2 ** 32 - 1 && String(index) === key;
+}
+
 //#endregion
 //#region src/card-registry.ts
 var CardRegistry = class {
@@ -228,6 +483,12 @@ var CardRegistry = class {
 	getRender(type) {
 		return this.cards.get(type)?.render;
 	}
+	get(type) {
+		return this.cards.get(type);
+	}
+	list() {
+		return [...this.cards.values()];
+	}
 	parse(type, rawJson) {
 		const def = this.cards.get(type);
 		const { data, complete } = parsePartialJSON(rawJson);
@@ -236,17 +497,21 @@ var CardRegistry = class {
 			complete,
 			valid: false
 		};
-		const valid = complete && this.validate(def, data);
+		const valid = complete && this.validateDefinition(def, data);
 		return {
 			data,
 			complete,
 			valid
 		};
 	}
-	validate(def, data) {
+	validate(type, data) {
+		const def = this.cards.get(type);
+		return def ? this.validateDefinition(def, data) : false;
+	}
+	validateDefinition(def, data) {
 		try {
 			if (def.validate) return def.validate(data);
-			if (def.schema) return validateSchema(def.schema, data);
+			if (def.schema) return validateJSONSchema(def.schema, data).valid;
 			return true;
 		} catch {
 			return false;
@@ -277,42 +542,908 @@ var CardRegistry = class {
 		};
 	}
 };
-/** Minimal JSON Schema validation: covers type / required / properties, enough for cards. */
-function validateSchema(schema, data) {
-	if (schema.type === "object") {
-		if (typeof data !== "object" || data === null || Array.isArray(data)) return false;
-		const obj = data;
-		for (const req of schema.required ?? []) if (!(req in obj)) return false;
-		for (const [key, sub] of Object.entries(schema.properties ?? {})) if (key in obj && !validateSchema(sub, obj[key])) return false;
+
+//#endregion
+//#region src/card-store.ts
+const CARD_ID_MAX_LENGTH = 256;
+const CARD_JSON_MAX_DEPTH = 32;
+const CARD_JSON_MAX_NODES = 1e4;
+const CARD_PATCH_BATCH_MAX_SIZE = 100;
+var CardStore = class {
+	debugSource = "card-store";
+	registry;
+	cards = new Map();
+	lastMutationEpoch = new Map();
+	mutationEpoch = 0;
+	listeners = new Map();
+	allListeners = new Set();
+	debug;
+	constructor(options = {}) {
+		this.registry = options.registry;
+		this.debug = new DebugEmitter(this.debugSource, options);
+	}
+	register(input) {
+		validateCardId(input.id);
+		validateCardType(input.type);
+		assertRecordId(input.id, input.data);
+		const existing = this.cards.get(input.id);
+		if (existing) {
+			if (existing.type !== input.type) throw new CardTypeConflictError(input.id, existing.type, input.type);
+			return existing;
+		}
+		const data = cloneJSON(input.data);
+		this.assertValid(input.type, data);
+		const record = makeRecord(input.id, input.type, data, 0, { status: "idle" });
+		this.cards.set(input.id, record);
+		this.lastMutationEpoch.set(input.id, this.nextMutationEpoch());
+		this.notify(input.id);
+		return record;
+	}
+	get(id) {
+		return this.cards.get(id);
+	}
+	list() {
+		return [...this.cards.values()];
+	}
+	subscribe(id, listener) {
+		let listeners = this.listeners.get(id);
+		if (!listeners) {
+			listeners = new Set();
+			this.listeners.set(id, listeners);
+		}
+		listeners.add(listener);
+		return () => {
+			listeners?.delete(listener);
+			if (listeners?.size === 0) this.listeners.delete(id);
+		};
+	}
+	subscribeAll(listener) {
+		this.allListeners.add(listener);
+		return () => this.allListeners.delete(listener);
+	}
+	subscribeDebug(listener) {
+		return this.debug.subscribe(listener);
+	}
+	apply(patch) {
+		const next = this.preparePatch(this.cards, patch);
+		this.cards.set(next.id, next);
+		this.lastMutationEpoch.set(next.id, this.nextMutationEpoch());
+		this.notify(next.id);
+		if (this.debug.active) this.debug.emit("card-store-patch", {
+			patch,
+			cards: this.list()
+		});
+		return next;
+	}
+	applyAll(patches) {
+		if (patches.length > CARD_PATCH_BATCH_MAX_SIZE) throw new CardLimitError(`Card patch batches cannot exceed ${CARD_PATCH_BATCH_MAX_SIZE} operations`);
+		const nextCards = new Map(this.cards);
+		const changed = new Map();
+		for (const patch of patches) {
+			const next = this.preparePatch(nextCards, patch);
+			nextCards.set(next.id, next);
+			changed.set(next.id, next);
+		}
+		this.cards = nextCards;
+		for (const id of changed.keys()) this.lastMutationEpoch.set(id, this.nextMutationEpoch());
+		for (const id of changed.keys()) this.notifyOne(id);
+		if (changed.size) this.notifyAll();
+		if (changed.size && this.debug.active) {
+			const cards = this.list();
+			this.debug.emit("card-store-change", {
+				cardIds: [...changed.keys()],
+				cards
+			});
+			this.debug.emit("card-store-patch", {
+				patch: {
+					op: "batch",
+					patches
+				},
+				cards
+			});
+		}
+		return [...changed.values()];
+	}
+	delete(id) {
+		if (!this.cards.delete(id)) return false;
+		this.lastMutationEpoch.delete(id);
+		this.nextMutationEpoch();
+		this.notify(id);
 		return true;
 	}
-	if (schema.type === "array") {
-		if (!Array.isArray(data)) return false;
-		return schema.items ? data.every((d) => validateSchema(schema.items, d)) : true;
+	clear() {
+		if (this.cards.size === 0) return;
+		const ids = [...this.cards.keys()];
+		this.cards.clear();
+		this.lastMutationEpoch.clear();
+		this.nextMutationEpoch();
+		for (const id of ids) this.notifyOne(id);
+		this.notifyAll();
+		if (this.debug.active) this.debug.emit("card-store-change", {
+			operation: "clear",
+			cardIds: ids,
+			cards: []
+		});
+	}
+	snapshot() {
+		return {
+			version: 1,
+			cards: this.list().map(({ id, type, data, revision }) => ({
+				id,
+				type,
+				data: cloneJSON(data),
+				revision
+			}))
+		};
+	}
+	restore(snapshot) {
+		if (!snapshot || snapshot.version !== 1 || !Array.isArray(snapshot.cards)) throw new CardSnapshotError("Unsupported card snapshot");
+		const restored = new Map();
+		for (const input of snapshot.cards) {
+			if (!input || typeof input !== "object") throw new CardSnapshotError("Invalid card snapshot record");
+			validateCardId(input.id);
+			validateCardType(input.type);
+			if (!Number.isSafeInteger(input.revision) || input.revision < 0) throw new CardSnapshotError(`Invalid revision for card "${input.id}"`);
+			if (restored.has(input.id)) throw new CardSnapshotError(`Duplicate card id "${input.id}" in snapshot`);
+			const data = cloneJSON(input.data);
+			try {
+				assertRecordId(input.id, data);
+			} catch (cause) {
+				throw new CardSnapshotError(`Card snapshot data id does not match record id "${input.id}"`, { cause });
+			}
+			this.assertValid(input.type, data);
+			restored.set(input.id, makeRecord(input.id, input.type, data, input.revision, { status: "idle" }));
+		}
+		const ids = new Set([...this.cards.keys(), ...restored.keys()]);
+		this.cards = restored;
+		this.lastMutationEpoch = new Map([...restored.keys()].map((id) => [id, this.nextMutationEpoch()]));
+		if (restored.size === 0 && ids.size > 0) this.nextMutationEpoch();
+		for (const id of ids) this.notifyOne(id);
+		if (ids.size) this.notifyAll();
+		if (ids.size && this.debug.active) this.debug.emit("card-store-change", {
+			operation: "restore",
+			cardIds: [...ids],
+			cards: this.list()
+		});
+	}
+	beginAction(id, actionId) {
+		return this.setAction(id, actionId, {
+			status: "loading",
+			actionId
+		}, true);
+	}
+	succeedAction(id, actionId) {
+		return this.setAction(id, actionId, {
+			status: "success",
+			actionId
+		});
+	}
+	failAction(id, actionId, error) {
+		return this.setAction(id, actionId, {
+			status: "error",
+			actionId,
+			error: normalizeCardActionError(error)
+		});
+	}
+	cancelAction(id, actionId) {
+		return this.setAction(id, actionId, { status: "idle" });
+	}
+	isActionCurrent(id, actionId) {
+		const action = this.cards.get(id)?.action;
+		return action?.status === "loading" && action.actionId === actionId;
+	}
+	revisions() {
+		return new Map([...this.cards].map(([id, card]) => [id, card.revision]));
+	}
+	captureMutationEpoch() {
+		return this.mutationEpoch;
+	}
+	applyActionResult(result, startedEpoch) {
+		const patches = result.op === "batch" ? result.patches : [result];
+		if (patches.length > CARD_PATCH_BATCH_MAX_SIZE) throw new CardLimitError(`Card patch batches cannot exceed ${CARD_PATCH_BATCH_MAX_SIZE} operations`);
+		for (const cardId of new Set(patches.map((patch) => patch.cardId))) {
+			const current = this.cards.get(cardId);
+			if (!current) throw new CardNotFoundError(cardId);
+			const lastMutationEpoch = this.lastMutationEpoch.get(cardId);
+			if (lastMutationEpoch === void 0 || lastMutationEpoch > startedEpoch) throw new CardRevisionConflictError(cardId, startedEpoch, lastMutationEpoch ?? this.mutationEpoch);
+		}
+		return result.op === "batch" ? this.applyAll(result.patches) : [this.apply(result)];
+	}
+	preparePatch(cards, patch) {
+		assertPatch(patch);
+		const current = cards.get(patch.cardId);
+		if (!current) throw new CardNotFoundError(patch.cardId);
+		if (patch.revision !== void 0 && patch.revision !== current.revision) throw new CardRevisionConflictError(patch.cardId, patch.revision, current.revision);
+		const patchData = cloneJSON(patch.data);
+		assertPatchId(current.id, patchData);
+		const data = patch.op === "replace" ? patchData : mergeJSON(current.data, patchData);
+		assertStableId(current.id, current.data, data);
+		this.assertValid(current.type, data);
+		return makeRecord(current.id, current.type, data, current.revision + 1, current.action);
+	}
+	assertValid(type, data) {
+		if (this.registry && !this.registry.validate(type, data)) throw new CardValidationError(type);
+	}
+	setAction(id, actionId, action, start = false) {
+		const current = this.cards.get(id);
+		if (!current) throw new CardNotFoundError(id);
+		if (!start && (current.action.status !== "loading" || current.action.actionId !== actionId)) return false;
+		this.cards.set(id, makeRecord(current.id, current.type, current.data, current.revision, action));
+		this.notify(id);
+		return true;
+	}
+	nextMutationEpoch() {
+		return ++this.mutationEpoch;
+	}
+	notify(id) {
+		this.notifyOne(id);
+		this.notifyAll();
+		if (this.debug.active) this.debug.emit("card-store-change", {
+			cardId: id,
+			cards: this.list()
+		});
+	}
+	notifyOne(id) {
+		const card = this.cards.get(id);
+		for (const listener of this.listeners.get(id) ?? []) safeCall(listener, card);
+	}
+	notifyAll() {
+		const cards = this.list();
+		for (const listener of this.allListeners) safeCall(listener, cards);
+	}
+};
+var CardStoreError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = new.target.name;
+	}
+};
+var CardNotFoundError = class extends CardStoreError {
+	constructor(id) {
+		super(`Card "${id}" was not found`);
+	}
+};
+var CardTypeConflictError = class extends CardStoreError {
+	constructor(id, currentType, nextType) {
+		super(`Card "${id}" is already registered as "${currentType}", not "${nextType}"`);
+	}
+};
+var CardValidationError = class extends CardStoreError {
+	constructor(type) {
+		super(`Card data is invalid for type "${type}"`);
+	}
+};
+var CardRevisionConflictError = class extends CardStoreError {
+	constructor(id, expected, actual) {
+		super(`Card "${id}" revision conflict: expected ${expected}, actual ${actual}`);
+	}
+};
+var CardJSONError = class extends CardStoreError {};
+var CardLimitError = class extends CardStoreError {};
+var CardSnapshotError = class extends CardStoreError {};
+function isCardPatchResult(value) {
+	if (!isPlainObject(value) || typeof value.op !== "string") return false;
+	if (value.op === "batch") return Array.isArray(value.patches) && value.patches.every(isCardPatch);
+	return isCardPatch(value);
+}
+function isCardPatch(value) {
+	return isPlainObject(value) && (value.op === "merge" || value.op === "replace") && typeof value.cardId === "string" && Object.hasOwn(value, "data") && (value.revision === void 0 || Number.isSafeInteger(value.revision));
+}
+function assertPatch(patch) {
+	if (!isCardPatch(patch)) throw new CardStoreError("Invalid card patch");
+	validateCardId(patch.cardId);
+	if (patch.revision !== void 0 && patch.revision < 0) throw new CardStoreError("Card patch revision must be non-negative");
+}
+function validateCardId(id) {
+	if (typeof id !== "string" || id.trim().length === 0 || id.length > CARD_ID_MAX_LENGTH) throw new CardStoreError(`Card id must be a non-empty string up to ${CARD_ID_MAX_LENGTH} characters`);
+}
+function validateCardType(type) {
+	if (typeof type !== "string" || type.trim().length === 0) throw new CardStoreError("Card type must be a non-empty string");
+}
+function cloneJSON(value) {
+	let nodes = 0;
+	const path = new WeakSet();
+	const clone = (input, depth) => {
+		nodes++;
+		if (nodes > CARD_JSON_MAX_NODES) throw new CardLimitError(`Card JSON cannot exceed ${CARD_JSON_MAX_NODES} nodes`);
+		if (depth > CARD_JSON_MAX_DEPTH) throw new CardLimitError(`Card JSON cannot exceed depth ${CARD_JSON_MAX_DEPTH}`);
+		if (input === null || typeof input === "string" || typeof input === "boolean") return input;
+		if (typeof input === "number" && Number.isFinite(input)) return input;
+		if (typeof input !== "object") throw new CardJSONError("Card data must contain only JSON values");
+		if (path.has(input)) throw new CardJSONError("Card data cannot contain cycles");
+		path.add(input);
+		try {
+			if (Array.isArray(input)) {
+				if (Object.keys(input).length !== input.length) throw new CardJSONError("Card arrays must not be sparse");
+				return Object.freeze(input.map((item) => clone(item, depth + 1)));
+			}
+			if (!isPlainObject(input)) throw new CardJSONError("Card objects must be plain JSON objects");
+			const output = {};
+			for (const key of Object.keys(input)) {
+				if (isDangerousKey(key)) throw new CardJSONError(`Card data contains dangerous key "${key}"`);
+				Object.defineProperty(output, key, {
+					value: clone(input[key], depth + 1),
+					enumerable: true,
+					writable: false,
+					configurable: false
+				});
+			}
+			return Object.freeze(output);
+		} finally {
+			path.delete(input);
+		}
+	};
+	return clone(value, 0);
+}
+function mergeJSON(current, patch) {
+	if (!isPlainObject(current) || !isPlainObject(patch)) return patch;
+	const output = {};
+	for (const key of Object.keys(current)) output[key] = current[key];
+	for (const key of Object.keys(patch)) output[key] = mergeJSON(current[key], patch[key]);
+	return cloneJSON(output);
+}
+function assertPatchId(cardId, data) {
+	if (isPlainObject(data) && Object.hasOwn(data, "id") && data.id !== cardId) throw new CardStoreError(`Card patch cannot change id from "${cardId}"`);
+}
+function assertRecordId(cardId, data) {
+	if (isPlainObject(data) && Object.hasOwn(data, "id") && data.id !== cardId) throw new CardStoreError(`Card data id must match record id "${cardId}"`);
+}
+function assertStableId(cardId, current, next) {
+	const currentHasId = isPlainObject(current) && Object.hasOwn(current, "id");
+	const nextHasId = isPlainObject(next) && Object.hasOwn(next, "id");
+	if (currentHasId !== nextHasId || nextHasId && next.id !== cardId) throw new CardStoreError(`Card patch cannot change id from "${cardId}"`);
+}
+function makeRecord(id, type, data, revision, action) {
+	return Object.freeze({
+		id,
+		type,
+		data,
+		revision,
+		action: Object.freeze(action)
+	});
+}
+function normalizeCardActionError(error) {
+	if (error instanceof Error) return Object.freeze({
+		name: error.name || "Error",
+		message: error.message
+	});
+	return Object.freeze({
+		name: "Error",
+		message: typeof error === "string" ? error : "Unknown error"
+	});
+}
+function isPlainObject(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	if (prototype !== Object.prototype && prototype !== null) return false;
+	if (Object.getOwnPropertySymbols(value).length) return false;
+	return Object.values(Object.getOwnPropertyDescriptors(value)).every((descriptor) => descriptor.enumerable && "value" in descriptor);
+}
+function isDangerousKey(key) {
+	return key === "__proto__" || key === "prototype" || key === "constructor";
+}
+function safeCall(listener, ...args) {
+	try {
+		listener(...args);
+	} catch {}
+}
+
+//#endregion
+//#region src/actions.ts
+let nextRuntimeId = 0;
+var ActionRegistry = class {
+	actions = new Map();
+	register(definition, options = {}) {
+		if (typeof definition?.type !== "string" || definition.type.trim() === "") throw new TypeError("Action type must be a non-empty string");
+		if (typeof definition.run !== "function") throw new TypeError(`Action "${definition.type}" run must be a function`);
+		if (this.actions.has(definition.type) && !options.override) throw new ActionAlreadyRegisteredError(definition.type);
+		this.actions.set(definition.type, definition);
+	}
+	has(type) {
+		return this.actions.has(type);
+	}
+	get(type) {
+		return this.actions.get(type);
+	}
+	list() {
+		return [...this.actions.values()];
+	}
+};
+var ActionRuntime = class {
+	debugSource = "action-runtime";
+	registry;
+	cardStore;
+	defaultTimeoutMs;
+	onActionStart;
+	onActionSuccess;
+	onActionError;
+	states = new Map();
+	pending = new Map();
+	listeners = new Set();
+	defaultOwner = {};
+	runtimeId = ++nextRuntimeId;
+	generation = 0;
+	nextActionId = 0;
+	destroyed = false;
+	debug;
+	constructor(options) {
+		this.debug = new DebugEmitter(this.debugSource, options);
+		this.registry = options.registry;
+		this.cardStore = options.cardStore;
+		this.defaultTimeoutMs = options.timeoutMs;
+		this.onActionStart = options.onActionStart;
+		this.onActionSuccess = options.onActionSuccess;
+		this.onActionError = options.onActionError;
+	}
+	dispatch(request, options = {}) {
+		if (this.destroyed) return Promise.reject(new ActionDestroyedError());
+		const key = getActionKey(request.type, request.cardType, request.cardId);
+		const owner = options.owner ?? this.defaultOwner;
+		const existing = this.pending.get(key)?.get(owner);
+		if (existing) return existing.promise;
+		const actionId = `r${this.runtimeId}:${request.type}:${++this.nextActionId}`;
+		const event = {
+			key,
+			type: request.type,
+			params: request.params,
+			actionId,
+			cardType: request.cardType,
+			cardId: request.cardId
+		};
+		if (this.debug.active) this.debug.emit("action-dispatched", { ...event });
+		const definition = this.registry.get(request.type);
+		if (!definition) return this.rejectPreflight(event, new ActionNotFoundError(request.type));
+		if (definition.schema !== void 0) try {
+			const validation = validateJSONSchema(definition.schema, request.params);
+			if (!validation.valid) return this.rejectPreflight(event, new ActionValidationError(request.type, validation.issues));
+		} catch (cause) {
+			return this.rejectPreflight(event, new ActionExecutionError(request.type, cause));
+		}
+		let startedMutationEpoch;
+		try {
+			startedMutationEpoch = this.cardStore?.captureMutationEpoch();
+		} catch (cause) {
+			return this.rejectPreflight(event, new ActionExecutionError(request.type, cause));
+		}
+		if (request.cardId && this.cardStore) try {
+			this.cardStore.beginAction(request.cardId, actionId);
+		} catch (cause) {
+			return this.rejectPreflight(event, new ActionExecutionError(request.type, cause));
+		}
+		const generation = this.generation;
+		const controller = new AbortController();
+		const timeoutMs = options.timeoutMs ?? this.defaultTimeoutMs;
+		let timer;
+		let timedOut = false;
+		let settled = false;
+		let resolvePromise;
+		let rejectPromise;
+		const promise = new Promise((resolve, reject) => {
+			resolvePromise = resolve;
+			rejectPromise = reject;
+		});
+		const state = {
+			status: "pending",
+			key,
+			type: request.type,
+			cardType: request.cardType,
+			cardId: request.cardId,
+			actionId
+		};
+		const pending = {
+			controller,
+			promise
+		};
+		const runtime = this;
+		let cleanupExternalSignal = () => {};
+		let cleanupAbortSignal = () => {};
+		let owners = this.pending.get(key);
+		if (!owners) {
+			owners = new Map();
+			this.pending.set(key, owners);
+		}
+		owners.set(owner, pending);
+		const cleanup = () => {
+			if (timer !== void 0) clearTimeout(timer);
+			cleanupExternalSignal();
+			cleanupAbortSignal();
+			const currentOwners = this.pending.get(key);
+			if (currentOwners?.get(owner) === pending) {
+				currentOwners.delete(owner);
+				if (currentOwners.size === 0) this.pending.delete(key);
+			}
+		};
+		const finishSuccess = (result) => {
+			if (settled) return;
+			const wasPublic = this.isPublic(key, actionId, generation);
+			const canAffectCard = !request.cardId || !this.cardStore || this.cardStore.isActionCurrent(request.cardId, actionId);
+			const canApplyResult = request.cardId ? canAffectCard : wasPublic;
+			if (canApplyResult && this.cardStore && startedMutationEpoch !== void 0 && isCardPatchResult(result)) try {
+				this.cardStore.applyActionResult(result, startedMutationEpoch);
+			} catch (error) {
+				finishError(error);
+				return;
+			}
+			settled = true;
+			cleanup();
+			if (wasPublic) {
+				this.commit({
+					status: "success",
+					key,
+					type: request.type,
+					cardType: request.cardType,
+					cardId: request.cardId,
+					actionId,
+					result
+				});
+				callEventHandler(this.onActionSuccess, {
+					...event,
+					result
+				});
+				if (this.debug.active) this.debug.emit("action-success", {
+					...event,
+					result
+				});
+			}
+			if (request.cardId && this.cardStore && canAffectCard) settleCardAction(() => this.cardStore?.succeedAction(request.cardId, actionId));
+			resolvePromise(result);
+		};
+		function finishError(cause) {
+			if (settled) return;
+			settled = true;
+			const wasPublic = runtime.isPublic(key, actionId, generation);
+			cleanup();
+			const error = normalizeError(request.type, cause, controller.signal.aborted, timedOut, timeoutMs);
+			if (request.cardId && runtime.cardStore) settleCardAction(() => error instanceof ActionAbortedError ? runtime.cardStore?.cancelAction(request.cardId, actionId) : runtime.cardStore?.failAction(request.cardId, actionId, error));
+			if (wasPublic) {
+				const state$1 = error instanceof ActionAbortedError ? {
+					status: "cancelled",
+					key,
+					type: request.type,
+					cardType: request.cardType,
+					actionId,
+					error
+				} : {
+					status: "error",
+					key,
+					type: request.type,
+					cardType: request.cardType,
+					cardId: request.cardId,
+					actionId,
+					error
+				};
+				if (request.cardId) state$1.cardId = request.cardId;
+				runtime.commit(state$1);
+				callEventHandler(runtime.onActionError, {
+					...event,
+					error
+				});
+				if (runtime.debug.active) runtime.debug.emit("action-error", {
+					...event,
+					error
+				});
+			}
+			rejectPromise(error);
+		}
+		this.commit(state);
+		callEventHandler(this.onActionStart, event);
+		cleanupExternalSignal = forwardAbort(options.signal, controller);
+		cleanupAbortSignal = listenForAbort(controller.signal, (cause) => finishError(cause));
+		if (timeoutMs !== void 0 && timeoutMs > 0 && !settled) timer = setTimeout(() => {
+			timedOut = true;
+			controller.abort(new ActionTimeoutError(request.type, timeoutMs));
+		}, timeoutMs);
+		if (controller.signal.aborted || this.generation !== generation || this.destroyed) {
+			finishError(controller.signal.reason ?? new ActionAbortedError(request.type));
+			return promise;
+		}
+		try {
+			const result = definition.run(request.params, {
+				signal: controller.signal,
+				actionId,
+				cardType: request.cardType,
+				cardId: request.cardId
+			});
+			Promise.resolve(result).then(finishSuccess, finishError);
+		} catch (error) {
+			finishError(error);
+		}
+		return promise;
+	}
+	getState(key) {
+		return this.states.get(key) ?? getIdleActionState(key);
+	}
+	/** Check the runtime allowlist without exposing executable action definitions. */
+	hasAction(type) {
+		return !this.destroyed && this.registry.has(type);
+	}
+	/** List registered action names without exposing executable definitions. */
+	listActionTypes() {
+		return this.destroyed ? [] : Object.freeze(this.registry.list().map((action) => action.type));
+	}
+	subscribe(listener) {
+		if (this.destroyed) return () => {};
+		this.listeners.add(listener);
+		return () => this.listeners.delete(listener);
+	}
+	subscribeDebug(listener) {
+		return this.debug.subscribe(listener);
+	}
+	cancel(key) {
+		const actions = this.pending.get(key);
+		if (!actions?.size) return false;
+		const type = this.states.get(key)?.type ?? getIdleActionState(key).type;
+		for (const action of [...actions.values()]) action.controller.abort(new ActionAbortedError(type));
+		return true;
+	}
+	reset() {
+		const oldStates = [...this.states.values()];
+		this.generation++;
+		const actions = [...this.pending.values()].flatMap((owners) => [...owners.values()]);
+		for (const action of actions) action.controller.abort(new ActionAbortedError("Action"));
+		this.pending.clear();
+		this.states.clear();
+		for (const state of oldStates) this.notify(idleStateFrom(state));
+	}
+	destroy() {
+		if (this.destroyed) return;
+		this.reset();
+		this.destroyed = true;
+		this.listeners.clear();
+	}
+	rejectPreflight(event, error) {
+		const errorState = {
+			status: "error",
+			key: event.key,
+			type: event.type,
+			cardType: event.cardType,
+			cardId: event.cardId,
+			actionId: event.actionId,
+			error
+		};
+		this.commit(errorState);
+		callEventHandler(this.onActionError, {
+			...event,
+			error
+		});
+		if (this.debug.active) this.debug.emit("action-error", {
+			...event,
+			error
+		});
+		return Promise.reject(error);
+	}
+	isPublic(key, actionId, generation) {
+		return !this.destroyed && this.generation === generation && this.states.get(key)?.actionId === actionId;
+	}
+	commit(state) {
+		this.states.set(state.key, state);
+		if (this.debug.active) this.debug.emit("action-state", { ...state });
+		this.notify(state);
+	}
+	notify(state) {
+		for (const listener of this.listeners) try {
+			listener(state);
+		} catch {}
+	}
+};
+function createActionRuntime(options) {
+	return new ActionRuntime(options);
+}
+var ActionRuntimeError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = new.target.name;
+	}
+};
+var ActionAlreadyRegisteredError = class extends ActionRuntimeError {
+	constructor(type) {
+		super(`Action "${type}" is already registered`);
+	}
+};
+var ActionNotFoundError = class extends ActionRuntimeError {
+	constructor(type) {
+		super(`Action "${type}" is not registered`);
+	}
+};
+var ActionValidationError = class extends ActionRuntimeError {
+	constructor(actionType, issues) {
+		super(`Action "${actionType}" parameters are invalid: ${issues.join(", ")}`);
+		this.actionType = actionType;
+		this.issues = issues;
+	}
+};
+var ActionExecutionError = class extends ActionRuntimeError {
+	constructor(type, cause) {
+		super(`Action "${type}" failed`, { cause });
+	}
+};
+var ActionAbortedError = class extends ActionRuntimeError {
+	constructor(type) {
+		super(`Action "${type}" was cancelled`);
+	}
+};
+var ActionTimeoutError = class extends ActionRuntimeError {
+	constructor(type, timeoutMs) {
+		super(`Action "${type}" timed out after ${timeoutMs}ms`);
+		this.timeoutMs = timeoutMs;
+	}
+};
+var ActionDestroyedError = class extends ActionRuntimeError {
+	constructor() {
+		super("Action runtime has been destroyed");
+	}
+};
+function getActionKey(type, cardType, cardId) {
+	if (cardId !== void 0) return `::${JSON.stringify([
+		cardType ?? null,
+		type,
+		cardId
+	])}`;
+	if (!type.includes(":") && !cardType?.includes(":")) return cardType ? `${cardType}:${type}` : type;
+	return `::${JSON.stringify([cardType ?? null, type])}`;
+}
+function getIdleActionState(key) {
+	if (key.startsWith("::")) try {
+		const [cardType, type, cardId] = JSON.parse(key.slice(2));
+		if (cardId !== void 0) return cardType === null ? {
+			status: "idle",
+			key,
+			type,
+			cardId
+		} : {
+			status: "idle",
+			key,
+			cardType,
+			type,
+			cardId
+		};
+		return cardType === null ? {
+			status: "idle",
+			key,
+			type
+		} : {
+			status: "idle",
+			key,
+			cardType,
+			type
+		};
+	} catch {
+		return {
+			status: "idle",
+			key,
+			type: key
+		};
 	}
-	if (schema.type === "string") return typeof data === "string";
-	if (schema.type === "number") return typeof data === "number";
-	if (schema.type === "boolean") return typeof data === "boolean";
-	return true;
+	const separator = key.indexOf(":");
+	return separator === -1 ? {
+		status: "idle",
+		key,
+		type: key
+	} : {
+		status: "idle",
+		key,
+		cardType: key.slice(0, separator),
+		type: key.slice(separator + 1)
+	};
+}
+function idleStateFrom(state) {
+	return {
+		status: "idle",
+		key: state.key,
+		type: state.type,
+		...state.cardType === void 0 ? {} : { cardType: state.cardType },
+		...state.cardId === void 0 ? {} : { cardId: state.cardId }
+	};
+}
+function listenForAbort(signal, onAbort) {
+	const abort = () => onAbort(signal.reason);
+	if (signal.aborted) abort();
+	else signal.addEventListener("abort", abort, { once: true });
+	return () => signal.removeEventListener("abort", abort);
+}
+function forwardAbort(signal, controller) {
+	if (!signal) return () => {};
+	const abort = () => controller.abort(signal.reason);
+	if (signal.aborted) abort();
+	else signal.addEventListener("abort", abort, { once: true });
+	return () => signal.removeEventListener("abort", abort);
+}
+function normalizeError(type, cause, aborted, timedOut, timeoutMs) {
+	if (cause instanceof ActionRuntimeError) return cause;
+	if (timedOut) return new ActionTimeoutError(type, timeoutMs ?? 0);
+	if (aborted || isAbortError(cause)) return new ActionAbortedError(type);
+	return new ActionExecutionError(type, cause);
+}
+function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+function callEventHandler(handler, event) {
+	try {
+		handler?.(event);
+	} catch {}
+}
+function settleCardAction(settle) {
+	try {
+		settle();
+	} catch {}
 }
 
 //#endregion
 //#region src/plugins.ts
 /** Merge every plugin's `nodeRenderers` into a single map (later plugins win). */
-function collectNodeRenderers(plugins = []) {
+function collectNodeRenderers(plugins = [], debugOptions = {}) {
 	const map = {};
-	for (const p of plugins) for (const [k, render] of Object.entries(p.nodeRenderers ?? {})) map[k] = (node) => node.complete === false ? {
-		kind: "html",
-		html: `<div data-aigui-block-loading="" data-block-type="${escapeAttr(node.type)}"></div>`
-	} : render(node);
+	const target = debugOptions.debugTarget;
+	const debug = target ? void 0 : debugOptions.debug === true ? new DebugEmitter("renderer", debugOptions) : void 0;
+	for (const p of plugins) for (const [k, render] of Object.entries(p.nodeRenderers ?? {})) {
+		if (!(target?.debugEnabled || debugOptions.debug === true)) {
+			map[k] = render;
+			continue;
+		}
+		map[k] = (node) => {
+			const emit = (type, data) => target?.emitDebug(type, data) ?? debug?.emit(type, data);
+			emit("plugin-render-started", {
+				plugin: p.name,
+				nodeType: node.type,
+				nodeKey: node.key
+			});
+			try {
+				const output = render(node);
+				if (isPromise(output)) return output.then((resolved) => {
+					emit("async-output-resolved", {
+						plugin: p.name,
+						nodeType: node.type,
+						nodeKey: node.key,
+						outputKind: resolved.kind
+					});
+					emit("plugin-render-completed", {
+						plugin: p.name,
+						nodeType: node.type,
+						nodeKey: node.key,
+						outputKind: resolved.kind
+					});
+					return resolved;
+				}, (error) => {
+					emit("async-output-rejected", {
+						plugin: p.name,
+						nodeType: node.type,
+						nodeKey: node.key,
+						error
+					});
+					emit("plugin-render-failed", {
+						plugin: p.name,
+						nodeType: node.type,
+						nodeKey: node.key,
+						error
+					});
+					throw error;
+				});
+				emit("plugin-render-completed", {
+					plugin: p.name,
+					nodeType: node.type,
+					nodeKey: node.key,
+					outputKind: output.kind
+				});
+				return output;
+			} catch (error) {
+				emit("plugin-render-failed", {
+					plugin: p.name,
+					nodeType: node.type,
+					nodeKey: node.key,
+					error
+				});
+				throw error;
+			}
+		};
+	}
 	return map;
 }
 /** The set of node types claimed by the given plugins. */
 function pluginNodeTypes(plugins = []) {
 	return new Set(Object.keys(collectNodeRenderers(plugins)));
 }
-function escapeAttr(value) {
-	return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+function isPromise(value) {
+	return typeof value?.then === "function";
 }
 
 //#endregion
@@ -366,13 +1497,15 @@ function createParserWithMetadata(options = {}) {
 					const cardType = info.slice(5);
 					const res = options.registry.parse(cardType, t.content);
 					const complete = res.complete && isClosedFence(rawSrc, t.map, t.markup);
+					const idResult = complete && res.valid ? getCardId(res.data) : void 0;
 					addNode({
 						type: "card",
 						card: {
 							type: cardType,
 							data: res.data,
 							complete,
-							valid: complete && res.valid
+							valid: complete && res.valid && idResult !== false,
+							...typeof idResult === "string" ? { id: idResult } : {}
 						}
 					}, t.map);
 				} else if (pluginTypes.has(info)) {
@@ -478,6 +1611,11 @@ function createParserWithMetadata(options = {}) {
 		};
 	};
 }
+function getCardId(data) {
+	if (typeof data !== "object" || data === null || Array.isArray(data) || !Object.hasOwn(data, "id")) return void 0;
+	const id = data.id;
+	return typeof id === "string" && id.trim().length > 0 && id.length <= 256 ? id : false;
+}
 function getLineOffsets(src) {
 	const offsets = [0];
 	for (let i = 0; i < src.length; i++) if (src[i] === "\r") {
@@ -588,6 +1726,7 @@ function nodeEqual(a, b) {
 * the resulting patches via `onPatch`.
 */
 var Renderer = class {
+	debugSource = "renderer";
 	buffer = "";
 	prevAst = [];
 	parse;
@@ -598,8 +1737,10 @@ var Renderer = class {
 	activeFeed;
 	renderScheduled = false;
 	scheduleGeneration = 0;
+	debug;
 	constructor(options = {}) {
 		this.options = options;
+		this.debug = new DebugEmitter(this.debugSource, options);
 		this.sanitize = options.sanitize === false ? false : typeof options.sanitize === "object" ? options.sanitize : {};
 		if (options.registry) for (const plugin of options.plugins ?? []) for (const card of plugin.cards ?? []) options.registry.register(card);
 		this.parse = createParserWithMetadata({
@@ -607,21 +1748,36 @@ var Renderer = class {
 			plugins: options.plugins
 		});
 	}
+	get debugEnabled() {
+		return this.debug.available;
+	}
+	emitDebug(type, data = {}) {
+		this.debug.emit(type, data);
+	}
 	push(chunk) {
 		this.buffer += chunk;
+		if (this.debug.active) this.debug.emit("chunk-received", {
+			chunk,
+			length: chunk.length,
+			bufferLength: this.buffer.length
+		});
 		this.scheduleRender();
 	}
+	subscribeDebug(listener) {
+		return this.debug.subscribe(listener);
+	}
 	async feed(source, options = {}) {
 		const generation = ++this.generation;
 		this.cancelActiveFeed(createAbortError("Superseded by a newer feed"));
+		if (this.debug.active) this.debug.emit("feed-started", { generation });
 		const decoder = new TextDecoder();
 		const signal = options.signal;
-		if (signal?.aborted) throw abortReason(signal);
+		if (signal?.aborted) throw abortReason$1(signal);
 		let aborted = false;
 		let abortError;
 		const abort = () => {
 			aborted = true;
-			abortError = abortReason(signal);
+			abortError = abortReason$1(signal);
 			if (this.activeFeed?.generation === generation) this.cancelActiveFeed(abortError);
 		};
 		signal?.addEventListener("abort", abort, { once: true });
@@ -631,7 +1787,7 @@ var Renderer = class {
 			if (text) this.push(text);
 		};
 		try {
-			if (isReadableStream$1(source)) {
+			if (isReadableStream$2(source)) {
 				const reader = source.getReader();
 				let cancelled = false;
 				this.activeFeed = {
@@ -680,8 +1836,22 @@ var Renderer = class {
 				if (tail) this.push(tail);
 				this.flush();
 			}
-			if (aborted) throw abortError;
+			if (aborted) {
+				if (this.debug.active) this.debug.emit("feed-cancelled", {
+					generation,
+					error: abortError
+				});
+				throw abortError;
+			}
+			if (generation === this.generation && this.debug.active) this.debug.emit("feed-completed", {
+				generation,
+				bufferLength: this.buffer.length
+			});
 		} finally {
+			if (!aborted && generation !== this.generation && this.debug.active) this.debug.emit("feed-cancelled", {
+				generation,
+				reason: "superseded-or-reset"
+			});
 			signal?.removeEventListener("abort", abort);
 			if (this.activeFeed?.generation === generation) this.activeFeed = void 0;
 		}
@@ -697,6 +1867,7 @@ var Renderer = class {
 		this.prevAst = [];
 		this.parsed = void 0;
 		this.options.onPatch?.(patches, []);
+		if (this.debug.active) this.debug.emit("renderer-reset", { patches });
 	}
 	/** Immediately render pending buffered input, bypassing the scheduler. */
 	flush() {
@@ -725,16 +1896,34 @@ var Renderer = class {
 		Promise.resolve(active.cancel(reason)).catch(() => {});
 	}
 	render() {
+		const debug = this.debug.active;
+		const renderStarted = debug ? now() : 0;
 		const previous = this.parsed;
 		let next;
+		let mode = "full";
 		if (previous?.incrementalSafe && previous.blocks.length > 1) {
 			const mutable = previous.blocks.at(-1);
 			const stableBlocks = previous.blocks.slice(0, -1);
 			const stableNodeEnd = mutable.nodeStart;
 			const rawTail = this.buffer.slice(mutable.start);
-			const tail = this.parse(repairMarkdown(rawTail), rawTail, mutable.start);
+			const repaired = repairMarkdown(rawTail);
+			if (debug) this.debug.emit("markdown-repaired", {
+				mode: "mutable-tail",
+				raw: rawTail,
+				rawLength: rawTail.length,
+				repaired,
+				repairedLength: repaired.length,
+				sourceOffset: mutable.start
+			});
+			const parseStarted = debug ? now() : 0;
+			const tail = this.parse(repaired, rawTail, mutable.start);
+			if (debug) this.debug.emit("mutable-tail-reparsed", {
+				sourceOffset: mutable.start,
+				durationMs: now() - parseStarted
+			});
 			if (tail.incrementalSafe) {
-				if (this.sanitize !== false) sanitizeNodes(tail.nodes, this.sanitize);
+				mode = "mutable-tail";
+				if (this.sanitize !== false) this.sanitizeNodesWithDebug(tail.nodes);
 				next = {
 					nodes: [...previous.nodes.slice(0, stableNodeEnd), ...tail.nodes],
 					blocks: [...stableBlocks, ...tail.blocks.map((block) => ({
@@ -744,19 +1933,100 @@ var Renderer = class {
 					}))],
 					incrementalSafe: true
 				};
+				if (debug) this.debug.emit("stable-prefix-committed", {
+					blocks: stableBlocks.length,
+					nodes: stableNodeEnd
+				});
 			} else {
-				next = this.parse(repairMarkdown(this.buffer), this.buffer);
-				if (this.sanitize !== false) sanitizeNodes(next.nodes, this.sanitize);
+				const fullRepaired = repairMarkdown(this.buffer);
+				if (debug) this.debug.emit("markdown-repaired", {
+					mode: "full",
+					raw: this.buffer,
+					rawLength: this.buffer.length,
+					repaired: fullRepaired,
+					repairedLength: fullRepaired.length
+				});
+				const fullParseStarted = debug ? now() : 0;
+				next = this.parse(fullRepaired, this.buffer);
+				if (debug) this.debug.emit("parse-completed", {
+					mode: "full",
+					durationMs: now() - fullParseStarted
+				});
+				if (this.sanitize !== false) this.sanitizeNodesWithDebug(next.nodes);
 			}
 		} else {
-			next = this.parse(repairMarkdown(this.buffer), this.buffer);
-			if (this.sanitize !== false) sanitizeNodes(next.nodes, this.sanitize);
+			const repaired = repairMarkdown(this.buffer);
+			if (debug) this.debug.emit("markdown-repaired", {
+				mode: "full",
+				raw: this.buffer,
+				rawLength: this.buffer.length,
+				repaired,
+				repairedLength: repaired.length
+			});
+			const parseStarted = debug ? now() : 0;
+			next = this.parse(repaired, this.buffer);
+			if (debug) this.debug.emit("parse-completed", {
+				mode: "full",
+				durationMs: now() - parseStarted
+			});
+			if (this.sanitize !== false) this.sanitizeNodesWithDebug(next.nodes);
 		}
 		const nextAst = next.nodes;
+		for (const plugin of this.options.plugins ?? []) {
+			if (!plugin.onASTCommit) continue;
+			try {
+				plugin.onASTCommit(nextAst, {
+					generation: this.generation,
+					emitDebug: (type, data = {}) => this.debug.emit(type, {
+						plugin: plugin.name,
+						...data
+					})
+				});
+			} catch (error) {
+				if (debug) this.debug.emit("plugin-commit-failed", {
+					plugin: plugin.name,
+					error
+				});
+			}
+		}
+		const diffStarted = debug ? now() : 0;
 		const patches = diffAst(this.prevAst, nextAst);
+		const diffDurationMs = debug ? now() - diffStarted : 0;
 		this.parsed = next;
 		this.prevAst = nextAst;
+		const patchDispatchStarted = debug ? now() : 0;
 		if (patches.length > 0) this.options.onPatch?.(patches, nextAst);
+		const patchDispatchDurationMs = debug ? now() - patchDispatchStarted : 0;
+		if (debug) {
+			this.debug.emit("ast-snapshot", {
+				mode,
+				nodes: nextAst
+			});
+			this.debug.emit("ast-patches", {
+				patches,
+				durationMs: diffDurationMs
+			});
+			this.debug.emit("patch-dispatched", {
+				patches: patches.length,
+				durationMs: patchDispatchDurationMs,
+				renderDurationMs: now() - renderStarted
+			});
+		}
+	}
+	sanitizeNodesWithDebug(nodes) {
+		if (this.sanitize === false) return;
+		if (!this.debug.active) {
+			sanitizeNodes(nodes, this.sanitize);
+			return;
+		}
+		const inputSize = nodeMarkupSize(nodes);
+		const started = now();
+		sanitizeNodes(nodes, this.sanitize);
+		this.debug.emit("sanitizer-completed", {
+			inputSize,
+			outputSize: nodeMarkupSize(nodes),
+			durationMs: now() - started
+		});
 	}
 };
 /**
@@ -770,10 +2040,10 @@ function sanitizeNodes(nodes, options) {
 		if (node.children) sanitizeNodes(node.children, options);
 	}
 }
-function isReadableStream$1(source) {
+function isReadableStream$2(source) {
 	return "getReader" in source && typeof source.getReader === "function";
 }
-function abortReason(signal) {
+function abortReason$1(signal) {
 	return signal?.reason ?? createAbortError("The operation was aborted");
 }
 function createAbortError(message) {
@@ -781,6 +2051,18 @@ function createAbortError(message) {
 	error.name = "AbortError";
 	return error;
 }
+function now() {
+	return typeof performance === "undefined" ? Date.now() : performance.now();
+}
+function nodeMarkupSize(nodes) {
+	let size = 0;
+	for (const node of nodes) {
+		size += node.content?.length ?? 0;
+		size += node.html?.length ?? 0;
+		if (node.children) size += nodeMarkupSize(node.children);
+	}
+	return size;
+}
 
 //#endregion
 //#region src/stream-router.ts
@@ -853,7 +2135,7 @@ var StreamRouter = class {
 				buffer = buffer.slice(newline + 1);
 			}
 		};
-		if (isReadableStream(source)) {
+		if (isReadableStream$1(source)) {
 			const reader = source.getReader();
 			try {
 				for (;;) {
@@ -901,7 +2183,7 @@ function tryParseJson(text) {
 function isEnvelope(value) {
 	return typeof value === "object" && value !== null && typeof value.ch === "string";
 }
-function isReadableStream(source) {
+function isReadableStream$1(source) {
 	return "getReader" in source && typeof source.getReader === "function";
 }
 
@@ -917,9 +2199,296 @@ function buildSystemPrompt(options = {}) {
 	if (options.base) parts.push(options.base);
 	const cardSpec = options.registry?.toPromptSpec();
 	if (cardSpec) parts.push(cardSpec);
-	for (const p of options.plugins ?? []) if (p.promptSpec) parts.push(p.promptSpec);
+	for (const plugin of options.plugins ?? []) {
+		const spec = typeof plugin.promptSpec === "function" ? plugin.promptSpec() : plugin.promptSpec;
+		if (spec) parts.push(spec);
+	}
 	return parts.join("\n\n");
 }
 
 //#endregion
-export { CardRegistry, Renderer, StreamRouter, applyPatches, buildSystemPrompt, collectNodeRenderers, createParser, createParserWithMetadata, diffAst, parsePartialJSON, pluginNodeTypes, repairMarkdown, sanitizeHtml };
+//#region src/model-stream.ts
+async function* parseSSE(source, options = {}) {
+	let buffer = "";
+	let eventName;
+	let id;
+	let retry;
+	let data = [];
+	const doneData = options.doneData === void 0 ? "[DONE]" : options.doneData;
+	const dispatch = () => {
+		if (data.length === 0) {
+			eventName = void 0;
+			retry = void 0;
+			return void 0;
+		}
+		const raw = data.join("\n");
+		data = [];
+		const result = { data: raw };
+		if (eventName !== void 0) result.event = eventName;
+		if (id !== void 0) result.id = id;
+		if (retry !== void 0) result.retry = retry;
+		eventName = void 0;
+		retry = void 0;
+		if (doneData !== false && raw === doneData) return "done";
+		if (options.parseJSON) try {
+			result.data = JSON.parse(raw);
+		} catch (cause) {
+			const error = malformedError("Invalid SSE JSON", raw, cause);
+			if (options.onMalformed?.(error, raw) === "skip") return void 0;
+			throw error;
+		}
+		return result;
+	};
+	const processLine = (line) => {
+		if (line === "") return dispatch();
+		if (line.startsWith(":")) return void 0;
+		const colon = line.indexOf(":");
+		const field = colon < 0 ? line : line.slice(0, colon);
+		let value = colon < 0 ? "" : line.slice(colon + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+		if (field === "data") data.push(value);
+		else if (field === "event") eventName = value;
+		else if (field === "id" && !value.includes("\0")) id = value;
+		else if (field === "retry" && /^\d+$/.test(value)) retry = Number(value);
+		return void 0;
+	};
+	const drainLines = function* (eof = false) {
+		for (;;) {
+			const cr = buffer.indexOf("\r");
+			const lf = buffer.indexOf("\n");
+			let newline = cr < 0 ? lf : lf < 0 ? cr : Math.min(cr, lf);
+			if (newline < 0) break;
+			if (!eof && buffer[newline] === "\r" && newline === buffer.length - 1) break;
+			const width = buffer[newline] === "\r" && buffer[newline + 1] === "\n" ? 2 : 1;
+			const line = buffer.slice(0, newline);
+			buffer = buffer.slice(newline + width);
+			const event$1 = processLine(line);
+			if (event$1) yield event$1;
+		}
+	};
+	for await (const chunk of decodedChunks(source, options.signal)) {
+		buffer += chunk;
+		for (const event$1 of drainLines()) {
+			if (event$1 === "done") return;
+			yield event$1;
+		}
+	}
+	for (const event$1 of drainLines(true)) {
+		if (event$1 === "done") return;
+		yield event$1;
+	}
+	if (buffer) processLine(buffer);
+	const event = dispatch();
+	if (event && event !== "done") yield event;
+}
+async function* jsonLines(source, options = {}) {
+	let buffer = "";
+	for await (const chunk of decodedChunks(source, options.signal)) {
+		buffer += chunk;
+		for (;;) {
+			const newline = buffer.indexOf("\n");
+			if (newline < 0) break;
+			const line = buffer.slice(0, newline).replace(/\r$/, "");
+			buffer = buffer.slice(newline + 1);
+			const value$1 = parseJSONLine(line, options);
+			if (value$1 !== SKIP) yield value$1;
+		}
+	}
+	const value = parseJSONLine(buffer.replace(/\r$/, ""), options);
+	if (value !== SKIP) yield value;
+}
+const ndjson = jsonLines;
+async function* textLines(source, options = {}) {
+	let buffer = "";
+	for await (const chunk of decodedChunks(source, options.signal)) {
+		buffer += chunk;
+		for (;;) {
+			const newline = buffer.indexOf("\n");
+			if (newline < 0) break;
+			yield buffer.slice(0, newline).replace(/\r$/, "");
+			buffer = buffer.slice(newline + 1);
+		}
+	}
+	if (buffer) yield buffer.replace(/\r$/, "");
+}
+async function* contentDeltas(events) {
+	for await (const event of events) if (event.type === "content") yield event.delta;
+}
+async function* mockModelStream(events, options = {}) {
+	for await (const event of events) {
+		throwIfAborted(options.signal);
+		if (options.delayMs && options.delayMs > 0) await delay(options.delayMs, options.signal);
+		yield event;
+	}
+}
+function readableBytes(chunks) {
+	const iterator = toAsyncIterator(chunks);
+	const encoder = new TextEncoder();
+	return new ReadableStream({
+		async pull(controller) {
+			try {
+				const result = await iterator.next();
+				if (result.done) controller.close();
+				else controller.enqueue(typeof result.value === "string" ? encoder.encode(result.value) : result.value);
+			} catch (error) {
+				controller.error(error);
+			}
+		},
+		async cancel(reason) {
+			await iterator.return?.(reason);
+		}
+	});
+}
+async function* decodedChunks(source, signal) {
+	throwIfAborted(signal);
+	const decoder = new TextDecoder();
+	const body = isResponse(source) ? source.body : source;
+	if (!body) throw new TypeError("Response body is null");
+	if (isReadableStream(body)) {
+		const reader = body.getReader();
+		let done$1 = false;
+		let primaryError$1;
+		let cancelPromise;
+		const cancel = (reason) => {
+			if (done$1) return Promise.resolve();
+			cancelPromise ??= Promise.resolve().then(() => reader.cancel(reason));
+			return cancelPromise;
+		};
+		const abort = () => {
+			cancel(abortReason(signal)).catch(() => {});
+		};
+		signal?.addEventListener("abort", abort, { once: true });
+		try {
+			for (;;) {
+				throwIfAborted(signal);
+				const result = await reader.read();
+				throwIfAborted(signal);
+				if (result.done) {
+					done$1 = true;
+					break;
+				}
+				const text = decoder.decode(result.value, { stream: true });
+				if (text) yield text;
+			}
+			throwIfAborted(signal);
+			const tail = decoder.decode();
+			if (tail) yield tail;
+		} catch (error) {
+			primaryError$1 = error;
+			throw error;
+		} finally {
+			signal?.removeEventListener("abort", abort);
+			try {
+				if (!done$1) await cancel(abortReason(signal, "Stream iteration stopped"));
+			} catch (error) {
+				if (primaryError$1 === void 0) throw error;
+			} finally {
+				reader.releaseLock();
+			}
+		}
+		return;
+	}
+	const iterator = body[Symbol.asyncIterator]();
+	let done = false;
+	let primaryError;
+	try {
+		for (;;) {
+			throwIfAborted(signal);
+			const result = await nextWithAbort(iterator, signal);
+			throwIfAborted(signal);
+			if (result.done) {
+				done = true;
+				break;
+			}
+			const text = typeof result.value === "string" ? decoder.decode() + result.value : decoder.decode(result.value, { stream: true });
+			if (text) yield text;
+		}
+		const tail = decoder.decode();
+		if (tail) yield tail;
+	} catch (error) {
+		primaryError = error;
+		throw error;
+	} finally {
+		if (!done) try {
+			await iterator.return?.();
+		} catch (error) {
+			if (primaryError === void 0) throw error;
+		}
+	}
+}
+async function nextWithAbort(iterator, signal) {
+	if (!signal) return iterator.next();
+	throwIfAborted(signal);
+	const next = Promise.resolve(iterator.next());
+	let abort;
+	const aborted = new Promise((_resolve, reject) => {
+		abort = () => reject(abortReason(signal));
+		signal.addEventListener("abort", abort, { once: true });
+	});
+	try {
+		return await Promise.race([next, aborted]);
+	} finally {
+		signal.removeEventListener("abort", abort);
+	}
+}
+const SKIP = Symbol("skip");
+function parseJSONLine(line, options) {
+	if (!line.trim()) return SKIP;
+	try {
+		return JSON.parse(line);
+	} catch (cause) {
+		const error = malformedError("Invalid JSON line", line, cause);
+		if (options.onMalformed?.(error, line) === "skip") return SKIP;
+		throw error;
+	}
+}
+function malformedError(message, input, cause) {
+	const error = new SyntaxError(`${message}: ${input}`);
+	error.cause = cause;
+	return error;
+}
+function isResponse(value) {
+	return typeof Response !== "undefined" && value instanceof Response;
+}
+function isReadableStream(value) {
+	return typeof value === "object" && value !== null && "getReader" in value && typeof value.getReader === "function";
+}
+function toAsyncIterator(source) {
+	if (Symbol.asyncIterator in source) return source[Symbol.asyncIterator]();
+	const iterator = source[Symbol.iterator]();
+	return {
+		next: async () => iterator.next(),
+		return: iterator.return ? async (value) => iterator.return(value) : void 0
+	};
+}
+function throwIfAborted(signal) {
+	if (signal?.aborted) throw abortReason(signal);
+}
+function abortReason(signal, fallback = "The operation was aborted") {
+	if (signal?.reason !== void 0) return signal.reason;
+	const error = new Error(fallback);
+	error.name = "AbortError";
+	return error;
+}
+function delay(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(abortReason(signal));
+			return;
+		}
+		const finish = () => {
+			signal?.removeEventListener("abort", abort);
+			resolve();
+		};
+		const timer = setTimeout(finish, ms);
+		const abort = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", abort);
+			reject(abortReason(signal));
+		};
+		signal?.addEventListener("abort", abort, { once: true });
+	});
+}
+
+//#endregion
+export { ActionAbortedError, ActionAlreadyRegisteredError, ActionDestroyedError, ActionExecutionError, ActionNotFoundError, ActionRegistry, ActionRuntime, ActionRuntimeError, ActionTimeoutError, ActionValidationError, CARD_ID_MAX_LENGTH, CARD_JSON_MAX_DEPTH, CARD_JSON_MAX_NODES, CARD_PATCH_BATCH_MAX_SIZE, CardJSONError, CardLimitError, CardNotFoundError, CardRegistry, CardRevisionConflictError, CardSnapshotError, CardStore, CardStoreError, CardTypeConflictError, CardValidationError, DebugEmitter, Renderer, StreamRouter, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, textLines, validateJSONSchema };