@ai-gui/core 0.3.0 → 0.4.1

package/dist/index.cjs

@@ -507,6 +507,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);
@@ -1175,6 +1181,10 @@ var ActionRuntime = class {
 	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);
@@ -1986,6 +1996,23 @@ var Renderer = class {
 			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;
@@ -2196,7 +2223,10 @@ 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");
 }
 

package/dist/index.d.cts

@@ -153,9 +153,24 @@ type RenderOutput = {
   data: unknown;
 } | {
   kind: "mount";
-  mount: (el: HTMLElement) => void | (() => void);
+  mount: (el: HTMLElement, context: RenderMountContext) => void | (() => void);
 };
+interface MountCardSlotRequest {
+  type: string;
+  data: unknown;
+}
+interface MountedCardSlot {
+  update(data: unknown): void;
+  destroy(): void;
+}
+interface RenderMountContext {
+  mountCard?: (host: HTMLElement, request: MountCardSlotRequest) => MountedCardSlot | undefined;
+}
 type NodeRenderer = (node: ASTNode) => RenderOutput | Promise<RenderOutput>;
+interface PluginCommitContext {
+  readonly generation: number;
+  emitDebug(type: string, data?: Record<string, unknown>): void;
+}
 type KnownJSONSchemaType = "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
 interface JSONSchema {
   type?: KnownJSONSchemaType | (string & {});
@@ -188,9 +203,11 @@ interface AIGuiPlugin {
   cards?: CardDef[];
   nodeRenderers?: Record<string, NodeRenderer>;
   isBlockComplete?: (nodeType: string, raw: string) => boolean;
+  /** Runs synchronously after the AST is finalized and before patches are dispatched. */
+  onASTCommit?: (nodes: readonly ASTNode[], context: PluginCommitContext) => void;
   css?: string;
   /** LLM-facing guidance describing this plugin's fence syntax. */
-  promptSpec?: string;
+  promptSpec?: string | (() => string);
 }
 interface RendererOptions extends DebugOptions {
   registry?: CardRegistry;
@@ -218,6 +235,8 @@ declare class CardRegistry {
   register(def: CardDef): void;
   has(type: string): boolean;
   getRender(type: string): unknown;
+  get(type: string): Readonly<CardDef> | undefined;
+  list(): Readonly<CardDef>[];
   parse(type: string, rawJson: string): CardParseResult;
   validate(type: string, data: unknown): boolean;
   private validateDefinition;
@@ -453,6 +472,8 @@ declare class ActionRuntime {
   getState(key: string): ActionState;
   /** Check the runtime allowlist without exposing executable action definitions. */
   hasAction(type: string): boolean;
+  /** List registered action names without exposing executable definitions. */
+  listActionTypes(): readonly string[];
   subscribe(listener: ActionStateListener): () => void;
   subscribeDebug(listener: DebugEventListener): () => void;
   cancel(key: string): boolean;
@@ -673,4 +694,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, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, ModelStreamEvent, NodeRenderer, ParseResult, ParserOptions, PartialJSONResult, Patch, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SourceBlock, StreamParseOptions, StreamRouter, Usage, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, textLines, validateJSONSchema };
+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, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, ModelStreamEvent, MountCardSlotRequest, MountedCardSlot, NodeRenderer, ParseResult, ParserOptions, PartialJSONResult, Patch, PluginCommitContext, RenderMountContext, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SourceBlock, StreamParseOptions, StreamRouter, Usage, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, textLines, validateJSONSchema };

package/dist/index.d.ts

@@ -153,9 +153,24 @@ type RenderOutput = {
   data: unknown;
 } | {
   kind: "mount";
-  mount: (el: HTMLElement) => void | (() => void);
+  mount: (el: HTMLElement, context: RenderMountContext) => void | (() => void);
 };
+interface MountCardSlotRequest {
+  type: string;
+  data: unknown;
+}
+interface MountedCardSlot {
+  update(data: unknown): void;
+  destroy(): void;
+}
+interface RenderMountContext {
+  mountCard?: (host: HTMLElement, request: MountCardSlotRequest) => MountedCardSlot | undefined;
+}
 type NodeRenderer = (node: ASTNode) => RenderOutput | Promise<RenderOutput>;
+interface PluginCommitContext {
+  readonly generation: number;
+  emitDebug(type: string, data?: Record<string, unknown>): void;
+}
 type KnownJSONSchemaType = "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
 interface JSONSchema {
   type?: KnownJSONSchemaType | (string & {});
@@ -188,9 +203,11 @@ interface AIGuiPlugin {
   cards?: CardDef[];
   nodeRenderers?: Record<string, NodeRenderer>;
   isBlockComplete?: (nodeType: string, raw: string) => boolean;
+  /** Runs synchronously after the AST is finalized and before patches are dispatched. */
+  onASTCommit?: (nodes: readonly ASTNode[], context: PluginCommitContext) => void;
   css?: string;
   /** LLM-facing guidance describing this plugin's fence syntax. */
-  promptSpec?: string;
+  promptSpec?: string | (() => string);
 }
 interface RendererOptions extends DebugOptions {
   registry?: CardRegistry;
@@ -218,6 +235,8 @@ declare class CardRegistry {
   register(def: CardDef): void;
   has(type: string): boolean;
   getRender(type: string): unknown;
+  get(type: string): Readonly<CardDef> | undefined;
+  list(): Readonly<CardDef>[];
   parse(type: string, rawJson: string): CardParseResult;
   validate(type: string, data: unknown): boolean;
   private validateDefinition;
@@ -453,6 +472,8 @@ declare class ActionRuntime {
   getState(key: string): ActionState;
   /** Check the runtime allowlist without exposing executable action definitions. */
   hasAction(type: string): boolean;
+  /** List registered action names without exposing executable definitions. */
+  listActionTypes(): readonly string[];
   subscribe(listener: ActionStateListener): () => void;
   subscribeDebug(listener: DebugEventListener): () => void;
   cancel(key: string): boolean;
@@ -673,4 +694,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, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, ModelStreamEvent, NodeRenderer, ParseResult, ParserOptions, PartialJSONResult, Patch, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SourceBlock, StreamParseOptions, StreamRouter, Usage, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, textLines, validateJSONSchema };
+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, FeedChunk, FeedOptions, FeedSource, JSONSchema, JSONSchemaValidationResult, ModelStreamEvent, MountCardSlotRequest, MountedCardSlot, NodeRenderer, ParseResult, ParserOptions, PartialJSONResult, Patch, PluginCommitContext, RenderMountContext, RenderOutput, Renderer, RendererOptions, SSEEvent, SSEOptions, SafeDebugValueOptions, SanitizeHtmlOptions, SourceBlock, StreamParseOptions, StreamRouter, Usage, applyPatches, buildSystemPrompt, collectNodeRenderers, contentDeltas, createActionRuntime, createParser, createParserWithMetadata, diffAst, getActionKey, getIdleActionState, isCardPatchResult, jsonLines, mockModelStream, ndjson, parsePartialJSON, parseSSE, pluginNodeTypes, readableBytes, repairMarkdown, safeDebugValue, sanitizeHtml, textLines, validateJSONSchema };

package/dist/index.js

@@ -483,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);
@@ -1151,6 +1157,10 @@ var ActionRuntime = class {
 	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);
@@ -1962,6 +1972,23 @@ var Renderer = class {
 			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;
@@ -2172,7 +2199,10 @@ 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");
 }
 

package/package.json

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