@absolutejs/ai 0.0.30 → 0.0.32

package/dist/src/ai/index.d.ts

@@ -3,6 +3,7 @@ export { streamAI } from "./streamAI";
 export { streamAIToSSE } from "./streamAIToSSE";
 export { streamAIWithTools } from "./streamAIWithTools";
 export type { StreamAIWithToolsEvent, StreamAIWithToolsOptions, StreamAIWithToolsSummary, } from "./streamAIWithTools";
+export * from "./ui";
 export { generateAI, generateAIWithTools, generateObjectAI, } from "./generateAI";
 export type { GenerateAIOptions, GenerateAIResult, GenerateAIToolCall, GenerateAIWithToolsOptions, GenerateAIWithToolsResult, GenerateObjectAIOptions, GenerateObjectAIResult, } from "./generateAI";
 export { createConversationManager } from "./conversationManager";

package/dist/src/ai/ui/catalog.d.ts

@@ -0,0 +1,55 @@
+import type { UiCardDefinition } from "./uiCards";
+/**
+ * Built-in UI card catalog: chart, table, stat tiles. Declarative specs the
+ * model authors and the host renders — see svg.ts for the dependency-free
+ * default renderer. Caps are hard product guards (a model can't render a
+ * 400-row table into a chat bubble).
+ */
+export declare const CHART_TYPES: readonly ["bar", "line", "donut"];
+export type ChartType = (typeof CHART_TYPES)[number];
+export type ChartSeries = {
+    name: string;
+    values: number[];
+};
+export type ChartSpec = {
+    type: ChartType;
+    title: string;
+    /** Category labels: x-axis (bar/line) or slice names (donut). */
+    labels: string[];
+    /** ≤ 8 series (fixed hue order). Donut charts use exactly one series. */
+    series: ChartSeries[];
+    /** Value formatting, e.g. "$" / "%". */
+    unitPrefix?: string;
+    unitSuffix?: string;
+};
+export type TableSpec = {
+    title?: string;
+    columns: string[];
+    rows: string[][];
+};
+export type StatTile = {
+    label: string;
+    value: string;
+    /** Optional change annotation, e.g. "+12% vs last month". */
+    delta?: string;
+    deltaDirection?: "up" | "down" | "flat";
+};
+export type StatTilesSpec = {
+    tiles: StatTile[];
+};
+export declare const CHART_MAX_SERIES = 8;
+export declare const CHART_MAX_POINTS = 24;
+export declare const TABLE_MAX_COLUMNS = 8;
+export declare const TABLE_MAX_ROWS = 30;
+export declare const STAT_TILES_MAX = 6;
+export declare const parseChartSpec: (input: unknown) => ChartSpec | null;
+export declare const parseTableSpec: (input: unknown) => TableSpec | null;
+export declare const parseStatTilesSpec: (input: unknown) => StatTilesSpec | null;
+/** render_chart — bar / line / donut from data you already have. */
+export declare const chartCard: UiCardDefinition<ChartSpec>;
+/** render_table — a compact data table. */
+export declare const tableCard: UiCardDefinition<TableSpec>;
+/** render_stat_tiles — a row of headline numbers. */
+export declare const statTilesCard: UiCardDefinition<StatTilesSpec>;
+/** The built-in catalog, ready for createUiCards. */
+export declare const BUILTIN_UI_CARDS: readonly [UiCardDefinition<ChartSpec>, UiCardDefinition<TableSpec>, UiCardDefinition<StatTilesSpec>];

package/dist/src/ai/ui/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `@absolutejs/ai` UI cards — generative UI for agent chats.
+ *
+ * A UI card is a schema-only tool: the model calls it with a structured spec,
+ * the loop feeds back a steering ack, and the HOST renders the validated spec
+ * with real components. {@link createUiCards} builds the tool map + collector
+ * for any card set; {@link BUILTIN_UI_CARDS} ships chart / table / stat-tile
+ * cards with hard caps, and {@link renderChartSvg} is a dependency-free
+ * default chart renderer (pure string — server or client, light/dark).
+ */
+export { createUiCards, type UiCardDefinition, type UiCardEvent, type UiCards, } from "./uiCards";
+export { BUILTIN_UI_CARDS, chartCard, CHART_MAX_POINTS, CHART_MAX_SERIES, CHART_TYPES, parseChartSpec, parseStatTilesSpec, parseTableSpec, STAT_TILES_MAX, statTilesCard, TABLE_MAX_COLUMNS, TABLE_MAX_ROWS, tableCard, type ChartSeries, type ChartSpec, type ChartType, type StatTile, type StatTilesSpec, type TableSpec, } from "./catalog";
+export { DARK_UI_THEME, LIGHT_UI_THEME, renderChartSvg, type RenderChartSvgOptions, type UiSvgTheme, } from "./svg";

package/dist/src/ai/ui/svg.d.ts

@@ -0,0 +1,33 @@
+import type { ChartSpec } from "./catalog";
+/**
+ * Dependency-free default chart renderer: a validated ChartSpec in, a
+ * self-contained SVG string out. Pure — no DOM — so it runs server-side or in
+ * any framework component (call it client-side with the viewer's mode so dark
+ * themes get the dark-stepped palette, not an automatic flip).
+ *
+ * Design method: thin marks with rounded data-ends, 2px surface gaps between
+ * adjacent fills, recessive horizontal grid, a legend for ≥2 series plus
+ * direct labels, all text in text tokens (never series colors), native <title>
+ * hover tooltips per mark. The default palette is the validated reference set
+ * (worst adjacent CVD ΔE 24.2 light / 10.3 dark) — override `palette` with
+ * your brand's VALIDATED hues, in their fixed slot order.
+ */
+export type UiSvgTheme = {
+    /** Categorical hues in fixed slot order (series 1..n). */
+    palette: string[];
+    surface: string;
+    textPrimary: string;
+    textSecondary: string;
+    grid: string;
+};
+export declare const LIGHT_UI_THEME: UiSvgTheme;
+export declare const DARK_UI_THEME: UiSvgTheme;
+export type RenderChartSvgOptions = {
+    mode?: "light" | "dark";
+    /** Override any theme slot (e.g. your brand palette / chat-bubble surface). */
+    theme?: Partial<UiSvgTheme>;
+    width?: number;
+    height?: number;
+};
+/** Render a validated ChartSpec to a self-contained SVG string. */
+export declare const renderChartSvg: (spec: ChartSpec, options?: RenderChartSvgOptions) => string;

package/dist/src/ai/ui/uiCards.d.ts

@@ -0,0 +1,46 @@
+import type { AIToolMap } from "../../../types/ai";
+/**
+ * UI cards — the generative-UI primitive extracted from onSpark's chat.
+ *
+ * A "card" is a schema-only tool: the model calls it with a structured payload,
+ * the handler only ACKNOWLEDGES (steering the model's continuation), and the
+ * host watches the executed tool calls to render the payload as a real,
+ * host-styled component (a chart, a table, an approval card, a deep link…).
+ * No model-written code ever executes: the payload is validated by the card's
+ * `parse` before anything renders, so a malformed call simply drops.
+ */
+export type UiCardDefinition<T = unknown> = {
+    /** Tool name the model calls, e.g. "render_chart". */
+    name: string;
+    /** Tool description — steer WHEN the model should render this card. */
+    description: string;
+    /** JSON schema for the tool input. */
+    inputSchema: Record<string, unknown>;
+    /** Tool-result text fed back to the model (e.g. "(chart rendered — don't
+     *  repeat its numbers in text)"). */
+    ack: string;
+    /** Validate + narrow the raw model input to the card payload. Return null
+     *  to reject the call (the card is dropped, the ack still steered). */
+    parse: (input: unknown) => T | null;
+};
+export type UiCardEvent = {
+    /** The card's tool name. */
+    card: string;
+    /** The parsed, validated payload. */
+    data: unknown;
+};
+export type UiCards = {
+    /** AIToolMap entries (ack handlers) — spread into the tools you hand to
+     *  streamAIWithTools / generateAIWithTools. */
+    tools: AIToolMap;
+    /** Pull validated card events out of a turn's tool calls, in call order.
+     *  Invalid payloads and non-card tools are skipped. */
+    collect: (calls: readonly {
+        name: string;
+        input: unknown;
+    }[]) => UiCardEvent[];
+    /** Is this tool name one of the registered cards? */
+    has: (name: string) => boolean;
+};
+/** Build the tool map + collector for a set of UI cards. */
+export declare const createUiCards: (definitions: readonly UiCardDefinition[]) => UiCards;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/ai",
-  "version": "0.0.30",
+  "version": "0.0.32",
   "homepage": "https://github.com/absolutejs/ai",
   "bugs": {
     "url": "https://github.com/absolutejs/ai/issues"
@@ -70,6 +70,10 @@
     "./tools": {
       "import": "./dist/ai/tools/index.js",
       "types": "./dist/src/ai/tools/index.d.ts"
+    },
+    "./ui": {
+      "import": "./dist/ai/ui/index.js",
+      "types": "./dist/src/ai/ui/index.d.ts"
     }
   },
   "dependencies": {
@@ -136,6 +140,9 @@
       "client": [
         "dist/src/ai/client/index.d.ts"
       ],
+      "ui": [
+        "dist/src/ai/ui/index.d.ts"
+      ],
       "react": [
         "dist/src/react/ai/index.d.ts"
       ],