codecaine-cli 0.0.0-stage → 0.1.2

package/dist/resources/bb-plugin/src/tools.ts

@@ -0,0 +1,830 @@
+/**
+ * What a bb-run agent can do to the design that is open on the board.
+ *
+ * These declarations live here, in the plugin package, rather than beside the
+ * code that answers them: this directory is registered with bb by path and its
+ * entry is loaded *inside the bb server process*, which has no way to import
+ * out of the editor's bundle. The renderer half — `src/editor/agent/tools.ts` —
+ * holds a handler per name and nothing else, and
+ * `src/editor/agent/__tests__/plugin-parity.test.ts` is what keeps the two sides
+ * from drifting: a tool declared here with no handler is one the model is told
+ * about and can never call, and neither side would say so at runtime.
+ *
+ * Deliberately dependency-free and side-effect-free, so that parity test can
+ * import it from Vitest, where none of bb's runtime exists.
+ */
+
+/** Which layer a tool is about. An id is exact; a selector is the fallback for
+ *  an agent that has only read the markup — see docs/canvas-api.md for the
+ *  grammar it accepts. */
+export const TARGET_SCHEMA = {
+  type: "object",
+  description:
+    "Layer handle: id (preferred — returned by listLayers/createLayer) or a CSS-shaped selector over the design.",
+  properties: {
+    id: { type: "string", description: "Layer id, as the document holds it." },
+    selector: {
+      type: "string",
+      description:
+        'Selector fallback, matched against the design: ".Hero > button", "text", "#id".',
+    },
+  },
+} as const;
+
+/**
+ * The one description that promises something the editor's own
+ * `canvas.screenshot()` does not: a file on disk rather than a data URL.
+ *
+ * bb's provider bridge keeps only text content parts before the model sees a
+ * tool result (verified in bb-app 0.42.1,
+ * `packages/agent-runtime/src/shared/bridge-tool-calls.ts`), so an inline image
+ * reaches one provider and is dropped for every other. The path is therefore
+ * the contract, and the image part the plugin also returns is a bonus for the
+ * provider that keeps it.
+ */
+const SCREENSHOT_DESCRIPTION =
+  "Picture of the design: the whole page, or one layer with `target`. Writes a PNG into the OS temp dir and returns { path, width, height } — read the file at `path` with your own file-reading tool to look at it. The shot is re-rendered from the design's own markup: no script runs and nothing animates, so a page whose script builds or moves things looks the same here working or broken — to see behaviour, setPageView mode \"interact\" then canvasPointer with shot: true, then mode \"design\" again. A hidden layer draws blank. Anything that would need a network request (a remote image, a webfont the machine lacks) draws as a fallback.";
+
+/** Several layers at once, for the tools that act on a set. */
+export const TARGETS_SCHEMA = {
+  type: "array",
+  description: "The layers, each { id } or { selector }.",
+  items: TARGET_SCHEMA,
+} as const;
+
+export interface CanvasToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+/** The tools, in the order bb advertises them. Adding one means adding its
+ *  handler in `src/editor/agent/tools.ts` — the parity test fails until both
+ *  sides exist. */
+export const CANVAS_TOOLS = [
+  {
+    name: "listLayers",
+    description:
+      "List the layers of the open design, in document order: { count, layers: [{ id, name, type, tag, text, parentId }] }. With no argument it lists everything, which is how to get your bearings on a document you have not seen.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: {
+          type: "string",
+          description: "Only layers matching this selector.",
+        },
+        search: {
+          type: "string",
+          description:
+            "Free text over name, type, tag, text and id, best matches first. Ignored when `selector` is given.",
+        },
+        limit: {
+          type: "number",
+          description: "Cap the rows returned (default 200).",
+        },
+      },
+    },
+  },
+  {
+    name: "listAnnotations",
+    description:
+      "What the person has pinned on the running page in code mode: { count, annotations: [{ id, selector, label, body }] }. Each one is something they pointed at and said out loud, and `selector` is what finds that element in the project\u2019s own source. Empty when nothing is pinned.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "resolveAnnotation",
+    description:
+      "Take a pin off the running page, once what it asked for has actually been done. The pin is the person\u2019s record of what is still outstanding, so resolve one only when the change is written \u2014 not when you have described it. Answers { resolved: true }, or an error when no pin has that id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        id: {
+          type: "string",
+          description: "The annotation's id, as `listAnnotations` gives it and as the message that raised it names it.",
+        },
+      },
+      required: ["id"],
+    },
+  },
+  {
+    name: "getSelection",
+    description:
+      "What the person is pointing at: the layers selected on the board right now, as { count, layers: [{ id, name, type, tag, text }] }. Empty when nothing is selected. This is how to answer \"this\" and \"these\" — check it before asking which layer they mean.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "getLayer",
+    description:
+      "Everything about one layer: { id, name, type, tag, text, path, props, style, ownStyle, box, size, position, children, hidden, locked }. `style` is the look it resolves to; `ownStyle` is only what it declares itself. For an element inside a running project (`remote: true`) there is only `style`: its computed style with the browser's own defaults left out, so a property that is absent is at its default. A picture the editor holds is named `asset:media/images/<hash>.<ext>`, and `files` gives its path on this machine (desktop app) so you can open it — for a picture inside a running project too, which exists nowhere else: to use it in the project's code, copy that file into the project (e.g. `public/`) and point the element at the copy; pass the `asset:` name back anywhere — in markup, a src, a url() — and it is the same picture. Anything still inline comes back as a short `media:…` reference that works the same way.",
+    inputSchema: {
+      type: "object",
+      properties: { target: TARGET_SCHEMA },
+      required: ["target"],
+    },
+  },
+  {
+    name: "createLayer",
+    description:
+      "Put a new layer on the board. `type` is an element type the build knows (text, frame, image, …). Returns { id } of the new layer. Omit `parent` for a layer straight on the page, and omit `at` with it: the layer then lands in clear space beside what is already on the board, which is what you want unless the person named a place. Do not invent coordinates to avoid a collision — you cannot see the board and the editor can. `at` is ignored inside a parent that lays its own children out — an auto-layout frame decides where its children go.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", description: "Element type from the registry." },
+        parent: {
+          type: "string",
+          description:
+            "Id of the layer to put it inside. If it is not found, list the layers again and use an id from that answer — never drop `parent` to get past the error, which puts the layer on the board instead of inside it. An id inside a running project changes when the page re-renders.",
+        },
+        index: {
+          type: "number",
+          description: "Where among the parent's children it goes.",
+        },
+        name: { type: "string" },
+        text: { type: "string", description: "Text content, for a text layer." },
+        style: {
+          type: "object",
+          description:
+            'CSS declarations, camelCased or hyphenated: { "backgroundColor": "#111", "padding": 16 }.',
+        },
+        at: {
+          type: "object",
+          description:
+            "Board coordinates for a free-placed layer. Leave it out and the editor finds clear space beside the design — it can see the board and you cannot. Ignored inside a container that arranges its own children.",
+          properties: { x: { type: "number" }, y: { type: "number" } },
+        },
+        size: {
+          type: "object",
+          properties: {
+            width: { type: "number" },
+            height: { type: "number" },
+          },
+        },
+      },
+      required: ["type"],
+    },
+  },
+  {
+    name: "updateLayer",
+    description:
+      "Change one layer in a single undoable step: name, tag, text, style (merged), clearStyle (taken off), props, hidden, locked, script and packages. Two things to get right: a style write lands in whichever band and pseudo-state the editor is currently showing unless `at` says otherwise (pass at.state \"\" for the ordinary design), and taking a declaration off is clearStyle, not setting it to an empty string. Any other field is refused, not ignored: a layer's type never changes, position goes in style.left/top, a move is moveLayer. The answer reads back the style values it wrote.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        name: { type: "string" },
+        tag: { type: "string" },
+        text: { type: "string" },
+        style: { type: "object", description: "Declarations to merge in." },
+        clearStyle: {
+          type: "array",
+          items: { type: "string" },
+          description: "Declarations to take off outright.",
+        },
+        props: { type: "object" },
+        hidden: { type: "boolean" },
+        locked: { type: "boolean" },
+        script: {
+          type: "string",
+          description:
+            "The code the page runs for this layer in Interact mode and Preview — never on the design canvas, and only while the layer is inside a webpage. A module with `element` already bound to this layer's rendered element: select inside it (element.querySelector; the markup's class names are there to select by), not across the document, so every copy of the layer works on its own. Change what it touches with inline styles or attributes — the design has no stylesheet for a class you toggle. Tell the person to try it in Interact mode or Preview. On a webpage it is the page's own code instead. An empty string removes it.",
+        },
+        packages: {
+          type: "object",
+          description:
+            'npm packages the script imports by bare name, name → version ({ "gsap": "3" }), loaded from esm.sh. Replaces the layer\'s list.',
+        },
+        at: {
+          type: "object",
+          description:
+            "Which band and pseudo-state the style is for. Defaults to what the editor is showing.",
+          properties: {
+            breakpoint: { type: "string" },
+            state: { type: "string" },
+          },
+        },
+      },
+      required: ["target"],
+    },
+  },
+  {
+    name: "replaceLayer",
+    description:
+      "Rewrite a layer as HTML, in place. This is the tool for a real change — a card, a section, a whole hero — because the markup carries structure, text and design in one call instead of twenty. The layer keeps its id, its place, its size and its name, so carry on addressing it by the id you already have — but its type becomes whatever the markup is (an image replaced by a <section> is now a section), and the answer says so under `changed`. A webpage stays a webpage: the markup replaces what is ON the page, and its code and bands stay. A live project or a 3D canvas cannot be replaced. Everything it was made of is replaced, so read it again before you touch a child of it. A <style> block's class rules are dropped — style with Tailwind classes or inline style, and put motion in a <script> (element.animate). If the markup makes no element the layer is left as it was. Tailwind classes are resolved, fonts the markup names are registered, and pictures it points at are fetched. A <script> in the markup, and its on* handlers, are kept on the new layer and run only in Interact mode and Preview (see updateLayer's `script`); in it `element` is that layer — the script runs as a module, so document.currentScript is null. Write real elements — <button>, <a href>, <input> of any type (range, checkbox, date…), <select> with <option>s, <textarea>, <label>, <form>, <details> — never a <div> styled to look like one. hover:, focus:, focus-visible:, active: and disabled: classes become that layer's own state designs, so give every control them in the same markup. Classes are resolved into styles on the way in and no stylesheet comes with them: a script changes inline styles or attributes (hidden, open, aria-*), never toggles a class. A running page never fires a form's submit event: handle the submit button's click. On an element inside a running project it works too, and the element gets a new id, given in `changed`.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        html: {
+          type: "string",
+          description:
+            "The replacement, as one HTML element (its children come with it).",
+        },
+        keepStyle: {
+          type: "boolean",
+          description:
+            "Carry the old layer's styles onto the new one, under the markup's own. Off by default — a button's design is mostly not a heading's.",
+        },
+      },
+      required: ["target", "html"],
+    },
+  },
+  {
+    name: "insertHtml",
+    description:
+      "Put new HTML on the board — inside `parent`, or free on the page when there is none. The same importer as replaceLayer, and the same reason to prefer it: one call for a whole block. A <script> in it is kept on the layer it made, as that layer's `script`, where `element` is that layer (document.currentScript is null: it runs as a module). Write real elements — <button>, <a href>, <input> of any type (range, checkbox, date…), <select> with <option>s, <textarea>, <label>, <form>, <details> — never a <div> styled to look like one. hover:, focus:, focus-visible:, active: and disabled: classes become that layer's own state designs, so give every control them in the same markup. Classes are resolved into styles on the way in and no stylesheet comes with them: a script changes inline styles or attributes (hidden, open, aria-*), never toggles a class. A <style> block's class rules are dropped, so style inline or with Tailwind and animate from the <script> (element.animate). A running page never fires a form's submit event: handle the submit button's click. To fill a webpage, pass the webpage as `parent` — never replace or delete the webpage itself. Free on the page and with no `at`, it lands in clear space beside what is already there rather than over it. Returns { ids } of what it made.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        html: { type: "string", description: "HTML for what to add." },
+        parent: {
+          type: "string",
+          description:
+            "Id of the layer to put it inside. Omit for the page. If it is not found, list the layers again and use an id from that answer — never drop `parent` to get past the error, which puts the layer on the board instead of inside it. An id inside a running project changes when the page re-renders.",
+        },
+        at: {
+          type: "object",
+          description:
+            "Board coordinates. Leave it out and the editor finds clear space beside the design; only name a point when the person asked for one.",
+          properties: { x: { type: "number" }, y: { type: "number" } },
+        },
+      },
+      required: ["html"],
+    },
+  },
+  {
+    name: "holdLayer",
+    description:
+      "Take a layer while you rewrite it. The board shows it as yours — a band of colour round the frame, a chip beside its name — and everybody else's edits are refused until you release it; yours still land. Hold what you are REWRITING, so nothing is edited underneath a half-applied change. Do not hold what you are only reading, and do not hold the original when you are making variants BESIDE it — that layer stays the person's to work on. Always release what you hold, with releaseLayer. Called again on a layer you already hold, it picks the work back up (after askAboutLayer, say). Returns { id, phase, label }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        label: {
+          type: "string",
+          description:
+            'What you are doing, in two or three words — "Rewriting hero". It is shown on the frame while you work, so a person who walks up knows what is happening to their design.',
+        },
+      },
+      required: ["target"],
+    },
+  },
+  {
+    name: "askAboutLayer",
+    description:
+      "Say you need an answer before you can finish a layer you are holding. The hold stays — half your change is applied, which is exactly when an edit underneath does damage — and the board says so, with a sound and a button that takes the person to the layer. Ask your question in the conversation as well; this is what makes it visible on the board. Call holdLayer again on the same layer to pick the work back up. Returns { id, phase, question }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        question: {
+          type: "string",
+          description: "What you need to know, in one sentence.",
+        },
+      },
+      required: ["target", "question"],
+    },
+  },
+  {
+    name: "releaseLayer",
+    description:
+      "Give a layer back. The hold ends at once and `message` is what the board says about it. Release everything you hold before your turn ends, including when you are giving up or the work failed — a layer left held refuses the person's own edits. It is safe to call on a layer that is not held. Returns { id, released }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        message: {
+          type: "string",
+          description:
+            "One line about what happened, shown to the person — \"Rewrote the hero in the new type scale\". Say so plainly here when it did not work.",
+        },
+      },
+      required: ["target"],
+    },
+  },
+  {
+    name: "removeLayer",
+    description:
+      "Delete a layer and everything inside it. Returns { removed } — the ids that actually went. A layer you did not make in this session is the person's: deleting it is refused unless they asked for that layer to go (then pass userAsked: true). Never delete a layer to replace it with a new one — the id everything points at is lost. If one of your edits broke a layer, canvasHistory undo brings it back as it was.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        userAsked: {
+          type: "boolean",
+          description: "True only when the person asked, in this conversation, for this layer to be deleted.",
+        },
+      },
+      required: ["target"],
+    },
+  },
+  {
+    name: "moveLayer",
+    description:
+      "Move a layer the way dragging it does: NEST it inside another layer (`parent`, at `index`), take it out onto the board (`parent: \"board\"`), or REORDER it among its siblings (`index`, or `order`). Works across every boundary — into a running project, out of one, within one — through the same placement engine a drag uses, so it never jumps. One undo step. Answers the layer where it now is; its id changes when it crosses into or out of a project, so use the one returned.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        parent: {
+          type: "string",
+          description: "The new parent's id, or \"board\" for the board itself.",
+        },
+        index: {
+          type: "number",
+          description: "Place among the parent's children, from 0. The end by default.",
+        },
+        order: {
+          type: "string",
+          enum: ["front", "back", "forward", "backward"],
+          description: "Without `parent`: move among its siblings — in a flow, reading order; on the board, what overlaps what.",
+        },
+        at: {
+          type: "object",
+          description: "Board coordinates, for a layer landing on the board.",
+          properties: { x: { type: "number" }, y: { type: "number" } },
+        },
+      },
+      required: ["target"],
+    },
+  },
+  {
+    name: "duplicateLayers",
+    description:
+      "Copy layers, each beside itself in the same parent, with everything inside. Answers { ids, layers } — the copies, to go on editing.",
+    inputSchema: {
+      type: "object",
+      properties: { targets: TARGETS_SCHEMA },
+      required: ["targets"],
+    },
+  },
+  {
+    name: "groupLayers",
+    description:
+      "Put a frame round layers, or take one away. `as: \"group\"` (default) wraps them in a plain frame that keeps each where it is; `as: \"auto-layout\"` wraps them in a frame that ARRANGES them — a row, a column or a grid, read off where they sit unless `direction` says — which is \"put these in a row\"; `as: \"ungroup\"` dissolves the named frames into their parents. The layers need one parent in common. A webpage or live project is never grouped or ungrouped. Ungrouping a frame you did not make deletes the person's frame, so it needs userAsked: true. Answers the new frame, or the freed layers and the `dissolved` frames.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        targets: TARGETS_SCHEMA,
+        as: { type: "string", enum: ["group", "auto-layout", "ungroup"] },
+        direction: { type: "string", enum: ["row", "column", "grid"] },
+        userAsked: {
+          type: "boolean",
+          description: "Ungroup only: true when the person asked for these frames to be taken away.",
+        },
+      },
+      required: ["targets"],
+    },
+  },
+  {
+    name: "scaleLayers",
+    description:
+      "Scale layers with everything in them — font sizes, padding, gaps, radii, borders, shadows and the children's places — so the design keeps its proportions (the K tool). Not a resize: resizing changes the box and leaves the type the size it was.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        targets: TARGETS_SCHEMA,
+        factor: { type: "number", description: "1.5 is half again as big; 0.5 halves it." },
+      },
+      required: ["targets", "factor"],
+    },
+  },
+  {
+    name: "setLayerFont",
+    description:
+      "Set layers in a typeface AND register it with the design, in one step. Writing `fontFamily` with updateLayer changes nothing on screen for a family the design does not carry yet; this fetches it (Google Fonts by name) and sets it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        targets: TARGETS_SCHEMA,
+        family: { type: "string", description: "As it is written: \"Playfair Display\", \"Inter\"." },
+        weight: { type: "number" },
+        style: { type: "string", description: "\"italic\" or \"normal\"." },
+      },
+      required: ["targets", "family"],
+    },
+  },
+  {
+    name: "selectLayers",
+    description:
+      "Select layers on the board, so the person sees which ones you mean — the way to point back at something. An empty `targets` clears the selection. A view change: nothing to undo.",
+    inputSchema: {
+      type: "object",
+      properties: { targets: TARGETS_SCHEMA },
+      required: ["targets"],
+    },
+  },
+  {
+    name: "setPageView",
+    description:
+      "How a page on the board is framed and run — the Design panel's View controls and the toolbar's mode. `view`: \"whole-page\" frames the document at its full height and never scrolls (so scroll-driven animations never fire); \"in-view\" is a real window (1440×1024 unless it has been resized) that scrolls — switch to it before watching or driving anything scroll-linked. `device`: \"desktop\" | \"tablet\" | \"mobile\" (the page's bands). `motion`: \"stop\" holds every animation still, \"reduced\", \"playing\" runs them as a visitor sees them (the default). `mode`: \"interact\" hands the board's pointer to the pages on it, \"design\" gives it back. `preview`: true opens the page in Preview, false closes it. `theme`: \"light\" | \"dark\" shows a live project's running page or a webpage in that theme — its `.dark` class / `data-theme` and its `prefers-color-scheme` rules switched from outside (and a webpage's variables drawn in their dark mode), nothing written into the project or the design — and \"system\" gives it back to the page; the way to check a change in both themes. `target` is a live project, a webpage, or any element inside one. Answers the page's view as it now is.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        view: { type: "string", enum: ["whole-page", "in-view"] },
+        device: { type: "string", description: "A band id: \"desktop\", \"tablet\", \"mobile\"." },
+        motion: { type: "string", enum: ["stop", "reduced", "playing"] },
+        mode: { type: "string", enum: ["design", "interact"] },
+        preview: { type: "boolean" },
+        theme: { type: "string", enum: ["light", "dark", "system"] },
+      },
+      required: ["target"],
+    },
+  },
+  {
+    name: "canvasPointer",
+    description:
+      "Use a page with a REAL mouse and keyboard — the desktop app's own input, not script events — so :hover styles, drag libraries, wheel-driven smooth scrolling and focus behave exactly as for a visitor. `target` is the page (a live project or webpage) or a layer; the editor switches to Interact, brings every point on screen, plays `actions` in order and puts the mode back (`stay: true` keeps Interact — then end with setPageView mode \"design\", or the person is left in Interact). Each action's place is `on`/`from`/`to`: { selector } (the PAGE's selector inside a live project), { id }, or { x, y } in the target's own pixels from its top-left. Actions: { do: \"hover\" | \"move\" | \"click\" | \"double-click\" | \"right-click\" | \"down\" | \"up\", on }, { do: \"drag\", from, to, steps }, { do: \"wheel\", on, dy, dx } (dy > 0 scrolls down, sent as notches like a real wheel), { do: \"type\", text } (into whatever has focus — click a field first), { do: \"key\", press: \"Enter\", modifiers: [\"Shift\"] }, { do: \"wait\", ms }. `shot: true` answers a PNG path of the target as composited afterwards — hover state and all, which canvasScreenshot cannot show. Pair with observePage to read what the input changed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        actions: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              do: {
+                type: "string",
+                enum: ["hover", "move", "click", "double-click", "right-click", "down", "up", "drag", "wheel", "type", "key", "wait"],
+              },
+              on: { type: "object", description: "{ selector } | { id } | { x, y }" },
+              from: { type: "object" },
+              to: { type: "object" },
+              steps: { type: "number" },
+              dy: { type: "number" },
+              dx: { type: "number" },
+              text: { type: "string" },
+              press: { type: "string" },
+              modifiers: { type: "array", items: { type: "string" } },
+              ms: { type: "number" },
+              button: { type: "string", enum: ["left", "right", "middle"] },
+            },
+            required: ["do"],
+          },
+        },
+        shot: { type: "boolean" },
+        settleMs: { type: "number", description: "Pause before the picture, for a transition to finish. 250 by default." },
+        stay: { type: "boolean" },
+      },
+      required: ["target", "actions"],
+    },
+  },
+  {
+    name: "canvasHistory",
+    description:
+      "Undo or redo on the design — the same history the person's ⌘Z walks, shared with them: an undo takes back the last edit, whoever made it. This is how to repair an edit of yours that broke a layer: it comes back with its own id, which a rebuilt copy never has. Answers how many steps were taken and what they changed: `appeared`, `disappeared`, `changedLayers` — read them to check you did not take back the person's work.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["undo", "redo"] },
+        steps: { type: "number", description: "How many. 1 by default." },
+      },
+      required: ["action"],
+    },
+  },
+  {
+    name: "listElementTypes",
+    description:
+      "The element types this build can make — the vocabulary for createLayer's `type` — as { types: [{ type, label, description }] }. Most are ordinary markup; the canvas element is the one that runs code, and its entry carries the whole contract its scene code is written to.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "getCanvasScene",
+    description:
+      "A canvas element's scene: { id, name, preset, code, controls, bindings, values, params, actions, status, contract }. `controls` is the DialKit config the person tunes it with; `params` is what the code sees right now; `status` is what the board's runner made of the code — { state: \"running\" | \"starting\" | \"error\", error, frames } — so an error here is a bug in the code to fix.",
+    inputSchema: {
+      type: "object",
+      properties: { target: TARGET_SCHEMA },
+      required: ["target"],
+    },
+  },
+  {
+    name: "setCanvasScene",
+    description:
+      "Make or rewrite a canvas element — a <canvas> tag running a three.js scene, tuned with DialKit controls. The tool for anything DRAWN or ANIMATED rather than laid out: a 3D scene, a simulator, a game, a particle field, a data visualisation. Without `target` it creates a new canvas (in clear space, or inside `parent`); with one it rewrites that canvas in one undoable step. " +
+      "`code` is the BODY of an async function with THREE, renderer, scene, camera (at z=5), params, frame((time, delta) => …), resize, change((params, keys) => …), action(name, fn), pointer ({ x, y } in -1…1, down, inside), onPointer, keys (a Set of KeyboardEvent.code) and onKey in scope; `scene` is rendered with `camera` after every frame unless your code rendered itself. No DOM and no network: build geometry in code, draw text on an OffscreenCanvas and use it as a CanvasTexture. " +
+      "`controls` is a DialKit config — speed: [1, 0, 5, 0.1] (slider), color: \"#a78bfa\", wireframe: false, mode: { type: \"select\", options: [...] }, restart: { type: \"action\" }, and a plain object is a folder — read in the code as params.speed, params.folder.key. Answers { id, status, params }: status.error is your code failing — fix it and call again. getCanvasScene or listElementTypes gives the full contract.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        code: { type: "string", description: "The scene's code: the body of an async function." },
+        controls: {
+          type: "object",
+          description: "The DialKit config the person tunes the scene with.",
+        },
+        bindings: {
+          type: "object",
+          description:
+            "Which dials also drive the element's own style, so a dial can set the box itself: { radius: \"borderRadius\", fill: \"backgroundColor\" } (a folder's dial is \"folder.key\"; { prop, unit } picks the unit of a length). Bindable: borderRadius, borderWidth, gap, padding, fontSize, letterSpacing (a slider, in px unless a unit is given), opacity, fontWeight, lineHeight (a slider, unitless), backgroundColor, color, borderColor (a colour dial). Replaces what was bound.",
+        },
+        values: {
+          type: "object",
+          description: "Dial settings, merged over what is set.",
+        },
+        preset: {
+          type: "string",
+          description: "Start from a built-in scene instead: knot, galaxy, waves or dodge (a small game).",
+        },
+        name: { type: "string", description: "The layer's name, for a new canvas or a rename." },
+        parent: {
+          type: "string",
+          description:
+            "Id of the layer to put a new canvas inside. Omit for the board. If it is not found, list the layers again and use an id from that answer — never drop `parent` to get past the error, which puts the canvas on the board instead of inside it.",
+        },
+        size: {
+          type: "object",
+          description: "A new canvas's size in px. Defaults to 640 × 400.",
+          properties: { width: { type: "number" }, height: { type: "number" } },
+        },
+      },
+    },
+  },
+  {
+    name: "exportHtml",
+    description:
+      "The design as markup — the whole page, or one layer with `target`. This is the fastest way to read a document you are about to change. `responsive` and `states` emit the media queries and the :hover rules the design carries. Pictures are named `asset:media/images/<hash>.<ext>` (getLayer's `files` gives the path on disk); pass the name back in markup and it is the same picture. Anything still inline comes back as a short `media:…` reference that works the same way. A `target` inside a running project answers that element as its page has it — its own classes and attributes, its computed look inline — which is what to copy when moving a block from one project to another.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        mode: { type: "string", enum: ["fragment", "document"] },
+        styles: { type: "string", enum: ["inline", "classes"] },
+        responsive: { type: "boolean" },
+        states: { type: "boolean" },
+      },
+    },
+  },
+  {
+    name: "listVariables",
+    description:
+      "The CSS variables this board can reach: { collections: [{ id, name, modes, remote, source }], variables: [{ name, property, collection, category, values, resolved, alias, usedBy, owner }] }. Two kinds sit in one list and the difference matters. The DOCUMENT's own are this design's to create, rename and delete. A framed project's are read out of its running stylesheets \u2014 marked `remote`, with `source` naming the file they are declared in (`src/index.css` where the dev server could be traced) \u2014 and are that application's, not the design's. `values` is keyed by mode name (\"Light\", \"Dark\"), so a token with two themes reports both; `alias` names the variable a row points at instead of holding a value of its own, which is usually the answer to \"why is this the wrong colour\". Read this before changing a colour by hand: a design with a `--primary` wants that changed once, not a hex written onto forty layers.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: {
+          type: "string",
+          enum: ["all", "document", "project"],
+          description:
+            "Which half to list. Default `all`. `project` is the framed application's own scale, and is empty when no project is on the board.",
+        },
+        search: {
+          type: "string",
+          description:
+            "Free text over the name, the property and the value. A compiled Tailwind theme is several hundred rows; narrow it.",
+        },
+        limit: { type: "number", description: "Cap the rows returned (default 200)." },
+      },
+    },
+  },
+  {
+    name: "setVariable",
+    description:
+      "Create or change one CSS variable, by name. On the DOCUMENT this creates the variable when nothing holds that property and updates it when something does; every layer bound to it repaints, which is the point of using one. On a FRAMED PROJECT (a property `listVariables` reports as `remote`) the write goes into the running page under the selector that declares that theme, is counted as a change to that page, and is written into the project's own file when the person saves the page into code \u2014 so changing an application's `--primary` here is a real edit to their design system, not a preview. `value` is any CSS the property takes; `var(--other)` makes it an alias. Answers { property, scope, mode, created }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description:
+            "The variable, as `listVariables` names it: `surface/primary`, or the property itself (`--surface-primary`). Slashes are groups.",
+        },
+        value: {
+          type: "string",
+          description:
+            "What it should say \u2014 `#155efa`, `16px`, `var(--color-neutral-0)` to alias another variable. An empty string on a project's variable takes this editor's override off and lets the file answer again.",
+        },
+        mode: {
+          type: "string",
+          description:
+            "Which column, by name or selector: `Dark`, `.dark`. The collection's first mode when left out.",
+        },
+        description: {
+          type: "string",
+          description: "One sentence on how it should be used. Document variables only.",
+        },
+      },
+      required: ["name", "value"],
+    },
+  },
+  {
+    name: "deleteVariable",
+    description:
+      "Take one of the DESIGN's variables out. Every use of it is written back as the value it resolved to, so nothing on the board changes appearance \u2014 the layers simply stop sharing a decision. A framed project's variables cannot be deleted from here: they are declarations in that application's own file. Answers { deleted, inlined }.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "The variable, as `listVariables` names it, or its property.",
+        },
+      },
+      required: ["name"],
+    },
+  },
+  {
+    name: "canvasReadPage",
+    description:
+      "Read a RUNNING project framed on the board by its own CSS selectors \u2014 the fast way to find out what is actually on somebody's application. Answers { matched, count, rows: [{ nodeId, tag, id, text, href, src, alt, value, checked, rect, visible }] }, and `nodeId` is a layer every other tool here takes, so read the page and then act on what you found. The selector is run by the PAGE's own querySelectorAll, so `:has()`, `[data-state=open]` and `:nth-of-type` work here and do not work in listLayers, which matches the editor's own grammar over the handful of fields a snapshot carries. This is the only way to an attribute at all: a snapshot carries none, so a link's target, a field's current value and a component's data- state are unreachable without it. `text` is the element's rendered words, not the truncated label listLayers shows. Ask for `fields` (classes, attrs, selector, html, path) and `styles` only when you need them \u2014 a page's class lists are longer than its content. Empty when no live project is framed; this tool does not read the design itself, which listLayers and exportHtml already answer. With SEVERAL projects framed and none selected it refuses and names them rather than guessing \u2014 pass `target`, or check getSelection for the one the person is looking at.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: {
+          type: "string",
+          description:
+            "A CSS selector in the PAGE's grammar, e.g. \"a[href]\", \"[data-state=open]\", \"section:has(h2)\". Omitted, the answer is the element named by `target`, or the page's top-level elements.",
+        },
+        target: {
+          type: "object",
+          description:
+            "Read inside this element instead of the whole page: the id of a live project, or of an element inside one (`live:...`, as this tool and listLayers return it).",
+          properties: { id: { type: "string" } },
+        },
+        fields: {
+          type: "array",
+          description:
+            "Extra per-row fields, each of which costs more than the rest of the row: \"classes\", \"attrs\", \"selector\", \"html\", \"path\".",
+          items: { type: "string", enum: ["classes", "attrs", "selector", "html", "path"] },
+        },
+        attrs: {
+          type: "array",
+          description: "Report exactly these attributes rather than all of them.",
+          items: { type: "string" },
+        },
+        styles: {
+          type: "array",
+          description: "Computed properties to report per row, as CSS names (\"font-size\").",
+          items: { type: "string" },
+        },
+        limit: { type: "number", description: "Rows to answer with (default 100, ceiling 500). `matched` says how many there were." },
+        textLimit: { type: "number", description: "Where each row's text is cut (default 200)." },
+      },
+    },
+  },
+  {
+    name: "observePage",
+    description:
+      "Watch a page that is NOT this design, to see how an effect on it works — the call to make when somebody points at a site or a running app and says \"do that\". Frames any address that allows framing (or a live project already on the board — any other layer id is refused, since a webpage on the board is watched with setPageView interact + canvasPointer), drives it, and answers per watched element: which CSS properties moved and at which scroll offsets, its `scrollPath` (where it sat on screen at each scroll step, folded into segments: `pinned` for sticky/fixed, `flow` for moving with the content, `parallax` with the rate it moves per pixel scrolled — so \"from A to B over 100px\" is read, not guessed), the page's own transitions, and its @keyframes read exactly out of the browser's animation system (real duration, real easing, real keyframes — the parts an approximation always drops). A screenshot shows the end state and says nothing about what happens between the two ends of a scroll. Nothing is written to the observed page. START WITH NO `watch`: the answer then carries `candidates`, the elements on that page that actually declare an effect, and you name two or three of their selectors in a second call. Read `notes` first — it says when an empty answer is a page that does nothing and when it is a gesture that never landed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        url: {
+          type: "string",
+          description:
+            "The page: an address, or the id of a live project already on the board.",
+        },
+        watch: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            'What to watch, each either a CSS selector read inside that page ("h1", "[data-slot=card] button") or the id of a layer already inside it (a "live:…" id from listLayers or getSelection). Leave it out on the first call to get `candidates` instead.',
+        },
+        plan: {
+          type: "array",
+          description:
+            'Drive the page yourself, step by step — use this when the canned passes do not reach the thing you are looking at (a menu that has to be opened before its item can be hovered, a section three clicks in, a range of scroll you want read closely). Each step is answered with where the page actually ended up and what the pointer actually landed on. Steps: {do:"scroll",to:<px|"top"|"bottom"|selector>}, {do:"scrollBy",y:<px>}, {do:"hover",on:<selector>}, {do:"click",on:<selector>}, {do:"state",on:<selector>,state:"hover"|"active"|"focus"|"focus-visible"|"disabled"|""}, {do:"key",press:"Escape"}, {do:"wait",ms:200}, {do:"settle"}. A reading is taken after every step. NOTE a dispatched hover does not fire CSS :hover — pair {do:"hover"} with {do:"state",state:"hover"} on the same selector to see both a JavaScript handler and the page\'s own :hover rules.',
+          items: {
+            type: "object",
+            properties: {
+              do: {
+                type: "string",
+                enum: [
+                  "scroll",
+                  "scrollBy",
+                  "hover",
+                  "click",
+                  "state",
+                  "key",
+                  "wait",
+                  "settle",
+                ],
+              },
+              to: {
+                description:
+                  'For scroll: a pixel offset, "top", "bottom", or a selector to scroll to.',
+              },
+              y: { type: "number", description: "For scrollBy: pixels down." },
+              x: { type: "number", description: "For scrollBy: pixels across." },
+              on: {
+                type: "string",
+                description: "For hover, click and state: a CSS selector in that page.",
+              },
+              state: {
+                type: "string",
+                description: 'For state: the pseudo-state to show, or "" to clear it.',
+              },
+              press: { type: "string", description: "For key: the key name." },
+              ms: { type: "number", description: "For wait and settle." },
+            },
+            required: ["do"],
+          },
+        },
+        do: {
+          type: "string",
+          enum: ["scroll", "hover", "click"],
+          description:
+            "A canned pass, when you do not need a plan of your own. `scroll` goes down the whole document; `hover` and `click` act on the first watched selector. Ignored when `plan` is given.",
+        },
+        steps: {
+          type: "number",
+          description: "Readings across a canned scroll. Default 12.",
+        },
+        properties: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "CSS properties to sample instead of the default set. Naming a few gives a small answer.",
+        },
+        shots: {
+          type: "boolean",
+          description:
+            "Also take a picture of each watched element at each step, written as PNGs into the OS temp dir — the answer then carries `frames: [{ path, step, label, … }]` and you read those files with your own file-reading tool. They are rebuilt from the element's markup rather than captured as pixels, so a font the machine lacks draws as a fallback. Worth it when a number needs checking against a picture; it is the expensive part of the call.",
+        },
+      },
+      required: ["url"],
+    },
+  },
+  {
+    name: "observeVideo",
+    description:
+      "Stills out of a video layer on the board, at moments you name. Writes a JPEG per frame into the OS temp dir and returns { frames: [{ path, at, asked, width, height }] } — read the files at `path` with your own file-reading tool to look at them. Ask for one time (`at`), several (`times`), or a sweep (`from`/`to`/`every`). Use it to answer a question about something in a reference clip: what the transition at ten seconds does, what the type looks like in the third shot.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        at: { type: "number", description: "One moment, in seconds." },
+        times: {
+          type: "array",
+          items: { type: "number" },
+          description: "Or several moments.",
+        },
+        from: { type: "number", description: "Or a sweep: from this second…" },
+        to: { type: "number", description: "…to this one." },
+        every: {
+          type: "number",
+          description: "…taking a frame every this many seconds.",
+        },
+        limit: {
+          type: "number",
+          description: "How many frames a sweep may produce. Default 24.",
+        },
+        maxWidth: {
+          type: "number",
+          description: "Longest edge of each still. Default 1280.",
+        },
+      },
+      required: ["target"],
+    },
+  },
+  {
+    name: "setAppBrief",
+    description:
+      "Hand back an app description the person asked you to improve, from the Apps directory's Create with AI page. The text replaces what is in their description box, where they can edit it or undo it before asking for the app to be built. Call it only when asked to improve an app description, and write no files for it. Returns { delivered } — false when that page is no longer open, in which case give the text in the conversation instead.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: {
+          type: "string",
+          description:
+            "The improved description, in plain prose: what the app does, what it reads and changes on the board, and what it connects to.",
+        },
+      },
+      required: ["text"],
+    },
+  },
+  {
+    name: "canvasScreenshot",
+    description: SCREENSHOT_DESCRIPTION,
+    inputSchema: {
+      type: "object",
+      properties: {
+        target: TARGET_SCHEMA,
+        width: { type: "number" },
+        height: { type: "number" },
+        scale: { type: "number", description: "Device-pixel multiplier." },
+        background: {
+          type: "string",
+          description:
+            "Painted under the design. Transparent by default, which is what a layer lifted off the board looks like.",
+        },
+      },
+    },
+  },
+] as const satisfies readonly CanvasToolDefinition[];
+
+export type CanvasToolName = (typeof CANVAS_TOOLS)[number]["name"];
+
+/** The one tool whose result carries image bytes the plugin must spill to a
+ *  file before the model can be told about it. */
+export const SCREENSHOT_TOOL: CanvasToolName = "canvasScreenshot";
+
+/** And the ones whose results carry *several*. Same reason and same spill —
+ *  bb keeps only text parts before most providers see a tool result, so a
+ *  picture the model is meant to look at has to become a path.
+ *
+ *  Unlike the screenshot, a result here is not only its pictures: an observed
+ *  scene carries the tracks and the animations, which are the answer, and the
+ *  frames ride alongside. So the spill replaces the frames *in place* and
+ *  leaves everything else standing. */
+export const FRAMES_TOOLS: readonly CanvasToolName[] = ["observeVideo", "observePage", "canvasPointer"];