@ai-gui/core 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -126,7 +126,10 @@ function repair(str) {
 				break;
 		}
 	}
-	if (inString && !stringIsKey) return [closeContainers(str + "\"", stack)];
+	if (inString && !stringIsKey) {
+		const body = escaped ? str.slice(0, -1) : str;
+		return [closeContainers(body + "\"", stack)];
+	}
 	const fallback = lastGoodEnd === -1 ? [] : [closeContainers(str.slice(0, lastGoodEnd), stack)];
 	if (inLiteral) return [closeContainers(str, stack), ...fallback];
 	return fallback;
@@ -150,20 +153,68 @@ function closeContainers(body, stack) {
 */
 function repairMarkdown(buffer) {
 	let out = buffer;
-	const fenceCount = (out.match(/^```/gm) ?? []).length;
-	if (fenceCount % 2 === 1) {
+	const openFence = findOpenFence(out);
+	if (openFence) {
 		if (!out.endsWith("\n")) out += "\n";
-		out += "```";
+		out += openFence;
 		return out;
 	}
-	const tick = (out.match(/`/g) ?? []).length;
-	if (tick % 2 === 1) out += "`";
-	const bold = (out.match(/\*\*/g) ?? []).length;
-	if (bold % 2 === 1) out += "**";
-	const strike = (out.match(/~~/g) ?? []).length;
+	const inline = findOpenInlineCode(out);
+	const visible = inline ? out.slice(0, inline.index) : out;
+	const bold = countUnescaped(visible, "**");
+	const strike = countUnescaped(visible, "~~");
+	if (inline) out += inline.marker;
 	if (strike % 2 === 1) out += "~~";
+	if (bold % 2 === 1) out += "**";
 	return out;
 }
+function findOpenFence(buffer) {
+	let open;
+	for (const line of buffer.split(/\r\n|\r|\n/)) {
+		const match = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+		if (!match) continue;
+		const marker = match[1];
+		if (!open) open = {
+			char: marker[0],
+			length: marker.length,
+			marker
+		};
+		else if (marker[0] === open.char && marker.length >= open.length && match[2].trim() === "") open = void 0;
+	}
+	return open?.marker;
+}
+function findOpenInlineCode(buffer) {
+	let open;
+	for (let i = 0; i < buffer.length;) {
+		if (buffer[i] !== "`" || isEscaped(buffer, i)) {
+			i++;
+			continue;
+		}
+		let end = i + 1;
+		while (buffer[end] === "`") end++;
+		const marker = buffer.slice(i, end);
+		if (!open) open = {
+			index: i,
+			marker
+		};
+		else if (open.marker === marker) open = void 0;
+		i = end;
+	}
+	return open;
+}
+function countUnescaped(buffer, marker) {
+	let count = 0;
+	for (let i = 0; i <= buffer.length - marker.length; i++) if (buffer.startsWith(marker, i) && !isEscaped(buffer, i)) {
+		count++;
+		i += marker.length - 1;
+	}
+	return count;
+}
+function isEscaped(buffer, index) {
+	let slashes = 0;
+	for (let i = index - 1; i >= 0 && buffer[i] === "\\"; i--) slashes++;
+	return slashes % 2 === 1;
+}
 
 //#endregion
 //#region src/sanitizer.ts
@@ -179,8 +230,12 @@ function escapeHtml(html) {
 * fall back to escaping the HTML-significant characters. This never emits raw
 * markup and never throws.
 */
-function sanitizeHtml(html) {
-	if (typeof window === "undefined") return escapeHtml(html);
+function sanitizeHtml(html, options = {}) {
+	if (options.sanitizer) return options.sanitizer(html);
+	if (typeof window === "undefined") {
+		if (options.ssr === "throw") throw new Error("sanitizeHtml requires a DOM or an injected sanitizer");
+		return escapeHtml(html);
+	}
 	return dompurify.default.sanitize(html);
 }
 
@@ -213,11 +268,16 @@ var CardRegistry = class {
 		};
 	}
 	validate(def, data) {
-		if (def.validate) return def.validate(data);
-		if (def.schema) return validateSchema(def.schema, data);
-		return true;
+		try {
+			if (def.validate) return def.validate(data);
+			if (def.schema) return validateSchema(def.schema, data);
+			return true;
+		} catch {
+			return false;
+		}
 	}
 	toPromptSpec() {
+		if (this.cards.size === 0) return "";
 		const lines = ["You can output cards. Format: a ```card:<type> fenced block with JSON inside. Available cards:"];
 		for (const def of this.cards.values()) {
 			lines.push(`- \`card:${def.type}\`: ${def.description}`);
@@ -229,6 +289,9 @@ var CardRegistry = class {
 		}
 		return lines.join("\n");
 	}
+	get size() {
+		return this.cards.size;
+	}
 	toJSONSchema() {
 		const properties = {};
 		for (const def of this.cards.values()) if (def.schema) properties[def.type] = def.schema;
@@ -262,29 +325,63 @@ function validateSchema(schema, data) {
 /** Merge every plugin's `nodeRenderers` into a single map (later plugins win). */
 function collectNodeRenderers(plugins = []) {
 	const map = {};
-	for (const p of plugins) for (const [k, v] of Object.entries(p.nodeRenderers ?? {})) map[k] = v;
+	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);
 	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;");
+}
 
 //#endregion
 //#region src/parser.ts
 /** Build a parser that turns markdown source into a flat list of ASTNodes. */
 function createParser(options = {}) {
+	const parse = createParserWithMetadata(options);
+	return (src, rawSrc = src) => parse(src, rawSrc).nodes;
+}
+/** Build a parser that also reports the source range for each top-level block. */
+function createParserWithMetadata(options = {}) {
 	const md = new markdown_it.default({
 		html: true,
 		linkify: true
 	});
 	options.configureMd?.(md);
 	for (const plugin of options.plugins ?? []) plugin.extendParser?.(md);
+	const hasParserExtensions = Boolean(options.configureMd || options.plugins?.some((plugin) => plugin.extendParser));
 	const pluginTypes = pluginNodeTypes(options.plugins);
-	return (src) => {
-		const tokens = md.parse(src, {});
+	const completeness = new Map();
+	for (const plugin of options.plugins ?? []) for (const type of Object.keys(plugin.nodeRenderers ?? {})) if (plugin.isBlockComplete) completeness.set(type, plugin.isBlockComplete);
+	return (src, rawSrc = src, sourceOffset = 0) => {
+		const env = {};
+		const tokens = md.parse(normalizeLineEndings(src), env);
 		const nodes = [];
-		let index = 0;
+		const blocks = [];
+		const lineOffsets = getLineOffsets(rawSrc);
+		const startSlots = new Map();
+		const addNode = (node, map) => {
+			const range = sourceRange(map, rawSrc.length, lineOffsets, sourceOffset);
+			const previous = blocks.at(-1);
+			const block = previous && previous.start === range.start && previous.end === range.end ? previous : void 0;
+			const slot = startSlots.get(range.start) ?? 0;
+			startSlots.set(range.start, slot + 1);
+			nodes.push({
+				key: `${range.start}:${slot}`,
+				...node
+			});
+			if (block) block.nodeEnd = nodes.length;
+			else blocks.push({
+				...range,
+				nodeStart: nodes.length - 1,
+				nodeEnd: nodes.length
+			});
+		};
 		for (let i = 0; i < tokens.length; i++) {
 			const t = tokens[i];
 			if (t.type === "fence") {
@@ -292,79 +389,82 @@ function createParser(options = {}) {
 				if (info.startsWith("card:") && options.registry) {
 					const cardType = info.slice(5);
 					const res = options.registry.parse(cardType, t.content);
-					nodes.push({
-						key: `${index++}:card`,
+					const complete = res.complete && isClosedFence(rawSrc, t.map, t.markup);
+					addNode({
 						type: "card",
 						card: {
 							type: cardType,
 							data: res.data,
-							complete: res.complete,
-							valid: res.valid
+							complete,
+							valid: complete && res.valid
 						}
-					});
-				} else if (pluginTypes.has(info)) nodes.push({
-					key: `${index++}:${info}`,
-					type: info,
-					content: t.content,
-					attrs: { info }
-				});
-				else nodes.push({
-					key: `${index++}:code`,
+					}, t.map);
+				} else if (pluginTypes.has(info)) {
+					const predicate = completeness.get(info);
+					const fenceComplete = isClosedFence(rawSrc, t.map, t.markup);
+					let complete = fenceComplete;
+					if (complete && predicate) try {
+						complete = predicate(info, t.content);
+					} catch {
+						complete = false;
+					}
+					addNode({
+						type: info,
+						content: t.content,
+						attrs: { info },
+						complete
+					}, t.map);
+				} else addNode({
 					type: "code",
 					tag: "code",
 					attrs: info ? { lang: info } : void 0,
 					content: t.content
-				});
+				}, t.map);
 				continue;
 			}
 			if (t.type === "hr") {
-				nodes.push({
-					key: `${index++}:hr`,
+				addNode({
 					type: "hr",
 					tag: "hr"
-				});
+				}, t.map);
 				continue;
 			}
 			if (t.type === "code_block") {
-				nodes.push({
-					key: `${index++}:code`,
+				addNode({
 					type: "code",
 					tag: "code",
 					content: t.content
-				});
+				}, t.map);
 				continue;
 			}
 			if (t.type === "html_block") {
-				nodes.push({
-					key: `${index++}:html`,
+				addNode({
 					type: "html",
 					content: t.content
-				});
+				}, t.map);
 				continue;
 			}
 			if (t.type === "heading_open") {
 				const inline = tokens[i + 1];
 				const raw = inline?.content ?? "";
-				nodes.push({
-					key: `${index++}:heading`,
+				addNode({
 					type: "heading",
 					tag: t.tag,
 					content: raw,
-					html: md.renderInline(raw)
-				});
+					html: md.renderer.renderInline(inline?.children ?? [], md.options, env)
+				}, t.map);
 				i += 2;
 				continue;
 			}
 			if (t.type === "paragraph_open") {
 				const inline = tokens[i + 1];
 				const raw = inline?.content ?? "";
-				nodes.push({
-					key: `${index++}:paragraph`,
+				addNode({
 					type: "paragraph",
 					tag: "p",
 					content: raw,
-					html: md.renderInline(raw)
-				});
+					html: md.renderer.renderInline(inline?.children ?? [], md.options, env)
+				}, t.map);
 				i += 2;
 				continue;
 			}
@@ -380,54 +480,127 @@ function createParser(options = {}) {
 					}
 				}
 				const slice = tokens.slice(i, j + 1);
-				nodes.push({
-					key: `${index++}:${t.type}`,
+				addNode({
 					type: "html",
-					content: md.renderer.render(slice, md.options, {})
-				});
+					content: md.renderer.render(slice, md.options, env)
+				}, t.map);
 				i = j;
 				continue;
 			}
 			if (t.block && t.level === 0) {
-				nodes.push({
-					key: `${index++}:${t.type}`,
+				addNode({
 					type: "html",
-					content: md.renderer.render([t], md.options, {})
-				});
+					content: md.renderer.render([t], md.options, env)
+				}, t.map);
 				continue;
 			}
 		}
-		return nodes;
+		return {
+			nodes,
+			blocks,
+			incrementalSafe: !hasParserExtensions && !hasReferenceSyntax(rawSrc)
+		};
 	};
 }
+function getLineOffsets(src) {
+	const offsets = [0];
+	for (let i = 0; i < src.length; i++) if (src[i] === "\r") {
+		if (src[i + 1] === "\n") i++;
+		offsets.push(i + 1);
+	} else if (src[i] === "\n") offsets.push(i + 1);
+	offsets.push(src.length);
+	return offsets;
+}
+function sourceRange(map, sourceLength, lineOffsets, sourceOffset) {
+	if (!map) return {
+		start: sourceOffset,
+		end: sourceOffset + sourceLength
+	};
+	return {
+		start: sourceOffset + Math.min(lineOffsets[map[0]] ?? sourceLength, sourceLength),
+		end: sourceOffset + Math.min(lineOffsets[map[1]] ?? sourceLength, sourceLength)
+	};
+}
+function hasReferenceSyntax(src) {
+	return /^ {0,3}\[[^\]\n]+\]:/m.test(src) || /\[[^\]\n]+\]\s*\[[^\]\n]*\]/.test(src) || /(^|[^!])\[[^\]\n]+\](?![([])/m.test(src);
+}
+function isClosedFence(src, map, markup) {
+	if (!map) return false;
+	const line = src.split(/\r\n|\r|\n/)[map[1] - 1]?.trim() ?? "";
+	if (line.length < markup.length || line[0] !== markup[0]) return false;
+	return line.split("").every((char) => char === markup[0]);
+}
+function normalizeLineEndings(src) {
+	return src.replace(/\r\n|\r/g, "\n");
+}
 
 //#endregion
 //#region src/diff.ts
 /** Produce a minimal set of patches turning `prev` into `next`, keyed by node key. */
 function diffAst(prev, next) {
 	const patches = [];
-	const prevByKey = new Map(prev.map((n) => [n.key, n]));
 	const nextKeys = new Set(next.map((n) => n.key));
-	next.forEach((node, index) => {
-		const old = prevByKey.get(node.key);
-		if (!old) patches.push({
-			op: "insert",
-			index,
-			node
-		});
-		else if (!nodeEqual(old, node)) patches.push({
-			op: "update",
-			key: node.key,
-			node
+	const working = [...prev];
+	for (let index = working.length - 1; index >= 0; index--) if (!nextKeys.has(working[index].key)) {
+		patches.push({
+			op: "remove",
+			key: working[index].key
 		});
-	});
-	for (const node of prev) if (!nextKeys.has(node.key)) patches.push({
-		op: "remove",
-		key: node.key
-	});
+		working.splice(index, 1);
+	}
+	for (let index = 0; index < next.length; index++) {
+		const node = next[index];
+		const currentIndex = working.findIndex((candidate) => candidate.key === node.key);
+		if (currentIndex === -1) {
+			patches.push({
+				op: "insert",
+				index,
+				node
+			});
+			working.splice(index, 0, node);
+			continue;
+		}
+		if (currentIndex !== index) {
+			patches.push({
+				op: "move",
+				key: node.key,
+				index
+			});
+			const [moved] = working.splice(currentIndex, 1);
+			working.splice(index, 0, moved);
+		}
+		if (!nodeEqual(working[index], node)) {
+			patches.push({
+				op: "update",
+				key: node.key,
+				node
+			});
+			working[index] = node;
+		}
+	}
 	return patches;
 }
+/** Apply patches in order, primarily for framework adapters and verification. */
+function applyPatches(nodes, patches) {
+	const next = [...nodes];
+	for (const patch of patches) if (patch.op === "insert") next.splice(patch.index, 0, patch.node);
+	else if (patch.op === "remove") {
+		const index = next.findIndex((node) => node.key === patch.key);
+		if (index !== -1) next.splice(index, 1);
+	} else if (patch.op === "move") {
+		const index = next.findIndex((node) => node.key === patch.key);
+		if (index !== -1) {
+			const [node] = next.splice(index, 1);
+			next.splice(patch.index, 0, node);
+		}
+	} else {
+		const index = next.findIndex((node) => node.key === patch.key);
+		if (index !== -1) next[index] = patch.node;
+	}
+	return next;
+}
 function nodeEqual(a, b) {
+	if (a === b) return true;
 	return JSON.stringify(a) === JSON.stringify(b);
 }
 
@@ -442,42 +615,170 @@ var Renderer = class {
 	buffer = "";
 	prevAst = [];
 	parse;
+	parsed;
 	options;
 	sanitize;
+	generation = 0;
+	activeFeed;
+	renderScheduled = false;
+	scheduleGeneration = 0;
 	constructor(options = {}) {
 		this.options = options;
-		this.sanitize = options.sanitize !== false;
+		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 = createParser({
+		this.parse = createParserWithMetadata({
 			registry: options.registry,
 			plugins: options.plugins
 		});
 	}
 	push(chunk) {
 		this.buffer += chunk;
-		this.render();
+		this.scheduleRender();
 	}
-	async feed(source) {
-		if (Symbol.asyncIterator in source) {
-			for await (const chunk of source) this.push(chunk);
-			return;
-		}
-		const reader = source.getReader();
-		for (;;) {
-			const { done, value } = await reader.read();
-			if (done) break;
-			if (value != null) this.push(value);
+	async feed(source, options = {}) {
+		const generation = ++this.generation;
+		this.cancelActiveFeed(createAbortError("Superseded by a newer feed"));
+		const decoder = new TextDecoder();
+		const signal = options.signal;
+		if (signal?.aborted) throw abortReason(signal);
+		let aborted = false;
+		let abortError;
+		const abort = () => {
+			aborted = true;
+			abortError = abortReason(signal);
+			if (this.activeFeed?.generation === generation) this.cancelActiveFeed(abortError);
+		};
+		signal?.addEventListener("abort", abort, { once: true });
+		const consume = (chunk) => {
+			if (generation !== this.generation || aborted) return;
+			const text = typeof chunk === "string" ? decoder.decode() + chunk : decoder.decode(chunk, { stream: true });
+			if (text) this.push(text);
+		};
+		try {
+			if (isReadableStream$1(source)) {
+				const reader = source.getReader();
+				let cancelled = false;
+				this.activeFeed = {
+					generation,
+					cancel: async (reason) => {
+						if (cancelled) return;
+						cancelled = true;
+						await reader.cancel(reason);
+					}
+				};
+				try {
+					for (;;) {
+						const { done, value } = await reader.read();
+						if (done || generation !== this.generation || aborted) break;
+						if (value != null) consume(value);
+					}
+				} finally {
+					reader.releaseLock();
+				}
+			} else {
+				const iterator = source[Symbol.asyncIterator]();
+				let returned = false;
+				this.activeFeed = {
+					generation,
+					cancel: async () => {
+						if (returned) return;
+						returned = true;
+						await iterator.return?.();
+					}
+				};
+				try {
+					for (;;) {
+						const { done, value } = await iterator.next();
+						if (done || generation !== this.generation || aborted) break;
+						consume(value);
+					}
+				} finally {
+					if ((generation !== this.generation || aborted) && !returned) {
+						returned = true;
+						await iterator.return?.();
+					}
+				}
+			}
+			if (generation === this.generation && !aborted) {
+				const tail = decoder.decode();
+				if (tail) this.push(tail);
+				this.flush();
+			}
+			if (aborted) throw abortError;
+		} finally {
+			signal?.removeEventListener("abort", abort);
+			if (this.activeFeed?.generation === generation) this.activeFeed = void 0;
 		}
 	}
 	reset() {
+		this.generation++;
+		this.cancelActiveFeed(createAbortError("Renderer reset"));
+		this.activeFeed = void 0;
 		this.buffer = "";
+		this.renderScheduled = false;
+		this.scheduleGeneration++;
+		const patches = diffAst(this.prevAst, []);
 		this.prevAst = [];
+		this.parsed = void 0;
+		this.options.onPatch?.(patches, []);
+	}
+	/** Immediately render pending buffered input, bypassing the scheduler. */
+	flush() {
+		if (!this.renderScheduled) return;
+		this.renderScheduled = false;
+		this.scheduleGeneration++;
+		this.render();
+	}
+	scheduleRender() {
+		if (!this.options.scheduler) {
+			this.render();
+			return;
+		}
+		if (this.renderScheduled) return;
+		this.renderScheduled = true;
+		const scheduledGeneration = ++this.scheduleGeneration;
+		this.options.scheduler(() => {
+			if (!this.renderScheduled || scheduledGeneration !== this.scheduleGeneration) return;
+			this.renderScheduled = false;
+			this.render();
+		});
+	}
+	cancelActiveFeed(reason) {
+		const active = this.activeFeed;
+		if (!active) return;
+		Promise.resolve(active.cancel(reason)).catch(() => {});
 	}
 	render() {
-		const repaired = repairMarkdown(this.buffer);
-		const nextAst = this.parse(repaired);
-		if (this.sanitize) sanitizeNodes(nextAst);
+		const previous = this.parsed;
+		let next;
+		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);
+			if (tail.incrementalSafe) {
+				if (this.sanitize !== false) sanitizeNodes(tail.nodes, this.sanitize);
+				next = {
+					nodes: [...previous.nodes.slice(0, stableNodeEnd), ...tail.nodes],
+					blocks: [...stableBlocks, ...tail.blocks.map((block) => ({
+						...block,
+						nodeStart: block.nodeStart + stableNodeEnd,
+						nodeEnd: block.nodeEnd + stableNodeEnd
+					}))],
+					incrementalSafe: true
+				};
+			} else {
+				next = this.parse(repairMarkdown(this.buffer), this.buffer);
+				if (this.sanitize !== false) sanitizeNodes(next.nodes, this.sanitize);
+			}
+		} else {
+			next = this.parse(repairMarkdown(this.buffer), this.buffer);
+			if (this.sanitize !== false) sanitizeNodes(next.nodes, this.sanitize);
+		}
+		const nextAst = next.nodes;
 		const patches = diffAst(this.prevAst, nextAst);
+		this.parsed = next;
 		this.prevAst = nextAst;
 		if (patches.length > 0) this.options.onPatch?.(patches, nextAst);
 	}
@@ -486,119 +787,132 @@ var Renderer = class {
 * Recursively sanitize node markup in place: the content of `html` nodes and
 * the rendered inline `html` field carried by any node.
 */
-function sanitizeNodes(nodes) {
+function sanitizeNodes(nodes, options) {
 	for (const node of nodes) {
-		if (node.type === "html" && typeof node.content === "string") node.content = sanitizeHtml(node.content);
-		if (node.html) node.html = sanitizeHtml(node.html);
-		if (node.children) sanitizeNodes(node.children);
+		if (node.type === "html" && typeof node.content === "string") node.content = sanitizeHtml(node.content, options);
+		if (node.html) node.html = sanitizeHtml(node.html, options);
+		if (node.children) sanitizeNodes(node.children, options);
 	}
 }
+function isReadableStream$1(source) {
+	return "getReader" in source && typeof source.getReader === "function";
+}
+function abortReason(signal) {
+	return signal?.reason ?? createAbortError("The operation was aborted");
+}
+function createAbortError(message) {
+	const error = new Error(message);
+	error.name = "AbortError";
+	return error;
+}
 
 //#endregion
 //#region src/stream-router.ts
 const DEFAULT_CHANNEL = "content";
-/**
-* Demultiplexes one incoming stream into multiple named channels so different
-* UI regions can update independently (e.g. `progress` + `content` from a single
-* SSE). Framing is auto-detected per line and supports:
-*
-*  1. JSON envelope: `{"ch":"<channel>","delta":"text"}` (a text delta) or
-*     `{"ch":"<channel>","data":<any>}` (a structured value). May appear bare or
-*     after a `data: ` prefix.
-*  2. SSE `event: <name>` sets the channel for the following `data:` line(s).
-*  3. A plain `data: <text>` line with no `ch` and no preceding `event:` is a
-*     text delta on the default `content` channel.
-*/
+/** Demultiplex JSON-lines and standards-compliant SSE into named channels. */
 var StreamRouter = class {
 	sinks = new Map();
 	handlers = new Map();
-	/** Bind a text-stream sink to a channel: text deltas call `sink.push(delta)`. */
+	/** Most recently received SSE `id` field. */
+	lastEventId = "";
+	/** Most recently received valid non-negative SSE reconnection delay. */
+	retry;
 	channel(name, sink) {
 		this.sinks.set(name, sink);
 		return this;
 	}
-	/** Bind a handler to a channel: data values (and deltas as strings) call it. */
 	on(name, handler) {
 		this.handlers.set(name, handler);
 		return this;
 	}
-	/**
-	* Consume a stream to completion, dispatching each parsed line to its channel.
-	* Accepts an async iterable of strings, or a `ReadableStream` of either strings
-	* or `Uint8Array` bytes (decoded as UTF-8).
-	*/
 	async feed(source) {
 		let buffer = "";
-		let currentEvent;
+		let eventName = "";
+		let dataLines = [];
+		const decoder = new TextDecoder();
+		const dispatchEvent = () => {
+			if (dataLines.length === 0) {
+				eventName = "";
+				return;
+			}
+			const payload = dataLines.join("\n");
+			const channel = eventName || DEFAULT_CHANNEL;
+			dataLines = [];
+			eventName = "";
+			this.dispatchPayload(channel, payload, channel === DEFAULT_CHANNEL);
+		};
+		const processLine = (rawLine) => {
+			const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
+			if (line === "") {
+				dispatchEvent();
+				return;
+			}
+			if (line.startsWith(":")) return;
+			const bareJson = tryParseJson(line);
+			if (isEnvelope(bareJson)) {
+				this.dispatchEnvelope(bareJson);
+				return;
+			}
+			const colon = line.indexOf(":");
+			const field = colon === -1 ? line : line.slice(0, colon);
+			let value = colon === -1 ? "" : line.slice(colon + 1);
+			if (value.startsWith(" ")) value = value.slice(1);
+			if (field === "event") eventName = value;
+			else if (field === "data") {
+				const envelope = tryParseJson(value);
+				if (!eventName && isEnvelope(envelope)) this.dispatchEnvelope(envelope);
+				else dataLines.push(value);
+			} else if (field === "id") {
+				if (!value.includes("\0")) this.lastEventId = value;
+			} else if (field === "retry") {
+				if (/^\d+$/.test(value)) this.retry = Number(value);
+			} else if (colon === -1) dataLines.push(line);
+		};
 		const consume = (chunk) => {
-			buffer += chunk;
-			let index;
-			while ((index = buffer.indexOf("\n")) !== -1) {
-				const line = buffer.slice(0, index);
-				buffer = buffer.slice(index + 1);
-				currentEvent = this.processLine(line, currentEvent);
+			const text = typeof chunk === "string" ? decoder.decode() + chunk : decoder.decode(chunk, { stream: true });
+			buffer += text;
+			let newline;
+			while ((newline = buffer.indexOf("\n")) !== -1) {
+				processLine(buffer.slice(0, newline));
+				buffer = buffer.slice(newline + 1);
 			}
 		};
-		if ("getReader" in source && typeof source.getReader === "function") {
+		if (isReadableStream(source)) {
 			const reader = source.getReader();
-			const decoder = new TextDecoder();
-			for (;;) {
-				const { done, value } = await reader.read();
-				if (done) break;
-				if (value == null) continue;
-				consume(typeof value === "string" ? value : decoder.decode(value, { stream: true }));
+			try {
+				for (;;) {
+					const { done, value } = await reader.read();
+					if (done) break;
+					if (value != null) consume(value);
+				}
+			} finally {
+				reader.releaseLock();
 			}
-			const tail = decoder.decode();
-			if (tail) consume(tail);
 		} else for await (const chunk of source) consume(chunk);
-		if (buffer.length > 0) this.processLine(buffer, currentEvent);
-	}
-	/** Process a single raw line; returns the (possibly updated) current event. */
-	processLine(rawLine, currentEvent) {
-		const line = rawLine.endsWith("\r") ? rawLine.slice(0, -1) : rawLine;
-		if (line.trim() === "") return void 0;
-		if (line.startsWith("event:")) return line.slice(6).trim();
-		let payload = line;
-		if (payload.startsWith("data:")) {
-			payload = payload.slice(5);
-			if (payload.startsWith(" ")) payload = payload.slice(1);
-		}
-		if (payload.startsWith("{")) {
-			const parsed = tryParseJson(payload);
-			if (parsed !== void 0 && isRecord(parsed) && typeof parsed.ch === "string") {
-				if ("delta" in parsed) this.routeDelta(parsed.ch, String(parsed.delta));
-				else this.routeData(parsed.ch, parsed.data);
-				return currentEvent;
-			}
-			if (parsed !== void 0) {
-				this.routeData(currentEvent ?? DEFAULT_CHANNEL, parsed);
-				return currentEvent;
-			}
-		}
-		if (currentEvent !== void 0) {
-			const parsed = tryParseJson(payload);
-			this.routeData(currentEvent, parsed !== void 0 ? parsed : payload);
-			return currentEvent;
-		}
-		this.routeDelta(DEFAULT_CHANNEL, payload);
-		return currentEvent;
+		const tail = decoder.decode();
+		if (tail) consume(tail);
+		if (buffer.length > 0) processLine(buffer);
+		dispatchEvent();
+	}
+	dispatchPayload(channel, payload, defaultIsDelta) {
+		const parsed = tryParseJson(payload);
+		if (isEnvelope(parsed)) this.dispatchEnvelope(parsed);
+		else if (defaultIsDelta) this.routeDelta(channel, payload);
+		else this.routeData(channel, parsed !== void 0 ? parsed : payload);
+	}
+	dispatchEnvelope(envelope) {
+		const channel = envelope.ch;
+		if ("delta" in envelope) this.routeDelta(channel, String(envelope.delta));
+		else this.routeData(channel, envelope.data);
 	}
-	/** Route a text delta: to a bound sink and/or an on() handler (either/both). */
 	routeDelta(channel, text) {
-		const sink = this.sinks.get(channel);
-		const handler = this.handlers.get(channel);
-		if (sink) sink.push(text);
-		if (handler) handler(text);
+		this.sinks.get(channel)?.push(text);
+		this.handlers.get(channel)?.(text);
 	}
-	/** Route a structured value: to the handler, or a string value to a lone sink. */
 	routeData(channel, value) {
 		const handler = this.handlers.get(channel);
-		if (handler) {
-			handler(value);
-			return;
-		}
-		const sink = this.sinks.get(channel);
-		if (sink && typeof value === "string") sink.push(value);
+		if (handler) handler(value);
+		else if (typeof value === "string") this.sinks.get(channel)?.push(value);
 	}
 };
 function tryParseJson(text) {
@@ -608,8 +922,11 @@ function tryParseJson(text) {
 		return void 0;
 	}
 }
-function isRecord(value) {
-	return typeof value === "object" && value !== null;
+function isEnvelope(value) {
+	return typeof value === "object" && value !== null && typeof value.ch === "string";
+}
+function isReadableStream(source) {
+	return "getReader" in source && typeof source.getReader === "function";
 }
 
 //#endregion
@@ -623,21 +940,20 @@ function buildSystemPrompt(options = {}) {
 	const parts = [];
 	if (options.base) parts.push(options.base);
 	const cardSpec = options.registry?.toPromptSpec();
-	if (options.registry && hasCards(options.registry) && cardSpec) parts.push(cardSpec);
+	if (cardSpec) parts.push(cardSpec);
 	for (const p of options.plugins ?? []) if (p.promptSpec) parts.push(p.promptSpec);
 	return parts.join("\n\n");
 }
-function hasCards(registry) {
-	return registry.toPromptSpec().includes("card:");
-}
 
 //#endregion
 exports.CardRegistry = CardRegistry
 exports.Renderer = Renderer
 exports.StreamRouter = StreamRouter
+exports.applyPatches = applyPatches
 exports.buildSystemPrompt = buildSystemPrompt
 exports.collectNodeRenderers = collectNodeRenderers
 exports.createParser = createParser
+exports.createParserWithMetadata = createParserWithMetadata
 exports.diffAst = diffAst
 exports.parsePartialJSON = parsePartialJSON
 exports.pluginNodeTypes = pluginNodeTypes