@ai-gui/core 0.27.0 → 0.29.0

package/README.md

@@ -108,6 +108,39 @@ const runtime = createActionRuntime({ registry: actions, cardStore })
 
 `CardStore` supports initialize-if-absent registration, immutable records, recursive object merge, replace, atomic patch batches, revision checks, subscriptions, delete/clear, and snapshot/restore. Action patch results use optimistic mutation epochs, so an older Action cannot overwrite a Card changed, deleted, recreated, or restored after that Action started.
 
+## One stream, many channels
+
+`Renderer` is a single-writer append-only buffer: `push` concatenates, and markdown block boundaries do not survive two sources interleaving into them. So anything arriving *alongside* the answer — progress, a background job, a tool that finished late — goes on its own channel and updates a Card by id, in any order, as many times as it likes.
+
+```ts
+import { CardStore, Renderer, StreamRouter, cardChannel } from "@ai-gui/core"
+
+const store = new CardStore({ registry })
+const renderer = new Renderer({ plugins, onPatch })
+
+await new StreamRouter()
+  .channel("content", renderer)                 // text deltas → the answer
+  .on("cards", cardChannel(store, { onError })) // card messages → the store
+  .on("usage", (u) => setTokens(u))             // anything else → your callback
+  .feed(response.body)
+```
+
+The wire accepts either form, mixed freely in one stream:
+
+```
+{"ch":"content","delta":"Working"}
+{"ch":"cards","data":{"op":"register","id":"job-7","type":"task","data":{"pct":0}}}
+{"ch":"cards","data":{"op":"merge","cardId":"job-7","data":{"pct":60}}}
+event: usage
+data: {"in":120}
+```
+
+`cardChannel` accepts `register`, `merge`, `replace` and `batch`. Not `delete`: a card the reader is looking at should not vanish because a late frame said so — call `store.delete` from your own handler where you can decide.
+
+Send `revision` on a patch when a late frame overwriting newer state would be wrong; the store rejects the stale one. Without it, last write wins.
+
+Every failure is reported through `onError` rather than thrown, because the handler runs inside one long `feed` await — a throw there would not just drop the card, it would kill the content channel and stop the answer mid-sentence. Leave `onError` unset and failures go to `console.error`; a silently swallowed one is indistinguishable from a card the model never sent.
+
 ## Exports
 
 - `Renderer` — `push(chunk)`, `feed(AsyncIterable | ReadableStream)`, `reset()`, `setPlugins(plugins)`; constructor `{ registry?, plugins?, sanitize?, rawHtml?, onPatch?(patches, nodes) }`.
@@ -115,6 +148,7 @@ const runtime = createActionRuntime({ registry: actions, cardStore })
   - `rawHtml: false` escapes raw HTML the model wrote instead of interpreting it — a stray `<code>` in prose otherwise swallows the rest of the line.
   - Emphasis is parsed CJK-friendly, one deliberate deviation from CommonMark. CommonMark will not let `**` close when it follows punctuation and precedes a character that is neither whitespace nor punctuation, so `**严格单调（单射）**的函数` renders its asterisks literally. ASCII is unaffected: `a * b * c` and `snake_case_word` parse exactly as before.
 - `StreamRouter` — demultiplex one stream into named channels: `.channel(name, sink)`, `.on(name, cb)`, `.feed(source)`.
+- `cardChannel(store, { onError? })` — a `StreamRouter` handler that applies `register` / `merge` / `replace` / `batch` messages to a `CardStore`, reporting failures instead of throwing into the feed.
 - `CardRegistry` — `register(def)`, `parse(type, rawJson)`, `getRender(type)`, `toPromptSpec()`, `toJSONSchema()`.
 - `CardStore` — `register`, `get`, `list`, `subscribe`, `apply`, `applyAll`, `delete`, `clear`, `snapshot`, and `restore` for Cards with stable IDs.
 - `ActionRegistry`, `ActionRuntime`, `createActionRuntime`, `getActionKey`, `getIdleActionState` — validated application-owned action execution and observable lifecycle state.

package/dist/index.cjs

@@ -1002,6 +1002,82 @@ function safeCall(listener, ...args) {
 	} catch {}
 }
 
+//#endregion
+//#region src/card-channel.ts
+const OPS = "register, merge, replace, batch";
+/**
+* Apply card messages arriving on a stream channel to a `CardStore`.
+*
+* ```ts
+* new StreamRouter()
+*   .channel("content", renderer)
+*   .on("cards", cardChannel(store))
+* ```
+*
+* This is the parallel half of the design. The content channel is one append-only buffer with a
+* single writer, because markdown block boundaries cannot survive two sources interleaving into
+* them. Cards are addressed by id instead, so anything on the wire — a background job, a tool that
+* finished late, a second model — can update one without touching the text, in any order, as many
+* times as it likes.
+*
+* Ordering is the store's contract, not this adapter's: a patch carrying `revision` is an
+* optimistic lock and a stale one is rejected through `onError`; a patch without one is
+* last-write-wins. Send `revision` when a late frame overwriting a newer state would be wrong.
+*
+* A card channel carries whole messages, not text deltas — one JSON object per frame.
+*/
+function cardChannel(store, options = {}) {
+	const report = (error, message) => {
+		if (options.onError) options.onError(error, message);
+		else console.error("[aigui] card channel:", error);
+	};
+	return (value) => {
+		let message = value;
+		if (typeof message === "string") try {
+			message = JSON.parse(message);
+		} catch {
+			report(new TypeError("Card channel received text that is not a JSON message"), value);
+			return;
+		}
+		if (typeof message !== "object" || message === null || Array.isArray(message)) {
+			report(new TypeError("A card message must be a JSON object"), value);
+			return;
+		}
+		const op = message.op;
+		try {
+			if (op === "register") {
+				const { id, type, data } = message;
+				if (typeof id !== "string" || typeof type !== "string") {
+					report(new TypeError("A register message needs a string id and type"), value);
+					return;
+				}
+				store.register({
+					id,
+					type,
+					data
+				});
+				return;
+			}
+			if (isCardPatchResult(message)) {
+				if (message.op === "batch") store.applyAll(message.patches);
+				else store.apply(message);
+				return;
+			}
+			if (op === "merge" || op === "replace") {
+				report(new TypeError(`A ${op} message needs a string cardId and a data field`), value);
+				return;
+			}
+			if (op === "batch") {
+				report(new TypeError("A batch message needs a patches array of merge or replace patches"), value);
+				return;
+			}
+			report(new TypeError(`Card message op must be one of ${OPS}, not ${JSON.stringify(op)}`), value);
+		} catch (error) {
+			report(error, value);
+		}
+	};
+}
+
 //#endregion
 //#region src/actions.ts
 let nextRuntimeId = 0;
@@ -2919,6 +2995,7 @@ exports.assertPlugins = assertPlugins
 exports.availableLocales = availableLocales
 exports.baseCss = baseCss
 exports.buildSystemPrompt = buildSystemPrompt
+exports.cardChannel = cardChannel
 exports.collectNodeRenderers = collectNodeRenderers
 exports.collectPluginStyles = collectPluginStyles
 exports.contentDeltas = contentDeltas

package/dist/index.d.cts

@@ -463,6 +463,58 @@ declare class CardLimitError extends CardStoreError {}
 declare class CardSnapshotError extends CardStoreError {}
 declare function isCardPatchResult(value: unknown): value is CardPatchResult;
 
+//#endregion
+//#region src/card-channel.d.ts
+/**
+ * A message a stream may send on a card channel.
+ *
+ * `register` first, then any number of patches against that id. Deletion is deliberately not here:
+ * a card the reader is looking at, or has already acted on, should not vanish because a late frame
+ * said so. A host that wants it calls `store.delete` from its own handler, where it can decide.
+ */
+type CardMessage = {
+  op: "register";
+  id: string;
+  type: string;
+  data: unknown;
+} | CardPatch | CardPatchBatch;
+interface CardChannelOptions {
+  /**
+   * Where a message that could not be applied goes.
+   *
+   * This is the reason the adapter exists rather than being three lines at the call site. The
+   * handler runs inside `StreamRouter.feed`, one long await over the whole response — a throw here
+   * does not just drop the card, it kills the content channel with it and the answer stops
+   * mid-sentence. So every failure is caught, and reported here instead.
+   *
+   * Left unset, failures go to `console.error`: a swallowed one looks exactly like a card that the
+   * model never sent, which is the hardest version of this bug to find.
+   */
+  onError?: (error: unknown, message: unknown) => void;
+}
+/**
+ * Apply card messages arriving on a stream channel to a `CardStore`.
+ *
+ * ```ts
+ * new StreamRouter()
+ *   .channel("content", renderer)
+ *   .on("cards", cardChannel(store))
+ * ```
+ *
+ * This is the parallel half of the design. The content channel is one append-only buffer with a
+ * single writer, because markdown block boundaries cannot survive two sources interleaving into
+ * them. Cards are addressed by id instead, so anything on the wire — a background job, a tool that
+ * finished late, a second model — can update one without touching the text, in any order, as many
+ * times as it likes.
+ *
+ * Ordering is the store's contract, not this adapter's: a patch carrying `revision` is an
+ * optimistic lock and a stale one is rejected through `onError`; a patch without one is
+ * last-write-wins. Send `revision` when a late frame overwriting a newer state would be wrong.
+ *
+ * A card channel carries whole messages, not text deltas — one JSON object per frame.
+ */
+declare function cardChannel(store: CardStore, options?: CardChannelOptions): (value: unknown) => void;
+
 //#endregion
 //#region src/json-schema.d.ts
 interface JSONSchemaValidationResult {
@@ -1000,4 +1052,4 @@ declare function mockModelStream(events: Iterable<ModelStreamEvent> | AsyncItera
 declare function readableBytes(chunks: Iterable<string | Uint8Array> | AsyncIterable<string | Uint8Array>): ReadableStream<Uint8Array>;
 
 //#endregion
-export { AIGuiPlugin, ASTNode, ActionAbortedError, ActionAlreadyRegisteredError, ActionContext, ActionDefinition, ActionDestroyedError, ActionDispatchOptions, ActionErrorEvent, ActionEventBase, ActionExecutionError, ActionNotFoundError, ActionOutcome, ActionRegisterOptions, ActionRegistry, ActionRequest, ActionRuntime, ActionRuntimeError, ActionRuntimeOptions, ActionStartEvent, ActionState, ActionStateListener, ActionStatus, ActionSuccessEvent, ActionTimeoutError, ActionValidationError, BuildSystemPromptOptions, ByteStreamSource, CARD_ID_MAX_LENGTH, CARD_JSON_MAX_DEPTH, CARD_JSON_MAX_NODES, CARD_PATCH_BATCH_MAX_SIZE, CardAction, CardActionError, CardDef, CardJSONError, CardLimitError, CardListener, CardNotFoundError, CardParseResult, CardPatch, CardPatchBatch, CardPatchResult, CardRecord, CardRegistry, CardRevisionConflictError, CardSnapshot, CardSnapshotError, CardStore, CardStoreError, CardStoreListener, CardStoreOptions, CardTypeConflictError, CardValidationError, ChannelSink, Citation, CollectNodeRendererOptions, DEFAULT_LOCALE, DebugEmitter, DebugEvent, DebugEventListener, DebugEventTarget, DebugInstrumentationTarget, DebugOptions, DebugRedactContext, DebugSource, ExportImageOptions, ExportedImage, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, Locale, MessageBundle, Messages, ModelStreamEvent, MountCardSlotRequest, MountedCardSlot, NodeRenderContext, NodeRenderer, OutcomeTone, ParseResult, ParserOptions, PartialJSONResult, Patch, PluginCommitContext, PluginSource, PluginStyle, PluginsLoader, RenderMountContext, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SanitizeSetting, SourceBlock, StreamParseOptions, StreamRouter, Usage, actionOutcome, applyPatches, assertPlugins, availableLocales, baseCss, buildSystemPrompt, collectNodeRenderers, collectPluginStyles, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, injectPluginStyles, isCardPatchResult, jsonLines, loadPlugins, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, resolveMessages, safeDebugValue, samePlugins, sanitizeHtml, sanitizeRenderedHtml, textLines, translate, translator, validateJSONSchema };
+export { AIGuiPlugin, ASTNode, ActionAbortedError, ActionAlreadyRegisteredError, ActionContext, ActionDefinition, ActionDestroyedError, ActionDispatchOptions, ActionErrorEvent, ActionEventBase, ActionExecutionError, ActionNotFoundError, ActionOutcome, ActionRegisterOptions, ActionRegistry, ActionRequest, ActionRuntime, ActionRuntimeError, ActionRuntimeOptions, ActionStartEvent, ActionState, ActionStateListener, ActionStatus, ActionSuccessEvent, ActionTimeoutError, ActionValidationError, BuildSystemPromptOptions, ByteStreamSource, CARD_ID_MAX_LENGTH, CARD_JSON_MAX_DEPTH, CARD_JSON_MAX_NODES, CARD_PATCH_BATCH_MAX_SIZE, CardAction, CardActionError, CardChannelOptions, CardDef, CardJSONError, CardLimitError, CardListener, CardMessage, CardNotFoundError, CardParseResult, CardPatch, CardPatchBatch, CardPatchResult, CardRecord, CardRegistry, CardRevisionConflictError, CardSnapshot, CardSnapshotError, CardStore, CardStoreError, CardStoreListener, CardStoreOptions, CardTypeConflictError, CardValidationError, ChannelSink, Citation, CollectNodeRendererOptions, DEFAULT_LOCALE, DebugEmitter, DebugEvent, DebugEventListener, DebugEventTarget, DebugInstrumentationTarget, DebugOptions, DebugRedactContext, DebugSource, ExportImageOptions, ExportedImage, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, Locale, MessageBundle, Messages, ModelStreamEvent, MountCardSlotRequest, MountedCardSlot, NodeRenderContext, NodeRenderer, OutcomeTone, ParseResult, ParserOptions, PartialJSONResult, Patch, PluginCommitContext, PluginSource, PluginStyle, PluginsLoader, RenderMountContext, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SanitizeSetting, SourceBlock, StreamParseOptions, StreamRouter, Usage, actionOutcome, applyPatches, assertPlugins, availableLocales, baseCss, buildSystemPrompt, cardChannel, collectNodeRenderers, collectPluginStyles, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, injectPluginStyles, isCardPatchResult, jsonLines, loadPlugins, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, resolveMessages, safeDebugValue, samePlugins, sanitizeHtml, sanitizeRenderedHtml, textLines, translate, translator, validateJSONSchema };

package/dist/index.d.ts

@@ -463,6 +463,58 @@ declare class CardLimitError extends CardStoreError {}
 declare class CardSnapshotError extends CardStoreError {}
 declare function isCardPatchResult(value: unknown): value is CardPatchResult;
 
+//#endregion
+//#region src/card-channel.d.ts
+/**
+ * A message a stream may send on a card channel.
+ *
+ * `register` first, then any number of patches against that id. Deletion is deliberately not here:
+ * a card the reader is looking at, or has already acted on, should not vanish because a late frame
+ * said so. A host that wants it calls `store.delete` from its own handler, where it can decide.
+ */
+type CardMessage = {
+  op: "register";
+  id: string;
+  type: string;
+  data: unknown;
+} | CardPatch | CardPatchBatch;
+interface CardChannelOptions {
+  /**
+   * Where a message that could not be applied goes.
+   *
+   * This is the reason the adapter exists rather than being three lines at the call site. The
+   * handler runs inside `StreamRouter.feed`, one long await over the whole response — a throw here
+   * does not just drop the card, it kills the content channel with it and the answer stops
+   * mid-sentence. So every failure is caught, and reported here instead.
+   *
+   * Left unset, failures go to `console.error`: a swallowed one looks exactly like a card that the
+   * model never sent, which is the hardest version of this bug to find.
+   */
+  onError?: (error: unknown, message: unknown) => void;
+}
+/**
+ * Apply card messages arriving on a stream channel to a `CardStore`.
+ *
+ * ```ts
+ * new StreamRouter()
+ *   .channel("content", renderer)
+ *   .on("cards", cardChannel(store))
+ * ```
+ *
+ * This is the parallel half of the design. The content channel is one append-only buffer with a
+ * single writer, because markdown block boundaries cannot survive two sources interleaving into
+ * them. Cards are addressed by id instead, so anything on the wire — a background job, a tool that
+ * finished late, a second model — can update one without touching the text, in any order, as many
+ * times as it likes.
+ *
+ * Ordering is the store's contract, not this adapter's: a patch carrying `revision` is an
+ * optimistic lock and a stale one is rejected through `onError`; a patch without one is
+ * last-write-wins. Send `revision` when a late frame overwriting a newer state would be wrong.
+ *
+ * A card channel carries whole messages, not text deltas — one JSON object per frame.
+ */
+declare function cardChannel(store: CardStore, options?: CardChannelOptions): (value: unknown) => void;
+
 //#endregion
 //#region src/json-schema.d.ts
 interface JSONSchemaValidationResult {
@@ -1000,4 +1052,4 @@ declare function mockModelStream(events: Iterable<ModelStreamEvent> | AsyncItera
 declare function readableBytes(chunks: Iterable<string | Uint8Array> | AsyncIterable<string | Uint8Array>): ReadableStream<Uint8Array>;
 
 //#endregion
-export { AIGuiPlugin, ASTNode, ActionAbortedError, ActionAlreadyRegisteredError, ActionContext, ActionDefinition, ActionDestroyedError, ActionDispatchOptions, ActionErrorEvent, ActionEventBase, ActionExecutionError, ActionNotFoundError, ActionOutcome, ActionRegisterOptions, ActionRegistry, ActionRequest, ActionRuntime, ActionRuntimeError, ActionRuntimeOptions, ActionStartEvent, ActionState, ActionStateListener, ActionStatus, ActionSuccessEvent, ActionTimeoutError, ActionValidationError, BuildSystemPromptOptions, ByteStreamSource, CARD_ID_MAX_LENGTH, CARD_JSON_MAX_DEPTH, CARD_JSON_MAX_NODES, CARD_PATCH_BATCH_MAX_SIZE, CardAction, CardActionError, CardDef, CardJSONError, CardLimitError, CardListener, CardNotFoundError, CardParseResult, CardPatch, CardPatchBatch, CardPatchResult, CardRecord, CardRegistry, CardRevisionConflictError, CardSnapshot, CardSnapshotError, CardStore, CardStoreError, CardStoreListener, CardStoreOptions, CardTypeConflictError, CardValidationError, ChannelSink, Citation, CollectNodeRendererOptions, DEFAULT_LOCALE, DebugEmitter, DebugEvent, DebugEventListener, DebugEventTarget, DebugInstrumentationTarget, DebugOptions, DebugRedactContext, DebugSource, ExportImageOptions, ExportedImage, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, Locale, MessageBundle, Messages, ModelStreamEvent, MountCardSlotRequest, MountedCardSlot, NodeRenderContext, NodeRenderer, OutcomeTone, ParseResult, ParserOptions, PartialJSONResult, Patch, PluginCommitContext, PluginSource, PluginStyle, PluginsLoader, RenderMountContext, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SanitizeSetting, SourceBlock, StreamParseOptions, StreamRouter, Usage, actionOutcome, applyPatches, assertPlugins, availableLocales, baseCss, buildSystemPrompt, collectNodeRenderers, collectPluginStyles, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, injectPluginStyles, isCardPatchResult, jsonLines, loadPlugins, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, resolveMessages, safeDebugValue, samePlugins, sanitizeHtml, sanitizeRenderedHtml, textLines, translate, translator, validateJSONSchema };
+export { AIGuiPlugin, ASTNode, ActionAbortedError, ActionAlreadyRegisteredError, ActionContext, ActionDefinition, ActionDestroyedError, ActionDispatchOptions, ActionErrorEvent, ActionEventBase, ActionExecutionError, ActionNotFoundError, ActionOutcome, ActionRegisterOptions, ActionRegistry, ActionRequest, ActionRuntime, ActionRuntimeError, ActionRuntimeOptions, ActionStartEvent, ActionState, ActionStateListener, ActionStatus, ActionSuccessEvent, ActionTimeoutError, ActionValidationError, BuildSystemPromptOptions, ByteStreamSource, CARD_ID_MAX_LENGTH, CARD_JSON_MAX_DEPTH, CARD_JSON_MAX_NODES, CARD_PATCH_BATCH_MAX_SIZE, CardAction, CardActionError, CardChannelOptions, CardDef, CardJSONError, CardLimitError, CardListener, CardMessage, CardNotFoundError, CardParseResult, CardPatch, CardPatchBatch, CardPatchResult, CardRecord, CardRegistry, CardRevisionConflictError, CardSnapshot, CardSnapshotError, CardStore, CardStoreError, CardStoreListener, CardStoreOptions, CardTypeConflictError, CardValidationError, ChannelSink, Citation, CollectNodeRendererOptions, DEFAULT_LOCALE, DebugEmitter, DebugEvent, DebugEventListener, DebugEventTarget, DebugInstrumentationTarget, DebugOptions, DebugRedactContext, DebugSource, ExportImageOptions, ExportedImage, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, Locale, MessageBundle, Messages, ModelStreamEvent, MountCardSlotRequest, MountedCardSlot, NodeRenderContext, NodeRenderer, OutcomeTone, ParseResult, ParserOptions, PartialJSONResult, Patch, PluginCommitContext, PluginSource, PluginStyle, PluginsLoader, RenderMountContext, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SanitizeSetting, SourceBlock, StreamParseOptions, StreamRouter, Usage, actionOutcome, applyPatches, assertPlugins, availableLocales, baseCss, buildSystemPrompt, cardChannel, collectNodeRenderers, collectPluginStyles, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, injectPluginStyles, isCardPatchResult, jsonLines, loadPlugins, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, resolveMessages, safeDebugValue, samePlugins, sanitizeHtml, sanitizeRenderedHtml, textLines, translate, translator, validateJSONSchema };

package/dist/index.js

@@ -978,6 +978,82 @@ function safeCall(listener, ...args) {
 	} catch {}
 }
 
+//#endregion
+//#region src/card-channel.ts
+const OPS = "register, merge, replace, batch";
+/**
+* Apply card messages arriving on a stream channel to a `CardStore`.
+*
+* ```ts
+* new StreamRouter()
+*   .channel("content", renderer)
+*   .on("cards", cardChannel(store))
+* ```
+*
+* This is the parallel half of the design. The content channel is one append-only buffer with a
+* single writer, because markdown block boundaries cannot survive two sources interleaving into
+* them. Cards are addressed by id instead, so anything on the wire — a background job, a tool that
+* finished late, a second model — can update one without touching the text, in any order, as many
+* times as it likes.
+*
+* Ordering is the store's contract, not this adapter's: a patch carrying `revision` is an
+* optimistic lock and a stale one is rejected through `onError`; a patch without one is
+* last-write-wins. Send `revision` when a late frame overwriting a newer state would be wrong.
+*
+* A card channel carries whole messages, not text deltas — one JSON object per frame.
+*/
+function cardChannel(store, options = {}) {
+	const report = (error, message) => {
+		if (options.onError) options.onError(error, message);
+		else console.error("[aigui] card channel:", error);
+	};
+	return (value) => {
+		let message = value;
+		if (typeof message === "string") try {
+			message = JSON.parse(message);
+		} catch {
+			report(new TypeError("Card channel received text that is not a JSON message"), value);
+			return;
+		}
+		if (typeof message !== "object" || message === null || Array.isArray(message)) {
+			report(new TypeError("A card message must be a JSON object"), value);
+			return;
+		}
+		const op = message.op;
+		try {
+			if (op === "register") {
+				const { id, type, data } = message;
+				if (typeof id !== "string" || typeof type !== "string") {
+					report(new TypeError("A register message needs a string id and type"), value);
+					return;
+				}
+				store.register({
+					id,
+					type,
+					data
+				});
+				return;
+			}
+			if (isCardPatchResult(message)) {
+				if (message.op === "batch") store.applyAll(message.patches);
+				else store.apply(message);
+				return;
+			}
+			if (op === "merge" || op === "replace") {
+				report(new TypeError(`A ${op} message needs a string cardId and a data field`), value);
+				return;
+			}
+			if (op === "batch") {
+				report(new TypeError("A batch message needs a patches array of merge or replace patches"), value);
+				return;
+			}
+			report(new TypeError(`Card message op must be one of ${OPS}, not ${JSON.stringify(op)}`), value);
+		} catch (error) {
+			report(error, value);
+		}
+	};
+}
+
 //#endregion
 //#region src/actions.ts
 let nextRuntimeId = 0;
@@ -2861,4 +2937,4 @@ function delay(ms, signal) {
 }
 
 //#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, DEFAULT_LOCALE, DebugEmitter, Renderer, StreamRouter, actionOutcome, applyPatches, assertPlugins, availableLocales, baseCss, buildSystemPrompt, collectNodeRenderers, collectPluginStyles, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, injectPluginStyles, isCardPatchResult, jsonLines, loadPlugins, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, resolveMessages, safeDebugValue, samePlugins, sanitizeHtml, sanitizeRenderedHtml, textLines, translate, translator, validateJSONSchema };
+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, DEFAULT_LOCALE, DebugEmitter, Renderer, StreamRouter, actionOutcome, applyPatches, assertPlugins, availableLocales, baseCss, buildSystemPrompt, cardChannel, collectNodeRenderers, collectPluginStyles, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, injectPluginStyles, isCardPatchResult, jsonLines, loadPlugins, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, resolveMessages, safeDebugValue, samePlugins, sanitizeHtml, sanitizeRenderedHtml, textLines, translate, translator, validateJSONSchema };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-gui/core",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "description": "Headless streaming renderer core for LLM-generated UI — markdown/JSON repair, card registry, AST diff, plugin engine, sanitizer.",
   "keywords": [
     "llm",