@braincrew-lab/langchain-canvas 0.3.0 → 0.4.9

package/dist/index.d.ts

@@ -1,296 +1,9 @@
+import { A as Artifact, a as CanvasEvent, E as ElementSelection, S as StreamEvent, C as CanvasTransport, F as FileData, b as SlidesData, T as TableData, D as DocumentData, c as ChartData, H as HtmlData } from './types-BfGP9R2I.js';
+export { d as ArtifactStatus, e as CanvasAppend, f as CanvasCommit, g as CanvasCreate, h as CanvasNodePatch, i as CanvasPatch, j as CanvasReplace, k as CanvasStatus, l as ChartArtifact, m as ChartOptions, n as ChartSeries, o as ChatEvent, p as DocumentArtifact, q as DoneEvent, r as ErrorEvent, s as FileArtifact, t as HtmlArtifact, K as KnownArtifact, M as MessageDelta, u as MessageEnd, v as Slide, w as SlideElement, x as SlidePage, y as SlidesArtifact, z as TableArtifact, B as TableColumn, G as ToolEnd, I as ToolStart, J as TransportRequest, L as isCanvasEvent, N as isChatEvent } from './types-BfGP9R2I.js';
 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;
-    /** Chart title shown above the plot. */
-    title?: string;
-    /** Per-slice colors for pie charts, index-aligned to `rows`. */
-    colors?: string[];
-}
-interface ChartData {
-    chart: "line" | "bar" | "area" | "pie" | "scatter" | "donut";
-    /** 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 PDF shown in the browser's native viewer. `src` is a `data:application/pdf`
- * URL (self-contained, the common case for agent/file-sourced PDFs), a `blob:`
- * URL, or an `https:` URL the host is allowed to frame.
- */
-interface PdfData {
-    src: string;
-    /** Optional original filename, used for the download attribute. */
-    filename?: string;
-}
-/** A freely-positioned element on a "blank" slide (percent geometry, 0–100). */
-interface SlideElement {
-    id: string;
-    type: "text" | "image" | "shape";
-    x: number;
-    y: number;
-    w: number;
-    h: number;
-    text?: string;
-    src?: string;
-    fontSize?: number;
-    bold?: boolean;
-    color?: string;
-    align?: "left" | "center" | "right";
-    /** Shape kind for `type: "shape"`. */
-    shape?: "rect" | "ellipse" | "line";
-    /** Fill (rect/ellipse) or stroke (line) color for a shape. */
-    fill?: string;
-    /** Rotation in degrees, clockwise, about the element's center. Purely visual:
-     *  `x`/`y`/`w`/`h` always describe the unrotated box. */
-    rotate?: number;
-    /** How an image fills its box — "contain" (default, letterboxed) or "cover"
-     *  (fill and crop). */
-    fit?: "contain" | "cover";
-    /** Corner radius in px (0–32) for images and rect shapes. */
-    radius?: number;
-    /** Editor-only grouping: elements sharing a `group` id select and move as
-     *  one. Purely additive — exporters and the presenter ignore it. */
-    group?: string;
-}
-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;
-    /** Theme accent color (hex) — used by quick layouts and new shapes for rules,
-     *  section numbers, and stats. Set by the theme presets. */
-    accent?: string;
-    /** Font stack for the slide's text (system fonts only, no external loads).
-     *  Set by the theme presets; cascades to every element. */
-    fontFamily?: string;
-    /** Speaker notes (not shown on the slide; exported to the .pptx notes pane). */
-    notes?: string;
-    /** Content padding as a percent of the slide width (a safe margin around the
-     *  free canvas). Applied in the editor, present view, thumbnails, and export. */
-    padding?: number;
-}
-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 PdfArtifact = Artifact<PdfData> & {
-    type: "pdf";
-};
-type KnownArtifact = HtmlArtifact | DocumentArtifact | ChartArtifact | TableArtifact | SlidesArtifact | PdfArtifact;
-
-/**
- * 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;
-}
-/**
- * Promote the artifact's current state to a described version snapshot.
- * `revision` is the opaque store revision when a CanvasStore backs the canvas.
- */
-interface CanvasCommit {
-    type: "canvas.commit";
-    id: string;
-    description: string;
-    revision?: string;
-}
-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 | CanvasCommit | 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.
  *
@@ -367,8 +80,13 @@ 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;
+ *  the same in the preview, in export, and on a real device.
+ *
+ *  With `assetBaseUrl`, the inspector also resolves canvas-asset references
+ *  (`src="assets/…"` / `src="sources/…"`) for display: the original relative
+ *  src is kept in `data-lcx-src` and restored on every serialization, so the
+ *  stored document never sees a resolved URL. */
+declare function withInspector(html: string, assetBaseUrl?: 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"];
 
@@ -391,6 +109,35 @@ interface MockStreamOptions {
 /** Yield a fixed list of events over time — a drop-in for `streamChat`. */
 declare function mockStream(events: StreamEvent[], options?: MockStreamOptions): AsyncGenerator<StreamEvent>;
 
+/**
+ * `sseTransport` — the default socket: the Canvas Wire Protocol over SSE.
+ *
+ * Speaks to a reference-style server (`POST endpoint` with
+ * `{thread_id, message, selections}`, answered by an SSE stream of
+ * `StreamEvent` frames). This is exactly what `useCanvasStream` always did;
+ * it is now one `CanvasTransport` implementation among several.
+ */
+
+interface SseTransportOptions {
+    /** Chat SSE endpoint. Defaults to `/api/chat`. */
+    endpoint?: string;
+    /** Extra request headers (e.g. auth). */
+    headers?: Record<string, string>;
+}
+declare function sseTransport(options?: SseTransportOptions): CanvasTransport;
+
+/**
+ * `mockTransport` — scripted offline playback as a socket implementation.
+ *
+ * Wraps the `mockStream` player in the `CanvasTransport` contract: the script
+ * maps a user message to the `StreamEvent[]` to play. Returning `null` falls
+ * through to the wrapped transport (a live backend), which is how the demo
+ * mixes canned examples with real chat.
+ */
+
+type MockScript = (message: string) => StreamEvent[] | null;
+declare function mockTransport(script: MockScript, fallback?: CanvasTransport, options?: Pick<MockStreamOptions, "delayMs">): CanvasTransport;
+
 /**
  * The canvas store — chat transcript + reconciled canvas state in one place.
  *
@@ -451,6 +198,11 @@ interface CanvasStore {
     redoStack: CanvasState[];
     /** Host callback fired after a user edit reconciles — the write-back hook. */
     onUserEdit: UserEditHandler | null;
+    /** URL prefix that resolves a canvas-relative asset path (see `resolveAssetUrl`).
+     *  Renderers use it to display `assets/` / `sources/` references live; the
+     *  export menu uses it to inline them. Null = no file endpoint (references
+     *  stay unresolved, everything else behaves as before). */
+    assetBaseUrl: string | null;
     applyEvent: (event: StreamEvent) => void;
     /** Apply a batch of events in a single store write (one re-render per frame). */
     applyEvents: (events: StreamEvent[]) => void;
@@ -465,6 +217,7 @@ interface CanvasStore {
     sendIframeCommand: (command: Omit<IframeCommand, "seq">) => void;
     /** Register (or clear) the user-edit write-back handler. */
     setOnUserEdit: (handler: UserEditHandler | null) => void;
+    setAssetBaseUrl: (url: string | null) => void;
     reset: () => void;
 }
 /** Create an isolated canvas store. */
@@ -482,14 +235,21 @@ declare function useCanvasStoreApi(): StoreApi<CanvasStore>;
 declare function useCanvasStore<T>(selector: (state: CanvasStore) => T): T;
 
 interface UseCanvasStreamOptions {
-    /** Chat SSE endpoint. Defaults to `/api/chat`. */
+    /**
+     * How to reach the agent backend. Defaults to the reference Canvas Wire
+     * Protocol over SSE (`sseTransport`); pass `langgraphTransport(...)` (from
+     * the `/langgraph` entry) or your own `CanvasTransport` to speak to a
+     * different backend.
+     */
+    transport?: CanvasTransport;
+    /** Chat SSE endpoint for the default transport. 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.
+     * real LLM call. Return `null` to fall through to the live transport.
      */
     mock?: (message: string) => StreamEvent[] | null;
 }
@@ -571,699 +331,6 @@ interface Scenario {
 }
 declare const scenarios: Scenario[];
 
-type CanvasLocale = "en" | "ko";
-declare const MESSAGES: {
-    undo: {
-        en: string;
-        ko: string;
-    };
-    redo: {
-        en: string;
-        ko: string;
-    };
-    export: {
-        en: string;
-        ko: string;
-    };
-    openInTab: {
-        en: string;
-        ko: string;
-    };
-    copyHtml: {
-        en: string;
-        ko: string;
-    };
-    copied: {
-        en: string;
-        ko: string;
-    };
-    versionHistory: {
-        en: string;
-        ko: string;
-    };
-    prevVersion: {
-        en: string;
-        ko: string;
-    };
-    nextVersion: {
-        en: string;
-        ko: string;
-    };
-    backToLatest: {
-        en: string;
-        ko: string;
-    };
-    historyNote: {
-        en: string;
-        ko: string;
-    };
-    loading: {
-        en: string;
-        ko: string;
-    };
-    noRenderer: {
-        en: string;
-        ko: string;
-    };
-    writing: {
-        en: string;
-        ko: string;
-    };
-    open: {
-        en: string;
-        ko: string;
-    };
-    kindWeb: {
-        en: string;
-        ko: string;
-    };
-    kindDocument: {
-        en: string;
-        ko: string;
-    };
-    kindChart: {
-        en: string;
-        ko: string;
-    };
-    kindTable: {
-        en: string;
-        ko: string;
-    };
-    kindSlides: {
-        en: string;
-        ko: string;
-    };
-    kindPdf: {
-        en: string;
-        ko: string;
-    };
-    design: {
-        en: string;
-        ko: string;
-    };
-    code: {
-        en: string;
-        ko: string;
-    };
-    add: {
-        en: string;
-        ko: string;
-    };
-    heading: {
-        en: string;
-        ko: string;
-    };
-    text: {
-        en: string;
-        ko: string;
-    };
-    button: {
-        en: string;
-        ko: string;
-    };
-    image: {
-        en: string;
-        ko: string;
-    };
-    divider: {
-        en: string;
-        ko: string;
-    };
-    pageMenu: {
-        en: string;
-        ko: string;
-    };
-    sectionMenu: {
-        en: string;
-        ko: string;
-    };
-    outlineMenu: {
-        en: string;
-        ko: string;
-    };
-    layoutMenu: {
-        en: string;
-        ko: string;
-    };
-    themeMenu: {
-        en: string;
-        ko: string;
-    };
-    fontMenu: {
-        en: string;
-        ko: string;
-    };
-    shapeMenu: {
-        en: string;
-        ko: string;
-    };
-    a11yCheck: {
-        en: string;
-        ko: string;
-    };
-    a11yTitle: {
-        en: string;
-        ko: string;
-    };
-    a11yClean: {
-        en: string;
-        ko: string;
-    };
-    bgImage: {
-        en: string;
-        ko: string;
-    };
-    present: {
-        en: string;
-        ko: string;
-    };
-    bold: {
-        en: string;
-        ko: string;
-    };
-    italic: {
-        en: string;
-        ko: string;
-    };
-    inlineCode: {
-        en: string;
-        ko: string;
-    };
-    bulletList: {
-        en: string;
-        ko: string;
-    };
-    numberedList: {
-        en: string;
-        ko: string;
-    };
-    quote: {
-        en: string;
-        ko: string;
-    };
-    link: {
-        en: string;
-        ko: string;
-    };
-    words: {
-        en: string;
-        ko: string;
-    };
-    minRead: {
-        en: string;
-        ko: string;
-    };
-    addColumn: {
-        en: string;
-        ko: string;
-    };
-    addRow: {
-        en: string;
-        ko: string;
-    };
-    sortBy: {
-        en: string;
-        ko: string;
-    };
-    filterRows: {
-        en: string;
-        ko: string;
-    };
-    cleanStyling: {
-        en: string;
-        ko: string;
-    };
-    freezeHeader: {
-        en: string;
-        ko: string;
-    };
-    fillColor: {
-        en: string;
-        ko: string;
-    };
-    textColor: {
-        en: string;
-        ko: string;
-    };
-    alignLeft: {
-        en: string;
-        ko: string;
-    };
-    alignCenter: {
-        en: string;
-        ko: string;
-    };
-    alignRight: {
-        en: string;
-        ko: string;
-    };
-    numberFormat: {
-        en: string;
-        ko: string;
-    };
-    mergeCells: {
-        en: string;
-        ko: string;
-    };
-    unmergeCells: {
-        en: string;
-        ko: string;
-    };
-    sheetHint: {
-        en: string;
-        ko: string;
-    };
-    quickFunction: {
-        en: string;
-        ko: string;
-    };
-    quickFunctionTip: {
-        en: string;
-        ko: string;
-    };
-    mergeTip: {
-        en: string;
-        ko: string;
-    };
-    unmergeTip: {
-        en: string;
-        ko: string;
-    };
-    cleanStylingTip: {
-        en: string;
-        ko: string;
-    };
-    freezeOnTip: {
-        en: string;
-        ko: string;
-    };
-    freezeOffTip: {
-        en: string;
-        ko: string;
-    };
-    numberFormatTip: {
-        en: string;
-        ko: string;
-    };
-    sortByColumn: {
-        en: string;
-        ko: string;
-    };
-    ascending: {
-        en: string;
-        ko: string;
-    };
-    descending: {
-        en: string;
-        ko: string;
-    };
-    filterTip: {
-        en: string;
-        ko: string;
-    };
-    fxPlaceholder: {
-        en: string;
-        ko: string;
-    };
-    groupInsert: {
-        en: string;
-        ko: string;
-    };
-    groupFont: {
-        en: string;
-        ko: string;
-    };
-    groupAlign: {
-        en: string;
-        ko: string;
-    };
-    groupNumber: {
-        en: string;
-        ko: string;
-    };
-    groupEdit: {
-        en: string;
-        ko: string;
-    };
-    groupView: {
-        en: string;
-        ko: string;
-    };
-    boldGlyph: {
-        en: string;
-        ko: string;
-    };
-    textGlyph: {
-        en: string;
-        ko: string;
-    };
-    autoSum: {
-        en: string;
-        ko: string;
-    };
-    fmtGeneral: {
-        en: string;
-        ko: string;
-    };
-    fmtCurrency: {
-        en: string;
-        ko: string;
-    };
-    fmtPercent: {
-        en: string;
-        ko: string;
-    };
-    fmtThousands: {
-        en: string;
-        ko: string;
-    };
-    fmtDecimal: {
-        en: string;
-        ko: string;
-    };
-    fmtDate: {
-        en: string;
-        ko: string;
-    };
-    chartTitle: {
-        en: string;
-        ko: string;
-    };
-    editData: {
-        en: string;
-        ko: string;
-    };
-    doneEditing: {
-        en: string;
-        ko: string;
-    };
-    addRowBtn: {
-        en: string;
-        ko: string;
-    };
-    downloadPng: {
-        en: string;
-        ko: string;
-    };
-    stacked: {
-        en: string;
-        ko: string;
-    };
-    seriesColor: {
-        en: string;
-        ko: string;
-    };
-    seriesName: {
-        en: string;
-        ko: string;
-    };
-    removeRow: {
-        en: string;
-        ko: string;
-    };
-    addText: {
-        en: string;
-        ko: string;
-    };
-    addImage: {
-        en: string;
-        ko: string;
-    };
-    addShape: {
-        en: string;
-        ko: string;
-    };
-    arrangeMenu: {
-        en: string;
-        ko: string;
-    };
-    padding: {
-        en: string;
-        ko: string;
-    };
-    duplicate: {
-        en: string;
-        ko: string;
-    };
-    delete: {
-        en: string;
-        ko: string;
-    };
-    group: {
-        en: string;
-        ko: string;
-    };
-    ungroup: {
-        en: string;
-        ko: string;
-    };
-    bringToFront: {
-        en: string;
-        ko: string;
-    };
-    sendToBack: {
-        en: string;
-        ko: string;
-    };
-    fontSize: {
-        en: string;
-        ko: string;
-    };
-    resizeTip: {
-        en: string;
-        ko: string;
-    };
-    fitToggle: {
-        en: string;
-        ko: string;
-    };
-    cornerRadius: {
-        en: string;
-        ko: string;
-    };
-    rotateStep: {
-        en: string;
-        ko: string;
-    };
-    rotationDeg: {
-        en: string;
-        ko: string;
-    };
-    duplicateShort: {
-        en: string;
-        ko: string;
-    };
-    bringForward: {
-        en: string;
-        ko: string;
-    };
-    sendBackward: {
-        en: string;
-        ko: string;
-    };
-    groupShort: {
-        en: string;
-        ko: string;
-    };
-    ungroupShort: {
-        en: string;
-        ko: string;
-    };
-    alignLeftEdges: {
-        en: string;
-        ko: string;
-    };
-    alignHCenters: {
-        en: string;
-        ko: string;
-    };
-    alignRightEdges: {
-        en: string;
-        ko: string;
-    };
-    alignTopEdges: {
-        en: string;
-        ko: string;
-    };
-    alignVCenters: {
-        en: string;
-        ko: string;
-    };
-    alignBottomEdges: {
-        en: string;
-        ko: string;
-    };
-    deleteSelection: {
-        en: string;
-        ko: string;
-    };
-    presentHint: {
-        en: string;
-        ko: string;
-    };
-    speakerNotes: {
-        en: string;
-        ko: string;
-    };
-    download: {
-        en: string;
-        ko: string;
-    };
-    openBtn: {
-        en: string;
-        ko: string;
-    };
-    fitWidth: {
-        en: string;
-        ko: string;
-    };
-    zoomIn: {
-        en: string;
-        ko: string;
-    };
-    zoomOut: {
-        en: string;
-        ko: string;
-    };
-    waitingPdf: {
-        en: string;
-        ko: string;
-    };
-    addTextBox: {
-        en: string;
-        ko: string;
-    };
-    addImageTip: {
-        en: string;
-        ko: string;
-    };
-    addShapeTip: {
-        en: string;
-        ko: string;
-    };
-    applyLayout: {
-        en: string;
-        ko: string;
-    };
-    autoLayoutTip: {
-        en: string;
-        ko: string;
-    };
-    bgColor: {
-        en: string;
-        ko: string;
-    };
-    bgImageTip: {
-        en: string;
-        ko: string;
-    };
-    padTip: {
-        en: string;
-        ko: string;
-    };
-    presentTip: {
-        en: string;
-        ko: string;
-    };
-    duplicateSlide: {
-        en: string;
-        ko: string;
-    };
-    deleteSlide: {
-        en: string;
-        ko: string;
-    };
-    theme: {
-        en: string;
-        ko: string;
-    };
-    desktop: {
-        en: string;
-        ko: string;
-    };
-    tablet: {
-        en: string;
-        ko: string;
-    };
-    mobile: {
-        en: string;
-        ko: string;
-    };
-    a11yIssues: {
-        en: string;
-        ko: string;
-    };
-    a11yNone: {
-        en: string;
-        ko: string;
-    };
-    pageTemplateTitle: {
-        en: string;
-        ko: string;
-    };
-    sectionTemplateTitle: {
-        en: string;
-        ko: string;
-    };
-    jumpToHeading: {
-        en: string;
-        ko: string;
-    };
-    insertSlideLayout: {
-        en: string;
-        ko: string;
-    };
-    applySlideTheme: {
-        en: string;
-        ko: string;
-    };
-    insertShape: {
-        en: string;
-        ko: string;
-    };
-    slideFont: {
-        en: string;
-        ko: string;
-    };
-    slideBgImage: {
-        en: string;
-        ko: string;
-    };
-    moveUp: {
-        en: string;
-        ko: string;
-    };
-    moveDown: {
-        en: string;
-        ko: string;
-    };
-    waitingData: {
-        en: string;
-        ko: string;
-    };
-    calculating: {
-        en: string;
-        ko: string;
-    };
-    loadingSheet: {
-        en: string;
-        ko: string;
-    };
-    dropToOpen: {
-        en: string;
-        ko: string;
-    };
-};
-type MessageKey = keyof typeof MESSAGES;
-interface CanvasLocaleProviderProps {
-    locale?: CanvasLocale;
-    children: ReactNode;
-}
-declare function CanvasLocaleProvider({ locale, children }: CanvasLocaleProviderProps): react.JSX.Element;
-declare function useLocale(): CanvasLocale;
-/** `const t = useT(); t("sortBy")` → the label in the canvas's locale. */
-declare function useT(): (key: MessageKey) => string;
-
 interface RendererProps<TData = unknown> {
     artifact: Artifact<TData>;
 }
@@ -1279,11 +346,31 @@ declare function useRenderer(type: string): ArtifactRenderer | undefined;
 /** Merge registries — later entries win. Handy for extending the built-ins. */
 declare function mergeRegistries(...registries: ArtifactRegistry[]): ArtifactRegistry;
 
+/**
+ * `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.
+ */
+
+interface CanvasImportOptions {
+    /**
+     * Fired once per successfully imported file with the artifact that now
+     * renders on the canvas — the hook for a host to persist an imported
+     * table/document to its store right away.
+     */
+    onImported?: (artifact: Artifact, file: File) => void;
+}
+declare function useCanvasImport({ onImported }?: CanvasImportOptions): {
+    importFiles: (files: Iterable<File>) => Promise<string | null>;
+    canImport: (file: File) => boolean;
+};
+
 interface CanvasProps {
     /** Renderer map. Defaults to the built-in html/document/chart/table renderers. */
     registry?: ArtifactRegistry;
-    /** UI language for the canvas chrome (toolbars, menus, states). Default "en". */
-    locale?: CanvasLocale;
     /** Rendered when no artifact has been opened yet. */
     emptyState?: ReactNode;
     /**
@@ -1307,8 +394,26 @@ interface CanvasProps {
      * stay in-memory exactly as before.
      */
     onSave?: CanvasSaveHandler;
+    /**
+     * Fired with the raw files whenever the user opens files (picker or drop),
+     * before any import parsing — the hook for a host to upload originals to
+     * its store so the agent can read them. When provided, the file picker
+     * accepts every file type (the canvas still previews only what it can
+     * import; the host decides what to do with the rest).
+     */
+    onFilesOpened?: (files: File[]) => void;
+    /** Fired per successfully imported file with its canvas artifact (see `useCanvasImport`). */
+    onImported?: CanvasImportOptions["onImported"];
+    /**
+     * URL prefix that resolves a canvas-relative asset path (`assets/…`,
+     * `sources/…`) to fetchable bytes — the whole encoded path is appended, e.g.
+     * `http://host/api/canvas/<id>/file?path=`. With it, asset references in
+     * artifacts display live and export inlined as `data:` URIs. Omit it and
+     * references stay unresolved — everything else behaves exactly as before.
+     */
+    assetBaseUrl?: string;
 }
-declare function Canvas({ registry, locale, emptyState, onEditElement, onUserEdit, onSave }: CanvasProps): react.JSX.Element;
+declare function Canvas({ registry, emptyState, onEditElement, onUserEdit, onSave, onFilesOpened, onImported, assetBaseUrl, }: CanvasProps): react.JSX.Element;
 
 interface ExportMenuProps {
     artifact: Artifact;
@@ -1339,7 +444,7 @@ declare function ArtifactCard({ artifactId }: {
     artifactId: string;
 }): react.JSX.Element | null;
 
-declare function PdfRenderer$1({ artifact }: RendererProps<PdfData>): react.JSX.Element;
+declare function FileRenderer$1({ artifact }: RendererProps<FileData>): react.JSX.Element;
 
 declare function SlidesRenderer$1({ artifact }: RendererProps<SlidesData>): react.JSX.Element;
 
@@ -1355,7 +460,7 @@ 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>;
-declare const PdfRenderer: react.LazyExoticComponent<typeof PdfRenderer$1>;
+declare const FileRenderer: react.LazyExoticComponent<typeof FileRenderer$1>;
 
 /**
  * The batteries-included renderers. `html` is the base substrate (sandboxed
@@ -1443,7 +548,7 @@ declare function printToPdf(html: string): void;
  */
 
 /** 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", ".pdf", ".hwpx", ".hwp", ".docx", ".pptx"];
+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;
 /**
@@ -1456,16 +561,75 @@ declare function importFile(file: File): Promise<StreamEvent[]>;
 declare function parseCsv(text: string): TableData;
 
 /**
- * `useCanvasImport` — open local files onto the canvas.
+ * Canvas asset references — relative paths that point at files on 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.
+ * The reference contract: inside canvas content, a relative path starting with
+ * `assets/` (files brought in by the agent) or `sources/` (the user's uploads)
+ * points at a file on the *same* canvas — `<img src="assets/logo.png">` in an
+ * html page, `![logo](assets/logo.png)` in a document, `src: "assets/logo.png"`
+ * on a slide image element.
+ *
+ * Display resolves a reference against the host's file endpoint
+ * (`resolveAssetUrl`), keeping the stored content relative. Export restores
+ * self-containment at the door (`inlineArtifactAssets` / `inlineHtmlAssets`):
+ * every reference becomes a `data:` URI so the exported file carries its
+ * images. The unit of self-containment is the canvas folder while
+ * collaborating, and the single file once exported.
+ *
+ * The Python twin lives in `langchain_canvas/assets.py`; the prefix list below
+ * is compared against it by the protocol parity tests.
  */
-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 CanvasCommit, type CanvasCreate, type CanvasEvent, type CanvasLocale, CanvasLocaleProvider, type CanvasNodePatch, type CanvasPatch, type CanvasProps, CanvasProvider, type CanvasProviderProps, CanvasRegistryProvider, type CanvasReplace, type CanvasSaveHandler, type CanvasSavePayload, 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 MessageKey, type MockStreamOptions, type PdfArtifact, type PdfData, PdfRenderer, 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, type UserEditHandler, builtinRenderers, canImport, createCanvasStore, dataExporters, downloadBlob, emptyCanvasState, importFile, isCanvasEvent, isChatEvent, mergePatch, mergeRegistries, mockStream, parseCsv, parseSSE, printToPdf, reduceCanvas, scenarios, slidesToPrintHtml, slugify, streamChat, toStandaloneHtml, useArtifactPatch, useCanvasImport, useCanvasReplay, useCanvasSave, useCanvasStore, useCanvasStoreApi, useCanvasStream, useLocale, useRenderer, useT, withInspector };
+declare const ASSET_REFERENCE_PREFIXES: readonly ["assets/", "sources/"];
+/**
+ * The canvas-root-relative path `src` refers to, or `null`.
+ *
+ * References are root-relative by contract, but a model writing a page that
+ * lives in a folder often produces the document-relative form
+ * (`../sources/photo.png`). Store paths can never contain `..` (the store
+ * contract rejects them), and `assets/` / `sources/` exist only at the root —
+ * so folding leading `./` / `../` segments onto the root reading is lossless
+ * tolerance, not guesswork. Stored content is never rewritten; only consumers
+ * (display, export inlining) interpret leniently.
+ */
+declare function normalizeAssetReference(src: string | undefined | null): string | null;
+declare function isAssetReference(src: string | undefined | null): src is string;
+/**
+ * Absolute URL for a canvas-relative asset path. `assetBaseUrl` is a prefix the
+ * whole (URI-encoded) path is appended to — e.g. the reference server's
+ * `http://host/api/canvas/<id>/file?path=`.
+ */
+declare function resolveAssetUrl(src: string, assetBaseUrl: string): string;
+/** Fetch one canvas asset and encode it as a `data:` URI (null on any failure). */
+declare function fetchAssetDataUri(path: string, assetBaseUrl: string): Promise<string | null>;
+/**
+ * Replace canvas-asset references in an HTML string with `data:` URIs.
+ *
+ * Handles both the stored form (`src="assets/logo.png"`) and the display form a
+ * rendered DOM serializes (`src="<assetBaseUrl><encoded path>"`). A reference
+ * that cannot be fetched is left untouched — honest: the export shows exactly
+ * what could be resolved. Only `src` attributes are rewritten; CSS `url(...)`
+ * references are out of contract.
+ */
+declare function inlineHtmlAssets(html: string, assetBaseUrl: string): Promise<string>;
+/**
+ * An artifact with every canvas-asset reference inlined as a `data:` URI —
+ * the export chokepoint. `html` inlines its page source; `slides` inlines
+ * image elements and the image-layout `image`; other types (and a missing
+ * `assetBaseUrl`) pass through unchanged, so hosts without a file endpoint
+ * keep today's behavior exactly.
+ */
+declare function inlineArtifactAssets<T extends Artifact>(artifact: T, assetBaseUrl: string | null | undefined): Promise<T>;
+
+/**
+ * Display-time resolver for canvas-asset references.
+ *
+ * Returns a function that maps a `src` to a displayable URL: a canvas-relative
+ * reference (`assets/…`, `sources/…`) resolves against the host's asset
+ * endpoint; anything else — and every reference when no endpoint is configured
+ * — passes through untouched. Resolution is display-only: stored artifact data
+ * always keeps the relative reference.
+ */
+declare function useAssetUrl(): (src: string | undefined) => string | undefined;
+
+export { ASSET_REFERENCE_PREFIXES, Artifact, ArtifactCard, type ArtifactRegistry, type ArtifactRenderer, Canvas, CanvasEvent, type CanvasProps, CanvasProvider, type CanvasProviderProps, CanvasRegistryProvider, type CanvasSaveHandler, type CanvasSavePayload, type CanvasState, type CanvasStore, CanvasTransport, ChartData, ChartRenderer, type ChatMessage, type ChatRequest, DocumentData, DocumentRenderer, ElementSelection, ExportMenu, FileData, type FileExport, FileRenderer, HtmlData, HtmlRenderer, IMPORTABLE_EXTENSIONS, INSPECTOR_MARK, type IframeCommand, type MockScript, type MockStreamOptions, type RendererProps, STYLE_PROPS, type Scenario, SelectionBar, SlidesData, SlidesRenderer, type SseTransportOptions, StreamEvent, type StreamOptions, StylePanel, TableData, TableRenderer, type UseCanvasStreamOptions, type UserEditHandler, builtinRenderers, canImport, createCanvasStore, dataExporters, downloadBlob, emptyCanvasState, fetchAssetDataUri, importFile, inlineArtifactAssets, inlineHtmlAssets, isAssetReference, mergePatch, mergeRegistries, mockStream, mockTransport, normalizeAssetReference, parseCsv, parseSSE, printToPdf, reduceCanvas, resolveAssetUrl, scenarios, slidesToPrintHtml, slugify, sseTransport, streamChat, toStandaloneHtml, useArtifactPatch, useAssetUrl, useCanvasImport, useCanvasReplay, useCanvasSave, useCanvasStore, useCanvasStoreApi, useCanvasStream, useRenderer, withInspector };