@browxai/plugin-figma 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-figma
+
+First-party browxai canvas-app adapter for Figma. Exposes five small,
+useful tools (`figma.get_selection`, `figma.get_viewport`,
+`figma.select_node`, `figma.move_node`, `figma.create_rectangle`) over the
+page-side `figma.*` global that Figma's plugin context exposes. Each tool
+is a thin wrapper around an `eval_js` round-trip: the plugin builds the
+appropriate `figma.viewport` / `figma.currentPage.selection` /
+`figma.createRectangle()` expression, dispatches through `eval_js`, and
+parses the value back. When `figma` isn't defined on the page (no editor
+loaded), every tool returns the structured `code:"figma-not-loaded"`
+envelope rather than crashing.
+
+## Install
+
+```sh
+$ browxai plugin install @browxai/plugin-figma
+```
+
+The host must have the `eval` and `canvas` capabilities enabled — the
+plugin declares both at the manifest level and the runtime gates the
+whole plugin against the operator's active capability set.
+
+After install, restart the browxai server (plugin lifecycle is
+resolved-once-at-server-start). The tools surface as
+`figma.get_selection` (etc.) on MCP `tools/list`, and on the SDK as
+`client.plugins.figma.get_selection(...)`.
+
+## Targeted Figma API surface
+
+This plugin pokes the long-stable parts of the Figma plugin API as of
+2026-06: `figma.viewport.{center,zoom}`, `figma.currentPage.selection`,
+`figma.getNodeById()`, `figma.createRectangle()`, plus mutable `x` / `y`
+/ `fills` properties on scene nodes. Future Figma versions may add
+fields; the targeted surface should remain compatible.
+
+## 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: {
+    /** `figma.get_selection()` → `{ok, nodes:[{id,name,type,x,y,width,height}]}`. */
+    get_selection(api: PluginApi, _args: unknown): Promise<ToolResponse>;
+    /** `figma.get_viewport()` → `{ok, center:{x,y}, zoom}`. */
+    get_viewport(api: PluginApi, _args: unknown): Promise<ToolResponse>;
+    /** `figma.select_node({nodeId})` — sets `figma.currentPage.selection`. */
+    select_node(api: PluginApi, args: unknown): Promise<ToolResponse>;
+    /** `figma.move_node({nodeId, dx, dy})` — mutates `node.x`/`node.y` in place. */
+    move_node(api: PluginApi, args: unknown): Promise<ToolResponse>;
+    /** `figma.create_rectangle({x,y,width,height, fillColor?})` → `{ok, nodeId}`. */
+    create_rectangle(api: PluginApi, args: unknown): Promise<ToolResponse>;
+};
+export declare function register(api: PluginApi): void;
+export default register;

package/dist/index.js

@@ -0,0 +1,220 @@
+// @browxai/plugin-figma — Figma canvas-app adapter.
+//
+// Surfaces a small, useful first-party tool surface (selection, viewport,
+// node mutate, rectangle create) over the page-side `figma.*` global that
+// Figma exposes in its plugin-iframe context (and, for agent-driven
+// sessions, reachable through `eval_js` when the file is open in the
+// editor with the plugin context loaded).
+//
+// Design contract:
+//   - All five tools route through `api.callTool("eval_js", {expr})`.
+//   - The plugin declares the `eval` + `canvas` capabilities at the
+//     manifest level — the host gates the whole plugin against those.
+//   - Handlers are resilient to the app not being loaded: a guard
+//     `typeof figma === "undefined"` returns the structured
+//     `figma-not-loaded` error.
+//   - The canonical canvas-app adapter pattern — keep `register(api)`
+//     small, push the heavy lifting into the eval-expression strings,
+//     parse the result back in the plugin.
+//
+// Targeted API surface (as of 2026-06): figma.viewport.{center,zoom},
+// figma.currentPage.selection, figma.createRectangle(),
+// figma.getNodeById(). These are the stable parts of Figma's plugin API
+// and have been present for years; later versions may add fields but
+// shouldn't break this set.
+const json = (obj) => ({
+    content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+});
+const NOT_LOADED = {
+    ok: false,
+    error: "Figma not loaded — open the app first OR the surface is not exposed on this version of the app",
+    code: "figma-not-loaded",
+};
+const badArg = (which) => ({
+    ok: false,
+    error: `bad-arg: missing or invalid \`${which}\``,
+    code: "bad-arg",
+});
+/** Parse the first text item of an eval_js MCP envelope as JSON. */
+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}` };
+    }
+}
+/**
+ * Run an eval_js expression and unwrap its envelope to the page-side value.
+ *
+ * Returns `{ok:true, value}` on a successful page-side eval, or a structured
+ * error envelope (passed straight through to the caller) otherwise.
+ */
+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 };
+}
+/**
+ * Probe `typeof figma` in the page; if undefined, the editor isn't
+ * loaded (or the surface isn't exposed for this build) and the caller
+ * should return the canonical `figma-not-loaded` envelope.
+ */
+async function figmaLoaded(api) {
+    const r = await runEval(api, `(typeof figma !== "undefined")`);
+    return r.ok && r.value === true;
+}
+export const handlers = {
+    /** `figma.get_selection()` → `{ok, nodes:[{id,name,type,x,y,width,height}]}`. */
+    async get_selection(api, _args) {
+        if (!(await figmaLoaded(api)))
+            return json(NOT_LOADED);
+        const expr = `(() => {
+      const sel = figma.currentPage.selection || [];
+      return {
+        nodes: sel.map(n => ({
+          id: n.id,
+          name: n.name,
+          type: n.type,
+          x: n.x,
+          y: n.y,
+          width: n.width,
+          height: n.height,
+        })),
+      };
+    })()`;
+        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 });
+    },
+    /** `figma.get_viewport()` → `{ok, center:{x,y}, zoom}`. */
+    async get_viewport(api, _args) {
+        if (!(await figmaLoaded(api)))
+            return json(NOT_LOADED);
+        const expr = `(() => {
+      const v = figma.viewport;
+      return { center: { x: v.center.x, y: v.center.y }, zoom: v.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 });
+    },
+    /** `figma.select_node({nodeId})` — sets `figma.currentPage.selection`. */
+    async select_node(api, args) {
+        const a = (args ?? {});
+        if (typeof a.nodeId !== "string" || a.nodeId.length === 0)
+            return json(badArg("nodeId"));
+        if (!(await figmaLoaded(api)))
+            return json(NOT_LOADED);
+        const id = JSON.stringify(a.nodeId);
+        const expr = `(() => {
+      const n = figma.getNodeById(${id});
+      if (!n) return { found: false };
+      figma.currentPage.selection = [n];
+      return { found: true, nodeId: n.id };
+    })()`;
+        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.found)
+            return json({ ok: false, error: `node not found: ${a.nodeId}`, code: "node-not-found" });
+        return json({ ok: true, nodeId: v.nodeId });
+    },
+    /** `figma.move_node({nodeId, dx, dy})` — mutates `node.x`/`node.y` in place. */
+    async move_node(api, args) {
+        const a = (args ?? {});
+        if (typeof a.nodeId !== "string" || a.nodeId.length === 0)
+            return json(badArg("nodeId"));
+        if (typeof a.dx !== "number")
+            return json(badArg("dx"));
+        if (typeof a.dy !== "number")
+            return json(badArg("dy"));
+        if (!(await figmaLoaded(api)))
+            return json(NOT_LOADED);
+        const id = JSON.stringify(a.nodeId);
+        const expr = `(() => {
+      const n = figma.getNodeById(${id});
+      if (!n) return { found: false };
+      n.x = n.x + (${a.dx});
+      n.y = n.y + (${a.dy});
+      return { found: true, nodeId: n.id, x: n.x, y: n.y };
+    })()`;
+        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.found)
+            return json({ ok: false, error: `node not found: ${a.nodeId}`, code: "node-not-found" });
+        return json({ ok: true, nodeId: v.nodeId, x: v.x, y: v.y });
+    },
+    /** `figma.create_rectangle({x,y,width,height, fillColor?})` → `{ok, nodeId}`. */
+    async create_rectangle(api, args) {
+        const a = (args ?? {});
+        if (typeof a.x !== "number")
+            return json(badArg("x"));
+        if (typeof a.y !== "number")
+            return json(badArg("y"));
+        if (typeof a.width !== "number" || a.width <= 0)
+            return json(badArg("width"));
+        if (typeof a.height !== "number" || a.height <= 0)
+            return json(badArg("height"));
+        const fill = a.fillColor && typeof a.fillColor === "object"
+            ? a.fillColor
+            : undefined;
+        if (fill &&
+            (typeof fill.r !== "number" || typeof fill.g !== "number" || typeof fill.b !== "number")) {
+            return json(badArg("fillColor"));
+        }
+        if (!(await figmaLoaded(api)))
+            return json(NOT_LOADED);
+        const fillExpr = fill
+            ? `rect.fills = [{ type: "SOLID", color: { r: ${fill.r}, g: ${fill.g}, b: ${fill.b} } }];`
+            : "";
+        const expr = `(() => {
+      const rect = figma.createRectangle();
+      rect.x = ${a.x};
+      rect.y = ${a.y};
+      rect.resize(${a.width}, ${a.height});
+      ${fillExpr}
+      return { nodeId: rect.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, nodeId: v.nodeId });
+    },
+};
+export function register(api) {
+    api.log.info("figma plugin: registering tools", { namespace: api.namespace });
+    api.registerTool(`${api.namespace}.get_selection`, {
+        description: "Read the current `figma.currentPage.selection` — returns `{ok, nodes:[{id,name,type,x,y,width,height}]}`. App-not-loaded surfaces `code:'figma-not-loaded'`.",
+        inputSchema: {},
+    }, (args) => handlers.get_selection(api, args));
+    api.registerTool(`${api.namespace}.get_viewport`, {
+        description: "Read `figma.viewport.center` + `figma.viewport.zoom` — returns `{ok, center:{x,y}, zoom}`. App-not-loaded surfaces `code:'figma-not-loaded'`.",
+        inputSchema: {},
+    }, (args) => handlers.get_viewport(api, args));
+    api.registerTool(`${api.namespace}.select_node`, {
+        description: "Set `figma.currentPage.selection` to the node addressed by `nodeId`. Returns `{ok, nodeId}` on success, `{ok:false, code:'node-not-found'|'bad-arg'|'figma-not-loaded'}` otherwise.",
+        inputSchema: {},
+    }, (args) => handlers.select_node(api, args));
+    api.registerTool(`${api.namespace}.move_node`, {
+        description: "Translate a node by `(dx, dy)` — mutates `node.x` and `node.y` in place. Returns `{ok, nodeId, x, y}` with the post-move position. App-not-loaded / missing-arg / unknown-id surface structured errors.",
+        inputSchema: {},
+    }, (args) => handlers.move_node(api, args));
+    api.registerTool(`${api.namespace}.create_rectangle`, {
+        description: "Create a rectangle via `figma.createRectangle()` at `(x, y)` with `(width, height)`. Optional `fillColor:{r,g,b}` (0–1 floats — Figma's color convention) sets a solid fill. Returns `{ok, nodeId}`.",
+        inputSchema: {},
+    }, (args) => handlers.create_rectangle(api, args));
+}
+export default register;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@browxai/plugin-figma",
+  "version": "0.1.0",
+  "description": "Figma canvas-app adapter plugin for browxai — surfaces a small first-party tool surface (selection, viewport, node mutate, rectangle create) over the `figma.*` page-side global.",
+  "author": "Kalebtec",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "browxai",
+    "browxai-plugin",
+    "figma",
+    "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/figma"
+  },
+  "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": "figma",
+    "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,48 @@
+// Typed SDK overlay for `@browxai/plugin-figma` consumers.
+//
+// Compose this schema into the host's `BrowxaiClientWithPlugins` helper to
+// get autocomplete on every figma.* tool:
+//
+//   import type { FigmaPluginSchema } from "@browxai/plugin-figma/schema";
+//   import type { BrowxaiClientWithPlugins } from "browxai";
+//
+//   const client = (await createBrowxai({...})) as BrowxaiClientWithPlugins<FigmaPluginSchema>;
+//   await client.plugins.figma.get_selection({});
+
+interface FigmaBrowxaiResult {
+  readonly content: ReadonlyArray<
+    { type: "text"; text: string } | { type: "image"; data: string; mimeType: string }
+  >;
+  readonly data?: Record<string, unknown>;
+}
+
+export interface FigmaSceneNode {
+  readonly id: string;
+  readonly name: string;
+  readonly type: string;
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface FigmaPluginSchema {
+  readonly figma: {
+    /** Read the current `figma.currentPage.selection` shape. */
+    get_selection(args?: Record<string, never>): Promise<FigmaBrowxaiResult>;
+    /** Read `figma.viewport.center` + `figma.viewport.zoom`. */
+    get_viewport(args?: Record<string, never>): Promise<FigmaBrowxaiResult>;
+    /** Set `figma.currentPage.selection` to the node with `nodeId`. */
+    select_node(args: { nodeId: string }): Promise<FigmaBrowxaiResult>;
+    /** Mutate `node.x += dx; node.y += dy` on the addressed node. */
+    move_node(args: { nodeId: string; dx: number; dy: number }): Promise<FigmaBrowxaiResult>;
+    /** Create a rectangle via `figma.createRectangle()` — returns `{nodeId}`. */
+    create_rectangle(args: {
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+      fillColor?: { r: number; g: number; b: number };
+    }): Promise<FigmaBrowxaiResult>;
+  };
+}