agent-canvas 0.1.5 → 0.1.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Contember Limited
+
+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,71 @@
+# Agent Canvas
+
+Interactive browser-based visual canvas for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Create rich, annotatable JSX documents that render in the browser — with revision history, inline annotations, and structured feedback that flows back to Claude.
+
+![License](https://img.shields.io/npm/l/agent-canvas)
+![npm](https://img.shields.io/npm/v/agent-canvas)
+
+## What it does
+
+When Claude needs to present a plan, review, explanation, or decision — instead of dumping markdown in the terminal — it renders a full interactive canvas in your browser. You can:
+
+- **Annotate** any element with inline comments
+- **Choose options**, fill inputs, rate with sliders
+- **Browse files** referenced in the canvas
+- **Review revisions** as Claude iterates
+- **Send structured feedback** back to Claude in one click
+
+## Install
+
+```bash
+# Register the skill and hooks in Claude Code
+bunx agent-canvas install global    # for all projects
+bunx agent-canvas install local     # for current project only
+```
+
+This installs:
+- The `/canvas` skill so Claude knows how to use it
+- A `SessionStart` hook that sets up session IDs automatically
+
+**Requires [Bun](https://bun.sh/) runtime.**
+
+## Usage in Claude Code
+
+Once installed, use the `/canvas` command to create a canvas:
+
+```
+> /canvas Plan the authentication refactor
+> /canvas Show me an architecture overview
+> /canvas Review this PR
+```
+
+Claude creates a JSX document, pushes it to a local daemon, and opens it in your browser at `http://localhost:19400/s/<session-id>`.
+
+### Flow patterns
+
+Claude uses different canvas flows depending on the task:
+
+| Flow | When | Rounds |
+|------|------|--------|
+| **Feature** | Vague requests ("add auth") | Discovery → Requirements → Plan → Implementation → Summary |
+| **Plan** | Clear requirements | Plan → Implementation → Summary |
+| **Explain** | "How does X work?" | Single canvas |
+| **Review** | Code/architecture review | Findings → Fix Plan → Summary |
+| **Decision** | Choosing between options | Single canvas with comparison |
+
+## Development
+
+```bash
+bun install
+bun run build                  # build client assets
+bun daemon/build.ts --watch    # watch mode
+
+# Test with demo canvas
+bun bin/agent-canvas.ts daemon start
+CANVAS_SESSION_ID=demo bun bin/agent-canvas.ts push example/plan.jsx --label "Demo"
+# Open http://localhost:19400/s/demo
+```
+
+## License
+
+MIT

package/bin/agent-canvas.ts

@@ -1,377 +1,50 @@
 #!/usr/bin/env bun
 
-import { spawn } from "child_process";
-import { readFileSync, existsSync, writeFileSync, mkdirSync, unlinkSync, cpSync } from "fs";
-import { join, resolve, dirname } from "path";
-import { homedir, tmpdir } from "os";
-import { randomUUID } from "crypto";
-
-const PACKAGE_ROOT = resolve(join(dirname(import.meta.path), ".."));
-const DATA_DIR = join(homedir(), ".claude", "agent-canvas");
-const TEMP_DIR = join(tmpdir(), "agent-canvas");
-const DAEMON_PORT = parseInt(process.env.CANVAS_PORT || "19400", 10);
-const BASE_URL = `http://localhost:${DAEMON_PORT}`;
-const WS_URL = `ws://localhost:${DAEMON_PORT}`;
-const TIMEOUT_MS = parseInt(process.env.CANVAS_TIMEOUT || String(60 * 60 * 1000), 10);
-const PID_FILE = join(TEMP_DIR, "daemon.pid");
-
-function getSessionId(args?: string[]): string {
-  // Check --session flag first
-  if (args) {
-    const idx = args.indexOf("--session");
-    if (idx !== -1 && args[idx + 1]) {
-      return args[idx + 1];
-    }
-  }
-  return process.env.CANVAS_SESSION_ID || (() => {
-    const id = randomUUID();
-    console.error(`Warning: CANVAS_SESSION_ID not set, using generated ID: ${id}`);
-    return id;
-  })();
-}
-
-async function main() {
-  const args = process.argv.slice(2);
-
-  if (args.length === 0) {
-    printUsage();
-    process.exit(1);
-  }
-
-  const command = args[0];
-
-  switch (command) {
-    case "push": return handlePush(args.slice(1));
-    case "wait": return handleWait(args.slice(1));
-    case "install": return handleInstall(args.slice(1));
-    case "daemon": return handleDaemon(args.slice(1));
-    default:
-      console.error(`Unknown command: ${command}`);
-      printUsage();
-      process.exit(1);
-  }
-}
+import { handlePush } from "./lib/commands/push.ts";
+import { handleFetch } from "./lib/commands/fetch.ts";
+import { handleWatch } from "./lib/commands/watch.ts";
+import { handleDaemon } from "./lib/commands/daemon.ts";
+import { handleInstall } from "./lib/commands/install.ts";
 
 function printUsage() {
   console.error(`agent-canvas — Interactive visual canvas for Claude Code
 
 Commands:
-  agent-canvas install [local|global]  Install skill & hooks for Claude Code
+  agent-canvas install [local|global]  Install skill for Claude Code
   agent-canvas push <file.jsx>         Push a canvas, open browser
-  agent-canvas wait [--session <id>]   Wait for user feedback (prints to stdout)
+  agent-canvas fetch [--session <id>]  Check for feedback (returns immediately)
+  agent-canvas watch [--session <id>]  Wait for user feedback (blocks until submitted)
   agent-canvas daemon status           Show daemon status
   agent-canvas daemon stop             Stop the daemon
+  agent-canvas daemon start            Start the daemon
+  agent-canvas daemon restart          Restart the daemon
 
 Environment:
-  CANVAS_SESSION_ID     Session ID (set automatically by hooks)
-  CANVAS_PROJECT_ROOT   Project root (set automatically by hooks)
   CANVAS_PORT           Daemon port (default: 19400)`);
 }
 
-// ── install ──
-
-async function handleInstall(args: string[]) {
-  let mode = args[0] as "local" | "global" | undefined;
-
-  if (!mode) {
-    // Interactive prompt
-    process.stdout.write("Install canvas skill and hooks for Claude Code.\n\n");
-    process.stdout.write("  local  — install to .claude/ in current project\n");
-    process.stdout.write("  global — install to ~/.claude/ for all projects\n\n");
-    process.stdout.write("Choose [local/global]: ");
-
-    const input = await readLine();
-    mode = input.trim().toLowerCase() as "local" | "global";
-  }
-
-  if (mode !== "local" && mode !== "global") {
-    console.error("Error: specify 'local' or 'global'");
-    process.exit(1);
-  }
-
-  const targetBase = mode === "global"
-    ? join(homedir(), ".claude")
-    : join(process.cwd(), ".claude");
-
-  // Install skill
-  const skillTarget = join(targetBase, "skills", "canvas");
-  mkdirSync(skillTarget, { recursive: true });
-
-  const skillSrc = join(PACKAGE_ROOT, "skills", "canvas");
-  for (const file of ["SKILL.md", "components.md", "flows.md"]) {
-    const src = join(skillSrc, file);
-    if (existsSync(src)) {
-      cpSync(src, join(skillTarget, file));
-    }
-  }
-
-  console.log(`  Skill installed to ${skillTarget}`);
-
-  // Install hook script
-  const hooksDir = join(targetBase, "agent-canvas");
-  mkdirSync(hooksDir, { recursive: true });
-  const hookSrc = join(PACKAGE_ROOT, "hooks", "session-start.sh");
-  const hookDest = join(hooksDir, "session-start.sh");
-  cpSync(hookSrc, hookDest);
-  try { require("fs").chmodSync(hookDest, 0o755); } catch {}
-  console.log(`  Hook script installed to ${hookDest}`);
-
-  // Register hook in settings.json
-  const settingsPath = join(targetBase, "settings.json");
-  let settings: any = {};
-  if (existsSync(settingsPath)) {
-    try { settings = JSON.parse(readFileSync(settingsPath, "utf-8")); } catch {}
-  }
-
-  if (!settings.hooks) settings.hooks = {};
-  if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
-
-  const hasHook = settings.hooks.SessionStart.some((h: any) =>
-    h.hooks?.some((hh: any) => hh.command?.includes("CANVAS_SESSION_ID"))
-  );
-
-  if (!hasHook) {
-    settings.hooks.SessionStart.push({
-      matcher: "*",
-      hooks: [{
-        type: "command",
-        command: `bash "${hookDest}"`,
-      }],
-    });
-
-    mkdirSync(dirname(settingsPath), { recursive: true });
-    writeFileSync(settingsPath, JSON.stringify(settings, null, 2));
-    console.log(`  Hook registered in ${settingsPath}`);
-  } else {
-    console.log(`  Hook already registered in ${settingsPath}`);
-  }
-
-  console.log(`\nInstalled! The /canvas command is now available in Claude Code.`);
-}
-
-// ── push ──
-
-async function handlePush(args: string[]) {
-  const fromHook = args.includes("--from-hook");
-  let jsx: string;
-  let filePath: string | undefined;
-
-  if (fromHook) {
-    jsx = await readStdin();
-  } else {
-    filePath = args.find((a) => !a.startsWith("--"));
-    if (!filePath) {
-      console.error("Error: No file specified. Usage: agent-canvas push <file.jsx>");
-      process.exit(1);
-    }
-    filePath = resolve(filePath);
-    if (!existsSync(filePath)) {
-      console.error(`Error: File not found: ${filePath}`);
-      process.exit(1);
-    }
-    jsx = readFileSync(filePath, "utf-8");
-  }
-
-  const sessionId = getSessionId(args);
-  const projectRoot = process.env.CANVAS_PROJECT_ROOT || process.cwd();
-
-  // Extract --label flag
-  const labelIdx = args.indexOf("--label");
-  const label = labelIdx !== -1 && args[labelIdx + 1] ? args[labelIdx + 1] : undefined;
-  const autoLabel = !label && filePath ? filePath.split("/").pop()?.replace(/\.jsx$/, "") : undefined;
-
-  await ensureDaemon();
-
-  const response = await fetch(`${BASE_URL}/api/session/${sessionId}/plan`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ jsx, projectRoot, label: label || autoLabel, sourceFile: filePath ? filePath.split("/").pop() : undefined }),
-  });
-
-  const result = await response.json() as any;
-
-  if (!result.ok) {
-    console.error(`Compilation error:\n${result.error}`);
-    process.exit(1);
-  }
-
-  if (result.isNew) {
-    openBrowser(result.browserUrl);
-  }
-
-  console.log(JSON.stringify({
-    ok: true,
-    browserUrl: result.browserUrl,
-    revision: result.revision,
-    sessionId,
-  }));
-}
-
-// ── wait ──
-
-async function handleWait(args: string[]) {
-  const sessionId = getSessionId(args);
-
-  await ensureDaemon();
-
-  // Check if feedback already exists
-  try {
-    const metaRes = await fetch(`${BASE_URL}/api/session/${sessionId}/meta`);
-    const meta = await metaRes.json() as any;
-    if (meta.currentRevision && meta.revisions) {
-      const currentRev = meta.revisions.find((r: any) => r.revision === meta.currentRevision);
-      if (currentRev?.hasFeedback) {
-        const fbRes = await fetch(`${BASE_URL}/api/session/${sessionId}/revision/${meta.currentRevision}/feedback`);
-        const fbData = await fbRes.json() as any;
-        if (fbData.feedback) {
-          process.stdout.write(fbData.feedback);
-          process.exit(0);
-        }
-      }
-    }
-  } catch {}
-
-  await waitForFeedback(sessionId);
-}
-
-// ── daemon ──
-
-async function handleDaemon(args: string[]) {
-  const subcommand = args[0];
-
-  if (subcommand === "status") {
-    try {
-      const res = await fetch(`${BASE_URL}/health`, { signal: AbortSignal.timeout(2000) });
-      const data = await res.json() as any;
-      console.log(`Daemon: running on port ${DAEMON_PORT}`);
-      console.log(`Sessions: ${data.sessions.length > 0 ? data.sessions.join(", ") : "none"}`);
-    } catch {
-      console.log("Daemon: not running");
-    }
-  } else if (subcommand === "stop") {
-    if (existsSync(PID_FILE)) {
-      const pid = parseInt(readFileSync(PID_FILE, "utf-8").trim(), 10);
-      try {
-        process.kill(pid, "SIGTERM");
-        console.log("Daemon stopped.");
-      } catch {
-        console.log("Daemon was not running (stale PID file).");
-      }
-      try { unlinkSync(PID_FILE); } catch {}
-    } else {
-      console.log("No daemon PID file found.");
-    }
-  } else {
-    console.error("Usage: agent-canvas daemon [status|stop]");
-    process.exit(1);
-  }
-}
-
-// ── helpers ──
-
-async function ensureDaemon(): Promise<void> {
-  if (await isDaemonRunning()) return;
-
-  console.error("Starting canvas daemon...");
-  mkdirSync(TEMP_DIR, { recursive: true });
-
-  const daemonScript = join(PACKAGE_ROOT, "daemon", "src", "server.ts");
-
-  const child = spawn("bun", ["run", daemonScript], {
-    detached: true,
-    stdio: "ignore",
-    cwd: join(PACKAGE_ROOT, "daemon"),
-  });
-
-  child.unref();
-
-  for (let i = 0; i < 30; i++) {
-    await new Promise((r) => setTimeout(r, 100));
-    if (await isDaemonRunning()) {
-      console.error("Daemon started.");
-      return;
-    }
-  }
-
-  console.error("Error: Daemon failed to start within 3 seconds.");
-  process.exit(1);
-}
-
-async function isDaemonRunning(): Promise<boolean> {
-  try {
-    const res = await fetch(`${BASE_URL}/health`, { signal: AbortSignal.timeout(1000) });
-    const data = await res.json() as any;
-    return data.ok === true;
-  } catch {
-    return false;
-  }
-}
-
-function openBrowser(url: string) {
-  const candidates = process.platform === "darwin"
-    ? ["open"]
-    : ["xdg-open", "wslview", "sensible-browser"];
+async function main() {
+  const args = process.argv.slice(2);
 
-  for (const cmd of candidates) {
-    const which = Bun.spawnSync(["which", cmd]);
-    if (which.exitCode === 0) {
-      spawn(cmd, [url], { detached: true, stdio: "ignore" }).unref();
-      return;
-    }
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    printUsage();
+    process.exit(args.length === 0 ? 1 : 0);
   }
-  console.error(`Open this URL in your browser: ${url}`);
-}
 
-async function waitForFeedback(sessionId: string): Promise<void> {
-  return new Promise((resolveP, rejectP) => {
-    const ws = new WebSocket(`${WS_URL}/ws/wait/${sessionId}`);
-    const timeout = setTimeout(() => {
-      ws.close();
-      console.error("Error: Timeout waiting for feedback.");
-      process.exit(1);
-    }, TIMEOUT_MS);
-
-    ws.onmessage = (event) => {
-      try {
-        const data = JSON.parse(typeof event.data === "string" ? event.data : "");
-        if (data.type === "submit") {
-          clearTimeout(timeout);
-          process.stdout.write(data.feedback);
-          ws.close();
-          process.exit(0);
-        }
-      } catch {}
-    };
+  const command = args[0];
+  const rest = args.slice(1);
 
-    ws.onerror = () => {
-      clearTimeout(timeout);
-      console.error("Error: WebSocket connection failed.");
+  switch (command) {
+    case "push": return handlePush(rest);
+    case "fetch": return handleFetch(rest);
+    case "watch": return handleWatch(rest);
+    case "install": return handleInstall(rest);
+    case "daemon": return handleDaemon(rest);
+    default:
+      console.error(`Unknown command: ${command}`);
+      printUsage();
       process.exit(1);
-    };
-
-    ws.onclose = () => {
-      clearTimeout(timeout);
-    };
-  });
-}
-
-async function readStdin(): Promise<string> {
-  const chunks: Buffer[] = [];
-  for await (const chunk of Bun.stdin.stream()) {
-    chunks.push(Buffer.from(chunk));
-  }
-  return Buffer.concat(chunks).toString("utf-8");
-}
-
-async function readLine(): Promise<string> {
-  const buf: number[] = [];
-  for await (const chunk of Bun.stdin.stream()) {
-    for (const byte of chunk) {
-      if (byte === 10) return Buffer.from(buf).toString("utf-8");
-      buf.push(byte);
-    }
   }
-  return Buffer.from(buf).toString("utf-8");
 }
 
 main().catch((e) => {

package/bin/lib/commands/daemon.ts

@@ -0,0 +1,51 @@
+import { parseArgs } from "util";
+import { DAEMON_PORT, BASE_URL } from "../config.ts";
+import { isDaemonRunning, startDaemon, stopDaemon } from "../daemon-lifecycle.ts";
+
+export async function handleDaemon(args: string[]) {
+  const { positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+  });
+
+  const subcommand = positionals[0];
+
+  switch (subcommand) {
+    case "status": {
+      try {
+        const res = await fetch(`${BASE_URL}/health`, { signal: AbortSignal.timeout(2000) });
+        const data = await res.json() as any;
+        console.log(`Daemon: running on port ${DAEMON_PORT}`);
+        console.log(`Sessions: ${data.sessions.length > 0 ? data.sessions.join(", ") : "none"}`);
+      } catch {
+        console.log("Daemon: not running");
+      }
+      break;
+    }
+    case "stop": {
+      stopDaemon();
+      break;
+    }
+    case "start": {
+      if (await isDaemonRunning()) {
+        console.log("Daemon is already running.");
+        return;
+      }
+      await startDaemon();
+      break;
+    }
+    case "restart": {
+      stopDaemon();
+      for (let i = 0; i < 10; i++) {
+        if (!(await isDaemonRunning())) break;
+        await new Promise((r) => setTimeout(r, 100));
+      }
+      await startDaemon();
+      break;
+    }
+    default: {
+      console.error("Usage: agent-canvas daemon [status|stop|start|restart]");
+      process.exit(1);
+    }
+  }
+}

package/bin/lib/commands/fetch.ts

@@ -0,0 +1,20 @@
+import { parseArgs } from "util";
+import { ensureDaemon } from "../daemon-lifecycle.ts";
+import { getSessionId, consumeFeedback } from "../helpers.ts";
+
+export async function handleFetch(args: string[]) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      session: { type: "string" },
+    },
+  });
+
+  const sessionId = getSessionId(values.session);
+  await ensureDaemon();
+
+  const feedback = await consumeFeedback(sessionId);
+  if (feedback) {
+    process.stdout.write(feedback);
+  }
+}

package/bin/lib/commands/install.ts

@@ -0,0 +1,48 @@
+import { parseArgs } from "util";
+import { existsSync, mkdirSync, cpSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { PACKAGE_ROOT } from "../config.ts";
+import { readLine } from "../helpers.ts";
+
+export async function handleInstall(args: string[]) {
+  const { positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+  });
+
+  let mode = positionals[0] as "local" | "global" | undefined;
+
+  if (!mode) {
+    process.stdout.write("Install canvas skill for Claude Code.\n\n");
+    process.stdout.write("  local  — install to .claude/ in current project\n");
+    process.stdout.write("  global — install to ~/.claude/ for all projects\n\n");
+    process.stdout.write("Choose [local/global]: ");
+
+    const input = await readLine();
+    mode = input.trim().toLowerCase() as "local" | "global";
+  }
+
+  if (mode !== "local" && mode !== "global") {
+    console.error("Error: specify 'local' or 'global'");
+    process.exit(1);
+  }
+
+  const targetBase = mode === "global"
+    ? join(homedir(), ".claude")
+    : join(process.cwd(), ".claude");
+
+  const skillTarget = join(targetBase, "skills", "canvas");
+  mkdirSync(skillTarget, { recursive: true });
+
+  const skillSrc = join(PACKAGE_ROOT, "skills", "canvas");
+  for (const file of ["SKILL.md", "components.md", "flows.md"]) {
+    const src = join(skillSrc, file);
+    if (existsSync(src)) {
+      cpSync(src, join(skillTarget, file));
+    }
+  }
+
+  console.log(`  Skill installed to ${skillTarget}`);
+  console.log(`\nInstalled! The /canvas command is now available in Claude Code.`);
+}

package/bin/lib/commands/push.ts

@@ -0,0 +1,66 @@
+import { parseArgs } from "util";
+import { readFileSync, existsSync } from "fs";
+import { resolve } from "path";
+import { BASE_URL } from "../config.ts";
+import { ensureDaemon } from "../daemon-lifecycle.ts";
+import { getSessionId, openBrowser } from "../helpers.ts";
+
+export async function handlePush(args: string[]) {
+  const { values, positionals } = parseArgs({
+    args,
+    options: {
+      session: { type: "string" },
+      label: { type: "string" },
+    },
+    allowPositionals: true,
+  });
+
+  const filePath = positionals[0];
+  if (!filePath) {
+    console.error("Error: No file specified. Usage: agent-canvas push <file.jsx>");
+    process.exit(1);
+  }
+
+  const resolvedPath = resolve(filePath);
+  if (!existsSync(resolvedPath)) {
+    console.error(`Error: File not found: ${resolvedPath}`);
+    process.exit(1);
+  }
+  const jsx = readFileSync(resolvedPath, "utf-8");
+
+  const sessionId = getSessionId(values.session);
+  const projectRoot = process.env.CANVAS_PROJECT_ROOT || process.cwd();
+  const label = values.label;
+  const autoLabel = !label ? resolvedPath.split("/").pop()?.replace(/\.jsx$/, "") : undefined;
+
+  await ensureDaemon();
+
+  const response = await fetch(`${BASE_URL}/api/session/${sessionId}/plan`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ jsx, projectRoot, label: label || autoLabel, sourceFile: resolvedPath.split("/").pop() }),
+  });
+
+  const result = await response.json() as any;
+
+  if (!result.ok) {
+    if (result.unconsumedFeedback) {
+      console.error(`Error: ${result.error}`);
+      console.log(result.unconsumedFeedback);
+    } else {
+      console.error(`Compilation error:\n${result.error}`);
+    }
+    process.exit(1);
+  }
+
+  if (result.isNew) {
+    openBrowser(result.browserUrl);
+  }
+
+  console.log(JSON.stringify({
+    ok: true,
+    browserUrl: result.browserUrl,
+    revision: result.revision,
+    sessionId,
+  }));
+}