@xom11/whiteboard 0.24.2 → 0.25.0

package/dist/ai.d.mts

@@ -1,565 +1,7 @@
-import { S as State } from './types-DxlMPh-6.mjs';
+import { b as State, D as DslInputT, a as AiFigureUiResult } from './types-DWRyCa2m.mjs';
 import { z } from 'zod';
-
-declare const DslInput: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    points: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"free">;
-        x: z.ZodNumber;
-        y: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        kind: "free";
-        name: string;
-        x: number;
-        y: number;
-    }, {
-        kind: "free";
-        name: string;
-        x: number;
-        y: number;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"midpoint">;
-        p1: z.ZodString;
-        p2: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "midpoint";
-        name: string;
-        p1: string;
-        p2: string;
-    }, {
-        kind: "midpoint";
-        name: string;
-        p1: string;
-        p2: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"onSegment">;
-        segmentId: z.ZodString;
-        t: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        kind: "onSegment";
-        name: string;
-        segmentId: string;
-        t: number;
-    }, {
-        kind: "onSegment";
-        name: string;
-        segmentId: string;
-        t: number;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"onLine">;
-        lineId: z.ZodString;
-        t: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        kind: "onLine";
-        name: string;
-        t: number;
-        lineId: string;
-    }, {
-        kind: "onLine";
-        name: string;
-        t: number;
-        lineId: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"onCircle">;
-        circleId: z.ZodString;
-        theta: z.ZodNumber;
-    }, "strip", z.ZodTypeAny, {
-        kind: "onCircle";
-        name: string;
-        circleId: string;
-        theta: number;
-    }, {
-        kind: "onCircle";
-        name: string;
-        circleId: string;
-        theta: number;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"perpFoot">;
-        from: z.ZodString;
-        onLine: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "perpFoot";
-        name: string;
-        onLine: string;
-        from: string;
-    }, {
-        kind: "perpFoot";
-        name: string;
-        onLine: string;
-        from: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"circumcenter">;
-        vertices: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
-    }, "strip", z.ZodTypeAny, {
-        kind: "circumcenter";
-        name: string;
-        vertices: [string, string, string];
-    }, {
-        kind: "circumcenter";
-        name: string;
-        vertices: [string, string, string];
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"incenter">;
-        vertices: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
-    }, "strip", z.ZodTypeAny, {
-        kind: "incenter";
-        name: string;
-        vertices: [string, string, string];
-    }, {
-        kind: "incenter";
-        name: string;
-        vertices: [string, string, string];
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"centroid">;
-        vertices: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
-    }, "strip", z.ZodTypeAny, {
-        kind: "centroid";
-        name: string;
-        vertices: [string, string, string];
-    }, {
-        kind: "centroid";
-        name: string;
-        vertices: [string, string, string];
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"orthocenter">;
-        vertices: z.ZodTuple<[z.ZodString, z.ZodString, z.ZodString], null>;
-    }, "strip", z.ZodTypeAny, {
-        kind: "orthocenter";
-        name: string;
-        vertices: [string, string, string];
-    }, {
-        kind: "orthocenter";
-        name: string;
-        vertices: [string, string, string];
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"intersection">;
-        ref1: z.ZodString;
-        ref2: z.ZodString;
-        branch: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>]>>;
-    }, "strip", z.ZodTypeAny, {
-        kind: "intersection";
-        name: string;
-        ref1: string;
-        ref2: string;
-        branch?: 0 | 1 | undefined;
-    }, {
-        kind: "intersection";
-        name: string;
-        ref1: string;
-        ref2: string;
-        branch?: 0 | 1 | undefined;
-    }>]>, "many">;
-    shapes: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"segment">;
-        p1: z.ZodString;
-        p2: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "segment";
-        name: string;
-        p1: string;
-        p2: string;
-    }, {
-        kind: "segment";
-        name: string;
-        p1: string;
-        p2: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"line">;
-        p1: z.ZodString;
-        p2: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "line";
-        name: string;
-        p1: string;
-        p2: string;
-    }, {
-        kind: "line";
-        name: string;
-        p1: string;
-        p2: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"ray">;
-        origin: z.ZodString;
-        through: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "ray";
-        name: string;
-        origin: string;
-        through: string;
-    }, {
-        kind: "ray";
-        name: string;
-        origin: string;
-        through: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"polygon">;
-        vertices: z.ZodArray<z.ZodString, "many">;
-    }, "strip", z.ZodTypeAny, {
-        kind: "polygon";
-        name: string;
-        vertices: string[];
-    }, {
-        kind: "polygon";
-        name: string;
-        vertices: string[];
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"perpendicular">;
-        throughPoint: z.ZodString;
-        toLine: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "perpendicular";
-        name: string;
-        throughPoint: string;
-        toLine: string;
-    }, {
-        kind: "perpendicular";
-        name: string;
-        throughPoint: string;
-        toLine: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"parallel">;
-        throughPoint: z.ZodString;
-        toLine: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "parallel";
-        name: string;
-        throughPoint: string;
-        toLine: string;
-    }, {
-        kind: "parallel";
-        name: string;
-        throughPoint: string;
-        toLine: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"perpBisector">;
-        p1: z.ZodString;
-        p2: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "perpBisector";
-        name: string;
-        p1: string;
-        p2: string;
-    }, {
-        kind: "perpBisector";
-        name: string;
-        p1: string;
-        p2: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"angleBisector">;
-        p1: z.ZodString;
-        vertex: z.ZodString;
-        p2: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "angleBisector";
-        name: string;
-        p1: string;
-        p2: string;
-        vertex: string;
-    }, {
-        kind: "angleBisector";
-        name: string;
-        p1: string;
-        p2: string;
-        vertex: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"tangent">;
-        throughPoint: z.ZodString;
-        toCircle: z.ZodString;
-        branch: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<0>, z.ZodLiteral<1>, z.ZodLiteral<"on">]>>;
-    }, "strip", z.ZodTypeAny, {
-        kind: "tangent";
-        name: string;
-        throughPoint: string;
-        toCircle: string;
-        branch?: 0 | 1 | "on" | undefined;
-    }, {
-        kind: "tangent";
-        name: string;
-        throughPoint: string;
-        toCircle: string;
-        branch?: 0 | 1 | "on" | undefined;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"circleCP">;
-        center: z.ZodString;
-        surfacePoint: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "circleCP";
-        name: string;
-        center: string;
-        surfacePoint: string;
-    }, {
-        kind: "circleCP";
-        name: string;
-        center: string;
-        surfacePoint: string;
-    }>, z.ZodObject<{
-        name: z.ZodString;
-        kind: z.ZodLiteral<"circle3">;
-        p1: z.ZodString;
-        p2: z.ZodString;
-        p3: z.ZodString;
-    }, "strip", z.ZodTypeAny, {
-        kind: "circle3";
-        name: string;
-        p1: string;
-        p2: string;
-        p3: string;
-    }, {
-        kind: "circle3";
-        name: string;
-        p1: string;
-        p2: string;
-        p3: string;
-    }>]>, "many">>;
-}, "strip", z.ZodTypeAny, {
-    version: 1;
-    points: ({
-        kind: "free";
-        name: string;
-        x: number;
-        y: number;
-    } | {
-        kind: "midpoint";
-        name: string;
-        p1: string;
-        p2: string;
-    } | {
-        kind: "onSegment";
-        name: string;
-        segmentId: string;
-        t: number;
-    } | {
-        kind: "onLine";
-        name: string;
-        t: number;
-        lineId: string;
-    } | {
-        kind: "onCircle";
-        name: string;
-        circleId: string;
-        theta: number;
-    } | {
-        kind: "perpFoot";
-        name: string;
-        onLine: string;
-        from: string;
-    } | {
-        kind: "circumcenter";
-        name: string;
-        vertices: [string, string, string];
-    } | {
-        kind: "incenter";
-        name: string;
-        vertices: [string, string, string];
-    } | {
-        kind: "centroid";
-        name: string;
-        vertices: [string, string, string];
-    } | {
-        kind: "orthocenter";
-        name: string;
-        vertices: [string, string, string];
-    } | {
-        kind: "intersection";
-        name: string;
-        ref1: string;
-        ref2: string;
-        branch?: 0 | 1 | undefined;
-    })[];
-    shapes: ({
-        kind: "segment";
-        name: string;
-        p1: string;
-        p2: string;
-    } | {
-        kind: "line";
-        name: string;
-        p1: string;
-        p2: string;
-    } | {
-        kind: "ray";
-        name: string;
-        origin: string;
-        through: string;
-    } | {
-        kind: "polygon";
-        name: string;
-        vertices: string[];
-    } | {
-        kind: "perpendicular";
-        name: string;
-        throughPoint: string;
-        toLine: string;
-    } | {
-        kind: "parallel";
-        name: string;
-        throughPoint: string;
-        toLine: string;
-    } | {
-        kind: "perpBisector";
-        name: string;
-        p1: string;
-        p2: string;
-    } | {
-        kind: "angleBisector";
-        name: string;
-        p1: string;
-        p2: string;
-        vertex: string;
-    } | {
-        kind: "tangent";
-        name: string;
-        throughPoint: string;
-        toCircle: string;
-        branch?: 0 | 1 | "on" | undefined;
-    } | {
-        kind: "circleCP";
-        name: string;
-        center: string;
-        surfacePoint: string;
-    } | {
-        kind: "circle3";
-        name: string;
-        p1: string;
-        p2: string;
-        p3: string;
-    })[];
-}, {
-    version: 1;
-    points: ({
-        kind: "free";
-        name: string;
-        x: number;
-        y: number;
-    } | {
-        kind: "midpoint";
-        name: string;
-        p1: string;
-        p2: string;
-    } | {
-        kind: "onSegment";
-        name: string;
-        segmentId: string;
-        t: number;
-    } | {
-        kind: "onLine";
-        name: string;
-        t: number;
-        lineId: string;
-    } | {
-        kind: "onCircle";
-        name: string;
-        circleId: string;
-        theta: number;
-    } | {
-        kind: "perpFoot";
-        name: string;
-        onLine: string;
-        from: string;
-    } | {
-        kind: "circumcenter";
-        name: string;
-        vertices: [string, string, string];
-    } | {
-        kind: "incenter";
-        name: string;
-        vertices: [string, string, string];
-    } | {
-        kind: "centroid";
-        name: string;
-        vertices: [string, string, string];
-    } | {
-        kind: "orthocenter";
-        name: string;
-        vertices: [string, string, string];
-    } | {
-        kind: "intersection";
-        name: string;
-        ref1: string;
-        ref2: string;
-        branch?: 0 | 1 | undefined;
-    })[];
-    shapes?: ({
-        kind: "segment";
-        name: string;
-        p1: string;
-        p2: string;
-    } | {
-        kind: "line";
-        name: string;
-        p1: string;
-        p2: string;
-    } | {
-        kind: "ray";
-        name: string;
-        origin: string;
-        through: string;
-    } | {
-        kind: "polygon";
-        name: string;
-        vertices: string[];
-    } | {
-        kind: "perpendicular";
-        name: string;
-        throughPoint: string;
-        toLine: string;
-    } | {
-        kind: "parallel";
-        name: string;
-        throughPoint: string;
-        toLine: string;
-    } | {
-        kind: "perpBisector";
-        name: string;
-        p1: string;
-        p2: string;
-    } | {
-        kind: "angleBisector";
-        name: string;
-        p1: string;
-        p2: string;
-        vertex: string;
-    } | {
-        kind: "tangent";
-        name: string;
-        throughPoint: string;
-        toCircle: string;
-        branch?: 0 | 1 | "on" | undefined;
-    } | {
-        kind: "circleCP";
-        name: string;
-        center: string;
-        surfacePoint: string;
-    } | {
-        kind: "circle3";
-        name: string;
-        p1: string;
-        p2: string;
-        p3: string;
-    })[] | undefined;
-}>;
-type DslInputT = z.infer<typeof DslInput>;
+import 'react';
+import '@excalidraw/excalidraw/element/types';
 
 type TranspileErrorCode = 'SCHEMA' | 'DUPLICATE_NAME' | 'UNKNOWN_REF' | 'KIND_MISMATCH' | 'CYCLE';
 interface TranspileError {
@@ -569,14 +11,99 @@ interface TranspileError {
     hint?: string;
 }
 
-interface GenerateOptions {
+interface ProviderTokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    /** Anthropic prompt caching — local provider để 0. */
+    cacheReadTokens?: number;
+    /** Anthropic prompt caching — local provider để 0. */
+    cacheCreationTokens?: number;
+}
+interface ProviderRequest {
+    systemPrompt: string;
+    userPrompt: string;
+    /**
+     * JSON Schema mà provider phải honor để constrain output. Anthropic → wrap
+     * thành tool input_schema. Ollama → pass thẳng vào `format` (v0.5+).
+     */
+    schema: Record<string, unknown>;
+    /** Provider-specific model id (vd "gemma3:4b", "claude-opus-4-7"). */
+    model: string;
+    /** Token cap cho response. */
+    maxTokens: number;
+    signal?: AbortSignal;
+}
+type ProviderOutput = {
+    kind: 'json';
+    data: unknown;
+    usage?: ProviderTokenUsage;
+} | {
+    kind: 'error';
+    message: string;
+    status?: number;
+};
+interface AIProvider {
+    /** Tên định danh ("anthropic", "ollama", ...). */
+    readonly name: string;
+    /** Default model id khi caller không truyền. */
+    readonly defaultModel: string;
+    call(req: ProviderRequest): Promise<ProviderOutput>;
+}
+
+interface AnthropicProviderOptions {
     apiKey: string;
+    /** Cache system prompt qua Anthropic prompt-caching (mặc định bật). */
+    enableCaching?: boolean;
+}
+declare class AnthropicProvider implements AIProvider {
+    private readonly opts;
+    readonly name = "anthropic";
+    readonly defaultModel = "claude-opus-4-7";
+    constructor(opts: AnthropicProviderOptions);
+    call(req: ProviderRequest): Promise<ProviderOutput>;
+}
+
+interface OllamaProviderOptions {
+    /** Endpoint base URL, default http://localhost:11434. */
+    baseUrl?: string;
+    /** Default model id nếu request không truyền. */
+    defaultModel?: string;
+    /** Custom fetch impl (dùng cho test mock). */
+    fetchImpl?: typeof fetch;
+}
+declare class OllamaProvider implements AIProvider {
+    readonly name = "ollama";
+    readonly defaultModel: string;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    constructor(opts?: OllamaProviderOptions);
+    private resolveFetch;
+    call(req: ProviderRequest): Promise<ProviderOutput>;
+}
+
+interface SelectProviderOptions {
+    /** Provider instance dùng trực tiếp (override mọi env). */
+    provider?: AIProvider;
+    /** Anthropic API key. Khi truyền → auto chọn AnthropicProvider. */
+    apiKey?: string;
+    /** Anthropic prompt-caching, default true (chỉ áp dụng provider Anthropic). */
+    enableCaching?: boolean;
+    /** Ollama endpoint override. */
+    ollamaBaseUrl?: string;
+    /** Ollama model override (vd "gemma3:1b"). */
+    ollamaDefaultModel?: string;
+    /** Test env: env vars getter (default process.env). */
+    env?: Record<string, string | undefined>;
+}
+declare function selectProvider(opts?: SelectProviderOptions): AIProvider;
+
+interface GenerateOptions extends SelectProviderOptions {
+    /** Model id override (provider-specific). Mặc định: provider.defaultModel. */
     model?: string;
     maxTokens?: number;
-    enableCaching?: boolean;
     signal?: AbortSignal;
 }
-interface TokenUsage {
+interface TokenUsage$1 {
     inputTokens: number;
     outputTokens: number;
     cacheReadTokens: number;
@@ -586,18 +113,213 @@ type GenerateResult = {
     ok: true;
     state: State;
     dsl: DslInputT;
+    usage: TokenUsage$1;
+    provider: string;
+} | {
+    ok: false;
+    reason: 'refused';
+    message: string;
+    usage?: TokenUsage$1;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'parse_error';
+    message: string;
+    raw?: unknown;
+    usage?: TokenUsage$1;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'transpile_error';
+    message: string;
+    errors: TranspileError[];
+    dsl: unknown;
+    usage?: TokenUsage$1;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'api_error';
+    message: string;
+    status?: number;
+    provider?: string;
+};
+declare function generateFigure(problem: string, opts?: GenerateOptions): Promise<GenerateResult>;
+
+interface HandleGenerateFigureInput {
+    /** Đề bài tiếng Việt từ teacher. */
+    problem: string;
+}
+interface HandleGenerateFigureOptions extends GenerateOptions {
+    /**
+     * Optional telemetry hook. Gọi cho MỖI attempt với envelope nội bộ trước
+     * khi map sang AiFigureUiResult — consumer dùng để log usage/cost/error.
+     * Không throw từ logger — sẽ swallow để không vỡ response.
+     *
+     * @param result GenerateResult của attempt
+     * @param attempt 1-indexed (1 = lần đầu, 2 = retry, ...)
+     */
+    onResult?: (result: GenerateResult, attempt: number) => void;
+    /**
+     * Số attempt tối đa khi nhận `transpile_error`. Default 2 (1 retry).
+     * AI stochastic → lần 2 thường khá hơn. Min 1, max 5.
+     */
+    maxAttempts?: number;
+}
+/**
+ * Gọi AI orchestrator và trả về kết quả ở dạng `AiFigureUiResult` mà
+ * `<Whiteboard generateGeometryFigure>` chấp nhận trực tiếp.
+ *
+ * Auto-retry: chỉ retry khi `transpile_error` (DSL không hợp lệ — model
+ * stochastic có cơ hội emit khá hơn lần 2). KHÔNG retry `refused` (AI cố ý
+ * từ chối), `parse_error` (envelope sai schema — chắc chắn sai mọi lần),
+ * hay `api_error` (network / config — không liên quan model).
+ *
+ * Mapping:
+ *   - ok=true             → { ok: true, state }
+ *   - refused             → { ok: false, message: <message AI gửi> }
+ *   - parse_error         → { ok: false, message: 'AI trả JSON không hợp lệ…' }
+ *   - transpile_error     → { ok: false, message: 'AI tạo hình không hợp lệ…' }
+ *   - api_error           → { ok: false, message: <message gốc> }
+ *
+ * Server-side caller giữ `GenerateResult` đầy đủ qua `onResult` callback cho
+ * mục đích telemetry/logging.
+ */
+declare function handleGenerateFigure(input: HandleGenerateFigureInput, opts?: HandleGenerateFigureOptions): Promise<AiFigureUiResult>;
+
+declare const FigureEnvelopeZ: z.ZodEffects<z.ZodObject<{
+    decision: z.ZodEnum<["build", "refuse"]>;
+    figure: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        points: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, ...z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>[]]>, "many">;
+        shapes: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, ...z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>[]]>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    }, {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    decision: "build" | "refuse";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    } | undefined;
+}, {
+    decision: "build" | "refuse";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    } | undefined;
+}>, {
+    decision: "build" | "refuse";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    } | undefined;
+}, {
+    decision: "build" | "refuse";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    } | undefined;
+}>;
+type FigureEnvelopeT = z.infer<typeof FigureEnvelopeZ>;
+declare function envelopeJsonSchema(): Record<string, unknown>;
+/** Helper: ép envelope build hợp lệ về DslInputT (sau khi đã validate). */
+declare function envelopeBuildDsl(env: FigureEnvelopeT): DslInputT;
+
+interface GenerateDeltaOptions extends SelectProviderOptions {
+    model?: string;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    maxAttempts?: number;
+}
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheCreationTokens: number;
+}
+type GenerateDeltaResult = {
+    ok: true;
+    state: State;
+    mergedDsl: DslInputT;
+    mode: 'add' | 'replace';
     usage: TokenUsage;
+    provider: string;
 } | {
     ok: false;
     reason: 'refused';
     message: string;
     usage?: TokenUsage;
+    provider?: string;
 } | {
     ok: false;
     reason: 'parse_error';
     message: string;
     raw?: unknown;
     usage?: TokenUsage;
+    provider?: string;
 } | {
     ok: false;
     reason: 'transpile_error';
@@ -605,12 +327,146 @@ type GenerateResult = {
     errors: TranspileError[];
     dsl: unknown;
     usage?: TokenUsage;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'name_collision';
+    message: string;
+    collisions: string[];
+    errors: TranspileError[];
+    dsl: unknown;
+    usage?: TokenUsage;
+    provider?: string;
+} | {
+    ok: false;
+    reason: 'unresolved_ref';
+    message: string;
+    refs: string[];
+    errors: TranspileError[];
+    dsl: unknown;
+    usage?: TokenUsage;
+    provider?: string;
 } | {
     ok: false;
     reason: 'api_error';
     message: string;
     status?: number;
+    provider?: string;
 };
-declare function generateFigure(problem: string, opts: GenerateOptions): Promise<GenerateResult>;
+interface GenerateFigureDeltaInput {
+    problem: string;
+    currentDsl: DslInputT;
+}
+declare function generateFigureDelta(input: GenerateFigureDeltaInput, opts?: GenerateDeltaOptions): Promise<GenerateDeltaResult>;
+
+interface HandleGenerateFigureDeltaInput {
+    problem: string;
+    currentDsl: DslInputT;
+}
+interface HandleGenerateFigureDeltaOptions extends GenerateDeltaOptions {
+    onResult?: (result: GenerateDeltaResult, attempt: number) => void;
+    maxAttempts?: number;
+}
+declare function handleGenerateFigureDelta(input: HandleGenerateFigureDeltaInput, opts?: HandleGenerateFigureDeltaOptions): Promise<AiFigureUiResult>;
+
+declare const FigureRefineEnvelopeZ: z.ZodEffects<z.ZodObject<{
+    decision: z.ZodEnum<["add", "replace", "refuse"]>;
+    figure: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        points: z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, ...z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>[]]>, "many">;
+        shapes: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<"kind", [z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>, ...z.ZodObject<any, z.UnknownKeysParam, z.ZodTypeAny, {
+            [x: string]: any;
+        }, {
+            [x: string]: any;
+        }>[]]>, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    }, {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    }>>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    decision: "refuse" | "add" | "replace";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    } | undefined;
+}, {
+    decision: "refuse" | "add" | "replace";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    } | undefined;
+}>, {
+    decision: "refuse" | "add" | "replace";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes: {
+            [x: string]: any;
+        }[];
+    } | undefined;
+}, {
+    decision: "refuse" | "add" | "replace";
+    reason?: string | undefined;
+    figure?: {
+        points: {
+            [x: string]: any;
+        }[];
+        version: 1;
+        shapes?: {
+            [x: string]: any;
+        }[] | undefined;
+    } | undefined;
+}>;
+type FigureRefineEnvelopeT = z.infer<typeof FigureRefineEnvelopeZ>;
+declare function refineEnvelopeJsonSchema(): Record<string, unknown>;
 
-export { type GenerateOptions, type GenerateResult, type TokenUsage, generateFigure };
+export { type AIProvider, AnthropicProvider, type FigureEnvelopeT, FigureEnvelopeZ, type FigureRefineEnvelopeT, FigureRefineEnvelopeZ, type GenerateDeltaOptions, type GenerateDeltaResult, type GenerateFigureDeltaInput, type GenerateOptions, type GenerateResult, type HandleGenerateFigureDeltaInput, type HandleGenerateFigureDeltaOptions, type HandleGenerateFigureInput, type HandleGenerateFigureOptions, OllamaProvider, type ProviderOutput, type ProviderRequest, type ProviderTokenUsage, type SelectProviderOptions, type TokenUsage$1 as TokenUsage, envelopeBuildDsl, envelopeJsonSchema, generateFigure, generateFigureDelta, handleGenerateFigure, handleGenerateFigureDelta, refineEnvelopeJsonSchema, selectProvider };