excalidrop 0.1.1

package/skills/excalidraw-skill/references/cheatsheet.md

@@ -0,0 +1,142 @@
+# Excalidraw Skill Cheatsheet
+
+## Defaults
+
+- Canvas base URL: `EXPRESS_SERVER_URL` (default `http://127.0.0.1:3000`)
+- Canvas health: `GET /health`
+
+## MCP Tools (26 total)
+
+### Element CRUD
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `create_element` | Create shape/text/arrow/line | `type`, `x`, `y` |
+| `get_element` | Get single element by ID | `id` |
+| `update_element` | Update element properties | `id` |
+| `delete_element` | Delete element | `id` |
+| `query_elements` | Query by type/filters | (optional) `type`, `filter` |
+| `batch_create_elements` | Create many at once | `elements[]` |
+| `duplicate_elements` | Clone with offset | `elementIds[]`, (optional) `offsetX`, `offsetY` |
+
+### Layout & Organization
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `align_elements` | Align to left/center/right/top/middle/bottom | `elementIds[]`, `alignment` |
+| `distribute_elements` | Even spacing horizontal/vertical | `elementIds[]`, `direction` |
+| `group_elements` | Group elements | `elementIds[]` |
+| `ungroup_elements` | Ungroup | `groupId` |
+| `lock_elements` | Lock elements | `elementIds[]` |
+| `unlock_elements` | Unlock elements | `elementIds[]` |
+
+### Scene Awareness (Iterative Refinement)
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `describe_scene` | AI-readable scene description (types, positions, labels, connections, bounding box) | (none) |
+| `get_canvas_screenshot` | Returns PNG image of canvas for visual verification | (optional) `background` |
+| `get_resource` | Get scene/library/theme/elements | `resource` |
+
+### File I/O & Export
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `export_scene` | Export to .excalidraw JSON | (optional) `filePath` |
+| `import_scene` | Import from .excalidraw JSON | `mode` ("replace"\|"merge"), `filePath` or `data` |
+| `export_to_image` | Export to PNG/SVG (needs browser) | `format` ("png"\|"svg"), (optional) `filePath`, `background` |
+| `export_to_excalidraw_url` | Upload & get shareable excalidraw.com URL | (none) |
+
+### State Management
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `clear_canvas` | Remove all elements | (none) |
+| `snapshot_scene` | Save named snapshot | `name` |
+| `restore_snapshot` | Restore from snapshot | `name` |
+
+### Viewport & Camera
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `set_viewport` | Control camera: zoom-to-fit, center on element, manual zoom/scroll (needs browser) | (optional) `scrollToContent`, `scrollToElementId`, `zoom`, `offsetX`, `offsetY` |
+
+### Design Guide
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `read_diagram_guide` | Get design best practices (colors, sizing, layout, anti-patterns) | (none) |
+
+### Conversion
+
+| Tool | Description | Required params |
+|------|-------------|-----------------|
+| `create_from_mermaid` | Mermaid diagram to Excalidraw | `mermaidDiagram` |
+
+Notes:
+- **MCP tools**: Set `text` field on shapes to label them (auto-converts to `label.text`). Use `startElementId`/`endElementId` on arrows.
+- **REST API**: Use `"label": {"text": "..."}` for shape labels. Use `"start": {"id": "..."}` / `"end": {"id": "..."}` for arrow binding. (Different format from MCP!)
+- `fontFamily` must be a string (e.g. `"1"`) or omit it entirely — do NOT pass a number.
+- `points` accepts both `[[x,y]]` tuples and `[{x,y}]` objects.
+- **Curved arrows**: Use `"roundness": {"type": 2}` with 3+ points for smooth curves. Use `"elbowed": true` for right-angle routing.
+- Prefer creating shapes first, then arrows, then alignment/grouping.
+
+## Canvas REST API (HTTP)
+
+### Elements
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/elements` | List all elements |
+| `GET` | `/api/elements/:id` | Get element by ID |
+| `POST` | `/api/elements` | Create element |
+| `PUT` | `/api/elements/:id` | Update element |
+| `DELETE` | `/api/elements/:id` | Delete element |
+| `DELETE` | `/api/elements/clear` | Clear all elements |
+| `GET` | `/api/elements/search?type=...` | Search with filters |
+| `POST` | `/api/elements/batch` | Batch create |
+| `POST` | `/api/elements/sync` | Overwrite import (clear + write) |
+| `POST` | `/api/elements/from-mermaid` | Mermaid conversion via frontend |
+
+### Export
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/export/image` | Request image export (needs frontend) |
+| `POST` | `/api/export/image/result` | Frontend posts export result back |
+
+### Viewport
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/viewport` | Set viewport/camera (needs frontend) |
+| `POST` | `/api/viewport/result` | Frontend posts viewport result back |
+
+### Snapshots
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/snapshots` | Save snapshot `{name}` |
+| `GET` | `/api/snapshots` | List snapshots |
+| `GET` | `/api/snapshots/:name` | Get snapshot by name |
+
+### System
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/health` | Health check |
+| `GET` | `/api/sync/status` | Memory/WebSocket stats |
+
+## Skill Scripts
+
+All scripts accept `--url <canvasUrl>` (defaults to `EXPRESS_SERVER_URL`).
+
+```bash
+node scripts/healthcheck.cjs
+node scripts/clear-canvas.cjs
+node scripts/export-elements.cjs --out diagram.elements.json
+node scripts/import-elements.cjs --in diagram.elements.json --mode batch|sync
+node scripts/create-element.cjs --data '{...}'
+node scripts/update-element.cjs --id <id> --data '{...}'
+node scripts/delete-element.cjs --id <id>
+```

package/skills/excalidraw-skill/scripts/clear-canvas.cjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const DEFAULT_URL = process.env.EXPRESS_SERVER_URL || "http://127.0.0.1:3000";
+
+function parseArgs(argv) {
+  const out = { url: DEFAULT_URL };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+  }
+  return out;
+}
+
+async function main() {
+  if (typeof fetch !== "function") {
+    throw new Error("This script requires Node 18+ (global fetch).");
+  }
+
+  const { url } = parseArgs(process.argv.slice(2));
+  const baseUrl = url.replace(/\/$/, "");
+
+  const res = await fetch(`${baseUrl}/api/elements/clear`, {
+    method: "DELETE",
+  });
+
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json || json.success !== true) {
+    throw new Error(`Failed to clear canvas: ${res.status} ${res.statusText} ${json?.error ? `- ${json.error}` : ""}`);
+  }
+
+  console.log(`Cleared canvas (${json.count} elements removed)`);
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

package/skills/excalidraw-skill/scripts/create-element.cjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require("node:fs");
+
+const DEFAULT_URL = process.env.EXPRESS_SERVER_URL || "http://127.0.0.1:3000";
+
+function usage() {
+  console.error(
+    [
+      "Usage:",
+      "  node scripts/create-element.cjs (--data <json> | --file <path>) [--url <canvasUrl>]",
+      "",
+      "Examples:",
+      '  node scripts/create-element.cjs --data \'{"type":"rectangle","x":100,"y":100,"width":300,"height":200}\'',
+      "  node scripts/create-element.cjs --file element.json",
+    ].join("\n"),
+  );
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const out = { url: DEFAULT_URL, data: null, file: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+    else if (a === "--data") out.data = argv[++i];
+    else if (a === "--file") out.file = argv[++i];
+  }
+  return out;
+}
+
+function readJson({ data, file }) {
+  if (data) return JSON.parse(data);
+  if (file) return JSON.parse(fs.readFileSync(file, "utf8"));
+  usage();
+}
+
+async function main() {
+  if (typeof fetch !== "function") {
+    throw new Error("This script requires Node 18+ (global fetch).");
+  }
+
+  const args = parseArgs(process.argv.slice(2));
+  const payload = readJson(args);
+
+  const baseUrl = args.url.replace(/\/$/, "");
+  const res = await fetch(`${baseUrl}/api/elements`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json || json.success !== true) {
+    throw new Error(
+      `Failed to create element: ${res.status} ${res.statusText} ${json?.error ? `- ${json.error}` : ""}`,
+    );
+  }
+
+  process.stdout.write(JSON.stringify(json.element, null, 2) + "\n");
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});
+

package/skills/excalidraw-skill/scripts/delete-element.cjs

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const DEFAULT_URL = process.env.EXPRESS_SERVER_URL || "http://127.0.0.1:3000";
+
+function usage() {
+  console.error("Usage: node scripts/delete-element.cjs --id <id> [--url <canvasUrl>]");
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const out = { url: DEFAULT_URL, id: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+    else if (a === "--id") out.id = argv[++i];
+  }
+  return out;
+}
+
+async function main() {
+  if (typeof fetch !== "function") {
+    throw new Error("This script requires Node 18+ (global fetch).");
+  }
+
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.id) usage();
+
+  const baseUrl = args.url.replace(/\/$/, "");
+  const res = await fetch(`${baseUrl}/api/elements/${encodeURIComponent(args.id)}`, {
+    method: "DELETE",
+  });
+
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json || json.success !== true) {
+    throw new Error(
+      `Failed to delete element: ${res.status} ${res.statusText} ${json?.error ? `- ${json.error}` : ""}`,
+    );
+  }
+
+  console.log(`Deleted ${args.id}`);
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});
+

package/skills/excalidraw-skill/scripts/export-elements.cjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const DEFAULT_URL = process.env.EXPRESS_SERVER_URL || "http://127.0.0.1:3000";
+
+function parseArgs(argv) {
+  const out = { url: DEFAULT_URL, outFile: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+    else if (a === "--out") out.outFile = argv[++i];
+    else if (a === "-o") out.outFile = argv[++i];
+  }
+  return out;
+}
+
+async function main() {
+  if (typeof fetch !== "function") {
+    throw new Error("This script requires Node 18+ (global fetch).");
+  }
+
+  const { url, outFile } = parseArgs(process.argv.slice(2));
+  const res = await fetch(`${url.replace(/\/$/, "")}/api/elements`);
+  const json = await res.json();
+
+  if (!res.ok || !json || json.success !== true) {
+    throw new Error(`Failed to export elements: ${res.status} ${res.statusText}`);
+  }
+
+  const payload = {
+    exportedAt: new Date().toISOString(),
+    expressServerUrl: url,
+    elements: json.elements || [],
+  };
+
+  const text = JSON.stringify(payload, null, 2);
+  if (!outFile) {
+    process.stdout.write(text + "\n");
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  fs.writeFileSync(outFile, text + "\n");
+  console.log(`Wrote ${payload.elements.length} elements to ${outFile}`);
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

package/skills/excalidraw-skill/scripts/healthcheck.cjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const DEFAULT_URL = process.env.EXPRESS_SERVER_URL || "http://127.0.0.1:3000";
+
+function parseArgs(argv) {
+  const out = { url: DEFAULT_URL };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+  }
+  return out;
+}
+
+async function main() {
+  if (typeof fetch !== "function") {
+    throw new Error("This script requires Node 18+ (global fetch).");
+  }
+
+  const { url } = parseArgs(process.argv.slice(2));
+  const res = await fetch(`${url.replace(/\/$/, "")}/health`);
+  const text = await res.text();
+
+  if (!res.ok) {
+    console.error(text);
+    process.exit(1);
+  }
+
+  console.log(text);
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

package/skills/excalidraw-skill/scripts/import-elements.cjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require("node:fs");
+
+const DEFAULT_URL = process.env.EXPRESS_SERVER_URL || "http://127.0.0.1:3000";
+
+function usage() {
+  console.error(
+    [
+      "Usage:",
+      "  node scripts/import-elements.cjs --in <file> [--mode batch|sync] [--url <canvasUrl>]",
+      "",
+      "Modes:",
+      "  batch  POST /api/elements/batch    (append; creates elements)",
+      "  sync   POST /api/elements/sync     (overwrite; clears then writes)",
+    ].join("\n"),
+  );
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const out = { url: DEFAULT_URL, inFile: null, mode: "batch" };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+    else if (a === "--in") out.inFile = argv[++i];
+    else if (a === "--mode") out.mode = argv[++i];
+  }
+  return out;
+}
+
+function readElementsFromFile(inFile) {
+  const raw = fs.readFileSync(inFile, "utf8");
+  const data = JSON.parse(raw);
+  if (Array.isArray(data)) return data;
+  if (data && Array.isArray(data.elements)) return data.elements;
+  throw new Error('Input file must be an array, or an object with an "elements" array');
+}
+
+async function main() {
+  if (typeof fetch !== "function") {
+    throw new Error("This script requires Node 18+ (global fetch).");
+  }
+
+  const { url, inFile, mode } = parseArgs(process.argv.slice(2));
+  if (!inFile) usage();
+  if (mode !== "batch" && mode !== "sync") usage();
+
+  const elements = readElementsFromFile(inFile);
+  const baseUrl = url.replace(/\/$/, "");
+
+  let endpoint;
+  let body;
+  if (mode === "batch") {
+    endpoint = `${baseUrl}/api/elements/batch`;
+    body = { elements };
+  } else {
+    endpoint = `${baseUrl}/api/elements/sync`;
+    body = { elements, timestamp: new Date().toISOString() };
+  }
+
+  const res = await fetch(endpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json || json.success !== true) {
+    throw new Error(`Failed to import elements: ${res.status} ${res.statusText} ${json?.error ? `- ${json.error}` : ""}`);
+  }
+
+  const count = json.count ?? json.elements?.length ?? elements.length;
+  console.log(`Imported ${count} elements (${mode})`);
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});

package/skills/excalidraw-skill/scripts/update-element.cjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+const fs = require("node:fs");
+
+const DEFAULT_URL = process.env.EXPRESS_SERVER_URL || "http://127.0.0.1:3000";
+
+function usage() {
+  console.error(
+    [
+      "Usage:",
+      "  node scripts/update-element.cjs --id <id> (--data <json> | --file <path>) [--url <canvasUrl>]",
+      "",
+      "Examples:",
+      '  node scripts/update-element.cjs --id abc --data \'{"x":200,"y":250,"backgroundColor":"#ffeeee"}\'',
+      "  node scripts/update-element.cjs --id abc --file updates.json",
+    ].join("\n"),
+  );
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const out = { url: DEFAULT_URL, id: null, data: null, file: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[++i];
+    else if (a === "--id") out.id = argv[++i];
+    else if (a === "--data") out.data = argv[++i];
+    else if (a === "--file") out.file = argv[++i];
+  }
+  return out;
+}
+
+function readJson({ data, file }) {
+  if (data) return JSON.parse(data);
+  if (file) return JSON.parse(fs.readFileSync(file, "utf8"));
+  usage();
+}
+
+async function main() {
+  if (typeof fetch !== "function") {
+    throw new Error("This script requires Node 18+ (global fetch).");
+  }
+
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.id) usage();
+  const payload = readJson(args);
+
+  const baseUrl = args.url.replace(/\/$/, "");
+  const res = await fetch(`${baseUrl}/api/elements/${encodeURIComponent(args.id)}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload),
+  });
+
+  const json = await res.json().catch(() => null);
+  if (!res.ok || !json || json.success !== true) {
+    throw new Error(
+      `Failed to update element: ${res.status} ${res.statusText} ${json?.error ? `- ${json.error}` : ""}`,
+    );
+  }
+
+  process.stdout.write(JSON.stringify(json.element, null, 2) + "\n");
+}
+
+main().catch((err) => {
+  console.error(err?.stack || String(err));
+  process.exit(1);
+});
+