@browxai/plugin-tldraw 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,41 @@
+# @browxai/plugin-tldraw
+
+First-party browxai canvas-app adapter for Tldraw. Exposes five small,
+useful tools (`tldraw.get_selected_shapes`, `tldraw.get_viewport`,
+`tldraw.create_shape`, `tldraw.delete_shape`, `tldraw.select_shapes`)
+over the `window.editor` global that Tldraw v2+ exposes when an Editor
+component is mounted on the page. Each tool is a thin wrapper around an
+`eval_js` round-trip: the plugin builds the appropriate `editor.*`
+expression, dispatches through `eval_js`, and parses the value back.
+When `window.editor` is undefined (Tldraw not mounted), every tool
+returns the structured `code:"tldraw-not-loaded"` envelope.
+
+## Install
+
+```sh
+$ browxai plugin install @browxai/plugin-tldraw
+```
+
+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 `tldraw.get_selected_shapes` (etc.) on MCP
+`tools/list`, and on the SDK as
+`client.plugins.tldraw.get_selected_shapes(...)`.
+
+## Targeted Tldraw API surface
+
+This plugin pokes the Tldraw v2.x Editor API as of 2026-06:
+`editor.getSelectedShapes()`, `editor.getViewportPageBounds()`,
+`editor.getZoomLevel()`, `editor.createShapes([...])`,
+`editor.deleteShapes([...])`, `editor.setSelectedShapes(...)`. The
+v2 API has been stable across minor versions; if Tldraw renames a
+method, swap the eval-expression string in `src/index.ts` and the
+unit tests stay green.
+
+## 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: {
+    /** `tldraw.get_selected_shapes()` → `{ok, shapes:[{id,type,x,y,props}]}`. */
+    get_selected_shapes(api: PluginApi, _args: unknown): Promise<ToolResponse>;
+    /** `tldraw.get_viewport()` → `{ok, x, y, w, h, zoom}`. */
+    get_viewport(api: PluginApi, _args: unknown): Promise<ToolResponse>;
+    /** `tldraw.create_shape({type, x, y, props?})` → `{ok, shapeId}`. */
+    create_shape(api: PluginApi, args: unknown): Promise<ToolResponse>;
+    /** `tldraw.delete_shape({shapeId})` — `editor.deleteShapes([shapeId])`. */
+    delete_shape(api: PluginApi, args: unknown): Promise<ToolResponse>;
+    /** `tldraw.select_shapes({shapeIds})` — `editor.setSelectedShapes(shapeIds)`. */
+    select_shapes(api: PluginApi, args: unknown): Promise<ToolResponse>;
+};
+export declare function register(api: PluginApi): void;
+export default register;

package/dist/index.js

@@ -0,0 +1,195 @@
+// @browxai/plugin-tldraw — Tldraw canvas-app adapter.
+//
+// Surfaces five small, useful tools over the `window.editor` global that
+// Tldraw (v2+) exposes when an Editor component is mounted on the page.
+// Each tool routes through `eval_js` — the plugin builds the
+// `editor.*` expression, dispatches it, and parses the value back.
+//
+// Targeted API surface (Tldraw v2.x, current as of 2026-06):
+//   - editor.getSelectedShapes()    → Shape[]
+//   - editor.getViewportPageBounds() → {x,y,w,h}
+//   - editor.getZoomLevel()         → number
+//   - editor.createShapes([...])    → void (assigns shape ids)
+//   - editor.deleteShapes([ids])    → void
+//   - editor.setSelectedShapes(ids) → void
+//
+// When `window.editor` is undefined (Tldraw not mounted / not on the
+// page), every tool returns `code:"tldraw-not-loaded"`.
+const json = (obj) => ({
+    content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+});
+const NOT_LOADED = {
+    ok: false,
+    error: "Tldraw not loaded — open the app first OR the surface is not exposed on this version of the app",
+    code: "tldraw-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 tldrawLoaded(api) {
+    const r = await runEval(api, `(typeof window !== "undefined" && typeof window.editor !== "undefined" && window.editor !== null)`);
+    return r.ok && r.value === true;
+}
+export const handlers = {
+    /** `tldraw.get_selected_shapes()` → `{ok, shapes:[{id,type,x,y,props}]}`. */
+    async get_selected_shapes(api, _args) {
+        if (!(await tldrawLoaded(api)))
+            return json(NOT_LOADED);
+        const expr = `(() => {
+      const e = window.editor;
+      const shapes = (e.getSelectedShapes ? e.getSelectedShapes() : []) || [];
+      return {
+        shapes: shapes.map(s => ({
+          id: s.id,
+          type: s.type,
+          x: s.x,
+          y: s.y,
+          props: s.props || {},
+        })),
+      };
+    })()`;
+        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 });
+    },
+    /** `tldraw.get_viewport()` → `{ok, x, y, w, h, zoom}`. */
+    async get_viewport(api, _args) {
+        if (!(await tldrawLoaded(api)))
+            return json(NOT_LOADED);
+        const expr = `(() => {
+      const e = window.editor;
+      const b = e.getViewportPageBounds ? e.getViewportPageBounds() : { x: 0, y: 0, w: 0, h: 0 };
+      const z = e.getZoomLevel ? e.getZoomLevel() : 1;
+      return { x: b.x, y: b.y, w: b.w, h: b.h, zoom: z };
+    })()`;
+        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 });
+    },
+    /** `tldraw.create_shape({type, x, y, props?})` → `{ok, shapeId}`. */
+    async create_shape(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 (a.props !== undefined && (typeof a.props !== "object" || a.props === null)) {
+            return json(badArg("props"));
+        }
+        if (!(await tldrawLoaded(api)))
+            return json(NOT_LOADED);
+        const shape = {
+            type: a.type,
+            x: a.x,
+            y: a.y,
+            props: a.props ?? {},
+        };
+        const shapeJson = JSON.stringify(shape);
+        const expr = `(() => {
+      const e = window.editor;
+      const shape = ${shapeJson};
+      const before = new Set((e.getCurrentPageShapes ? e.getCurrentPageShapes() : []).map(s => s.id));
+      e.createShapes([shape]);
+      const after = (e.getCurrentPageShapes ? e.getCurrentPageShapes() : []);
+      const created = after.find(s => !before.has(s.id));
+      return { shapeId: created ? created.id : null };
+    })()`;
+        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.shapeId)
+            return json({
+                ok: false,
+                error: "tldraw create_shape did not produce a new shape id",
+                code: "create-failed",
+            });
+        return json({ ok: true, shapeId: v.shapeId });
+    },
+    /** `tldraw.delete_shape({shapeId})` — `editor.deleteShapes([shapeId])`. */
+    async delete_shape(api, args) {
+        const a = (args ?? {});
+        if (typeof a.shapeId !== "string" || a.shapeId.length === 0)
+            return json(badArg("shapeId"));
+        if (!(await tldrawLoaded(api)))
+            return json(NOT_LOADED);
+        const id = JSON.stringify(a.shapeId);
+        const expr = `(() => {
+      const e = window.editor;
+      e.deleteShapes([${id}]);
+      return { deleted: ${id} };
+    })()`;
+        const r = await runEval(api, expr);
+        if (!r.ok)
+            return json({ ok: false, error: r.error, code: "eval-failed" });
+        return json({ ok: true, shapeId: a.shapeId });
+    },
+    /** `tldraw.select_shapes({shapeIds})` — `editor.setSelectedShapes(shapeIds)`. */
+    async select_shapes(api, args) {
+        const a = (args ?? {});
+        if (!Array.isArray(a.shapeIds) || a.shapeIds.some((id) => typeof id !== "string")) {
+            return json(badArg("shapeIds"));
+        }
+        if (!(await tldrawLoaded(api)))
+            return json(NOT_LOADED);
+        const ids = JSON.stringify(a.shapeIds);
+        const expr = `(() => {
+      const e = window.editor;
+      e.setSelectedShapes(${ids});
+      return { selected: ${ids} };
+    })()`;
+        const r = await runEval(api, expr);
+        if (!r.ok)
+            return json({ ok: false, error: r.error, code: "eval-failed" });
+        return json({ ok: true, shapeIds: a.shapeIds });
+    },
+};
+export function register(api) {
+    api.log.info("tldraw plugin: registering tools", { namespace: api.namespace });
+    api.registerTool(`${api.namespace}.get_selected_shapes`, {
+        description: "Read `editor.getSelectedShapes()` — returns `{ok, shapes:[{id,type,x,y,props}]}`. App-not-loaded surfaces `code:'tldraw-not-loaded'`.",
+        inputSchema: {},
+    }, (args) => handlers.get_selected_shapes(api, args));
+    api.registerTool(`${api.namespace}.get_viewport`, {
+        description: "Read `editor.getViewportPageBounds()` + `editor.getZoomLevel()` — returns `{ok, x, y, w, h, zoom}`. App-not-loaded surfaces `code:'tldraw-not-loaded'`.",
+        inputSchema: {},
+    }, (args) => handlers.get_viewport(api, args));
+    api.registerTool(`${api.namespace}.create_shape`, {
+        description: "Create a shape via `editor.createShapes([{type, x, y, props}])`. Returns `{ok, shapeId}` (resolved by diffing the page shape list before/after). Bad-arg / app-not-loaded / create-failed surface structured errors.",
+        inputSchema: {},
+    }, (args) => handlers.create_shape(api, args));
+    api.registerTool(`${api.namespace}.delete_shape`, {
+        description: "Delete one shape via `editor.deleteShapes([shapeId])`. Returns `{ok, shapeId}` on success.",
+        inputSchema: {},
+    }, (args) => handlers.delete_shape(api, args));
+    api.registerTool(`${api.namespace}.select_shapes`, {
+        description: "Set the active selection via `editor.setSelectedShapes(shapeIds)`. Returns `{ok, shapeIds}`.",
+        inputSchema: {},
+    }, (args) => handlers.select_shapes(api, args));
+}
+export default register;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@browxai/plugin-tldraw",
+  "version": "0.1.0",
+  "description": "Tldraw canvas-app adapter plugin for browxai — surfaces shapes/viewport/create/delete/select over the `window.editor` page-side global.",
+  "author": "Kalebtec",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "browxai",
+    "browxai-plugin",
+    "tldraw",
+    "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/tldraw"
+  },
+  "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": "tldraw",
+    "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,36 @@
+// Typed SDK overlay for `@browxai/plugin-tldraw` consumers.
+
+interface TldrawBrowxaiResult {
+  readonly content: ReadonlyArray<
+    { type: "text"; text: string } | { type: "image"; data: string; mimeType: string }
+  >;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface TldrawShape {
+  readonly id: string;
+  readonly type: string;
+  readonly x: number;
+  readonly y: number;
+  readonly props: Record<string, unknown>;
+}
+
+export interface TldrawPluginSchema {
+  readonly tldraw: {
+    /** Read `editor.getSelectedShapes()` — returns `{ok, shapes:[...]}`. */
+    get_selected_shapes(args?: Record<string, never>): Promise<TldrawBrowxaiResult>;
+    /** Read viewport page bounds + zoom — returns `{ok, x, y, w, h, zoom}`. */
+    get_viewport(args?: Record<string, never>): Promise<TldrawBrowxaiResult>;
+    /** Create a shape via `editor.createShapes(...)` — returns `{ok, shapeId}`. */
+    create_shape(args: {
+      type: string;
+      x: number;
+      y: number;
+      props?: Record<string, unknown>;
+    }): Promise<TldrawBrowxaiResult>;
+    /** Delete one shape via `editor.deleteShapes([shapeId])`. */
+    delete_shape(args: { shapeId: string }): Promise<TldrawBrowxaiResult>;
+    /** Set the selected-shape ids via `editor.setSelectedShapes(shapeIds)`. */
+    select_shapes(args: { shapeIds: ReadonlyArray<string> }): Promise<TldrawBrowxaiResult>;
+  };
+}