@browxai/plugin-excalidraw 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kalebtec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @browxai/plugin-excalidraw
+
+First-party browxai canvas-app adapter for Excalidraw. Exposes five
+small, useful tools (`excalidraw.get_scene_state`,
+`excalidraw.get_viewport`, `excalidraw.add_element`,
+`excalidraw.delete_element`, `excalidraw.set_scroll`) over the
+`window.excalidrawAPI` global that the host page sets when embedding the
+Excalidraw React component. Each tool is a thin wrapper around an
+`eval_js` round-trip: the plugin builds the appropriate
+`excalidrawAPI.*` expression, dispatches through `eval_js`, and parses
+the value back. When `window.excalidrawAPI` is undefined (Excalidraw not
+mounted, or the host page didn't forward the ref), every tool returns
+the structured `code:"excalidraw-not-loaded"` envelope.
+
+## Install
+
+```sh
+$ browxai plugin install @browxai/plugin-excalidraw
+```
+
+The host must have the `eval` and `canvas` capabilities enabled — the
+plugin declares both at the manifest level. Restart the browxai server
+after install (plugin lifecycle is resolved-once-at-server-start).
+
+The tools surface as `excalidraw.get_scene_state` (etc.) on MCP
+`tools/list`, and on the SDK as
+`client.plugins.excalidraw.get_scene_state(...)`.
+
+## Targeted Excalidraw API surface
+
+This plugin pokes the Excalidraw 0.17+ ref API as of 2026-06:
+`excalidrawAPI.getSceneElements()`, `excalidrawAPI.getAppState()`,
+`excalidrawAPI.updateScene({elements, appState})`. These are the
+top-level stable methods of the imperative API. Host pages that embed
+the Excalidraw component must forward the `excalidrawAPI` ref to
+`window.excalidrawAPI` for this plugin to find it; the public
+excalidraw.com deployment does this by default.
+
+## Full reference
+
+The per-tool reference for this adapter — every op with args, return
+shape, and error codes, plus a usage walkthrough — lives at
+<https://browxai.com/plugins/first-party/>.

package/dist/index.d.ts

@@ -0,0 +1,38 @@
+interface ToolResponse {
+    readonly content: ReadonlyArray<{
+        type: "text";
+        text: string;
+    } | {
+        type: "image";
+        data: string;
+        mimeType: string;
+    }>;
+}
+interface PluginApi {
+    readonly namespace: string;
+    readonly declaredCapabilities: ReadonlyArray<string>;
+    registerTool(name: string, def: {
+        description: string;
+        inputSchema?: Record<string, any> | undefined;
+    }, handler: (args: unknown) => Promise<ToolResponse>): void;
+    callTool(name: string, args?: Record<string, unknown>): Promise<ToolResponse>;
+    log: {
+        info(msg: string, meta?: Record<string, unknown>): void;
+        warn(msg: string, meta?: Record<string, unknown>): void;
+        error(msg: string, meta?: Record<string, unknown>): void;
+    };
+}
+export declare const handlers: {
+    /** `excalidraw.get_scene_state()` → `{ok, elements:[...], appState:{...}}`. */
+    get_scene_state(api: PluginApi, _args: unknown): Promise<ToolResponse>;
+    /** `excalidraw.get_viewport()` → `{ok, scrollX, scrollY, zoom}`. */
+    get_viewport(api: PluginApi, _args: unknown): Promise<ToolResponse>;
+    /** `excalidraw.add_element({type, x, y, width, height, ...})` — append via updateScene. */
+    add_element(api: PluginApi, args: unknown): Promise<ToolResponse>;
+    /** `excalidraw.delete_element({elementId})` — updateScene without that element. */
+    delete_element(api: PluginApi, args: unknown): Promise<ToolResponse>;
+    /** `excalidraw.set_scroll({scrollX, scrollY})` — updateScene with appState. */
+    set_scroll(api: PluginApi, args: unknown): Promise<ToolResponse>;
+};
+export declare function register(api: PluginApi): void;
+export default register;

package/dist/index.js

@@ -0,0 +1,203 @@
+// @browxai/plugin-excalidraw — Excalidraw canvas-app adapter.
+//
+// Surfaces five small, useful tools over the `window.excalidrawAPI`
+// global that the host page sets when embedding the Excalidraw
+// component (the Excalidraw React component takes an `excalidrawAPI`
+// ref callback; community deployments typically forward it to
+// `window.excalidrawAPI`). Each tool routes through `eval_js`.
+//
+// Targeted API surface (Excalidraw 0.17+, current as of 2026-06):
+//   - excalidrawAPI.getSceneElements()  → Element[]
+//   - excalidrawAPI.getAppState()       → { viewBackgroundColor, viewModeEnabled, zoom, scrollX, scrollY, ... }
+//   - excalidrawAPI.updateScene({elements?, appState?})
+//
+// When `window.excalidrawAPI` is undefined (Excalidraw not mounted, or
+// the host page didn't expose the ref), every tool returns the
+// structured `code:"excalidraw-not-loaded"` envelope.
+const json = (obj) => ({
+    content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+});
+const NOT_LOADED = {
+    ok: false,
+    error: "Excalidraw not loaded — open the app first OR the surface is not exposed on this version of the app",
+    code: "excalidraw-not-loaded",
+};
+const badArg = (which) => ({
+    ok: false,
+    error: `bad-arg: missing or invalid \`${which}\``,
+    code: "bad-arg",
+});
+function parseEvalEnvelope(res) {
+    const first = res.content[0];
+    if (!first || first.type !== "text") {
+        return { ok: false, error: "eval_js returned no text content" };
+    }
+    try {
+        return JSON.parse(first.text);
+    }
+    catch (e) {
+        return { ok: false, error: `eval_js envelope parse failure: ${e.message}` };
+    }
+}
+async function runEval(api, expr) {
+    const res = await api.callTool("eval_js", { expr });
+    const env = parseEvalEnvelope(res);
+    if (!env.ok)
+        return { ok: false, error: env.error ?? "eval_js failed" };
+    return { ok: true, value: env.value };
+}
+async function excalidrawLoaded(api) {
+    const r = await runEval(api, `(typeof window !== "undefined" && typeof window.excalidrawAPI !== "undefined" && window.excalidrawAPI !== null)`);
+    return r.ok && r.value === true;
+}
+export const handlers = {
+    /** `excalidraw.get_scene_state()` → `{ok, elements:[...], appState:{...}}`. */
+    async get_scene_state(api, _args) {
+        if (!(await excalidrawLoaded(api)))
+            return json(NOT_LOADED);
+        const expr = `(() => {
+      const a = window.excalidrawAPI;
+      const els = (a.getSceneElements ? a.getSceneElements() : []) || [];
+      const st = (a.getAppState ? a.getAppState() : {}) || {};
+      return {
+        elements: els.map(e => ({
+          id: e.id,
+          type: e.type,
+          x: e.x,
+          y: e.y,
+          width: e.width,
+          height: e.height,
+        })),
+        appState: {
+          viewBackgroundColor: st.viewBackgroundColor,
+          viewModeEnabled: !!st.viewModeEnabled,
+          zoom: st.zoom,
+        },
+      };
+    })()`;
+        const r = await runEval(api, expr);
+        if (!r.ok)
+            return json({ ok: false, error: r.error, code: "eval-failed" });
+        return json({ ok: true, ...r.value });
+    },
+    /** `excalidraw.get_viewport()` → `{ok, scrollX, scrollY, zoom}`. */
+    async get_viewport(api, _args) {
+        if (!(await excalidrawLoaded(api)))
+            return json(NOT_LOADED);
+        const expr = `(() => {
+      const a = window.excalidrawAPI;
+      const st = (a.getAppState ? a.getAppState() : {}) || {};
+      const zoomVal = st.zoom && typeof st.zoom === "object" ? st.zoom.value : st.zoom;
+      return { scrollX: st.scrollX || 0, scrollY: st.scrollY || 0, zoom: zoomVal || 1 };
+    })()`;
+        const r = await runEval(api, expr);
+        if (!r.ok)
+            return json({ ok: false, error: r.error, code: "eval-failed" });
+        return json({ ok: true, ...r.value });
+    },
+    /** `excalidraw.add_element({type, x, y, width, height, ...})` — append via updateScene. */
+    async add_element(api, args) {
+        const a = (args ?? {});
+        if (typeof a.type !== "string" || a.type.length === 0)
+            return json(badArg("type"));
+        if (typeof a.x !== "number")
+            return json(badArg("x"));
+        if (typeof a.y !== "number")
+            return json(badArg("y"));
+        if (typeof a.width !== "number")
+            return json(badArg("width"));
+        if (typeof a.height !== "number")
+            return json(badArg("height"));
+        if (!(await excalidrawLoaded(api)))
+            return json(NOT_LOADED);
+        const elementJson = JSON.stringify(a);
+        const expr = `(() => {
+      const apiRef = window.excalidrawAPI;
+      const before = (apiRef.getSceneElements ? apiRef.getSceneElements() : []) || [];
+      const seed = ${elementJson};
+      // Excalidraw needs every element to carry a stable id; mint one
+      // if the caller didn't supply it. The crypto.randomUUID() path
+      // matches what Excalidraw itself does on internal creation.
+      const id = seed.id || (typeof crypto !== "undefined" && crypto.randomUUID ? crypto.randomUUID() : "el-" + Date.now() + "-" + Math.random().toString(36).slice(2));
+      const newEl = Object.assign({}, seed, { id });
+      apiRef.updateScene({ elements: before.concat([newEl]) });
+      return { elementId: id };
+    })()`;
+        const r = await runEval(api, expr);
+        if (!r.ok)
+            return json({ ok: false, error: r.error, code: "eval-failed" });
+        const v = r.value;
+        return json({ ok: true, elementId: v.elementId });
+    },
+    /** `excalidraw.delete_element({elementId})` — updateScene without that element. */
+    async delete_element(api, args) {
+        const a = (args ?? {});
+        if (typeof a.elementId !== "string" || a.elementId.length === 0)
+            return json(badArg("elementId"));
+        if (!(await excalidrawLoaded(api)))
+            return json(NOT_LOADED);
+        const id = JSON.stringify(a.elementId);
+        const expr = `(() => {
+      const apiRef = window.excalidrawAPI;
+      const before = (apiRef.getSceneElements ? apiRef.getSceneElements() : []) || [];
+      const after = before.filter(e => e.id !== ${id});
+      apiRef.updateScene({ elements: after });
+      return { removed: before.length - after.length };
+    })()`;
+        const r = await runEval(api, expr);
+        if (!r.ok)
+            return json({ ok: false, error: r.error, code: "eval-failed" });
+        const v = r.value;
+        if (v.removed === 0)
+            return json({
+                ok: false,
+                error: `element not found: ${a.elementId}`,
+                code: "element-not-found",
+            });
+        return json({ ok: true, elementId: a.elementId });
+    },
+    /** `excalidraw.set_scroll({scrollX, scrollY})` — updateScene with appState. */
+    async set_scroll(api, args) {
+        const a = (args ?? {});
+        if (typeof a.scrollX !== "number")
+            return json(badArg("scrollX"));
+        if (typeof a.scrollY !== "number")
+            return json(badArg("scrollY"));
+        if (!(await excalidrawLoaded(api)))
+            return json(NOT_LOADED);
+        const expr = `(() => {
+      const apiRef = window.excalidrawAPI;
+      const cur = (apiRef.getAppState ? apiRef.getAppState() : {}) || {};
+      apiRef.updateScene({ appState: Object.assign({}, cur, { scrollX: ${a.scrollX}, scrollY: ${a.scrollY} }) });
+      return { scrollX: ${a.scrollX}, scrollY: ${a.scrollY} };
+    })()`;
+        const r = await runEval(api, expr);
+        if (!r.ok)
+            return json({ ok: false, error: r.error, code: "eval-failed" });
+        return json({ ok: true, scrollX: a.scrollX, scrollY: a.scrollY });
+    },
+};
+export function register(api) {
+    api.log.info("excalidraw plugin: registering tools", { namespace: api.namespace });
+    api.registerTool(`${api.namespace}.get_scene_state`, {
+        description: "Read `excalidrawAPI.getSceneElements()` + `excalidrawAPI.getAppState()` — returns `{ok, elements:[{id,type,x,y,width,height}], appState:{viewBackgroundColor, viewModeEnabled, zoom}}`. App-not-loaded surfaces `code:'excalidraw-not-loaded'`.",
+        inputSchema: {},
+    }, (args) => handlers.get_scene_state(api, args));
+    api.registerTool(`${api.namespace}.get_viewport`, {
+        description: "Derive viewport from `appState.scrollX/scrollY/zoom` — returns `{ok, scrollX, scrollY, zoom}`. App-not-loaded surfaces `code:'excalidraw-not-loaded'`.",
+        inputSchema: {},
+    }, (args) => handlers.get_viewport(api, args));
+    api.registerTool(`${api.namespace}.add_element`, {
+        description: "Append a scene element via `excalidrawAPI.updateScene({elements: [...existing, new]})`. Required: `type, x, y, width, height`; any extra fields are passed through to Excalidraw. Returns `{ok, elementId}` — id minted via `crypto.randomUUID()` if not supplied. App-not-loaded / bad-arg surface structured errors.",
+        inputSchema: {},
+    }, (args) => handlers.add_element(api, args));
+    api.registerTool(`${api.namespace}.delete_element`, {
+        description: "Remove the element with `elementId` from the scene via `excalidrawAPI.updateScene`. Returns `{ok, elementId}` on success, `{code:'element-not-found'}` if the id isn't present.",
+        inputSchema: {},
+    }, (args) => handlers.delete_element(api, args));
+    api.registerTool(`${api.namespace}.set_scroll`, {
+        description: "Set `appState.scrollX/scrollY` via `excalidrawAPI.updateScene`. Returns `{ok, scrollX, scrollY}`.",
+        inputSchema: {},
+    }, (args) => handlers.set_scroll(api, args));
+}
+export default register;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@browxai/plugin-excalidraw",
+  "version": "0.1.0",
+  "description": "Excalidraw canvas-app adapter plugin for browxai — surfaces scene/viewport/add/delete/scroll over the `window.excalidrawAPI` page-side global.",
+  "author": "Kalebtec",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "browxai",
+    "browxai-plugin",
+    "excalidraw",
+    "canvas",
+    "mcp",
+    "browser-automation",
+    "ai-agent"
+  ],
+  "homepage": "https://browxai.com/plugins/first-party/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kalebteccom/browxai.git",
+    "directory": "packages/plugins/excalidraw"
+  },
+  "bugs": {
+    "url": "https://github.com/kalebteccom/browxai/issues"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "schema.d.ts",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "browxai": {
+    "apiVersion": "1.0.0",
+    "browxaiVersion": "^0.7.0",
+    "namespace": "excalidraw",
+    "register": "dist/index.js",
+    "capabilities": [
+      "eval",
+      "canvas"
+    ],
+    "trust": "kalebtec",
+    "dependsOn": []
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/schema.d.ts

@@ -0,0 +1,45 @@
+// Typed SDK overlay for `@browxai/plugin-excalidraw` consumers.
+
+interface ExcalidrawBrowxaiResult {
+  readonly content: ReadonlyArray<
+    { type: "text"; text: string } | { type: "image"; data: string; mimeType: string }
+  >;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface ExcalidrawElement {
+  readonly id: string;
+  readonly type: string;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface ExcalidrawAppState {
+  readonly viewBackgroundColor: string;
+  readonly viewModeEnabled: boolean;
+  readonly zoom: { value: number };
+}
+
+export interface ExcalidrawPluginSchema {
+  readonly excalidraw: {
+    /** Read scene elements + app state — `{ok, elements:[...], appState:{...}}`. */
+    get_scene_state(args?: Record<string, never>): Promise<ExcalidrawBrowxaiResult>;
+    /** Derive viewport from `appState.scrollX/Y/zoom` — `{ok, scrollX, scrollY, zoom}`. */
+    get_viewport(args?: Record<string, never>): Promise<ExcalidrawBrowxaiResult>;
+    /** Append an element via `excalidrawAPI.updateScene({elements:[...existing, new]})`. */
+    add_element(args: {
+      type: string;
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+      [key: string]: unknown;
+    }): Promise<ExcalidrawBrowxaiResult>;
+    /** Remove an element by id via `excalidrawAPI.updateScene`. */
+    delete_element(args: { elementId: string }): Promise<ExcalidrawBrowxaiResult>;
+    /** Set `appState.scrollX/Y` via `excalidrawAPI.updateScene`. */
+    set_scroll(args: { scrollX: number; scrollY: number }): Promise<ExcalidrawBrowxaiResult>;
+  };
+}