@ai-gui/core 0.6.1 → 0.7.0

package/dist/index.cjs

@@ -579,6 +579,38 @@ var CardRegistry = class {
 	}
 };
 
+//#endregion
+//#region src/action-outcome.ts
+const TONES = new Set([
+	"positive",
+	"warning",
+	"negative",
+	"neutral"
+]);
+function isTone(value) {
+	return typeof value === "string" && TONES.has(value);
+}
+/**
+* Read an outcome out of whatever a handler returned.
+*
+* A handler answers with its own result type, so the outcome is looked for rather than required:
+* `{ tone: "warning", message: "…" }` on its own, or under an `outcome` key beside the handler's
+* own data. Anything else means the handler did not judge, and the host shows nothing.
+*/
+function actionOutcome(value) {
+	const candidate = value;
+	const source = candidate?.outcome ?? candidate;
+	if (!source || !isTone(source.tone)) return void 0;
+	const outcome = { tone: source.tone };
+	if (typeof source.message === "string" && source.message.trim() !== "") outcome.message = source.message;
+	if (source.fields && typeof source.fields === "object") {
+		const fields = {};
+		for (const [name, tone] of Object.entries(source.fields)) if (isTone(tone)) fields[name] = tone;
+		if (Object.keys(fields).length > 0) outcome.fields = fields;
+	}
+	return outcome;
+}
+
 //#endregion
 //#region src/card-store.ts
 const CARD_ID_MAX_LENGTH = 256;
@@ -748,8 +780,13 @@ var CardStore = class {
 			actionId
 		}, true);
 	}
-	succeedAction(id, actionId) {
-		return this.setAction(id, actionId, {
+	succeedAction(id, actionId, result) {
+		const outcome = actionOutcome(result);
+		return this.setAction(id, actionId, outcome ? {
+			status: "success",
+			actionId,
+			outcome
+		} : {
 			status: "success",
 			actionId
 		});
@@ -1121,7 +1158,7 @@ var ActionRuntime = class {
 					result
 				});
 			}
-			if (request.cardId && this.cardStore && canAffectCard) settleCardAction(() => this.cardStore?.succeedAction(request.cardId, actionId));
+			if (request.cardId && this.cardStore && canAffectCard) settleCardAction(() => this.cardStore?.succeedAction(request.cardId, actionId, result));
 			resolvePromise(result);
 		};
 		function finishError(cause) {
@@ -2633,6 +2670,7 @@ exports.CardValidationError = CardValidationError
 exports.DebugEmitter = DebugEmitter
 exports.Renderer = Renderer
 exports.StreamRouter = StreamRouter
+exports.actionOutcome = actionOutcome
 exports.applyPatches = applyPatches
 exports.buildSystemPrompt = buildSystemPrompt
 exports.collectNodeRenderers = collectNodeRenderers

package/dist/index.d.cts

@@ -283,6 +283,40 @@ declare class CardRegistry {
   toJSONSchema(): JSONSchema;
 }
 
+//#endregion
+//#region src/action-outcome.d.ts
+/**
+ * How a completed action turned out, as opposed to whether it completed.
+ *
+ * The lifecycle a card and an action already report — idle, loading, success, error — answers "did
+ * the dispatch run". It cannot answer "was the answer right": a student who picks the wrong option
+ * submits perfectly well, so the action succeeds and nothing on screen says otherwise. Putting a
+ * "warning" beside "error" in that lifecycle would fold a wrong answer in with a failed request,
+ * which is the one distinction a host needs to keep.
+ *
+ * So the outcome travels on its own, returned by the handler that judged it.
+ */
+/** How the result should read to the person looking at it. */
+type OutcomeTone = "positive" | "warning" | "negative" | "neutral";
+interface ActionOutcome {
+  tone: OutcomeTone;
+  /** A sentence to show beside the control — why it is wrong, or what was expected. */
+  message?: string;
+  /**
+   * Per-field verdicts, so one wrong answer marks the field it came from rather than the whole
+   * form. Keyed by field name.
+   */
+  fields?: Record<string, OutcomeTone>;
+}
+/**
+ * Read an outcome out of whatever a handler returned.
+ *
+ * A handler answers with its own result type, so the outcome is looked for rather than required:
+ * `{ tone: "warning", message: "…" }` on its own, or under an `outcome` key beside the handler's
+ * own data. Anything else means the handler did not judge, and the host shows nothing.
+ */
+declare function actionOutcome(value: unknown): ActionOutcome | undefined;
+
 //#endregion
 //#region src/card-store.d.ts
 declare const CARD_ID_MAX_LENGTH = 256;
@@ -294,9 +328,14 @@ type CardAction = {
 } | {
   status: "loading";
   actionId: string;
-} | {
+}
+/**
+ * The dispatch ran. `outcome` carries how it turned out, when the handler judged it — a student
+ * answering wrong submits successfully, so the verdict cannot live in the status.
+ */ | {
   status: "success";
   actionId: string;
+  outcome?: ActionOutcome;
 } | {
   status: "error";
   actionId: string;
@@ -360,7 +399,7 @@ declare class CardStore {
   snapshot(): CardSnapshot;
   restore(snapshot: CardSnapshot): void;
   beginAction(id: string, actionId: string): boolean;
-  succeedAction(id: string, actionId: string): boolean;
+  succeedAction(id: string, actionId: string, result?: unknown): boolean;
   failAction(id: string, actionId: string, error: unknown): boolean;
   cancelAction(id: string, actionId: string): boolean;
   isActionCurrent(id: string, actionId: string): boolean;
@@ -783,4 +822,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, 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, DebugEmitter, DebugEvent, DebugEventListener, DebugEventTarget, DebugInstrumentationTarget, DebugOptions, DebugRedactContext, DebugSource, ExportImageOptions, ExportedImage, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, ModelStreamEvent, MountCardSlotRequest, MountedCardSlot, NodeRenderContext, NodeRenderer, ParseResult, ParserOptions, PartialJSONResult, Patch, PluginCommitContext, RenderMountContext, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SanitizeSetting, SourceBlock, StreamParseOptions, StreamRouter, Usage, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, sanitizeRenderedHtml, textLines, 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, CardDef, CardJSONError, CardLimitError, CardListener, CardNotFoundError, CardParseResult, CardPatch, CardPatchBatch, CardPatchResult, CardRecord, CardRegistry, CardRevisionConflictError, CardSnapshot, CardSnapshotError, CardStore, CardStoreError, CardStoreListener, CardStoreOptions, CardTypeConflictError, CardValidationError, ChannelSink, Citation, CollectNodeRendererOptions, DebugEmitter, DebugEvent, DebugEventListener, DebugEventTarget, DebugInstrumentationTarget, DebugOptions, DebugRedactContext, DebugSource, ExportImageOptions, ExportedImage, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, ModelStreamEvent, MountCardSlotRequest, MountedCardSlot, NodeRenderContext, NodeRenderer, OutcomeTone, ParseResult, ParserOptions, PartialJSONResult, Patch, PluginCommitContext, RenderMountContext, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SanitizeSetting, SourceBlock, StreamParseOptions, StreamRouter, Usage, actionOutcome, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, sanitizeRenderedHtml, textLines, validateJSONSchema };

package/dist/index.d.ts

@@ -283,6 +283,40 @@ declare class CardRegistry {
   toJSONSchema(): JSONSchema;
 }
 
+//#endregion
+//#region src/action-outcome.d.ts
+/**
+ * How a completed action turned out, as opposed to whether it completed.
+ *
+ * The lifecycle a card and an action already report — idle, loading, success, error — answers "did
+ * the dispatch run". It cannot answer "was the answer right": a student who picks the wrong option
+ * submits perfectly well, so the action succeeds and nothing on screen says otherwise. Putting a
+ * "warning" beside "error" in that lifecycle would fold a wrong answer in with a failed request,
+ * which is the one distinction a host needs to keep.
+ *
+ * So the outcome travels on its own, returned by the handler that judged it.
+ */
+/** How the result should read to the person looking at it. */
+type OutcomeTone = "positive" | "warning" | "negative" | "neutral";
+interface ActionOutcome {
+  tone: OutcomeTone;
+  /** A sentence to show beside the control — why it is wrong, or what was expected. */
+  message?: string;
+  /**
+   * Per-field verdicts, so one wrong answer marks the field it came from rather than the whole
+   * form. Keyed by field name.
+   */
+  fields?: Record<string, OutcomeTone>;
+}
+/**
+ * Read an outcome out of whatever a handler returned.
+ *
+ * A handler answers with its own result type, so the outcome is looked for rather than required:
+ * `{ tone: "warning", message: "…" }` on its own, or under an `outcome` key beside the handler's
+ * own data. Anything else means the handler did not judge, and the host shows nothing.
+ */
+declare function actionOutcome(value: unknown): ActionOutcome | undefined;
+
 //#endregion
 //#region src/card-store.d.ts
 declare const CARD_ID_MAX_LENGTH = 256;
@@ -294,9 +328,14 @@ type CardAction = {
 } | {
   status: "loading";
   actionId: string;
-} | {
+}
+/**
+ * The dispatch ran. `outcome` carries how it turned out, when the handler judged it — a student
+ * answering wrong submits successfully, so the verdict cannot live in the status.
+ */ | {
   status: "success";
   actionId: string;
+  outcome?: ActionOutcome;
 } | {
   status: "error";
   actionId: string;
@@ -360,7 +399,7 @@ declare class CardStore {
   snapshot(): CardSnapshot;
   restore(snapshot: CardSnapshot): void;
   beginAction(id: string, actionId: string): boolean;
-  succeedAction(id: string, actionId: string): boolean;
+  succeedAction(id: string, actionId: string, result?: unknown): boolean;
   failAction(id: string, actionId: string, error: unknown): boolean;
   cancelAction(id: string, actionId: string): boolean;
   isActionCurrent(id: string, actionId: string): boolean;
@@ -783,4 +822,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, 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, DebugEmitter, DebugEvent, DebugEventListener, DebugEventTarget, DebugInstrumentationTarget, DebugOptions, DebugRedactContext, DebugSource, ExportImageOptions, ExportedImage, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, ModelStreamEvent, MountCardSlotRequest, MountedCardSlot, NodeRenderContext, NodeRenderer, ParseResult, ParserOptions, PartialJSONResult, Patch, PluginCommitContext, RenderMountContext, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SanitizeSetting, SourceBlock, StreamParseOptions, StreamRouter, Usage, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, sanitizeRenderedHtml, textLines, 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, CardDef, CardJSONError, CardLimitError, CardListener, CardNotFoundError, CardParseResult, CardPatch, CardPatchBatch, CardPatchResult, CardRecord, CardRegistry, CardRevisionConflictError, CardSnapshot, CardSnapshotError, CardStore, CardStoreError, CardStoreListener, CardStoreOptions, CardTypeConflictError, CardValidationError, ChannelSink, Citation, CollectNodeRendererOptions, DebugEmitter, DebugEvent, DebugEventListener, DebugEventTarget, DebugInstrumentationTarget, DebugOptions, DebugRedactContext, DebugSource, ExportImageOptions, ExportedImage, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, ModelStreamEvent, MountCardSlotRequest, MountedCardSlot, NodeRenderContext, NodeRenderer, OutcomeTone, ParseResult, ParserOptions, PartialJSONResult, Patch, PluginCommitContext, RenderMountContext, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SanitizeSetting, SourceBlock, StreamParseOptions, StreamRouter, Usage, actionOutcome, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, sanitizeRenderedHtml, textLines, validateJSONSchema };

package/dist/index.js

@@ -555,6 +555,38 @@ var CardRegistry = class {
 	}
 };
 
+//#endregion
+//#region src/action-outcome.ts
+const TONES = new Set([
+	"positive",
+	"warning",
+	"negative",
+	"neutral"
+]);
+function isTone(value) {
+	return typeof value === "string" && TONES.has(value);
+}
+/**
+* Read an outcome out of whatever a handler returned.
+*
+* A handler answers with its own result type, so the outcome is looked for rather than required:
+* `{ tone: "warning", message: "…" }` on its own, or under an `outcome` key beside the handler's
+* own data. Anything else means the handler did not judge, and the host shows nothing.
+*/
+function actionOutcome(value) {
+	const candidate = value;
+	const source = candidate?.outcome ?? candidate;
+	if (!source || !isTone(source.tone)) return void 0;
+	const outcome = { tone: source.tone };
+	if (typeof source.message === "string" && source.message.trim() !== "") outcome.message = source.message;
+	if (source.fields && typeof source.fields === "object") {
+		const fields = {};
+		for (const [name, tone] of Object.entries(source.fields)) if (isTone(tone)) fields[name] = tone;
+		if (Object.keys(fields).length > 0) outcome.fields = fields;
+	}
+	return outcome;
+}
+
 //#endregion
 //#region src/card-store.ts
 const CARD_ID_MAX_LENGTH = 256;
@@ -724,8 +756,13 @@ var CardStore = class {
 			actionId
 		}, true);
 	}
-	succeedAction(id, actionId) {
-		return this.setAction(id, actionId, {
+	succeedAction(id, actionId, result) {
+		const outcome = actionOutcome(result);
+		return this.setAction(id, actionId, outcome ? {
+			status: "success",
+			actionId,
+			outcome
+		} : {
 			status: "success",
 			actionId
 		});
@@ -1097,7 +1134,7 @@ var ActionRuntime = class {
 					result
 				});
 			}
-			if (request.cardId && this.cardStore && canAffectCard) settleCardAction(() => this.cardStore?.succeedAction(request.cardId, actionId));
+			if (request.cardId && this.cardStore && canAffectCard) settleCardAction(() => this.cardStore?.succeedAction(request.cardId, actionId, result));
 			resolvePromise(result);
 		};
 		function finishError(cause) {
@@ -2582,4 +2619,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, DebugEmitter, Renderer, StreamRouter, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, sanitizeRenderedHtml, textLines, 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, DebugEmitter, Renderer, StreamRouter, actionOutcome, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, downloadImage, exportRenderedImages, exportSVGToImage, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, sanitizeRenderedHtml, textLines, validateJSONSchema };

package/package.json

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