@ai-gui/core 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,245 @@
+import MarkdownIt from "markdown-it";
+
+//#region src/partial-json.d.ts
+interface PartialJSONResult {
+  data: unknown;
+  complete: boolean;
+}
+/**
+ * Parse a possibly-incomplete JSON string, as produced by a streaming source.
+ *
+ * If the input is valid JSON, it is returned with `complete: true`. Otherwise
+ * the parser attempts to repair the fragment by dropping any trailing
+ * incomplete token (a dangling key, colon, or comma) and auto-closing unclosed
+ * strings, objects, and arrays, returning whatever data has arrived so far with
+ * `complete: false`. Unparseable input yields `{ data: undefined, complete: false }`
+ * and never throws.
+ */
+declare function parsePartialJSON(input: string): PartialJSONResult;
+
+//#endregion
+//#region src/repair-markdown.d.ts
+/**
+ * Temporarily repair half-finished markdown so a partial streaming buffer
+ * renders smoothly. Operates on a copy of the buffer and returns a new string;
+ * it never mutates the input. Pure function, no dependencies.
+ *
+ * The repairs are intentionally conservative: only unambiguous unclosed
+ * inline/fence syntax is completed. Ambiguous constructs (e.g. a dangling
+ * link text `[docs`) are left untouched to avoid guessing wrong.
+ */
+declare function repairMarkdown(buffer: string): string;
+
+//#endregion
+//#region src/sanitizer.d.ts
+/**
+ * Sanitize an HTML string, stripping scripts and unsafe attributes.
+ *
+ * When a DOM is available (browser, or Node with jsdom) DOMPurify is used. In a
+ * bare Node environment without a global `window`, DOMPurify cannot run, so we
+ * fall back to escaping the HTML-significant characters. This never emits raw
+ * markup and never throws.
+ */
+declare function sanitizeHtml(html: string): string;
+
+//#endregion
+//#region src/types.d.ts
+/** Framework-agnostic render node. */
+interface ASTNode {
+  key: string;
+  type: string;
+  tag?: string;
+  content?: string;
+  html?: string;
+  attrs?: Record<string, string>;
+  children?: ASTNode[];
+  /** card-specific payload */
+  card?: {
+    type: string;
+    data: unknown;
+    complete: boolean;
+    valid: boolean;
+  };
+}
+/** Patch event produced by diffing. */
+type Patch = {
+  op: "insert";
+  index: number;
+  node: ASTNode;
+} | {
+  op: "update";
+  key: string;
+  node: ASTNode;
+} | {
+  op: "remove";
+  key: string;
+};
+/** Framework-neutral render descriptor returned by plugin node renderers. */
+type RenderOutput = {
+  kind: "html";
+  html: string;
+} | {
+  kind: "element";
+  tag: string;
+  props?: Record<string, unknown>;
+  children?: RenderOutput[];
+} | {
+  kind: "card";
+  type: string;
+  data: unknown;
+} | {
+  kind: "mount";
+  mount: (el: HTMLElement) => void | (() => void);
+};
+type NodeRenderer = (node: ASTNode) => RenderOutput | Promise<RenderOutput>;
+interface JSONSchema {
+  type?: string;
+  properties?: Record<string, JSONSchema>;
+  items?: JSONSchema;
+  required?: string[];
+  [k: string]: unknown;
+}
+interface CardDef<TData = unknown, TComponent = unknown> {
+  type: string;
+  description: string;
+  schema?: JSONSchema;
+  example?: TData;
+  render?: TComponent;
+  validate?: (data: TData) => boolean;
+}
+interface AIGuiPlugin {
+  name: string;
+  extendParser?: (md: MarkdownIt) => void;
+  cards?: CardDef[];
+  nodeRenderers?: Record<string, NodeRenderer>;
+  isBlockComplete?: (nodeType: string, raw: string) => boolean;
+  css?: string;
+  /** LLM-facing guidance describing this plugin's fence syntax. */
+  promptSpec?: string;
+}
+interface RendererOptions {
+  registry?: CardRegistry;
+  plugins?: AIGuiPlugin[];
+  sanitize?: boolean;
+  onPatch?: (patches: Patch[], nodes: ASTNode[]) => void;
+}
+
+//#endregion
+//#region src/card-registry.d.ts
+interface CardParseResult {
+  data: unknown;
+  complete: boolean;
+  valid: boolean;
+}
+declare class CardRegistry {
+  private cards;
+  register(def: CardDef): void;
+  has(type: string): boolean;
+  getRender(type: string): unknown;
+  parse(type: string, rawJson: string): CardParseResult;
+  private validate;
+  toPromptSpec(): string;
+  toJSONSchema(): JSONSchema;
+}
+
+//#endregion
+//#region src/parser.d.ts
+interface ParserOptions {
+  registry?: CardRegistry;
+  plugins?: AIGuiPlugin[];
+  configureMd?: (md: MarkdownIt) => void;
+}
+/** Build a parser that turns markdown source into a flat list of ASTNodes. */
+declare function createParser(options?: ParserOptions): (src: string) => ASTNode[];
+
+//#endregion
+//#region src/plugins.d.ts
+/** Merge every plugin's `nodeRenderers` into a single map (later plugins win). */
+declare function collectNodeRenderers(plugins?: AIGuiPlugin[]): Record<string, NodeRenderer>;
+/** The set of node types claimed by the given plugins. */
+declare function pluginNodeTypes(plugins?: AIGuiPlugin[]): Set<string>;
+
+//#endregion
+//#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[];
+
+//#endregion
+//#region src/renderer.d.ts
+/**
+ * Streaming render orchestrator: accumulate incoming markdown chunks, repair the
+ * partial buffer, parse it into an AST, diff against the previous AST, and emit
+ * the resulting patches via `onPatch`.
+ */
+declare class Renderer {
+  private buffer;
+  private prevAst;
+  private parse;
+  private options;
+  private sanitize;
+  constructor(options?: RendererOptions);
+  push(chunk: string): void;
+  feed(source: AsyncIterable<string> | ReadableStream<string>): Promise<void>;
+  reset(): void;
+  private render;
+}
+
+//#endregion
+//#region src/stream-router.d.ts
+/**
+ * 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.
+ */
+declare class StreamRouter {
+  private readonly sinks;
+  private readonly handlers;
+  /** Bind a text-stream sink to a channel: text deltas call `sink.push(delta)`. */
+  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). */
+  private routeDelta;
+  /** Route a structured value: to the handler, or a string value to a lone sink. */
+  private routeData;
+}
+
+//#endregion
+//#region src/build-system-prompt.d.ts
+interface BuildSystemPromptOptions {
+  base?: string;
+  registry?: CardRegistry;
+  plugins?: AIGuiPlugin[];
+}
+/**
+ * Assembles the LLM system-prompt guidance: an optional base, the registered
+ * cards' spec, and every plugin's promptSpec. Consumers prepend this to their
+ * own system prompt so the model knows which fenced blocks it may emit.
+ */
+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 };

package/dist/index.d.ts

@@ -0,0 +1,245 @@
+import MarkdownIt from "markdown-it";
+
+//#region src/partial-json.d.ts
+interface PartialJSONResult {
+  data: unknown;
+  complete: boolean;
+}
+/**
+ * Parse a possibly-incomplete JSON string, as produced by a streaming source.
+ *
+ * If the input is valid JSON, it is returned with `complete: true`. Otherwise
+ * the parser attempts to repair the fragment by dropping any trailing
+ * incomplete token (a dangling key, colon, or comma) and auto-closing unclosed
+ * strings, objects, and arrays, returning whatever data has arrived so far with
+ * `complete: false`. Unparseable input yields `{ data: undefined, complete: false }`
+ * and never throws.
+ */
+declare function parsePartialJSON(input: string): PartialJSONResult;
+
+//#endregion
+//#region src/repair-markdown.d.ts
+/**
+ * Temporarily repair half-finished markdown so a partial streaming buffer
+ * renders smoothly. Operates on a copy of the buffer and returns a new string;
+ * it never mutates the input. Pure function, no dependencies.
+ *
+ * The repairs are intentionally conservative: only unambiguous unclosed
+ * inline/fence syntax is completed. Ambiguous constructs (e.g. a dangling
+ * link text `[docs`) are left untouched to avoid guessing wrong.
+ */
+declare function repairMarkdown(buffer: string): string;
+
+//#endregion
+//#region src/sanitizer.d.ts
+/**
+ * Sanitize an HTML string, stripping scripts and unsafe attributes.
+ *
+ * When a DOM is available (browser, or Node with jsdom) DOMPurify is used. In a
+ * bare Node environment without a global `window`, DOMPurify cannot run, so we
+ * fall back to escaping the HTML-significant characters. This never emits raw
+ * markup and never throws.
+ */
+declare function sanitizeHtml(html: string): string;
+
+//#endregion
+//#region src/types.d.ts
+/** Framework-agnostic render node. */
+interface ASTNode {
+  key: string;
+  type: string;
+  tag?: string;
+  content?: string;
+  html?: string;
+  attrs?: Record<string, string>;
+  children?: ASTNode[];
+  /** card-specific payload */
+  card?: {
+    type: string;
+    data: unknown;
+    complete: boolean;
+    valid: boolean;
+  };
+}
+/** Patch event produced by diffing. */
+type Patch = {
+  op: "insert";
+  index: number;
+  node: ASTNode;
+} | {
+  op: "update";
+  key: string;
+  node: ASTNode;
+} | {
+  op: "remove";
+  key: string;
+};
+/** Framework-neutral render descriptor returned by plugin node renderers. */
+type RenderOutput = {
+  kind: "html";
+  html: string;
+} | {
+  kind: "element";
+  tag: string;
+  props?: Record<string, unknown>;
+  children?: RenderOutput[];
+} | {
+  kind: "card";
+  type: string;
+  data: unknown;
+} | {
+  kind: "mount";
+  mount: (el: HTMLElement) => void | (() => void);
+};
+type NodeRenderer = (node: ASTNode) => RenderOutput | Promise<RenderOutput>;
+interface JSONSchema {
+  type?: string;
+  properties?: Record<string, JSONSchema>;
+  items?: JSONSchema;
+  required?: string[];
+  [k: string]: unknown;
+}
+interface CardDef<TData = unknown, TComponent = unknown> {
+  type: string;
+  description: string;
+  schema?: JSONSchema;
+  example?: TData;
+  render?: TComponent;
+  validate?: (data: TData) => boolean;
+}
+interface AIGuiPlugin {
+  name: string;
+  extendParser?: (md: MarkdownIt) => void;
+  cards?: CardDef[];
+  nodeRenderers?: Record<string, NodeRenderer>;
+  isBlockComplete?: (nodeType: string, raw: string) => boolean;
+  css?: string;
+  /** LLM-facing guidance describing this plugin's fence syntax. */
+  promptSpec?: string;
+}
+interface RendererOptions {
+  registry?: CardRegistry;
+  plugins?: AIGuiPlugin[];
+  sanitize?: boolean;
+  onPatch?: (patches: Patch[], nodes: ASTNode[]) => void;
+}
+
+//#endregion
+//#region src/card-registry.d.ts
+interface CardParseResult {
+  data: unknown;
+  complete: boolean;
+  valid: boolean;
+}
+declare class CardRegistry {
+  private cards;
+  register(def: CardDef): void;
+  has(type: string): boolean;
+  getRender(type: string): unknown;
+  parse(type: string, rawJson: string): CardParseResult;
+  private validate;
+  toPromptSpec(): string;
+  toJSONSchema(): JSONSchema;
+}
+
+//#endregion
+//#region src/parser.d.ts
+interface ParserOptions {
+  registry?: CardRegistry;
+  plugins?: AIGuiPlugin[];
+  configureMd?: (md: MarkdownIt) => void;
+}
+/** Build a parser that turns markdown source into a flat list of ASTNodes. */
+declare function createParser(options?: ParserOptions): (src: string) => ASTNode[];
+
+//#endregion
+//#region src/plugins.d.ts
+/** Merge every plugin's `nodeRenderers` into a single map (later plugins win). */
+declare function collectNodeRenderers(plugins?: AIGuiPlugin[]): Record<string, NodeRenderer>;
+/** The set of node types claimed by the given plugins. */
+declare function pluginNodeTypes(plugins?: AIGuiPlugin[]): Set<string>;
+
+//#endregion
+//#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[];
+
+//#endregion
+//#region src/renderer.d.ts
+/**
+ * Streaming render orchestrator: accumulate incoming markdown chunks, repair the
+ * partial buffer, parse it into an AST, diff against the previous AST, and emit
+ * the resulting patches via `onPatch`.
+ */
+declare class Renderer {
+  private buffer;
+  private prevAst;
+  private parse;
+  private options;
+  private sanitize;
+  constructor(options?: RendererOptions);
+  push(chunk: string): void;
+  feed(source: AsyncIterable<string> | ReadableStream<string>): Promise<void>;
+  reset(): void;
+  private render;
+}
+
+//#endregion
+//#region src/stream-router.d.ts
+/**
+ * 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.
+ */
+declare class StreamRouter {
+  private readonly sinks;
+  private readonly handlers;
+  /** Bind a text-stream sink to a channel: text deltas call `sink.push(delta)`. */
+  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). */
+  private routeDelta;
+  /** Route a structured value: to the handler, or a string value to a lone sink. */
+  private routeData;
+}
+
+//#endregion
+//#region src/build-system-prompt.d.ts
+interface BuildSystemPromptOptions {
+  base?: string;
+  registry?: CardRegistry;
+  plugins?: AIGuiPlugin[];
+}
+/**
+ * Assembles the LLM system-prompt guidance: an optional base, the registered
+ * cards' spec, and every plugin's promptSpec. Consumers prepend this to their
+ * own system prompt so the model knows which fenced blocks it may emit.
+ */
+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 };