@braincrew-lab/langchain-canvas 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,669 @@
+import * as react from 'react';
+import { ReactNode, ComponentType } from 'react';
+import { StoreApi } from 'zustand/vanilla';
+
+/**
+ * Artifact data shapes — mirror of `langchain_canvas/protocol/artifacts.py`.
+ *
+ * An `Artifact` is transport-agnostic: `{ id, type, title, version, status,
+ * data }`. `type` is a registry key resolved to a React component; `data` is the
+ * type-specific payload that component reads. Keep this file in lockstep with
+ * the Python module — a field here must exist there, and vice versa.
+ */
+type ArtifactStatus = "streaming" | "complete" | "error";
+interface Artifact<TData = unknown> {
+    /** Stable identity — the reconciliation key. */
+    id: string;
+    /** Registry key: "document" | "chart" | ... */
+    type: string;
+    /** Shown in the canvas header / tab. */
+    title: string;
+    /** 1-based; bumped on every `canvas.replace`. */
+    version: number;
+    status: ArtifactStatus;
+    data: TData;
+    meta?: Record<string, unknown>;
+}
+/**
+ * The base substrate: raw HTML, rendered in a sandboxed iframe. Everything a
+ * canvas can show is ultimately HTML; `document` / `chart` / `table` are
+ * structured conveniences the SDK renders for you, while `html` lets an agent
+ * emit an arbitrary self-contained page (the Claude-Artifacts / Genspark model).
+ */
+interface HtmlData {
+    html: string;
+}
+interface DocumentData {
+    format: "markdown";
+    content: string;
+}
+interface ChartSeries {
+    /** Column in `ChartData.rows` to plot. */
+    key: string;
+    label?: string;
+    color?: string;
+}
+interface ChartOptions {
+    stacked?: boolean;
+    yLabel?: string;
+    /** Per-slice colors for pie charts, index-aligned to `rows`. */
+    colors?: string[];
+}
+interface ChartData {
+    chart: "line" | "bar" | "area" | "pie";
+    /** Tidy/long-form rows, consumed directly by the charting library. */
+    rows: Array<Record<string, string | number>>;
+    /** Category / x-axis field. */
+    xKey: string;
+    series: ChartSeries[];
+    options?: ChartOptions;
+    /**
+     * Optional raw ECharts `option`. When present it's rendered verbatim — an
+     * escape hatch for agents/apps that already produce a full ECharts config
+     * (the tidy `rows`/`series` model is ignored, and inline editing is disabled).
+     */
+    echartsOption?: Record<string, unknown>;
+}
+interface TableColumn {
+    key: string;
+    label?: string;
+    align?: "left" | "right" | "center";
+}
+interface TableData {
+    columns: TableColumn[];
+    rows: Array<Record<string, string | number>>;
+    /**
+     * Opaque spreadsheet state (Fortune-sheet sheets) once the user has edited the
+     * grid — carries merges, per-cell fonts/formats, and formulas that the simple
+     * columns/rows shape can't hold. Present after the first interactive edit;
+     * exporters prefer it over columns/rows.
+     */
+    sheet?: Array<Record<string, unknown>>;
+}
+/** A freely-positioned element on a "blank" slide (percent geometry, 0–100). */
+interface SlideElement {
+    id: string;
+    type: "text" | "image";
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    text?: string;
+    src?: string;
+    fontSize?: number;
+    bold?: boolean;
+    color?: string;
+    align?: "left" | "center" | "right";
+}
+interface Slide {
+    /** title · content (bullets) · section · image · two-column · blank (free canvas). */
+    layout?: "title" | "content" | "section" | "image" | "two-column" | "blank";
+    /** Freely-positioned elements for the "blank" layout. */
+    elements?: SlideElement[];
+    title?: string;
+    subtitle?: string;
+    bullets?: string[];
+    /** Right-hand bullets for the "two-column" layout. */
+    bullets2?: string[];
+    /** Image (data: URL or https URL) for the "image" layout. */
+    image?: string;
+    /** Slide background color (hex). */
+    background?: string;
+    /** Slide text color (hex). */
+    textColor?: string;
+    /** Speaker notes (not shown on the slide; exported to the .pptx notes pane). */
+    notes?: string;
+}
+interface SlidesData {
+    slides: Slide[];
+}
+type HtmlArtifact = Artifact<HtmlData> & {
+    type: "html";
+};
+type DocumentArtifact = Artifact<DocumentData> & {
+    type: "document";
+};
+type ChartArtifact = Artifact<ChartData> & {
+    type: "chart";
+};
+type TableArtifact = Artifact<TableData> & {
+    type: "table";
+};
+type SlidesArtifact = Artifact<SlidesData> & {
+    type: "slides";
+};
+type KnownArtifact = HtmlArtifact | DocumentArtifact | ChartArtifact | TableArtifact | SlidesArtifact;
+
+/**
+ * Canvas Wire Protocol v1 — event envelopes. Mirror of
+ * `langchain_canvas/protocol/events.py`. Every SSE frame is one `StreamEvent`,
+ * discriminated by `type`. See `docs/02-protocol.md` for the specification.
+ */
+
+interface MessageDelta {
+    type: "message.delta";
+    messageId: string;
+    text: string;
+}
+interface MessageEnd {
+    type: "message.end";
+    messageId: string;
+}
+interface ToolStart {
+    type: "tool.start";
+    toolCallId: string;
+    name: string;
+}
+interface ToolEnd {
+    type: "tool.end";
+    toolCallId: string;
+    ok: boolean;
+}
+interface CanvasCreate {
+    type: "canvas.create";
+    artifact: Artifact;
+}
+/** Append `text` to the string at `data.<path>` (e.g. a document body). */
+interface CanvasAppend {
+    type: "canvas.append";
+    id: string;
+    path: string;
+    text: string;
+}
+/** JSON-merge-patch (RFC 7386) `patch` into the artifact's `data`. */
+interface CanvasPatch {
+    type: "canvas.patch";
+    id: string;
+    patch: Record<string, unknown>;
+}
+/**
+ * Replace a single element (by its `data-cid` tree path) inside an `html`
+ * artifact with new outer HTML — an O(1) surgical edit that avoids resending the
+ * whole page. The reconciler resolves the `cid` path against the source HTML.
+ */
+interface CanvasNodePatch {
+    type: "canvas.node_patch";
+    id: string;
+    cid: string;
+    html: string;
+}
+/** Replace wholesale — the reconciler snapshots a new version. */
+interface CanvasReplace {
+    type: "canvas.replace";
+    id: string;
+    artifact: Artifact;
+}
+interface CanvasStatus {
+    type: "canvas.status";
+    id: string;
+    status: ArtifactStatus;
+}
+interface CanvasClose {
+    type: "canvas.close";
+    id: string;
+}
+interface ErrorEvent {
+    type: "error";
+    message: string;
+}
+interface DoneEvent {
+    type: "done";
+}
+type ChatEvent = MessageDelta | MessageEnd | ToolStart | ToolEnd;
+type CanvasEvent = CanvasCreate | CanvasAppend | CanvasPatch | CanvasNodePatch | CanvasReplace | CanvasStatus | CanvasClose;
+type StreamEvent = ChatEvent | CanvasEvent | ErrorEvent | DoneEvent;
+/** Narrow a `StreamEvent` to the canvas family. */
+declare function isCanvasEvent(event: StreamEvent): event is CanvasEvent;
+/** Narrow a `StreamEvent` to the chat family. */
+declare function isChatEvent(event: StreamEvent): event is ChatEvent;
+
+/**
+ * Element selection — a client→server concern (it rides the chat request, not
+ * the SSE wire). When the user clicks an element inside an `html` artifact, the
+ * inspector reports which element was chosen; an edit instruction then carries
+ * this context so the agent can make a targeted change.
+ */
+interface ElementSelection {
+    /** The `html` artifact the element belongs to. */
+    artifactId: string;
+    /** Deterministic path id assigned by the inspector (e.g. "e-0-2"). */
+    cid: string;
+    /** Human/agent-readable selector, e.g. "button.cta". */
+    selector: string;
+    /** Lowercased tag name. */
+    tag: string;
+    /** Short text preview of the element. */
+    text?: string;
+    /** The element's current outer HTML (truncated) — edit context for the agent. */
+    outerHtml?: string;
+    /** Snapshot of the element's key computed styles (for the style panel). */
+    styles?: Record<string, string>;
+    /** True when the element is a group wrapper (offers "Ungroup"). */
+    isGroup?: boolean;
+}
+
+/**
+ * The reconciler — the single place artifact state is mutated.
+ *
+ * `reduceCanvas(state, event)` is a pure function: given the current canvas
+ * state and one canvas event, it returns the next state. The store, hooks, and
+ * components never branch on event `type` — they read the reconciled artifacts.
+ * That keeps streaming (`append`), partial updates (`patch`), and versioning
+ * (`replace`) auditable in one reducer.
+ */
+
+interface CanvasState {
+    /** Current (latest-version) artifact per id. */
+    artifacts: Record<string, Artifact>;
+    /** Version snapshots per id, oldest first. Grows on `canvas.replace`. */
+    history: Record<string, Artifact[]>;
+    /** Creation order — drives tab ordering in the panel. */
+    order: string[];
+    /** The artifact the panel currently focuses. */
+    activeId: string | null;
+}
+declare function emptyCanvasState(): CanvasState;
+declare function reduceCanvas(state: CanvasState, event: CanvasEvent): CanvasState;
+/**
+ * RFC 7386 JSON Merge Patch: `null` deletes a key, plain objects merge
+ * recursively, everything else (arrays, scalars) replaces.
+ */
+declare function mergePatch(target: unknown, patch: unknown): unknown;
+
+/**
+ * SSE client — POST a chat message and yield parsed `StreamEvent`s.
+ *
+ * We use `fetch` + `ReadableStream` rather than the browser `EventSource`
+ * because the chat endpoint is a POST (EventSource is GET-only) and we want an
+ * `AbortSignal` for cancellation. Frames are separated by a blank line; each
+ * `data:` payload is one JSON `StreamEvent`.
+ */
+
+interface ChatRequest {
+    threadId: string;
+    message: string;
+    /** Element context for a targeted edit (set when editing selected elements). */
+    selections?: ElementSelection[];
+}
+interface StreamOptions {
+    signal?: AbortSignal;
+    headers?: Record<string, string>;
+}
+/** Open the chat stream and yield events until the server sends `done`. */
+declare function streamChat(endpoint: string, request: ChatRequest, options?: StreamOptions): AsyncGenerator<StreamEvent>;
+/** Turn a byte stream of SSE frames into a stream of typed events. */
+declare function parseSSE(body: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<StreamEvent>;
+
+/**
+ * The iframe inspector — makes an `html` artifact directly editable.
+ *
+ * `withInspector(html)` injects a small, self-contained script + style into the
+ * page rendered inside the sandboxed iframe. That script:
+ *
+ *   1. stamps every element with a deterministic `data-cid` (a tree path like
+ *      `e-0-2`), so a selection survives re-renders and the agent can target it;
+ *   2. outlines the element under the cursor on hover;
+ *   3. on click, marks it selected and `postMessage`s a selection payload —
+ *      including a snapshot of its key computed styles — to the parent window;
+ *   4. on double-click, makes a text element `contenteditable`; on blur it posts
+ *      the edited element back as `node_edit` (the host commits it as a
+ *      `canvas.node_patch`);
+ *   5. responds to parent commands: `set_style` (apply a style live), `commit`
+ *      (post the element's current HTML back as `node_edit`), and `clear`.
+ *
+ * The script runs inside a `sandbox="allow-scripts"` iframe with a null origin,
+ * so it cannot reach the parent DOM, cookies, or storage — only `postMessage`.
+ */
+declare const INSPECTOR_MARK = "langchain-canvas";
+/** Inject the inspector into an HTML string, before `</body>` when present. The
+ *  injected nodes are tagged `data-lcx` so a full-document save can strip them.
+ *  Also ensures a responsive viewport meta so device-width media queries behave
+ *  the same in the preview, in export, and on a real device. */
+declare function withInspector(html: string): string;
+/** Computed-style properties surfaced to the style panel (camelCase). */
+declare const STYLE_PROPS: readonly ["color", "backgroundColor", "fontSize", "fontWeight", "textAlign", "lineHeight", "letterSpacing", "padding", "borderRadius", "width"];
+
+/**
+ * Schema-driven playback — render the canvas from a scripted list of wire
+ * events, with no backend, no LLM, and no API key.
+ *
+ * The canvas is defined entirely by the wire protocol (`StreamEvent`s). That
+ * means you can develop and demo the UI purely against the schema: hand it a
+ * fixture and watch it render exactly as a real LangGraph agent would drive it.
+ * `mockStream` turns an event array into a timed async stream, shaped identically
+ * to `streamChat`, so anything that consumes one consumes the other.
+ */
+
+interface MockStreamOptions {
+    /** Delay between events, ms. Simulates streaming cadence. Default 120. */
+    delayMs?: number;
+    signal?: AbortSignal;
+}
+/** Yield a fixed list of events over time — a drop-in for `streamChat`. */
+declare function mockStream(events: StreamEvent[], options?: MockStreamOptions): AsyncGenerator<StreamEvent>;
+
+/**
+ * The canvas store — chat transcript + reconciled canvas state in one place.
+ *
+ * This is a *factory*, not a singleton: `createCanvasStore()` returns an
+ * isolated store so an app can host several independent canvas/chat instances.
+ * `<CanvasProvider>` (see `context.tsx`) wires one up; provider-less apps share a
+ * lazily-created default store, keeping the simple API working.
+ *
+ * Every wire event flows through `applyEvent` → the pure `reduceCanvas` reducer
+ * for canvas events, folded into `messages` for chat events, so streaming,
+ * patching, and versioning stay in one auditable place.
+ */
+
+interface ChatMessage {
+    id: string;
+    role: "user" | "assistant";
+    text: string;
+    /** Artifact ids this assistant message produced — drives inline artifact cards. */
+    artifactIds?: string[];
+}
+/** A command the editing UI forwards to the active html artifact's iframe. */
+interface IframeCommand {
+    artifactId: string;
+    /** style · structure (duplicate/delete/move/insert/insert_html) · group/ungroup · set_src · clear. */
+    type: "set_style" | "commit" | "clear" | "set_src" | "duplicate" | "delete" | "move_up" | "move_down" | "insert" | "insert_html" | "group" | "ungroup";
+    /** Target element (omitted for document-level inserts with no selection). */
+    cid?: string;
+    /** Members to wrap for `group`. */
+    cids?: string[];
+    prop?: string;
+    value?: string;
+    /** Tag/block to insert for `insert` (e.g. "h2", "p", "button", "img", "hr", "section"). */
+    block?: string;
+    /** HTML fragment to insert for `insert_html` (a built-in section template). */
+    html?: string;
+    /** Monotonic counter so re-issuing an identical command still fires. */
+    seq: number;
+}
+interface CanvasStore {
+    canvas: CanvasState;
+    messages: ChatMessage[];
+    isStreaming: boolean;
+    error: string | null;
+    /** Elements the user selected inside an `html` artifact (click = 1, marquee = N). */
+    selections: ElementSelection[];
+    /** Last command forwarded to the html iframe (style panel → renderer bus). */
+    iframeCommand: IframeCommand | null;
+    /** Snapshots for undo/redo — only user edits are recorded (not agent streaming). */
+    undoStack: CanvasState[];
+    redoStack: CanvasState[];
+    applyEvent: (event: StreamEvent) => void;
+    /** Apply a batch of events in a single store write (one re-render per frame). */
+    applyEvents: (events: StreamEvent[]) => void;
+    /** Apply a *user*-initiated event, recording a snapshot so it can be undone. */
+    applyUserEvent: (event: StreamEvent) => void;
+    undo: () => void;
+    redo: () => void;
+    addUserMessage: (text: string) => void;
+    setStreaming: (value: boolean) => void;
+    setActiveArtifact: (id: string) => void;
+    setSelections: (selections: ElementSelection[]) => void;
+    sendIframeCommand: (command: Omit<IframeCommand, "seq">) => void;
+    reset: () => void;
+}
+/** Create an isolated canvas store. */
+declare function createCanvasStore(): StoreApi<CanvasStore>;
+
+interface CanvasProviderProps {
+    children: ReactNode;
+    /** Bring your own store (e.g. shared across trees); one is created otherwise. */
+    store?: StoreApi<CanvasStore>;
+}
+declare function CanvasProvider({ children, store }: CanvasProviderProps): react.JSX.Element;
+/** The raw store API for the nearest provider (or the default store). */
+declare function useCanvasStoreApi(): StoreApi<CanvasStore>;
+/** Subscribe to a slice of the canvas store. */
+declare function useCanvasStore<T>(selector: (state: CanvasStore) => T): T;
+
+interface UseCanvasStreamOptions {
+    /** Chat SSE endpoint. Defaults to `/api/chat`. */
+    endpoint?: string;
+    /** Conversation thread id (for server-side memory). Defaults to a fresh uuid. */
+    threadId?: string;
+    /**
+     * Offline mock: given the user's message, return a scripted `StreamEvent[]`
+     * to play instead of hitting the network — an OpenAPI-style "try it" with no
+     * real LLM call. Return `null` to fall through to the live endpoint.
+     */
+    mock?: (message: string) => StreamEvent[] | null;
+}
+declare function useCanvasStream(options?: UseCanvasStreamOptions): {
+    sendMessage: (text: string, withSelections?: ElementSelection[]) => Promise<void>;
+    stop: () => void | undefined;
+    reset: () => void;
+    setActiveArtifact: (id: string) => void;
+    selections: ElementSelection[];
+    editSelection: (instruction: string) => void;
+    clearSelection: () => void;
+    messages: ChatMessage[];
+    canvas: CanvasState;
+    isStreaming: boolean;
+    error: string | null;
+    threadId: string;
+};
+
+declare function useCanvasReplay(): {
+    play: (events: StreamEvent[], options?: MockStreamOptions) => Promise<void>;
+    stop: () => void | undefined;
+    reset: () => void;
+    canvas: CanvasState;
+    isPlaying: boolean;
+};
+
+/**
+ * `useArtifactPatch` — let a renderer commit an inline edit back to the store.
+ *
+ * Editing an artifact on the canvas is just a client-side `canvas.patch`: it
+ * flows through the exact same reconciler an agent's edits do, so the edited
+ * value is the one that renders, versions, and exports. Renderers stay in sync
+ * with the single source of truth instead of holding a private copy.
+ */
+declare function useArtifactPatch(id: string): (patch: Record<string, unknown>) => void;
+
+/**
+ * Schema fixtures — scripted wire-event sequences that render the canvas with no
+ * backend. Feed one to `useCanvasReplay().play(scenario.events)`.
+ *
+ * Each scenario is nothing but `StreamEvent`s: exactly what a LangGraph agent
+ * would emit over the wire. They double as living documentation of the protocol
+ * and as a zero-dependency way to develop renderers.
+ */
+
+interface Scenario {
+    id: string;
+    title: string;
+    description: string;
+    events: StreamEvent[];
+}
+declare const scenarios: Scenario[];
+
+interface RendererProps<TData = unknown> {
+    artifact: Artifact<TData>;
+}
+type ArtifactRenderer = ComponentType<RendererProps<any>>;
+type ArtifactRegistry = Record<string, ArtifactRenderer>;
+interface CanvasRegistryProviderProps {
+    registry: ArtifactRegistry;
+    children: ReactNode;
+}
+declare function CanvasRegistryProvider({ registry, children }: CanvasRegistryProviderProps): react.JSX.Element;
+/** Resolve the renderer for an artifact type, or `undefined` if unregistered. */
+declare function useRenderer(type: string): ArtifactRenderer | undefined;
+/** Merge registries — later entries win. Handy for extending the built-ins. */
+declare function mergeRegistries(...registries: ArtifactRegistry[]): ArtifactRegistry;
+
+interface CanvasProps {
+    /** Renderer map. Defaults to the built-in html/document/chart/table renderers. */
+    registry?: ArtifactRegistry;
+    /** Rendered when no artifact has been opened yet. */
+    emptyState?: ReactNode;
+    /**
+     * Handle a targeted edit of the selected element (from `useCanvasStream`'s
+     * `editSelection`). When provided, clicking an element in an `html` artifact
+     * reveals a quick-edit bar.
+     */
+    onEditElement?: (instruction: string) => void;
+}
+declare function Canvas({ registry, emptyState, onEditElement }: CanvasProps): react.JSX.Element;
+
+interface ExportMenuProps {
+    artifact: Artifact;
+    getRenderedHtml: () => string | null;
+}
+declare function ExportMenu({ artifact, getRenderedHtml }: ExportMenuProps): react.JSX.Element;
+
+interface SelectionBarProps {
+    selections: ElementSelection[];
+    onEdit: (instruction: string) => void;
+    onClear: () => void;
+}
+declare function SelectionBar({ selections, onEdit, onClear }: SelectionBarProps): react.JSX.Element;
+
+declare function StylePanel({ selection }: {
+    selection: ElementSelection;
+}): react.JSX.Element;
+
+/**
+ * `<ArtifactCard>` — an inline reference to an artifact, for the chat transcript.
+ *
+ * Assistant messages carry the ids of the artifacts they produced
+ * (`message.artifactIds`); render a card per id under the bubble so the artifact
+ * shows up *in the conversation* (like ChatGPT), and clicking it focuses that
+ * artifact in the `<Canvas />` panel.
+ */
+declare function ArtifactCard({ artifactId }: {
+    artifactId: string;
+}): react.JSX.Element | null;
+
+declare function SlidesRenderer$1({ artifact }: RendererProps<SlidesData>): react.JSX.Element;
+
+declare function TableRenderer$1({ artifact }: RendererProps<TableData>): react.JSX.Element;
+
+declare function DocumentRenderer$1({ artifact }: RendererProps<DocumentData>): react.JSX.Element;
+
+declare function ChartRenderer$1({ artifact }: RendererProps<ChartData>): react.JSX.Element;
+
+declare function HtmlRenderer({ artifact }: RendererProps<HtmlData>): react.JSX.Element;
+
+declare const ChartRenderer: react.LazyExoticComponent<typeof ChartRenderer$1>;
+declare const DocumentRenderer: react.LazyExoticComponent<typeof DocumentRenderer$1>;
+declare const TableRenderer: react.LazyExoticComponent<typeof TableRenderer$1>;
+declare const SlidesRenderer: react.LazyExoticComponent<typeof SlidesRenderer$1>;
+
+/**
+ * The batteries-included renderers. `html` is the base substrate (sandboxed
+ * iframe); the rest are structured conveniences, lazily loaded. Pass to
+ * `<Canvas registry />` or merge with your own. They render under `<Canvas>`'s
+ * Suspense boundary, so the on-demand chunks resolve transparently.
+ */
+declare const builtinRenderers: ArtifactRegistry;
+
+/** Browser download helpers — trigger a file save from an in-memory string. */
+/** Save `content` as a file named `filename` with the given MIME type. */
+declare function downloadBlob(filename: string, mime: string, content: BlobPart): void;
+/** Turn a title into a safe file stem: "Q1 Report!" -> "q1-report". */
+declare function slugify(text: string): string;
+
+/**
+ * Artifact → file exporters.
+ *
+ * Two kinds of export:
+ *
+ * 1. **HTML** (`toStandaloneHtml`) — wrap the *rendered* DOM of any artifact into
+ *    a self-contained `.html` document with inlined styles.
+ * 2. **Data exporters** (`dataExporters`) — deterministic, per-type conversions
+ *    straight from `artifact.data`: markdown `.md`, table `.csv`/`.xlsx`,
+ *    document `.docx`, slides `.pptx`, raw `.json`.
+ *
+ * Office formats (xlsx / docx / pptx) are produced with `exceljs` / `docx` /
+ * `pptxgenjs`, loaded via **dynamic import** so they never touch the main
+ * bundle — only the code path a user actually clicks pulls them in.
+ */
+
+interface FileExport {
+    /** Menu label, e.g. "Excel". */
+    label: string;
+    /** File extension without the dot, e.g. "xlsx". */
+    extension: string;
+    mime: string;
+    /** Build the file contents (text or binary; may be async for Office formats). */
+    build: (artifact: Artifact) => BlobPart | Promise<BlobPart>;
+}
+/** Per-type data exporters, keyed by `artifact.type`. */
+declare const dataExporters: Record<string, FileExport[]>;
+/** Wrap already-rendered inner HTML into a standalone, styled `.html` document. */
+declare function toStandaloneHtml(title: string, renderedHtml: string): string;
+/**
+ * A print-ready HTML document with one landscape page per slide — fed to the
+ * browser's print pipeline to produce a multi-page PDF. Elements keep their
+ * percentage geometry, so pages match the on-canvas layout exactly.
+ */
+declare function slidesToPrintHtml(data: SlidesData, title: string): string;
+
+/**
+ * PDF export via the browser's own print pipeline — zero dependencies, and the
+ * output is pixel-faithful to what the canvas renders (the browser is the best
+ * HTML→PDF engine there is).
+ *
+ * We write the standalone HTML into an offscreen iframe and trigger `print()`
+ * on it; the user picks "Save as PDF" in the print dialog. Using an iframe (not
+ * a popup) avoids popup blockers and never navigates the host page away.
+ */
+/**
+ * Print an HTML document to PDF through an offscreen iframe.
+ *
+ * Security: the export HTML may be untrusted (LLM-generated or imported), so the
+ * frame is **sandboxed without `allow-scripts`** — scripts, `onerror`, `onload`,
+ * etc. never execute, so nothing can run in the host origin. `allow-same-origin`
+ * (safe here precisely because scripts are disabled) lets us call `print()` on
+ * the frame; `allow-modals` permits the print dialog. `srcdoc` is used instead of
+ * `document.write` so the content is parsed inertly.
+ */
+declare function printToPdf(html: string): void;
+
+/**
+ * File → artifact importers — the inverse of `export/exporters.ts`.
+ *
+ * `langchain-canvas` isn't only a viewer for agent output: you can open a real
+ * file and edit it on the canvas, then export it back out (round-trip). Each
+ * importer maps a file to a `canvas.create` + `canvas.status: complete` event
+ * pair, so an opened file flows through the exact same reconciler path an
+ * agent's stream would — no special-casing downstream.
+ *
+ * Dependency policy mirrors the exporters: text formats (csv / md / html / json)
+ * are parsed inline with zero dependencies; `.xlsx` reuses `exceljs`, loaded via
+ * dynamic import so it never touches the main bundle.
+ */
+
+/** Extensions we can turn into an artifact, for `accept="…"` and drop filtering. */
+declare const IMPORTABLE_EXTENSIONS: readonly [".csv", ".md", ".markdown", ".txt", ".html", ".htm", ".json", ".xlsx"];
+/** True when the file has an extension we know how to import. */
+declare const canImport: (file: File) => boolean;
+/**
+ * Parse a file into canvas events. Rejects if the extension is unsupported so
+ * callers can surface a clear message. Text parsing is synchronous; `.xlsx`
+ * awaits its dynamic import.
+ */
+declare function importFile(file: File): Promise<StreamEvent[]>;
+/** RFC-4180-ish CSV parser: handles quoted fields, embedded commas, and "" escapes. */
+declare function parseCsv(text: string): TableData;
+
+/**
+ * `useCanvasImport` — open local files onto the canvas.
+ *
+ * Turns a `File` (from a file picker or a drag-and-drop) into canvas events and
+ * applies them through the store, so the imported document/sheet/page becomes a
+ * first-class artifact you can edit and re-export. Returns the id of the last
+ * artifact created so callers can focus it.
+ */
+declare function useCanvasImport(): {
+    importFiles: (files: Iterable<File>) => Promise<string | null>;
+    canImport: (file: File) => boolean;
+};
+
+export { type Artifact, ArtifactCard, type ArtifactRegistry, type ArtifactRenderer, type ArtifactStatus, Canvas, type CanvasAppend, type CanvasClose, type CanvasCreate, type CanvasEvent, type CanvasNodePatch, type CanvasPatch, type CanvasProps, CanvasProvider, type CanvasProviderProps, CanvasRegistryProvider, type CanvasReplace, type CanvasState, type CanvasStatus, type CanvasStore, type ChartArtifact, type ChartData, type ChartOptions, ChartRenderer, type ChartSeries, type ChatEvent, type ChatMessage, type ChatRequest, type DocumentArtifact, type DocumentData, DocumentRenderer, type DoneEvent, type ElementSelection, type ErrorEvent, ExportMenu, type FileExport, type HtmlArtifact, type HtmlData, HtmlRenderer, IMPORTABLE_EXTENSIONS, INSPECTOR_MARK, type IframeCommand, type KnownArtifact, type MessageDelta, type MessageEnd, type MockStreamOptions, type RendererProps, STYLE_PROPS, type Scenario, SelectionBar, type Slide, type SlideElement, type SlidesArtifact, type SlidesData, SlidesRenderer, type StreamEvent, type StreamOptions, StylePanel, type TableArtifact, type TableColumn, type TableData, TableRenderer, type ToolEnd, type ToolStart, type UseCanvasStreamOptions, builtinRenderers, canImport, createCanvasStore, dataExporters, downloadBlob, emptyCanvasState, importFile, isCanvasEvent, isChatEvent, mergePatch, mergeRegistries, mockStream, parseCsv, parseSSE, printToPdf, reduceCanvas, scenarios, slidesToPrintHtml, slugify, streamChat, toStandaloneHtml, useArtifactPatch, useCanvasImport, useCanvasReplay, useCanvasStore, useCanvasStoreApi, useCanvasStream, useRenderer, withInspector };