@ai-gui/core 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -32,6 +32,11 @@ declare function repairMarkdown(buffer: string): string;
 
 //#endregion
 //#region src/sanitizer.d.ts
+interface SanitizeHtmlOptions {
+  sanitizer?: (html: string) => string;
+  /** Bare SSR either escapes all markup (default) or fails explicitly. */
+  ssr?: "escape" | "throw";
+}
 /**
  * Sanitize an HTML string, stripping scripts and unsafe attributes.
  *
@@ -40,7 +45,7 @@ declare function repairMarkdown(buffer: string): string;
  * fall back to escaping the HTML-significant characters. This never emits raw
  * markup and never throws.
  */
-declare function sanitizeHtml(html: string): string;
+declare function sanitizeHtml(html: string, options?: SanitizeHtmlOptions): string;
 
 //#endregion
 //#region src/types.d.ts
@@ -53,6 +58,8 @@ interface ASTNode {
   html?: string;
   attrs?: Record<string, string>;
   children?: ASTNode[];
+  /** Whether a streaming block has enough source to invoke its renderer. */
+  complete?: boolean;
   /** card-specific payload */
   card?: {
     type: string;
@@ -70,6 +77,10 @@ type Patch = {
   op: "update";
   key: string;
   node: ASTNode;
+} | {
+  op: "move";
+  key: string;
+  index: number;
 } | {
   op: "remove";
   key: string;
@@ -120,9 +131,16 @@ interface AIGuiPlugin {
 interface RendererOptions {
   registry?: CardRegistry;
   plugins?: AIGuiPlugin[];
-  sanitize?: boolean;
+  sanitize?: boolean | SanitizeHtmlOptions;
+  /** Coalesce multiple pushes by scheduling one render callback. */
+  scheduler?: (render: () => void) => void;
   onPatch?: (patches: Patch[], nodes: ASTNode[]) => void;
 }
+interface FeedOptions {
+  signal?: AbortSignal;
+}
+type FeedChunk = string | Uint8Array;
+type FeedSource = AsyncIterable<FeedChunk> | ReadableStream<FeedChunk>;
 
 //#endregion
 //#region src/card-registry.d.ts
@@ -139,6 +157,7 @@ declare class CardRegistry {
   parse(type: string, rawJson: string): CardParseResult;
   private validate;
   toPromptSpec(): string;
+  get size(): number;
   toJSONSchema(): JSONSchema;
 }
 
@@ -149,8 +168,21 @@ interface ParserOptions {
   plugins?: AIGuiPlugin[];
   configureMd?: (md: MarkdownIt) => void;
 }
+interface SourceBlock {
+  start: number;
+  end: number;
+  nodeStart: number;
+  nodeEnd: number;
+}
+interface ParseResult {
+  nodes: ASTNode[];
+  blocks: SourceBlock[];
+  incrementalSafe: boolean;
+}
 /** Build a parser that turns markdown source into a flat list of ASTNodes. */
-declare function createParser(options?: ParserOptions): (src: string) => ASTNode[];
+declare function createParser(options?: ParserOptions): (src: string, rawSrc?: string) => ASTNode[];
+/** Build a parser that also reports the source range for each top-level block. */
+declare function createParserWithMetadata(options?: ParserOptions): (src: string, rawSrc?: string, sourceOffset?: number) => ParseResult;
 
 //#endregion
 //#region src/plugins.d.ts
@@ -163,6 +195,8 @@ declare function pluginNodeTypes(plugins?: AIGuiPlugin[]): Set<string>;
 //#region src/diff.d.ts
 /** Produce a minimal set of patches turning `prev` into `next`, keyed by node key. */
 declare function diffAst(prev: ASTNode[], next: ASTNode[]): Patch[];
+/** Apply patches in order, primarily for framework adapters and verification. */
+declare function applyPatches(nodes: ASTNode[], patches: Patch[]): ASTNode[];
 
 //#endregion
 //#region src/renderer.d.ts
@@ -175,55 +209,47 @@ declare class Renderer {
   private buffer;
   private prevAst;
   private parse;
+  private parsed?;
   private options;
   private sanitize;
+  private generation;
+  private activeFeed?;
+  private renderScheduled;
+  private scheduleGeneration;
   constructor(options?: RendererOptions);
   push(chunk: string): void;
-  feed(source: AsyncIterable<string> | ReadableStream<string>): Promise<void>;
+  feed(source: FeedSource, options?: FeedOptions): Promise<void>;
   reset(): void;
+  /** Immediately render pending buffered input, bypassing the scheduler. */
+  flush(): void;
+  private scheduleRender;
+  private cancelActiveFeed;
   private render;
 }
 
 //#endregion
 //#region src/stream-router.d.ts
-/**
- * A consumer of a channel's text stream. `Renderer` satisfies this shape.
- */
+/** A consumer of a channel's text stream. `Renderer` satisfies this shape. */
 interface ChannelSink {
   push(chunk: string): void;
 }
 /** Handler for structured data values (and text deltas as raw strings). */
 type ChannelHandler = (value: unknown) => void;
-/**
- * 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.
- */
+type StreamChunk = string | Uint8Array;
+/** Demultiplex JSON-lines and standards-compliant SSE into named channels. */
 declare class StreamRouter {
   private readonly sinks;
   private readonly handlers;
-  /** Bind a text-stream sink to a channel: text deltas call `sink.push(delta)`. */
+  /** Most recently received SSE `id` field. */
+  lastEventId: string;
+  /** Most recently received valid non-negative SSE reconnection delay. */
+  retry: number | undefined;
   channel(name: string, sink: ChannelSink): this;
-  /** Bind a handler to a channel: data values (and deltas as strings) call it. */
   on(name: string, handler: ChannelHandler): 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).
-   */
-  feed(source: AsyncIterable<string> | ReadableStream<Uint8Array | string>): Promise<void>;
-  /** Process a single raw line; returns the (possibly updated) current event. */
-  private processLine;
-  /** Route a text delta: to a bound sink and/or an on() handler (either/both). */
+  feed(source: AsyncIterable<StreamChunk> | ReadableStream<StreamChunk>): Promise<void>;
+  private dispatchPayload;
+  private dispatchEnvelope;
   private routeDelta;
-  /** Route a structured value: to the handler, or a string value to a lone sink. */
   private routeData;
 }
 
@@ -242,4 +268,4 @@ interface BuildSystemPromptOptions {
 declare function buildSystemPrompt(options?: BuildSystemPromptOptions): string;
 
 //#endregion
-export { AIGuiPlugin, ASTNode, BuildSystemPromptOptions, CardDef, CardParseResult, CardRegistry, ChannelSink, JSONSchema, NodeRenderer, ParserOptions, PartialJSONResult, Patch, RenderOutput, Renderer, RendererOptions, StreamRouter, buildSystemPrompt, collectNodeRenderers, createParser, diffAst, parsePartialJSON, pluginNodeTypes, repairMarkdown, sanitizeHtml };
+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 };

package/dist/index.d.ts

@@ -32,6 +32,11 @@ declare function repairMarkdown(buffer: string): string;
 
 //#endregion
 //#region src/sanitizer.d.ts
+interface SanitizeHtmlOptions {
+  sanitizer?: (html: string) => string;
+  /** Bare SSR either escapes all markup (default) or fails explicitly. */
+  ssr?: "escape" | "throw";
+}
 /**
  * Sanitize an HTML string, stripping scripts and unsafe attributes.
  *
@@ -40,7 +45,7 @@ declare function repairMarkdown(buffer: string): string;
  * fall back to escaping the HTML-significant characters. This never emits raw
  * markup and never throws.
  */
-declare function sanitizeHtml(html: string): string;
+declare function sanitizeHtml(html: string, options?: SanitizeHtmlOptions): string;
 
 //#endregion
 //#region src/types.d.ts
@@ -53,6 +58,8 @@ interface ASTNode {
   html?: string;
   attrs?: Record<string, string>;
   children?: ASTNode[];
+  /** Whether a streaming block has enough source to invoke its renderer. */
+  complete?: boolean;
   /** card-specific payload */
   card?: {
     type: string;
@@ -70,6 +77,10 @@ type Patch = {
   op: "update";
   key: string;
   node: ASTNode;
+} | {
+  op: "move";
+  key: string;
+  index: number;
 } | {
   op: "remove";
   key: string;
@@ -120,9 +131,16 @@ interface AIGuiPlugin {
 interface RendererOptions {
   registry?: CardRegistry;
   plugins?: AIGuiPlugin[];
-  sanitize?: boolean;
+  sanitize?: boolean | SanitizeHtmlOptions;
+  /** Coalesce multiple pushes by scheduling one render callback. */
+  scheduler?: (render: () => void) => void;
   onPatch?: (patches: Patch[], nodes: ASTNode[]) => void;
 }
+interface FeedOptions {
+  signal?: AbortSignal;
+}
+type FeedChunk = string | Uint8Array;
+type FeedSource = AsyncIterable<FeedChunk> | ReadableStream<FeedChunk>;
 
 //#endregion
 //#region src/card-registry.d.ts
@@ -139,6 +157,7 @@ declare class CardRegistry {
   parse(type: string, rawJson: string): CardParseResult;
   private validate;
   toPromptSpec(): string;
+  get size(): number;
   toJSONSchema(): JSONSchema;
 }
 
@@ -149,8 +168,21 @@ interface ParserOptions {
   plugins?: AIGuiPlugin[];
   configureMd?: (md: MarkdownIt) => void;
 }
+interface SourceBlock {
+  start: number;
+  end: number;
+  nodeStart: number;
+  nodeEnd: number;
+}
+interface ParseResult {
+  nodes: ASTNode[];
+  blocks: SourceBlock[];
+  incrementalSafe: boolean;
+}
 /** Build a parser that turns markdown source into a flat list of ASTNodes. */
-declare function createParser(options?: ParserOptions): (src: string) => ASTNode[];
+declare function createParser(options?: ParserOptions): (src: string, rawSrc?: string) => ASTNode[];
+/** Build a parser that also reports the source range for each top-level block. */
+declare function createParserWithMetadata(options?: ParserOptions): (src: string, rawSrc?: string, sourceOffset?: number) => ParseResult;
 
 //#endregion
 //#region src/plugins.d.ts
@@ -163,6 +195,8 @@ declare function pluginNodeTypes(plugins?: AIGuiPlugin[]): Set<string>;
 //#region src/diff.d.ts
 /** Produce a minimal set of patches turning `prev` into `next`, keyed by node key. */
 declare function diffAst(prev: ASTNode[], next: ASTNode[]): Patch[];
+/** Apply patches in order, primarily for framework adapters and verification. */
+declare function applyPatches(nodes: ASTNode[], patches: Patch[]): ASTNode[];
 
 //#endregion
 //#region src/renderer.d.ts
@@ -175,55 +209,47 @@ declare class Renderer {
   private buffer;
   private prevAst;
   private parse;
+  private parsed?;
   private options;
   private sanitize;
+  private generation;
+  private activeFeed?;
+  private renderScheduled;
+  private scheduleGeneration;
   constructor(options?: RendererOptions);
   push(chunk: string): void;
-  feed(source: AsyncIterable<string> | ReadableStream<string>): Promise<void>;
+  feed(source: FeedSource, options?: FeedOptions): Promise<void>;
   reset(): void;
+  /** Immediately render pending buffered input, bypassing the scheduler. */
+  flush(): void;
+  private scheduleRender;
+  private cancelActiveFeed;
   private render;
 }
 
 //#endregion
 //#region src/stream-router.d.ts
-/**
- * A consumer of a channel's text stream. `Renderer` satisfies this shape.
- */
+/** A consumer of a channel's text stream. `Renderer` satisfies this shape. */
 interface ChannelSink {
   push(chunk: string): void;
 }
 /** Handler for structured data values (and text deltas as raw strings). */
 type ChannelHandler = (value: unknown) => void;
-/**
- * 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.
- */
+type StreamChunk = string | Uint8Array;
+/** Demultiplex JSON-lines and standards-compliant SSE into named channels. */
 declare class StreamRouter {
   private readonly sinks;
   private readonly handlers;
-  /** Bind a text-stream sink to a channel: text deltas call `sink.push(delta)`. */
+  /** Most recently received SSE `id` field. */
+  lastEventId: string;
+  /** Most recently received valid non-negative SSE reconnection delay. */
+  retry: number | undefined;
   channel(name: string, sink: ChannelSink): this;
-  /** Bind a handler to a channel: data values (and deltas as strings) call it. */
   on(name: string, handler: ChannelHandler): 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).
-   */
-  feed(source: AsyncIterable<string> | ReadableStream<Uint8Array | string>): Promise<void>;
-  /** Process a single raw line; returns the (possibly updated) current event. */
-  private processLine;
-  /** Route a text delta: to a bound sink and/or an on() handler (either/both). */
+  feed(source: AsyncIterable<StreamChunk> | ReadableStream<StreamChunk>): Promise<void>;
+  private dispatchPayload;
+  private dispatchEnvelope;
   private routeDelta;
-  /** Route a structured value: to the handler, or a string value to a lone sink. */
   private routeData;
 }
 
@@ -242,4 +268,4 @@ interface BuildSystemPromptOptions {
 declare function buildSystemPrompt(options?: BuildSystemPromptOptions): string;
 
 //#endregion
-export { AIGuiPlugin, ASTNode, BuildSystemPromptOptions, CardDef, CardParseResult, CardRegistry, ChannelSink, JSONSchema, NodeRenderer, ParserOptions, PartialJSONResult, Patch, RenderOutput, Renderer, RendererOptions, StreamRouter, buildSystemPrompt, collectNodeRenderers, createParser, diffAst, parsePartialJSON, pluginNodeTypes, repairMarkdown, sanitizeHtml };
+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 };