@braincrew-lab/langchain-canvas 0.2.0 → 0.4.9

package/dist/types-BfGP9R2I.d.ts

@@ -0,0 +1,324 @@
+/**
+ * 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";
+    /** 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" | "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;
+}
+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;
+    /** 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;
+}
+/** The deck's page size in inches — the coordinate space percent geometry
+ *  refers to. Absent means the classic 16:9 canvas (10 x 5.625). When a
+ *  template skin is attached, tools fill this with the skin's real page so
+ *  the editor, the preview, and the exported file agree on one aspect
+ *  ratio. */
+interface SlidePage {
+    widthIn: number;
+    heightIn: number;
+}
+interface SlidesData {
+    slides: Slide[];
+    page?: SlidePage;
+    /** Optional pptx skin: a canvas reference ("sources/brand.pptx") whose
+     *  master and layouts the pptx export builds on. Export-time only — the
+     *  canvas preview does not render the skin; a missing or unreadable skin
+     *  degrades to the blank-layout export. */
+    template?: string;
+}
+/**
+ * A stored canvas file shown as itself — a window onto the store, not a copy.
+ * `path` is the canvas-relative reference (`sources/photo.png`); the renderer
+ * resolves it against the host's asset endpoint for display and download.
+ * `cover` / `excerpt` / `detail` are *derived* previews (never stored).
+ */
+interface FileData {
+    path: string;
+    name: string;
+    mediaType?: string;
+    size?: number;
+    /** data: URI thumbnail of page one (page-renderable sources). */
+    cover?: string;
+    /** Short text sample, via the source converter. */
+    excerpt?: string;
+    /** One-line content summary ("3 pages", "5 slides"). */
+    detail?: string;
+}
+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 FileArtifact = Artifact<FileData> & {
+    type: "file";
+};
+type KnownArtifact = HtmlArtifact | DocumentArtifact | ChartArtifact | TableArtifact | SlidesArtifact | FileArtifact;
+
+/**
+ * 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 ErrorEvent {
+    type: "error";
+    message: string;
+}
+interface DoneEvent {
+    type: "done";
+}
+type ChatEvent = MessageDelta | MessageEnd | ToolStart | ToolEnd;
+type CanvasEvent = CanvasCreate | CanvasAppend | CanvasPatch | CanvasNodePatch | CanvasReplace | CanvasStatus | CanvasCommit;
+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;
+}
+
+/**
+ * `CanvasTransport` — the socket between the canvas UI and an agent backend.
+ *
+ * The whole contract is one promise: *given a user message, return the stream
+ * of `StreamEvent`s the canvas should apply.* Everything downstream of the
+ * socket (event batching, reconcile, rendering, error display) is
+ * transport-agnostic, so swapping how the app talks to its backend never
+ * touches a component.
+ *
+ * First-party implementations: `sseTransport` (the reference Canvas Wire
+ * Protocol over SSE — the default), `mockTransport` (scripted offline
+ * streams), and `langgraphTransport` (a LangGraph server, from the
+ * `/langgraph` entry point). An app with its own backend implements this
+ * interface instead of forking the hook.
+ */
+
+/** One user turn, as handed to the transport by `useCanvasStream`. */
+interface TransportRequest {
+    /** Conversation thread id (server-side memory / canvas scope). */
+    threadId: string;
+    /** The user's message. */
+    message: string;
+    /** Element context for a targeted edit (set when editing selected elements). */
+    selections?: ElementSelection[];
+    /** Aborted when the user hits stop or the component unmounts. */
+    signal?: AbortSignal;
+}
+interface CanvasTransport {
+    /** Open the stream for one user turn and yield events until it ends. */
+    stream(request: TransportRequest): AsyncIterable<StreamEvent>;
+}
+
+export { type Artifact as A, type TableColumn as B, type CanvasTransport as C, type DocumentData as D, type ElementSelection as E, type FileData as F, type ToolEnd as G, type HtmlData as H, type ToolStart as I, type TransportRequest as J, type KnownArtifact as K, isCanvasEvent as L, type MessageDelta as M, isChatEvent as N, type StreamEvent as S, type TableData as T, type CanvasEvent as a, type SlidesData as b, type ChartData as c, type ArtifactStatus as d, type CanvasAppend as e, type CanvasCommit as f, type CanvasCreate as g, type CanvasNodePatch as h, type CanvasPatch as i, type CanvasReplace as j, type CanvasStatus as k, type ChartArtifact as l, type ChartOptions as m, type ChartSeries as n, type ChatEvent as o, type DocumentArtifact as p, type DoneEvent as q, type ErrorEvent as r, type FileArtifact as s, type HtmlArtifact as t, type MessageEnd as u, type Slide as v, type SlideElement as w, type SlidePage as x, type SlidesArtifact as y, type TableArtifact as z };

package/package.json

@@ -1,14 +1,35 @@
 {
   "name": "@braincrew-lab/langchain-canvas",
-  "version": "0.2.0",
+  "version": "0.4.9",
   "description": "A live canvas for LangChain agents — stream documents, charts, and rich artifacts into a React panel.",
   "license": "MIT",
+  "author": "Brain Crew (https://github.com/braincrew-lab)",
+  "homepage": "https://github.com/braincrew-lab/langchain-canvas#readme",
   "type": "module",
+  "keywords": [
+    "langchain",
+    "langgraph",
+    "ai",
+    "agent",
+    "canvas",
+    "artifacts",
+    "generative-ui",
+    "streaming",
+    "llm",
+    "react",
+    "document",
+    "chart",
+    "spreadsheet",
+    "slides"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/braincrew-lab/langchain-canvas.git",
     "directory": "packages/canvas-react"
   },
+  "bugs": {
+    "url": "https://github.com/braincrew-lab/langchain-canvas/issues"
+  },
   "sideEffects": [
     "*.css",
     "./dist/index.js"
@@ -25,14 +46,19 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./styles.css": "./dist/styles.css"
+    "./styles.css": "./dist/styles.css",
+    "./langgraph": {
+      "types": "./dist/langgraph/index.d.ts",
+      "import": "./dist/langgraph/index.js"
+    }
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
     "react": "^18 || ^19",
-    "react-dom": "^18 || ^19"
+    "react-dom": "^18 || ^19",
+    "@langchain/langgraph-sdk": ">=0.0.70"
   },
   "dependencies": {
     "@fortune-sheet/react": "^1.0.4",
@@ -52,12 +78,21 @@
     "jsdom": "^25",
     "tsup": "^8.2.4",
     "typescript": "^5.5.4",
-    "vitest": "^2"
+    "vitest": "^2",
+    "@langchain/langgraph-sdk": "^1.9.28"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/langgraph-sdk": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "release:patch": "npm version patch -m \"release: %s\"",
+    "release:minor": "npm version minor -m \"release: %s\"",
+    "release:major": "npm version major -m \"release: %s\""
   }
 }

package/dist/PdfRenderer-DPQT4E7O.js

@@ -1,97 +0,0 @@
-import { useState, useEffect, useMemo } from 'react';
-import { jsx, jsxs } from 'react/jsx-runtime';
-
-// src/components/renderers/PdfRenderer.tsx
-function dataUrlToBlob(url) {
-  const m = /^data:[^,]*?(;base64)?,(.*)$/s.exec(url);
-  if (!m) return null;
-  try {
-    if (m[1]) {
-      const bin = atob(m[2]);
-      const bytes = new Uint8Array(bin.length);
-      for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
-      return new Blob([bytes], { type: "application/pdf" });
-    }
-    return new Blob([decodeURIComponent(m[2])], { type: "application/pdf" });
-  } catch {
-    return null;
-  }
-}
-function PdfRenderer({ artifact }) {
-  const src = artifact.data.src;
-  const isData = typeof src === "string" && src.startsWith("data:");
-  const [blobUrl, setBlobUrl] = useState(null);
-  const [broken, setBroken] = useState(false);
-  useEffect(() => {
-    setBroken(false);
-    if (!isData) {
-      setBlobUrl(null);
-      return;
-    }
-    const blob = dataUrlToBlob(src);
-    if (!blob) {
-      setBroken(true);
-      setBlobUrl(null);
-      return;
-    }
-    const url = URL.createObjectURL(blob);
-    setBlobUrl(url);
-    return () => URL.revokeObjectURL(url);
-  }, [src, isData]);
-  const viewUrl = isData ? blobUrl : src;
-  const filename = useMemo(
-    () => artifact.data.filename || `${artifact.title || "document"}.pdf`,
-    [artifact.data.filename, artifact.title]
-  );
-  const [zoom, setZoom] = useState("fit");
-  const zoomOut = () => setZoom((z) => Math.max(50, (z === "fit" ? 100 : z) - 25));
-  const zoomIn = () => setZoom((z) => Math.min(300, (z === "fit" ? 100 : z) + 25));
-  const frameSrc = viewUrl ? `${viewUrl}#toolbar=0&navpanes=0&zoom=${zoom === "fit" ? "page-width" : zoom}` : null;
-  const download = () => {
-    if (!viewUrl) return;
-    const a = document.createElement("a");
-    a.href = viewUrl;
-    a.download = filename;
-    a.click();
-  };
-  if (!src || broken) {
-    return /* @__PURE__ */ jsx("div", { className: "cv-pdf cv-pdf--empty", children: "Waiting for PDF\u2026" });
-  }
-  if (!viewUrl) {
-    return /* @__PURE__ */ jsx("div", { className: "cv-pdf cv-pdf--empty", children: "Loading PDF\u2026" });
-  }
-  return /* @__PURE__ */ jsxs("div", { className: "cv-pdf-panel", children: [
-    /* @__PURE__ */ jsxs("div", { className: "cv-pdf-tools", children: [
-      /* @__PURE__ */ jsx("span", { className: "cv-pdf-tools__name", title: filename, children: filename }),
-      /* @__PURE__ */ jsx("span", { className: "cv-pdf-tools__spacer" }),
-      /* @__PURE__ */ jsxs("span", { className: "cv-pdf-tools__zoom", children: [
-        /* @__PURE__ */ jsx("button", { type: "button", onClick: zoomOut, title: "Zoom out", children: "\u2212" }),
-        /* @__PURE__ */ jsx(
-          "button",
-          {
-            type: "button",
-            className: "cv-pdf-tools__zoom-label",
-            onClick: () => setZoom("fit"),
-            title: "Fit to width",
-            children: zoom === "fit" ? "Fit" : `${zoom}%`
-          }
-        ),
-        /* @__PURE__ */ jsx("button", { type: "button", onClick: zoomIn, title: "Zoom in", children: "\uFF0B" })
-      ] }),
-      /* @__PURE__ */ jsx("span", { className: "cv-pdf-tools__sep" }),
-      /* @__PURE__ */ jsx("button", { type: "button", onClick: download, title: "Download PDF", children: "\u2913 Download" }),
-      /* @__PURE__ */ jsx(
-        "button",
-        {
-          type: "button",
-          onClick: () => window.open(viewUrl, "_blank", "noopener"),
-          title: "Open in a new tab",
-          children: "\u2197 Open"
-        }
-      )
-    ] }),
-    /* @__PURE__ */ jsx("div", { className: "cv-pdf", children: /* @__PURE__ */ jsx("iframe", { className: "cv-pdf__frame", src: frameSrc, title: filename }, frameSrc) })
-  ] });
-}
-
-export { PdfRenderer };