agent-canvas 0.1.0

package/daemon/src/session.ts

@@ -0,0 +1,274 @@
+import { mkdirSync, writeFileSync, readFileSync, existsSync, readdirSync, rmSync, renameSync } from "fs";
+import { join } from "path";
+import { SESSIONS_DIR } from "./paths";
+
+export interface RevisionInfo {
+  revision: number;
+  label?: string;
+  sourceFile?: string;
+  createdAt: string;
+  hasFeedback: boolean;
+}
+
+export interface SessionData {
+  id: string;
+  projectRoot: string;
+  jsx: string;
+  currentRevision: number;
+  revisions: RevisionInfo[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+interface SessionMeta {
+  projectRoot: string;
+  createdAt: string;
+  updatedAt: string;
+  currentRevision: number;
+  revisions: RevisionInfo[];
+}
+
+// Legacy format
+interface LegacyMeta {
+  projectRoot: string;
+  createdAt: string;
+  updatedAt: string;
+  version: number;
+}
+
+const STALE_TIMEOUT_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+export class SessionManager {
+  private sessions = new Map<string, SessionData>();
+
+  constructor() {
+    mkdirSync(SESSIONS_DIR, { recursive: true });
+    this.loadFromDisk();
+  }
+
+  private sessionDir(id: string): string {
+    return join(SESSIONS_DIR, id);
+  }
+
+  private revisionDir(id: string, rev: number): string {
+    return join(this.sessionDir(id), "revisions", String(rev));
+  }
+
+  private loadFromDisk() {
+    if (!existsSync(SESSIONS_DIR)) return;
+    for (const name of readdirSync(SESSIONS_DIR, { withFileTypes: true })) {
+      if (!name.isDirectory()) continue;
+      const dir = join(SESSIONS_DIR, name.name);
+      const metaPath = join(dir, "meta.json");
+      if (!existsSync(metaPath)) continue;
+
+      try {
+        const raw = JSON.parse(readFileSync(metaPath, "utf-8"));
+
+        // Detect and migrate legacy format
+        if ("version" in raw && !("currentRevision" in raw)) {
+          this.migrateLegacy(name.name, raw as LegacyMeta);
+          // Re-read after migration
+          const migrated: SessionMeta = JSON.parse(readFileSync(metaPath, "utf-8"));
+          const jsx = this.readRevisionJsx(name.name, migrated.currentRevision);
+          if (!jsx) continue;
+          this.sessions.set(name.name, {
+            id: name.name,
+            projectRoot: migrated.projectRoot,
+            jsx,
+            currentRevision: migrated.currentRevision,
+            revisions: migrated.revisions,
+            createdAt: migrated.createdAt,
+            updatedAt: migrated.updatedAt,
+          });
+          continue;
+        }
+
+        const meta = raw as SessionMeta;
+        const jsx = this.readRevisionJsx(name.name, meta.currentRevision);
+        if (!jsx) continue;
+
+        this.sessions.set(name.name, {
+          id: name.name,
+          projectRoot: meta.projectRoot,
+          jsx,
+          currentRevision: meta.currentRevision,
+          revisions: meta.revisions,
+          createdAt: meta.createdAt,
+          updatedAt: meta.updatedAt,
+        });
+      } catch {}
+    }
+  }
+
+  private migrateLegacy(id: string, legacy: LegacyMeta) {
+    const dir = this.sessionDir(id);
+    const flatJsx = join(dir, "plan.jsx");
+    const flatCompiled = join(dir, "plan.compiled.js");
+    const historyDir = join(dir, "history");
+
+    // Collect all historical revisions + current
+    const revisions: RevisionInfo[] = [];
+
+    // Migrate history files
+    if (existsSync(historyDir)) {
+      const files = readdirSync(historyDir).filter((f) => f.endsWith(".jsx")).sort();
+      for (const file of files) {
+        const num = parseInt(file.replace(".jsx", ""), 10);
+        if (isNaN(num)) continue;
+        const revDir = this.revisionDir(id, num);
+        mkdirSync(revDir, { recursive: true });
+        renameSync(join(historyDir, file), join(revDir, "plan.jsx"));
+        revisions.push({ revision: num, createdAt: legacy.createdAt, hasFeedback: false });
+      }
+      rmSync(historyDir, { recursive: true, force: true });
+    }
+
+    // Migrate current version
+    const currentRev = legacy.version;
+    const revDir = this.revisionDir(id, currentRev);
+    mkdirSync(revDir, { recursive: true });
+    if (existsSync(flatJsx)) {
+      renameSync(flatJsx, join(revDir, "plan.jsx"));
+    }
+    if (existsSync(flatCompiled)) {
+      renameSync(flatCompiled, join(revDir, "plan.compiled.js"));
+    }
+    revisions.push({ revision: currentRev, createdAt: legacy.updatedAt, hasFeedback: false });
+
+    // Write new meta
+    const meta: SessionMeta = {
+      projectRoot: legacy.projectRoot,
+      createdAt: legacy.createdAt,
+      updatedAt: legacy.updatedAt,
+      currentRevision: currentRev,
+      revisions,
+    };
+    writeFileSync(join(dir, "meta.json"), JSON.stringify(meta, null, 2));
+  }
+
+  private readRevisionJsx(id: string, rev: number): string | null {
+    try {
+      return readFileSync(join(this.revisionDir(id, rev), "plan.jsx"), "utf-8");
+    } catch {
+      return null;
+    }
+  }
+
+  upsert(id: string, jsx: string, projectRoot: string, label?: string, sourceFile?: string): SessionData {
+    const existing = this.sessions.get(id);
+    const now = new Date().toISOString();
+    const revision = existing ? existing.currentRevision + 1 : 1;
+
+    const revInfo: RevisionInfo = { revision, createdAt: now, hasFeedback: false, ...(label ? { label } : {}), ...(sourceFile ? { sourceFile } : {}) };
+    const revisions = existing ? [...existing.revisions, revInfo] : [revInfo];
+
+    const session: SessionData = {
+      id,
+      projectRoot,
+      jsx,
+      currentRevision: revision,
+      revisions,
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+    };
+
+    this.sessions.set(id, session);
+    this.persistToDisk(session);
+    return session;
+  }
+
+  private persistToDisk(session: SessionData) {
+    const dir = this.sessionDir(session.id);
+    const revDir = this.revisionDir(session.id, session.currentRevision);
+    mkdirSync(revDir, { recursive: true });
+
+    // Write revision JSX
+    writeFileSync(join(revDir, "plan.jsx"), session.jsx);
+
+    // Write meta
+    const meta: SessionMeta = {
+      projectRoot: session.projectRoot,
+      createdAt: session.createdAt,
+      updatedAt: session.updatedAt,
+      currentRevision: session.currentRevision,
+      revisions: session.revisions,
+    };
+    writeFileSync(join(dir, "meta.json"), JSON.stringify(meta, null, 2));
+  }
+
+  get(id: string): SessionData | undefined {
+    return this.sessions.get(id);
+  }
+
+  list(): SessionData[] {
+    return Array.from(this.sessions.values());
+  }
+
+  remove(id: string) {
+    this.sessions.delete(id);
+    rmSync(this.sessionDir(id), { recursive: true, force: true });
+  }
+
+  saveCompiled(id: string, js: string, rev?: number) {
+    const session = this.sessions.get(id);
+    const revision = rev ?? session?.currentRevision;
+    if (!revision) return;
+    const revDir = this.revisionDir(id, revision);
+    mkdirSync(revDir, { recursive: true });
+    writeFileSync(join(revDir, "plan.compiled.js"), js);
+  }
+
+  getCompiled(id: string, rev?: number): string | null {
+    const session = this.sessions.get(id);
+    const revision = rev ?? session?.currentRevision;
+    if (!revision) return null;
+    try {
+      return readFileSync(join(this.revisionDir(id, revision), "plan.compiled.js"), "utf-8");
+    } catch {
+      return null;
+    }
+  }
+
+  saveFeedback(id: string, rev: number, markdown: string) {
+    const revDir = this.revisionDir(id, rev);
+    mkdirSync(revDir, { recursive: true });
+    writeFileSync(join(revDir, "feedback.md"), markdown);
+
+    // Update in-memory and on-disk meta
+    const session = this.sessions.get(id);
+    if (session) {
+      const ri = session.revisions.find((r) => r.revision === rev);
+      if (ri) ri.hasFeedback = true;
+      const meta: SessionMeta = {
+        projectRoot: session.projectRoot,
+        createdAt: session.createdAt,
+        updatedAt: session.updatedAt,
+        currentRevision: session.currentRevision,
+        revisions: session.revisions,
+      };
+      writeFileSync(join(this.sessionDir(id), "meta.json"), JSON.stringify(meta, null, 2));
+    }
+  }
+
+  getFeedback(id: string, rev: number): string | null {
+    try {
+      return readFileSync(join(this.revisionDir(id, rev), "feedback.md"), "utf-8");
+    } catch {
+      return null;
+    }
+  }
+
+  getRevisionJsxPath(id: string, rev: number): string {
+    return join(this.revisionDir(id, rev), "plan.jsx");
+  }
+
+  cleanupStale(maxAge = STALE_TIMEOUT_MS) {
+    const now = Date.now();
+    for (const [id, session] of this.sessions) {
+      if (now - new Date(session.updatedAt).getTime() > maxAge) {
+        this.remove(id);
+      }
+    }
+  }
+}

package/daemon/src/watcher.ts

@@ -0,0 +1,59 @@
+import { watch, existsSync, readFileSync } from "fs";
+import { compilePlan } from "./compiler";
+import type { SessionManager } from "./session";
+
+type BroadcastFn = (sessionId: string) => void;
+
+const watchers = new Map<string, ReturnType<typeof watch>>();
+
+export function watchSession(
+  sessionId: string,
+  sessionManager: SessionManager,
+  broadcast: BroadcastFn,
+) {
+  // Close existing watcher for this session (revision may have changed)
+  unwatchSession(sessionId);
+
+  const session = sessionManager.get(sessionId);
+  if (!session) return;
+
+  const planPath = sessionManager.getRevisionJsxPath(sessionId, session.currentRevision);
+  if (!existsSync(planPath)) return;
+
+  let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  const rev = session.currentRevision;
+
+  const watcher = watch(planPath, async (event) => {
+    if (event !== "change") return;
+
+    // Debounce — Claude Code may do multiple rapid edits
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(async () => {
+      try {
+        const jsx = readFileSync(planPath, "utf-8");
+        const result = await compilePlan(jsx, session.projectRoot);
+        if (result.ok) {
+          sessionManager.saveCompiled(sessionId, result.js, rev);
+          broadcast(sessionId);
+        }
+      } catch {}
+    }, 200);
+  });
+
+  watchers.set(sessionId, watcher);
+}
+
+export function unwatchSession(sessionId: string) {
+  const watcher = watchers.get(sessionId);
+  if (watcher) {
+    watcher.close();
+    watchers.delete(sessionId);
+  }
+}
+
+export function unwatchAll() {
+  for (const [id, watcher] of watchers) {
+    watcher.close();
+  }
+  watchers.clear();
+}

package/hooks/session-start.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+# Injects CANVAS_SESSION_ID and CANVAS_PROJECT_ROOT into Claude Code environment.
+# Called by Claude Code's SessionStart hook.
+INPUT=$(cat /dev/stdin)
+SESSION_ID=$(echo "$INPUT" | grep -o '"session_id":"[^"]*"' | cut -d'"' -f4)
+CWD=$(echo "$INPUT" | grep -o '"cwd":"[^"]*"' | cut -d'"' -f4)
+
+if [ -n "$SESSION_ID" ] && [ -n "$CLAUDE_ENV_FILE" ]; then
+  echo "export CANVAS_SESSION_ID=$SESSION_ID" >> "$CLAUDE_ENV_FILE"
+  echo "export CANVAS_PROJECT_ROOT=$CWD" >> "$CLAUDE_ENV_FILE"
+fi

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "agent-canvas",
+  "version": "0.1.0",
+  "description": "Interactive visual canvas for Claude Code — rich annotatable documents in the browser",
+  "bin": {
+    "agent-canvas": "bin/agent-canvas.js"
+  },
+  "files": [
+    "bin/",
+    "daemon/src/",
+    "daemon/client/",
+    "daemon/dist/",
+    "daemon/build.ts",
+    "daemon/package.json",
+    "skills/",
+    "hooks/"
+  ],
+  "scripts": {
+    "build": "bun daemon/build.ts",
+    "prepublishOnly": "bun daemon/build.ts"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "4",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "tailwindcss": "4"
+  },
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "canvas",
+    "interactive",
+    "annotations"
+  ]
+}

package/skills/canvas/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: canvas
+description: >
+  Interactive visual canvas for structured communication between agent and user.
+  Opens a rich annotatable document in the user's browser where the user reviews,
+  comments, answers questions, and submits feedback.
+
+  Supports planning, architecture reviews, code reviews, discovery interviews,
+  implementation summaries, proposals, decision documents, and explanations.
+disable-model-invocation: true
+
+---
+
+# Canvas — Interactive Visual Documents
+
+Canvas opens a rich, annotatable document in the user's browser. You write JSX, the user reviews and annotates it like Google Docs, and feedback comes back as markdown. Use it whenever structured visual communication beats inline chat.
+
+**Read the flow reference before starting**: Check `flows.md` to pick the right flow for your task. Each flow has a specific sequence of canvases with templates.
+
+**Read the component reference as needed**: Check `components.md` for the full component API.
+
+## Core Mechanics
+
+### Writing a Canvas
+
+Use the **Write** tool to create a `.jsx` file in `.claude/canvas/`:
+
+```jsx
+// Write to: .claude/canvas/plan.jsx
+
+<Section title="Authentication Redesign">
+  A proposal to replace session-based auth with JWT tokens.
+  
+  <Item label="Current state" badge="context" badgeVariant="info">
+    The app uses express-session with Redis store.
+    <FilePreview path="src/auth/session.ts" lines={[1, 45]} />
+  </Item>
+
+  <Item label="Proposed change" badge="proposal">
+    Switch to stateless JWT with refresh token rotation.
+    <Callout type="warning">This will invalidate all existing sessions.</Callout>
+  </Item>
+</Section>
+```
+
+Components are auto-available — no imports needed. The file is a JSX fragment (just tags) or a full module with `export default`.
+
+### Pushing
+
+After writing the file, push it to open the canvas in the browser:
+
+```bash
+bunx agent-canvas push .claude/canvas/plan.jsx --label "Implementation Plan"
+```
+
+This opens the canvas in the user's browser (first time) and exits immediately. The round label defaults to the filename if `--label` is omitted.
+
+### Waiting for feedback
+
+After pushing, wait for the user to review and submit:
+
+```bash
+bunx agent-canvas wait
+```
+
+This **blocks until the user submits feedback**, then prints feedback markdown to stdout. If feedback was already submitted (e.g. retrying after a disconnect), it returns immediately with the existing feedback.
+
+### Iterating
+
+Use the **Edit** tool to modify the existing JSX based on feedback — targeted edits, not full rewrites. Then push and wait again:
+
+```bash
+bunx agent-canvas push .claude/canvas/plan.jsx --label "Implementation Plan (revised)"
+bunx agent-canvas wait
+```
+
+Each push creates a new **round** — the user sees previous rounds and their feedback in the UI.
+
+### Multiple Canvases
+
+Maintain separate files for different phases:
+
+```bash
+bunx agent-canvas push .claude/canvas/discovery.jsx --label "Discovery"
+bunx agent-canvas wait
+# ... process feedback ...
+bunx agent-canvas push .claude/canvas/requirements.jsx --label "Requirements"
+bunx agent-canvas wait
+# ... process feedback ...
+bunx agent-canvas push .claude/canvas/plan.jsx --label "Implementation Plan"
+bunx agent-canvas wait
+```
+
+### File Location
+
+All canvas files go in `.claude/canvas/` within the project root. Add `.claude/canvas/` to `.gitignore` — these are ephemeral working files.
+
+## Choosing a Flow
+
+Determine which flow fits before starting. See `flows.md` for full details with templates.
+
+```
+User wants something built/changed?
+├─ Vague request ("add auth", "refactor the API")
+│  └─ FEATURE flow: discovery → requirements → plan → [implement] → summary
+├─ Clear request with specifics
+│  └─ PLAN flow: plan → [implement] → summary
+├─ Complete instructions, just wants execution
+│  └─ Skip canvas, implement directly, optionally push summary
+
+User wants to understand something?
+├─ "How does X work?", "Explain the auth system"
+│  └─ EXPLAIN flow: single explanatory canvas
+
+User wants review/audit?
+├─ "Review this code", "Check for issues"
+│  └─ REVIEW flow: findings canvas with categorized issues
+
+User wants to make a decision?
+├─ "Should we use X or Y?", "What database?"
+│  └─ DECISION flow: options with tradeoffs, recommendation
+```
+
+**Adapt dynamically**: flows are guidelines, not rigid pipelines. Pivot if needed, skip if the user says so.
+
+## Flow Execution Pattern
+
+1. **Determine flow** from user intent
+2. **Announce** briefly: "I'll start with discovery, then create a detailed plan."
+3. **Write canvas JSX** with the Write tool to `.claude/canvas/<name>.jsx`
+4. **Push**: `bunx agent-canvas push .claude/canvas/<name>.jsx --label "<Label>"`
+5. **Tell the user** the canvas is ready for review (they see it in their browser)
+6. **Wait**: `bunx agent-canvas wait` — this blocks until the user submits feedback
+7. **Read feedback** — check for annotations, answers, added context files, approval
+8. **Edit with the Edit tool and re-push + wait**, or advance to next phase
+9. **After implementation**, push a summary canvas
+
+## Interview Integration
+
+For discovery phases, use iterative canvases or offer a checklist:
+
+```jsx
+<Section title="Before we start">
+  Which areas should we discuss in depth?
+  
+  <MultiChoice id="interview-areas" label="Select areas to cover" required
+    options={[
+      "Backend architecture & data model",
+      "API design & contracts", 
+      "Frontend / UI behavior",
+      "Edge cases & error handling",
+      "Performance & scaling",
+      "Security considerations",
+      "Testing strategy",
+      "Migration / deployment"
+    ]} />
+  
+  <UserInput id="anything-else" label="Anything else I should know upfront?" />
+</Section>
+```
+
+Then interview deeply in each selected area across subsequent rounds. Or ask in chat first: "Would you prefer a thorough interview before I plan, or should I make assumptions and you correct in review?"
+
+## Important Rules
+
+- **Write** canvas files to `.claude/canvas/` using the Write tool. Never use bash heredocs or cat.
+- **Edit** canvas files using the Edit tool. Never rewrite entire files — make targeted edits.
+- JSX can be a fragment (just tags) or a full module with `export default function Canvas()`.
+- Every `<Item>` and interactive component needs a unique `id`.
+- `<FilePreview path="...">` paths are relative to project root.
+- For inline styling use `style={{ ... }}` — Tailwind is NOT available in canvas JSX.
+- Read any files the user added to context (listed under "Added context" in feedback) with the Read tool before the next iteration.
+- Always push a summary canvas after implementation, even if brief.
+- When the user approves, confirm what you'll do next before proceeding.