@agent-workshop/adoc-plugin-sketch 0.1.0

package/dist/index.js

@@ -0,0 +1,41 @@
+import { definePlugin, html } from "@agent-workshop/adoc-plugin-kit";
+function parse(doc) {
+  if (!doc.text.trim()) return { type: "excalidraw", elements: [] };
+  const scene = JSON.parse(doc.text);
+  if (scene.type !== "excalidraw") throw new Error('not an Excalidraw file: "type" must be "excalidraw"');
+  return scene;
+}
+function board(doc) {
+  return html`<adoc-sketch data-adoc-document="${doc.key}" data-adoc-file="${doc.file}"></adoc-sketch>`;
+}
+var index_default = definePlugin({
+  description: "A drawing, such as a UI wireframe, that the user draws in Excalidraw; saved as Excalidraw JSON with a PNG beside it.",
+  layout: { kind: "file", extension: ".excalidraw", companions: [".png"] },
+  summarize(doc) {
+    const shapes = (parse(doc).elements ?? []).filter((e) => !e.isDeleted);
+    const texts = shapes.filter((e) => e.type === "text" && e.text?.trim()).sort((a, b) => (a.y ?? 0) - (b.y ?? 0));
+    return { title: texts[0]?.text?.split("\n")[0]?.trim() || doc.localId, status: `${shapes.length} shapes`, fields: { texts: texts.length } };
+  },
+  // The board loads the file itself, so this output stays the same across versions and the page keeps the board.
+  render(doc) {
+    parse(doc);
+    return board(doc);
+  },
+  // A line diff of the JSON says little; the change view shows the current drawing with a note.
+  renderChanges(doc) {
+    parse(doc);
+    return html`<p class="adoc-muted">The drawing changed since you looked; the board shows the current one.</p>${board(doc)}`;
+  },
+  actions: {
+    /** Sent by the board: the new Excalidraw JSON and the PNG export (base64). */
+    save(_doc, event) {
+      const { scene, png } = JSON.parse(event.value);
+      if (typeof scene !== "string" || typeof png !== "string") throw new Error("save needs { scene, png }");
+      if (JSON.parse(scene).type !== "excalidraw") throw new Error("save: the scene is not an Excalidraw file");
+      return { text: scene, companions: { ".png": { base64: png } } };
+    }
+  }
+});
+export {
+  index_default as default
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agent-workshop/adoc-plugin-sketch",
+  "version": "0.1.0",
+  "license": "0BSD",
+  "type": "module",
+  "description": "The SKETCH plugin of adoc: Excalidraw drawings that the user makes and the agent reads.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dirty49374/adoc.git",
+    "directory": "plugins/sketch"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "client",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@excalidraw/excalidraw": "0.18.1",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.2",
+    "esbuild": "0.28.2",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "@agent-workshop/adoc-plugin-kit": "0.1.0"
+  },
+  "peerDependencies": {
+    "@agent-workshop/adoc-plugin-kit": "^0.1.0"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "check": "tsc -p web"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: adoc-sketch
+description: "SKETCH documents: drawings, such as UI wireframes, that the user draws in Excalidraw, saved as JSON with a PNG beside it. Use when a message carries a comment that a sketch changed, when the user wants to draw something, or when a drawing must be read or tidied."
+---
+
+# SKETCH documents
+
+Document keys look like `SKETCH-<local id>`. Read the general workflow with `adoc skill view adoc`.
+
+## Purpose
+
+A SKETCH is a drawing the user makes in the web UI, usually a UI wireframe or a diagram that is easier to draw than to describe. It shows the agent what the user means, so that the agent can turn it into a NOTE, a spec or code.
+
+## States and workflow
+
+- A sketch has no states. The user draws, and the board saves about a second after they stop.
+- A save sends no message; it puts one draft comment on the sketch into the composer: `The sketch SKETCH-<local id> changed: <png path> (image) and <json path> (Excalidraw JSON).` It reaches you as an attached comment of the next message the user sends. Then read the sketch and do what the message asks.
+- You may offer the user an empty board when a drawing would help the conversation.
+
+## Instructions
+
+- Read **both** files of a changed sketch: look at the PNG to see the layout, and read the JSON for the exact texts, the shapes and how they connect. If you cannot view images, work from the JSON and say so.
+- Describe back in one or two sentences what you understood from the drawing before you act on it, when it is not obvious.
+- You may edit the JSON, for example to tidy a wireframe or add labels. Edit it only when the user is not drawing, and tell them first: the open board replaces its elements with yours, and strokes not yet saved are lost. Read it just before you edit it. The board does not fill in missing fields, so write every new element in full: copy an element of the same type, or use the example below, and give it a new unique `id`, `seed` and `versionNonce` (random integers) and `version: 1`.
+- Never write the PNG yourself: the web UI writes it on the user's next save, so after your own edit it shows the older drawing until then. Commit as usual and tell the user.
+- Ask the user in your conversation: the board shows no text you add to the file.
+- To give the user an empty board, create `SKETCH-<local id>.excalidraw` with the empty board below and open it for them with `adoc ui open SKETCH-<local id>`.
+
+## File
+
+- `SKETCH-<local id>.excalidraw`: the drawing as Excalidraw JSON (`"type": "excalidraw"`, `elements`, `appState`, `files`). Every shape is an element with `type` (`rectangle`, `ellipse`, `arrow`, `line`, `text`, …), position `x`, `y`, size `width`, `height`, and for text `text`. Arrows may bind to shapes (`startBinding`, `endBinding`).
+- `SKETCH-<local id>.png`: the same drawing as an image, a companion file written by the web UI on every save. A new board has none until the user's first save.
+- An empty board:
+
+```json
+{ "type": "excalidraw", "version": 2, "source": "adoc", "elements": [], "appState": {}, "files": {} }
+```
+
+- A box with a label: a `rectangle` and a `text` bound to it through `boundElements` and `containerId`:
+
+```json
+{ "id": "box1", "type": "rectangle", "x": 100, "y": 100, "width": 200, "height": 80, "angle": 0,
+  "strokeColor": "#1e1e1e", "backgroundColor": "transparent", "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid",
+  "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null, "roundness": null, "seed": 1468, "version": 1,
+  "versionNonce": 9134, "isDeleted": false, "boundElements": [{ "type": "text", "id": "box1-label" }], "updated": 1, "link": null, "locked": false },
+{ "id": "box1-label", "type": "text", "x": 150, "y": 128, "width": 100, "height": 25, "angle": 0,
+  "strokeColor": "#1e1e1e", "backgroundColor": "transparent", "fillStyle": "solid", "strokeWidth": 2, "strokeStyle": "solid",
+  "roughness": 1, "opacity": 100, "groupIds": [], "frameId": null, "roundness": null, "seed": 2201, "version": 1,
+  "versionNonce": 5521, "isDeleted": false, "boundElements": null, "updated": 1, "link": null, "locked": false,
+  "text": "Login", "originalText": "Login", "fontSize": 20, "fontFamily": 5, "textAlign": "center", "verticalAlign": "middle",
+  "containerId": "box1", "autoResize": true, "lineHeight": 1.25 }
+```
+
+- Recommended local id: today's date (yymmdd) and a title, such as `SKETCH-261002-login-screen`.
+
+## Anchors
+
+None: comment on the whole document.
+
+## Actions
+
+| action | what adoc already did | what you do |
+|---|---|---|
+| `save` | wrote the JSON and the PNG; sends no message | nothing; the change reaches you as the draft comment, attached to the user's next message |