agent-canvas 0.2.0 → 0.6.0

package/README.md

@@ -5,7 +5,7 @@ Interactive browser-based visual canvas for [Claude Code](https://docs.anthropic
 ![License](https://img.shields.io/npm/l/agent-canvas)
 ![npm](https://img.shields.io/npm/v/agent-canvas)
 
-![Agent Canvas](.github/light.png)
+![Agent Canvas](docs/light.png)
 
 ## What it does
 
@@ -27,6 +27,7 @@ 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
 
@@ -48,14 +49,14 @@ Claude creates a JSX document, pushes it to a local daemon, and opens it in your
 
 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 |
-| **Runbook** | User must complete manual setup or provide a secret | Instructions → secure handoff → command → result |
+| 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                              |
+| **Runbook**  | User must complete manual setup or provide a secret | Instructions → secure handoff → command → result           |
 
 ### Local secret handoff
 
@@ -72,27 +73,51 @@ bunx agent-canvas exec \
 
 Secret resolution requires a daemon capability available to the CLI but not to canvas JavaScript. A new canvas revision, daemon shutdown, or session cleanup clears the value. The target command must not print its environment or credentials.
 
+### Review mode
+
+Review mode puts the same comment loop on a running web application: a prototype, a mock or any dev server. Open the
+application through the daemon's review proxy:
+
+```bash
+bunx agent-canvas review open http://localhost:5173/ --project my-app
+```
+
+The daemon serves the application on a port of its own with the widget added to every HTML page (hot reload passes
+through) and opens it in the browser. To keep the application's own address, add the widget's tag to its page in
+development instead: `bunx agent-canvas review snippet --project my-app`.
+
+The widget mounts a toolbar in its own shadow root. The reviewer clicks **Comment**, picks an element or selects text,
+and saves the comment as a note or sends it to the agent. The agent waits with `bunx agent-canvas review watch` (`--follow` keeps waiting),
+receives each thread with its page URL, the element's role and accessible name, a CSS path, the React components that
+own it with their source positions (resolved through the dev server's source maps), the trimmed markup and, when the
+reviewer attaches one, a screenshot of the tab, changes the code and answers with `bunx agent-canvas review reply <thread> "<text>" --resolve`. The answer and
+the thread's state show up next to the element.
+
+Threads are stored per project under the daemon's data directory. The daemon accepts widget requests only from loopback
+origins (`localhost`, `127.0.0.1`, `*.localhost`) and agent requests only from clients that send no `Origin`, so a web
+page cannot queue work for the agent.
+
 ## Theming
 
 Agent Canvas supports light and dark themes, automatically matching your system preference.
 
 **Dark mode**
 
-![](.github/dark.png)
+![](docs/dark.png)
 
 ## Development
 
 ### Reusable packages
 
-| Package | Use without the Agent Canvas shell |
-| --- | --- |
-| [`@fabrika/daemon-kit`](https://github.com/contember/fabrika-platform/tree/main/packages/daemon-kit) | Bun daemon lifecycle, HTTP routing, WebSocket channels and CLI waiters |
-| [`@fabrika/annotations`](https://github.com/contember/fabrika-platform/tree/main/packages/annotations) | Annotation state, editors and text/block/region locators |
-| [`@fabrika/canvas-kernel`](https://github.com/contember/fabrika-platform/tree/main/packages/canvas-kernel) | JSX compiler, revisions, renderer and interactive canvas components |
+| Package                                                                                                    | Use without the Agent Canvas shell                                     |
+| ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| [`@fabrika/daemon-kit`](https://github.com/contember/fabrika-platform/tree/main/packages/daemon-kit)       | Bun daemon lifecycle, HTTP routing, WebSocket channels and CLI waiters |
+| [`@fabrika/annotations`](https://github.com/contember/fabrika-platform/tree/main/packages/annotations)     | Annotation state, editors and text/block/region locators               |
+| [`@fabrika/canvas-kernel`](https://github.com/contember/fabrika-platform/tree/main/packages/canvas-kernel) | JSX compiler, revisions, renderer and interactive canvas components    |
 
 The kernel depends on the other two; neither depends on the kernel. All ship as
-TypeScript sources from the [`fabrika-platform`](https://github.com/contember/fabrika-platform)
-repository. See the kernel README for the breaking 0.2 import migration.
+TypeScript sources and are released together with `agent-canvas` from the
+[`fabrika-platform`](https://github.com/contember/fabrika-platform) repository.
 
 ### Local commands
 

package/bin/agent-canvas.js

@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 
-const { execFileSync } = require("child_process");
-const { join } = require("path");
+const { execFileSync } = require('child_process')
+const { join } = require('path')
 
-const script = join(__dirname, "agent-canvas.ts");
+const script = join(__dirname, 'agent-canvas.ts')
 
 try {
-  execFileSync("bun", [script, ...process.argv.slice(2)], { stdio: "inherit" });
+	execFileSync('bun', [script, ...process.argv.slice(2)], { stdio: 'inherit' })
 } catch (e) {
-  if (e.status != null) process.exit(e.status);
-  console.error("Failed to run agent-canvas. Is Bun installed? https://bun.sh");
-  process.exit(1);
+	if (e.status != null) process.exit(e.status)
+	console.error('Failed to run agent-canvas. Is Bun installed? https://bun.sh')
+	process.exit(1)
 }

package/bin/agent-canvas.ts

@@ -1,16 +1,17 @@
 #!/usr/bin/env bun
 
-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";
-import { handleInstructions } from "./lib/commands/instructions.ts";
-import { handleExec } from "./lib/commands/exec.ts";
-import { VERSION } from "./lib/config.ts";
+import { handleDaemon } from './lib/commands/daemon.ts'
+import { handleExec } from './lib/commands/exec.ts'
+import { handleFetch } from './lib/commands/fetch.ts'
+import { handleInstall } from './lib/commands/install.ts'
+import { handleInstructions } from './lib/commands/instructions.ts'
+import { handlePush } from './lib/commands/push.ts'
+import { handleReview } from './lib/commands/review.ts'
+import { handleWatch } from './lib/commands/watch.ts'
+import { VERSION } from './lib/config.ts'
 
 function printUsage() {
-  console.log(`agent-canvas v${VERSION} — Interactive visual canvas for Claude Code
+	console.log(`agent-canvas v${VERSION} — Interactive visual canvas for Claude Code
 
 Commands:
   agent-canvas install [local|global]  Install skill for Claude Code
@@ -18,6 +19,7 @@ Commands:
   agent-canvas push <directory>        Push canvases, open browser
   agent-canvas fetch [--session <id>]  Check for feedback (returns immediately)
   agent-canvas watch [--session <id>]  Wait for user feedback (blocks until submitted)
+  agent-canvas review <command>        Comment on a running application (see: agent-canvas review --help)
   agent-canvas exec --secret ENV=id -- <command>
                                       Run a command with an in-memory secret
   agent-canvas daemon status           Show daemon status
@@ -26,41 +28,50 @@ Commands:
   agent-canvas daemon restart          Restart the daemon
 
 Environment:
-  CANVAS_PORT           Daemon port (default: 19400)`);
+  CANVAS_PORT           Daemon port (default: 19400)`)
 }
 
 async function main() {
-  const args = process.argv.slice(2);
+	const args = process.argv.slice(2)
 
-  if (args[0] === "--version" || args[0] === "-v") {
-    console.log(VERSION);
-    return;
-  }
+	if (args[0] === '--version' || args[0] === '-v') {
+		console.log(VERSION)
+		return
+	}
 
-  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
-    printUsage();
-    process.exit(args.length === 0 ? 1 : 0);
-  }
+	if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+		printUsage()
+		process.exit(args.length === 0 ? 1 : 0)
+	}
 
-  const command = args[0];
-  const rest = args.slice(1);
+	const command = args[0]
+	const rest = args.slice(1)
 
-  switch (command) {
-    case "push": return handlePush(rest);
-    case "fetch": return handleFetch(rest);
-    case "watch": return handleWatch(rest);
-    case "exec": return handleExec(rest);
-    case "instructions": return handleInstructions(rest);
-    case "install": return handleInstall(rest);
-    case "daemon": return handleDaemon(rest);
-    default:
-      console.error(`Unknown command: ${command}`);
-      printUsage();
-      process.exit(1);
-  }
+	switch (command) {
+		case 'push':
+			return handlePush(rest)
+		case 'fetch':
+			return handleFetch(rest)
+		case 'watch':
+			return handleWatch(rest)
+		case 'review':
+			return handleReview(rest)
+		case 'exec':
+			return handleExec(rest)
+		case 'instructions':
+			return handleInstructions(rest)
+		case 'install':
+			return handleInstall(rest)
+		case 'daemon':
+			return handleDaemon(rest)
+		default:
+			console.error(`Unknown command: ${command}`)
+			printUsage()
+			process.exit(1)
+	}
 }
 
 main().catch((e) => {
-  console.error(e);
-  process.exit(1);
-});
+	console.error(e)
+	process.exit(1)
+})

package/bin/lib/commands/daemon.ts

@@ -1,48 +1,51 @@
-import { parseArgs } from "util";
-import { DAEMON_PORT, BASE_URL } from "../config.ts";
-import { isDaemonRunning, startDaemon, stopDaemon } from "../daemon-lifecycle.ts";
+import { parseArgs } from 'util'
+import { z } from 'zod'
+import { BASE_URL, DAEMON_PORT } from '../config.ts'
+import { isDaemonRunning, startDaemon, stopDaemon } from '../daemon-lifecycle.ts'
+
+const healthResponseSchema = z.object({ sessions: z.array(z.string()) })
 
 export async function handleDaemon(args: string[]) {
-  const { positionals } = parseArgs({
-    args,
-    allowPositionals: true,
-  });
+	const { positionals } = parseArgs({
+		args,
+		allowPositionals: true,
+	})
 
-  const subcommand = positionals[0];
+	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": {
-      await stopDaemon();
-      break;
-    }
-    case "start": {
-      if (await isDaemonRunning()) {
-        console.log("Daemon is already running.");
-        return;
-      }
-      await startDaemon();
-      break;
-    }
-    case "restart": {
-      // stopDaemon() already waits for the daemon to go down.
-      await stopDaemon();
-      await startDaemon();
-      break;
-    }
-    default: {
-      console.error("Usage: agent-canvas daemon [status|stop|start|restart]");
-      process.exit(1);
-    }
-  }
+	switch (subcommand) {
+		case 'status': {
+			try {
+				const res = await fetch(`${BASE_URL}/health`, { signal: AbortSignal.timeout(2000) })
+				const data = healthResponseSchema.parse(await res.json())
+				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': {
+			await stopDaemon()
+			break
+		}
+		case 'start': {
+			if (await isDaemonRunning()) {
+				console.log('Daemon is already running.')
+				return
+			}
+			await startDaemon()
+			break
+		}
+		case 'restart': {
+			// stopDaemon() already waits for the daemon to go down.
+			await stopDaemon()
+			await startDaemon()
+			break
+		}
+		default: {
+			console.error('Usage: agent-canvas daemon [status|stop|start|restart]')
+			process.exit(1)
+		}
+	}
 }

package/bin/lib/commands/exec.ts

@@ -1,129 +1,129 @@
-import { existsSync, readFileSync } from "fs";
-import { resolve } from "path";
-import { parseArgs } from "util";
-import { BASE_URL, CLI_AUTH_FILE } from "../config.ts";
-import { ensureDaemon } from "../daemon-lifecycle.ts";
-import { getSessionId } from "../helpers.ts";
+import { existsSync, readFileSync } from 'fs'
+import { resolve } from 'path'
+import { parseArgs } from 'util'
+import { BASE_URL, CLI_AUTH_FILE } from '../config.ts'
+import { ensureDaemon } from '../daemon-lifecycle.ts'
+import { getSessionId } from '../helpers.ts'
 
-const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-const FIELD_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/
+const FIELD_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/
 
 export interface SecretAssignment {
-  envName: string;
-  fieldId: string;
+	envName: string
+	fieldId: string
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
 export function parseSecretAssignments(rawAssignments: string[]): SecretAssignment[] {
-  if (rawAssignments.length === 0) {
-    throw new Error("At least one --secret ENV_NAME=field-id mapping is required");
-  }
+	if (rawAssignments.length === 0) {
+		throw new Error('At least one --secret ENV_NAME=field-id mapping is required')
+	}
 
-  const assignments: SecretAssignment[] = [];
-  const environmentNames = new Set<string>();
-  for (const raw of rawAssignments) {
-    const separator = raw.indexOf("=");
-    const envName = separator === -1 ? "" : raw.slice(0, separator);
-    const fieldId = separator === -1 ? "" : raw.slice(separator + 1);
-    if (!ENV_NAME_RE.test(envName)) {
-      throw new Error(`Invalid environment variable name in --secret mapping: ${raw}`);
-    }
-    if (!FIELD_ID_RE.test(fieldId)) {
-      throw new Error(`Invalid secret field ID in --secret mapping: ${raw}`);
-    }
-    if (environmentNames.has(envName)) {
-      throw new Error(`Duplicate environment variable mapping: ${envName}`);
-    }
-    environmentNames.add(envName);
-    assignments.push({ envName, fieldId });
-  }
-  return assignments;
+	const assignments: SecretAssignment[] = []
+	const environmentNames = new Set<string>()
+	for (const raw of rawAssignments) {
+		const separator = raw.indexOf('=')
+		const envName = separator === -1 ? '' : raw.slice(0, separator)
+		const fieldId = separator === -1 ? '' : raw.slice(separator + 1)
+		if (!ENV_NAME_RE.test(envName)) {
+			throw new Error(`Invalid environment variable name in --secret mapping: ${raw}`)
+		}
+		if (!FIELD_ID_RE.test(fieldId)) {
+			throw new Error(`Invalid secret field ID in --secret mapping: ${raw}`)
+		}
+		if (environmentNames.has(envName)) {
+			throw new Error(`Duplicate environment variable mapping: ${envName}`)
+		}
+		environmentNames.add(envName)
+		assignments.push({ envName, fieldId })
+	}
+	return assignments
 }
 
 async function resolveSecretValues(sessionId: string, fieldIds: string[]): Promise<Map<string, string>> {
-  if (!existsSync(CLI_AUTH_FILE)) throw new Error("Canvas daemon CLI capability is unavailable");
-  const cliAuthToken = readFileSync(CLI_AUTH_FILE, "utf-8").trim();
-  const response = await fetch(`${BASE_URL}/api/session/${encodeURIComponent(sessionId)}/secrets/resolve`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json",
-      "X-Agent-Canvas-CLI-Token": cliAuthToken,
-    },
-    body: JSON.stringify({ fields: fieldIds }),
-  });
-  const raw: unknown = await response.json().catch(() => null);
-  if (!response.ok) {
-    const message = isRecord(raw) && typeof raw.error === "string"
-      ? raw.error
-      : `Secret API request failed with status ${response.status}`;
-    const missing = isRecord(raw) && Array.isArray(raw.missing)
-      ? raw.missing.filter((field): field is string => typeof field === "string")
-      : [];
-    throw new Error(missing.length > 0 ? `${message}: ${missing.join(", ")}` : message);
-  }
-  if (!isRecord(raw) || !Array.isArray(raw.values)) {
-    throw new Error("Secret API returned an invalid response");
-  }
+	if (!existsSync(CLI_AUTH_FILE)) throw new Error('Canvas daemon CLI capability is unavailable')
+	const cliAuthToken = readFileSync(CLI_AUTH_FILE, 'utf-8').trim()
+	const response = await fetch(`${BASE_URL}/api/session/${encodeURIComponent(sessionId)}/secrets/resolve`, {
+		method: 'POST',
+		headers: {
+			'Content-Type': 'application/json',
+			'X-Agent-Canvas-CLI-Token': cliAuthToken,
+		},
+		body: JSON.stringify({ fields: fieldIds }),
+	})
+	const raw: unknown = await response.json().catch(() => null)
+	if (!response.ok) {
+		const message = isRecord(raw) && typeof raw.error === 'string'
+			? raw.error
+			: `Secret API request failed with status ${response.status}`
+		const missing = isRecord(raw) && Array.isArray(raw.missing)
+			? raw.missing.filter((field): field is string => typeof field === 'string')
+			: []
+		throw new Error(missing.length > 0 ? `${message}: ${missing.join(', ')}` : message)
+	}
+	if (!isRecord(raw) || !Array.isArray(raw.values)) {
+		throw new Error('Secret API returned an invalid response')
+	}
 
-  const values = new Map<string, string>();
-  for (const entry of raw.values) {
-    if (!isRecord(entry) || typeof entry.id !== "string" || typeof entry.value !== "string") {
-      throw new Error("Secret API returned an invalid value entry");
-    }
-    values.set(entry.id, entry.value);
-  }
-  return values;
+	const values = new Map<string, string>()
+	for (const entry of raw.values) {
+		if (!isRecord(entry) || typeof entry.id !== 'string' || typeof entry.value !== 'string') {
+			throw new Error('Secret API returned an invalid value entry')
+		}
+		values.set(entry.id, entry.value)
+	}
+	return values
 }
 
 function executableExists(command: string): boolean {
-  if (command.includes("/")) return existsSync(resolve(command));
-  return Bun.spawnSync(["which", command], { stdout: "ignore", stderr: "ignore" }).exitCode === 0;
+	if (command.includes('/')) return existsSync(resolve(command))
+	return Bun.spawnSync(['which', command], { stdout: 'ignore', stderr: 'ignore' }).exitCode === 0
 }
 
 export async function spawnWithSecretEnvironment(
-  commandArgs: string[],
-  assignments: SecretAssignment[],
-  values: Map<string, string>,
+	commandArgs: string[],
+	assignments: SecretAssignment[],
+	values: Map<string, string>,
 ): Promise<number> {
-  const command = commandArgs[0];
-  if (!command) throw new Error("No command specified after --");
-  if (!executableExists(command)) throw new Error(`Executable not found: ${command}`);
+	const command = commandArgs[0]
+	if (!command) throw new Error('No command specified after --')
+	if (!executableExists(command)) throw new Error(`Executable not found: ${command}`)
 
-  const environment = { ...process.env };
-  for (const assignment of assignments) {
-    const value = values.get(assignment.fieldId);
-    if (value === undefined) throw new Error(`Secret is not ready: ${assignment.fieldId}`);
-    environment[assignment.envName] = value;
-  }
+	const environment = { ...process.env }
+	for (const assignment of assignments) {
+		const value = values.get(assignment.fieldId)
+		if (value === undefined) throw new Error(`Secret is not ready: ${assignment.fieldId}`)
+		environment[assignment.envName] = value
+	}
 
-  const child = Bun.spawn(commandArgs, {
-    env: environment,
-    stdin: "inherit",
-    stdout: "inherit",
-    stderr: "inherit",
-  });
-  return child.exited;
+	const child = Bun.spawn(commandArgs, {
+		env: environment,
+		stdin: 'inherit',
+		stdout: 'inherit',
+		stderr: 'inherit',
+	})
+	return child.exited
 }
 
 export async function handleExec(args: string[]): Promise<void> {
-  const { values, positionals } = parseArgs({
-    args,
-    options: {
-      session: { type: "string" },
-      secret: { type: "string", multiple: true },
-    },
-    allowPositionals: true,
-  });
+	const { values, positionals } = parseArgs({
+		args,
+		options: {
+			session: { type: 'string' },
+			secret: { type: 'string', multiple: true },
+		},
+		allowPositionals: true,
+	})
 
-  const assignments = parseSecretAssignments(values.secret ?? []);
-  if (positionals.length === 0) throw new Error("No command specified. Put the command after --");
+	const assignments = parseSecretAssignments(values.secret ?? [])
+	if (positionals.length === 0) throw new Error('No command specified. Put the command after --')
 
-  const sessionId = getSessionId(values.session);
-  await ensureDaemon();
-  const secretValues = await resolveSecretValues(sessionId, assignments.map((assignment) => assignment.fieldId));
-  const exitCode = await spawnWithSecretEnvironment(positionals, assignments, secretValues);
-  process.exit(exitCode);
+	const sessionId = getSessionId(values.session)
+	await ensureDaemon()
+	const secretValues = await resolveSecretValues(sessionId, assignments.map((assignment) => assignment.fieldId))
+	const exitCode = await spawnWithSecretEnvironment(positionals, assignments, secretValues)
+	process.exit(exitCode)
 }

package/bin/lib/commands/fetch.ts

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