@ai-gui/core 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -47,6 +47,58 @@ interface SanitizeHtmlOptions {
  */
 declare function sanitizeHtml(html: string, options?: SanitizeHtmlOptions): string;
 
+//#endregion
+//#region src/debug-events.d.ts
+type DebugSource = "renderer" | "action-runtime" | "card-store";
+interface DebugEvent<TData extends Record<string, unknown> = Record<string, unknown>> {
+  type: string;
+  source: DebugSource;
+  timestamp: number;
+  sequence: number;
+  data: TData;
+}
+type DebugEventListener = (event: DebugEvent) => void;
+interface DebugEventTarget {
+  readonly debugSource: DebugSource;
+  subscribeDebug(listener: DebugEventListener): () => void;
+}
+interface DebugOptions {
+  debug?: boolean;
+  onDebugEvent?: DebugEventListener;
+  maxStringLength?: number;
+  maxDepth?: number;
+  maxNodes?: number;
+  redact?: (context: DebugRedactContext) => boolean;
+}
+interface DebugRedactContext {
+  key: string;
+  path: readonly (string | number)[];
+  value: unknown;
+}
+interface DebugInstrumentationTarget extends DebugEventTarget {
+  readonly debugEnabled: boolean;
+  emitDebug(type: string, data?: Record<string, unknown>): void;
+}
+interface SafeDebugValueOptions {
+  maxStringLength?: number;
+  maxDepth?: number;
+  maxNodes?: number;
+  redact?: DebugOptions["redact"];
+}
+declare class DebugEmitter {
+  private readonly enabled;
+  private readonly source;
+  private readonly limits;
+  private readonly listeners;
+  private sequence;
+  constructor(source: DebugSource, options?: DebugOptions);
+  get active(): boolean;
+  get available(): boolean;
+  subscribe(listener: DebugEventListener): () => void;
+  emit(type: string, data?: Record<string, unknown>): void;
+}
+declare function safeDebugValue(value: unknown, options?: SafeDebugValueOptions): unknown;
+
 //#endregion
 //#region src/types.d.ts
 /** Framework-agnostic render node. */
@@ -62,6 +114,7 @@ interface ASTNode {
   complete?: boolean;
   /** card-specific payload */
   card?: {
+    id?: string;
     type: string;
     data: unknown;
     complete: boolean;
@@ -100,14 +153,40 @@ 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?: string;
+  type?: KnownJSONSchemaType | (string & {});
   properties?: Record<string, JSONSchema>;
   items?: JSONSchema;
-  required?: string[];
+  required?: readonly string[];
+  additionalProperties?: boolean | JSONSchema;
+  enum?: readonly unknown[];
+  const?: unknown;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  minimum?: number;
+  maximum?: number;
+  minItems?: number;
+  maxItems?: number;
   [k: string]: unknown;
 }
 interface CardDef<TData = unknown, TComponent = unknown> {
@@ -124,11 +203,13 @@ 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 {
+interface RendererOptions extends DebugOptions {
   registry?: CardRegistry;
   plugins?: AIGuiPlugin[];
   sanitize?: boolean | SanitizeHtmlOptions;
@@ -154,13 +235,288 @@ 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;
-  private validate;
+  validate(type: string, data: unknown): boolean;
+  private validateDefinition;
   toPromptSpec(): string;
   get size(): number;
   toJSONSchema(): JSONSchema;
 }
 
+//#endregion
+//#region src/card-store.d.ts
+declare const CARD_ID_MAX_LENGTH = 256;
+declare const CARD_JSON_MAX_DEPTH = 32;
+declare const CARD_JSON_MAX_NODES = 10000;
+declare const CARD_PATCH_BATCH_MAX_SIZE = 100;
+type CardAction = {
+  status: "idle";
+} | {
+  status: "loading";
+  actionId: string;
+} | {
+  status: "success";
+  actionId: string;
+} | {
+  status: "error";
+  actionId: string;
+  error: CardActionError;
+};
+interface CardActionError {
+  name: string;
+  message: string;
+}
+interface CardRecord {
+  readonly id: string;
+  readonly type: string;
+  readonly data: unknown;
+  readonly revision: number;
+  readonly action: CardAction;
+}
+interface CardPatch {
+  op: "merge" | "replace";
+  cardId: string;
+  data: unknown;
+  revision?: number;
+}
+interface CardPatchBatch {
+  op: "batch";
+  patches: CardPatch[];
+}
+type CardPatchResult = CardPatch | CardPatchBatch;
+interface CardSnapshot {
+  version: 1;
+  cards: Array<Pick<CardRecord, "id" | "type" | "data" | "revision">>;
+}
+interface CardStoreOptions extends DebugOptions {
+  registry?: CardRegistry;
+}
+type CardListener = (card: CardRecord | undefined) => void;
+type CardStoreListener = (cards: readonly CardRecord[]) => void;
+declare class CardStore {
+  readonly debugSource: "card-store";
+  private readonly registry?;
+  private cards;
+  private lastMutationEpoch;
+  private mutationEpoch;
+  private readonly listeners;
+  private readonly allListeners;
+  private readonly debug;
+  constructor(options?: CardStoreOptions);
+  register(input: {
+    id: string;
+    type: string;
+    data: unknown;
+  }): CardRecord;
+  get(id: string): CardRecord | undefined;
+  list(): CardRecord[];
+  subscribe(id: string, listener: CardListener): () => void;
+  subscribeAll(listener: CardStoreListener): () => void;
+  subscribeDebug(listener: DebugEventListener): () => void;
+  apply(patch: CardPatch): CardRecord;
+  applyAll(patches: readonly CardPatch[]): CardRecord[];
+  delete(id: string): boolean;
+  clear(): void;
+  snapshot(): CardSnapshot;
+  restore(snapshot: CardSnapshot): void;
+  beginAction(id: string, actionId: string): boolean;
+  succeedAction(id: string, actionId: string): boolean;
+  failAction(id: string, actionId: string, error: unknown): boolean;
+  cancelAction(id: string, actionId: string): boolean;
+  isActionCurrent(id: string, actionId: string): boolean;
+  revisions(): ReadonlyMap<string, number>;
+  captureMutationEpoch(): number;
+  applyActionResult(result: CardPatchResult, startedEpoch: number): CardRecord[];
+  private preparePatch;
+  private assertValid;
+  private setAction;
+  private nextMutationEpoch;
+  private notify;
+  private notifyOne;
+  private notifyAll;
+}
+declare class CardStoreError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+declare class CardNotFoundError extends CardStoreError {
+  constructor(id: string);
+}
+declare class CardTypeConflictError extends CardStoreError {
+  constructor(id: string, currentType: string, nextType: string);
+}
+declare class CardValidationError extends CardStoreError {
+  constructor(type: string);
+}
+declare class CardRevisionConflictError extends CardStoreError {
+  constructor(id: string, expected: number, actual: number);
+}
+declare class CardJSONError extends CardStoreError {}
+declare class CardLimitError extends CardStoreError {}
+declare class CardSnapshotError extends CardStoreError {}
+declare function isCardPatchResult(value: unknown): value is CardPatchResult;
+
+//#endregion
+//#region src/json-schema.d.ts
+interface JSONSchemaValidationResult {
+  valid: boolean;
+  issues: string[];
+}
+/** Small, dependency-free validator for the JSON Schema subset used by AIGUI definitions. */
+declare function validateJSONSchema(schema: JSONSchema, value: unknown): JSONSchemaValidationResult;
+
+//#endregion
+//#region src/actions.d.ts
+interface ActionContext {
+  signal: AbortSignal;
+  actionId: string;
+  cardType?: string;
+  cardId?: string;
+}
+interface ActionDefinition<TParams = unknown, TResult = unknown> {
+  type: string;
+  schema?: JSONSchema;
+  run: (params: TParams, context: ActionContext) => TResult | Promise<TResult>;
+}
+interface ActionRegisterOptions {
+  override?: boolean;
+}
+declare class ActionRegistry {
+  private actions;
+  register<TParams, TResult>(definition: ActionDefinition<TParams, TResult>, options?: ActionRegisterOptions): void;
+  has(type: string): boolean;
+  get(type: string): ActionDefinition<any, unknown> | undefined;
+  list(): ActionDefinition<any, unknown>[];
+}
+interface ActionRequest<TParams = unknown> {
+  type: string;
+  params: TParams;
+  cardType?: string;
+  cardId?: string;
+}
+interface ActionDispatchOptions {
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  owner?: object;
+}
+type ActionStatus = "idle" | "pending" | "success" | "error" | "cancelled";
+interface ActionStateBase {
+  key: string;
+  type: string;
+  cardType?: string;
+  cardId?: string;
+  actionId?: string;
+}
+type ActionState = (ActionStateBase & {
+  status: "idle";
+}) | (ActionStateBase & {
+  status: "pending";
+  actionId: string;
+}) | (ActionStateBase & {
+  status: "success";
+  actionId: string;
+  result: unknown;
+}) | (ActionStateBase & {
+  status: "error";
+  actionId: string;
+  error: ActionRuntimeError;
+}) | (ActionStateBase & {
+  status: "cancelled";
+  actionId: string;
+  error: ActionAbortedError;
+});
+interface ActionEventBase {
+  key: string;
+  type: string;
+  params: unknown;
+  actionId: string;
+  cardType?: string;
+  cardId?: string;
+}
+type ActionStartEvent = ActionEventBase;
+type ActionSuccessEvent = ActionEventBase & {
+  result: unknown;
+};
+type ActionErrorEvent = ActionEventBase & {
+  error: ActionRuntimeError;
+};
+interface ActionRuntimeOptions extends DebugOptions {
+  registry: ActionRegistry;
+  cardStore?: CardStore;
+  timeoutMs?: number;
+  onActionStart?: (event: ActionStartEvent) => void;
+  onActionSuccess?: (event: ActionSuccessEvent) => void;
+  onActionError?: (event: ActionErrorEvent) => void;
+}
+type ActionStateListener = (state: ActionState) => void;
+declare class ActionRuntime {
+  readonly debugSource: "action-runtime";
+  private readonly registry;
+  private readonly cardStore?;
+  private readonly defaultTimeoutMs?;
+  private readonly onActionStart?;
+  private readonly onActionSuccess?;
+  private readonly onActionError?;
+  private readonly states;
+  private readonly pending;
+  private readonly listeners;
+  private readonly defaultOwner;
+  private readonly runtimeId;
+  private generation;
+  private nextActionId;
+  private destroyed;
+  private readonly debug;
+  constructor(options: ActionRuntimeOptions);
+  dispatch<TResult = unknown>(request: ActionRequest, options?: ActionDispatchOptions): Promise<TResult>;
+  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;
+  reset(): void;
+  destroy(): void;
+  private rejectPreflight;
+  private isPublic;
+  private commit;
+  private notify;
+}
+declare function createActionRuntime(options: ActionRuntimeOptions): ActionRuntime;
+declare class ActionRuntimeError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+declare class ActionAlreadyRegisteredError extends ActionRuntimeError {
+  constructor(type: string);
+}
+declare class ActionNotFoundError extends ActionRuntimeError {
+  constructor(type: string);
+}
+declare class ActionValidationError extends ActionRuntimeError {
+  readonly actionType: string;
+  readonly issues: string[];
+  constructor(actionType: string, issues: string[]);
+}
+declare class ActionExecutionError extends ActionRuntimeError {
+  constructor(type: string, cause: unknown);
+}
+declare class ActionAbortedError extends ActionRuntimeError {
+  constructor(type: string);
+}
+declare class ActionTimeoutError extends ActionRuntimeError {
+  readonly timeoutMs: number;
+  constructor(type: string, timeoutMs: number);
+}
+declare class ActionDestroyedError extends ActionRuntimeError {
+  constructor();
+}
+declare function getActionKey(type: string, cardType?: string, cardId?: string): string;
+declare function getIdleActionState(key: string): Extract<ActionState, {
+  status: "idle";
+}>;
+
 //#endregion
 //#region src/parser.d.ts
 interface ParserOptions {
@@ -186,8 +542,11 @@ declare function createParserWithMetadata(options?: ParserOptions): (src: string
 
 //#endregion
 //#region src/plugins.d.ts
+interface CollectNodeRendererOptions extends DebugOptions {
+  debugTarget?: DebugInstrumentationTarget;
+}
 /** Merge every plugin's `nodeRenderers` into a single map (later plugins win). */
-declare function collectNodeRenderers(plugins?: AIGuiPlugin[]): Record<string, NodeRenderer>;
+declare function collectNodeRenderers(plugins?: AIGuiPlugin[], debugOptions?: CollectNodeRendererOptions): Record<string, NodeRenderer>;
 /** The set of node types claimed by the given plugins. */
 declare function pluginNodeTypes(plugins?: AIGuiPlugin[]): Set<string>;
 
@@ -206,6 +565,7 @@ declare function applyPatches(nodes: ASTNode[], patches: Patch[]): ASTNode[];
  * the resulting patches via `onPatch`.
  */
 declare class Renderer {
+  readonly debugSource: "renderer";
   private buffer;
   private prevAst;
   private parse;
@@ -216,8 +576,12 @@ declare class Renderer {
   private activeFeed?;
   private renderScheduled;
   private scheduleGeneration;
+  private readonly debug;
   constructor(options?: RendererOptions);
+  get debugEnabled(): boolean;
+  emitDebug(type: string, data?: Record<string, unknown>): void;
   push(chunk: string): void;
+  subscribeDebug(listener: DebugEventListener): () => void;
   feed(source: FeedSource, options?: FeedOptions): Promise<void>;
   reset(): void;
   /** Immediately render pending buffered input, bypassing the scheduler. */
@@ -225,6 +589,7 @@ declare class Renderer {
   private scheduleRender;
   private cancelActiveFeed;
   private render;
+  private sanitizeNodesWithDebug;
 }
 
 //#endregion
@@ -268,4 +633,65 @@ interface BuildSystemPromptOptions {
 declare function buildSystemPrompt(options?: BuildSystemPromptOptions): string;
 
 //#endregion
-export { AIGuiPlugin, ASTNode, BuildSystemPromptOptions, CardDef, CardParseResult, CardRegistry, ChannelSink, FeedChunk, FeedOptions, FeedSource, JSONSchema, NodeRenderer, ParseResult, ParserOptions, PartialJSONResult, Patch, RenderOutput, Renderer, RendererOptions, SanitizeHtmlOptions, SourceBlock, StreamRouter, applyPatches, buildSystemPrompt, collectNodeRenderers, createParser, createParserWithMetadata, diffAst, parsePartialJSON, pluginNodeTypes, repairMarkdown, sanitizeHtml };
+//#region src/model-stream.d.ts
+interface Citation {
+  type?: string;
+  id?: string;
+  url?: string;
+  title?: string;
+  citedText?: string;
+  [key: string]: unknown;
+}
+interface Usage {
+  inputTokens?: number;
+  outputTokens?: number;
+  totalTokens?: number;
+  [key: string]: unknown;
+}
+type ModelStreamEvent = {
+  type: "content";
+  delta: string;
+} | {
+  type: "reasoning";
+  delta: string;
+} | {
+  type: "citation";
+  data: Citation;
+} | {
+  type: "usage";
+  data: Usage;
+} | {
+  type: "error";
+  error: unknown;
+};
+type ByteStreamSource = Response | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array | string>;
+interface StreamParseOptions {
+  signal?: AbortSignal;
+  onMalformed?: (error: Error, input: string) => "skip" | void;
+}
+interface SSEOptions extends StreamParseOptions {
+  parseJSON?: boolean;
+  doneData?: string | false;
+}
+interface SSEEvent<T = string> {
+  data: T;
+  event?: string;
+  id?: string;
+  retry?: number;
+}
+declare function parseSSE(source: ByteStreamSource, options: SSEOptions & {
+  parseJSON: true;
+}): AsyncGenerator<SSEEvent<unknown>>;
+declare function parseSSE(source: ByteStreamSource, options?: SSEOptions): AsyncGenerator<SSEEvent<string>>;
+declare function jsonLines<T = unknown>(source: ByteStreamSource, options?: StreamParseOptions): AsyncGenerator<T>;
+declare const ndjson: typeof jsonLines;
+declare function textLines(source: ByteStreamSource, options?: Pick<StreamParseOptions, "signal">): AsyncGenerator<string>;
+declare function contentDeltas(events: AsyncIterable<ModelStreamEvent>): AsyncGenerator<string>;
+declare function mockModelStream(events: Iterable<ModelStreamEvent> | AsyncIterable<ModelStreamEvent>, options?: {
+  delayMs?: number;
+  signal?: AbortSignal;
+}): AsyncGenerator<ModelStreamEvent>;
+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, 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 };