agent-canvas 0.1.16 → 0.1.18

package/daemon/src/compiler.ts

@@ -130,6 +130,7 @@ export async function compilePlan(jsx: string, projectRoot?: string): Promise<Co
         entrypoints: [tmpFile],
         format: "esm",
         external: ["react", "react-dom", "#canvas/components", "#canvas/runtime"],
+        jsx: { runtime: "automatic", importSource: "react" },
       });
 
       if (!result.success) {

package/daemon/src/handlers/api.ts

@@ -8,11 +8,12 @@ import type { Route } from "../router";
 export interface ApiContext {
   sessionManager: SessionManager;
   broadcastPlanUpdate: (id: string) => void;
+  broadcastRevisionUpdate: (id: string) => void;
   port: number;
 }
 
 export function createApiHandlers(ctx: ApiContext): Route[] {
-  const { sessionManager, broadcastPlanUpdate, port } = ctx;
+  const { sessionManager, broadcastPlanUpdate, broadcastRevisionUpdate, port } = ctx;
 
   /**
    * Read *.jsx canvas files from a directory.
@@ -170,6 +171,7 @@ export function createApiHandlers(ctx: ApiContext): Route[] {
     const result = sessionManager.getLatestUnconsumedFeedback(sessionId);
     if (!result) return jsonResponse({ found: false });
     sessionManager.consumeFeedback(sessionId, result.revision);
+    broadcastRevisionUpdate(sessionId);
     return jsonResponse({ found: true, revision: result.revision, feedback: result.feedback });
   }
 

package/daemon/src/server.ts

@@ -21,7 +21,7 @@ const sessionManager = new SessionManager();
 const wsManager = createWebSocketManager(sessionManager);
 
 const routes = [
-  ...createApiHandlers({ sessionManager, broadcastPlanUpdate: wsManager.broadcastPlanUpdate, port: PORT }),
+  ...createApiHandlers({ sessionManager, broadcastPlanUpdate: wsManager.broadcastPlanUpdate, broadcastRevisionUpdate: wsManager.broadcastRevisionUpdate, port: PORT }),
   ...createFileHandlers(sessionManager),
   ...createUploadHandlers(sessionManager),
   ...createStaticHandlers(),

package/daemon/src/websocket.ts

@@ -36,12 +36,63 @@ export function createWebSocketManager(sessionManager: SessionManager) {
     }
   }
 
+  function broadcastWatcherStatus(sessionId: string) {
+    const sockets = browserSockets.get(sessionId);
+    if (!sockets) return;
+    const watching = (waitSockets.get(sessionId)?.size ?? 0) > 0;
+    const payload = JSON.stringify({ type: "watcher-status", watching });
+    for (const ws of sockets) {
+      ws.send(payload);
+    }
+  }
+
+  // Ping wait sockets periodically to detect dead connections.
+  // We can't rely on ws.close() triggering the close handler for dead sockets,
+  // so we manually remove dead sockets and broadcast status.
+  const PING_INTERVAL = 5_000;
+  const pongReceived = new WeakSet<ServerWebSocket<WSData>>();
+
+  function removeWaitSocket(ws: ServerWebSocket<WSData>, sessionId: string) {
+    const sockets = waitSockets.get(sessionId);
+    if (sockets) {
+      sockets.delete(ws);
+      if (sockets.size === 0) waitSockets.delete(sessionId);
+    }
+    try { ws.close(); } catch {}
+    broadcastWatcherStatus(sessionId);
+  }
+
+  setInterval(() => {
+    for (const [sessionId, sockets] of waitSockets) {
+      for (const ws of sockets) {
+        if (!pongReceived.has(ws)) {
+          // No pong since last ping — connection is dead
+          removeWaitSocket(ws, sessionId);
+          continue;
+        }
+        pongReceived.delete(ws);
+        try { ws.ping(); } catch {
+          removeWaitSocket(ws, sessionId);
+        }
+      }
+    }
+  }, PING_INTERVAL);
+
   const handlers = {
     open(ws: ServerWebSocket<WSData>) {
       const { type, sessionId } = ws.data;
       const map = type === "browser" ? browserSockets : waitSockets;
       if (!map.has(sessionId)) map.set(sessionId, new Set());
       map.get(sessionId)!.add(ws);
+      if (type === "browser") {
+        // Send current watcher status to newly connected browser
+        const watching = (waitSockets.get(sessionId)?.size ?? 0) > 0;
+        ws.send(JSON.stringify({ type: "watcher-status", watching }));
+      } else {
+        // CLI waiter connected — notify browsers
+        pongReceived.add(ws); // Give it a free pass on first interval
+        broadcastWatcherStatus(sessionId);
+      }
     },
     message(ws: ServerWebSocket<WSData>, message: string | Buffer) {
       const { type, sessionId } = ws.data;
@@ -59,6 +110,7 @@ export function createWebSocketManager(sessionManager: SessionManager) {
               const waiters = waitSockets.get(sessionId);
               if (waiters && waiters.size > 0) {
                 sessionManager.consumeFeedback(sessionId, session.currentRevision);
+                broadcastRevisionUpdate(sessionId);
                 const payload = JSON.stringify({ type: "submit", feedback });
                 for (const waiter of waiters) {
                   waiter.send(payload);
@@ -71,13 +123,22 @@ export function createWebSocketManager(sessionManager: SessionManager) {
         } catch {}
       }
     },
+    pong(ws: ServerWebSocket<WSData>) {
+      if (ws.data.type === "wait") {
+        pongReceived.add(ws);
+      }
+    },
     close(ws: ServerWebSocket<WSData>) {
       const { type, sessionId } = ws.data;
       const map = type === "browser" ? browserSockets : waitSockets;
       map.get(sessionId)?.delete(ws);
       if (map.get(sessionId)?.size === 0) map.delete(sessionId);
+      if (type === "wait") {
+        // CLI waiter disconnected — notify browsers
+        broadcastWatcherStatus(sessionId);
+      }
     },
   };
 
-  return { handlers, broadcastPlanUpdate, broadcastRevisionUpdate };
+  return { handlers, broadcastPlanUpdate, broadcastRevisionUpdate, broadcastWatcherStatus };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-canvas",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Interactive visual canvas for Claude Code — rich annotatable documents in the browser",
   "bin": {
     "agent-canvas": "bin/agent-canvas.js"

package/skills/canvas/SKILL.md

@@ -11,203 +11,18 @@ disable-model-invocation: true
 
 ---
 
-# Canvas — Interactive Visual Documents
+## Session
 
-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.
+Your canvas session ID is: `${CLAUDE_SESSION_ID}`
 
-**Read the flow reference before starting**: Check `${CLAUDE_SKILL_DIR}/flows.md` to pick the right flow for your task. Each flow has a specific sequence of canvases with templates.
+Use this value for:
+- File paths: `.claude/agent-canvas/${CLAUDE_SESSION_ID}/`
+- CLI flags: `--session ${CLAUDE_SESSION_ID}`
 
-**Read the component reference as needed**: Check `${CLAUDE_SKILL_DIR}/components.md` for the full component API.
+## Instructions
 
-## Core Mechanics
+!`bunx agent-canvas instructions`
 
-### Writing a Canvas
+!`bunx agent-canvas instructions --list`
 
-Use the **Write** tool to create a `.jsx` file in `.claude/agent-canvas/${CLAUDE_SESSION_ID}/`:
-
-```jsx
-// Write to: .claude/agent-canvas/${CLAUDE_SESSION_ID}/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 canvas files, push the directory to open all canvases in the browser:
-
-```bash
-bunx agent-canvas push .claude/agent-canvas/${CLAUDE_SESSION_ID}/ --session ${CLAUDE_SESSION_ID} --label "Implementation Plan"
-```
-
-This pushes all `*.jsx` files in the directory as a snapshot (like a git commit). Each file appears as a separate tab in the browser. The canvas opens in the user's browser (first time) and the command exits immediately. **Always show the `browserUrl` from the push output to the user** so they can open the canvas manually if auto-open didn't work.
-
-### Waiting for feedback
-
-After pushing, start the watch command **in the background** using the Bash tool's `run_in_background` parameter:
-
-```bash
-# Use Bash tool with run_in_background: true
-bunx agent-canvas watch --session ${CLAUDE_SESSION_ID}
-```
-
-This runs the watch process in the background. You will be **automatically notified** when the user submits feedback — the output will contain the feedback markdown. Do NOT poll, sleep, or proactively check on it. Just stop and wait for the notification.
-
-If feedback was already submitted but not yet consumed, the command returns immediately with the existing feedback.
-
-**Important**: After starting the background watch, do not continue with other work unless instructed. Wait for the notification that feedback has arrived before proceeding.
-
-### Checking for feedback without blocking
-
-Use `fetch` to retrieve feedback if the user tells you they've already submitted:
-
-```bash
-bunx agent-canvas fetch --session ${CLAUDE_SESSION_ID}
-```
-
-Returns immediately — prints feedback to stdout if available, otherwise produces no output. Use this when the user tells you they've submitted feedback (e.g. after a reconnect or if the background watch was lost).
-
-### Iterating
-
-Use the **Edit** tool to modify the existing JSX based on feedback — targeted edits, not full rewrites. Then push and watch again:
-
-```bash
-bunx agent-canvas push .claude/agent-canvas/${CLAUDE_SESSION_ID}/ --session ${CLAUDE_SESSION_ID} --label "Implementation Plan (revised)"
-
-# Use Bash tool with run_in_background: true
-bunx agent-canvas watch --session ${CLAUDE_SESSION_ID}
-```
-
-Each push creates a new **round** (revision) — all canvas files are snapshotted. The user sees which files changed in the revision selector.
-
-### Responding to feedback
-
-When pushing a revised canvas after receiving user feedback, use `--response` to tell the user how you addressed their feedback. The response renders as a short banner at the top of the canvas.
-
-```bash
-bunx agent-canvas push .claude/agent-canvas/${CLAUDE_SESSION_ID}/ --session ${CLAUDE_SESSION_ID} --label "Plan (revised)" --response "Incorporated all feedback. Switched to connection pooling as suggested. I kept the sync approach for writes — see the note in Phase 2 for my reasoning."
-```
-
-Use `--response` to:
-- Confirm what you incorporated and how
-- Explain any opposing stance — if you disagree with a suggestion, say why
-- Call out anything you intentionally did NOT change and why
-
-Keep it concise (2-4 sentences). The user can see the diff in the canvas UI, so focus on the "why" not the "what".
-
-### Multiple Canvases
-
-All `*.jsx` files in the canvas directory are pushed together as a snapshot. Each file appears as a separate tab in the browser. Use different files for different phases or concerns:
-
-```
-.claude/agent-canvas/${CLAUDE_SESSION_ID}/
-  discovery.jsx    # Discovery interview
-  requirements.jsx # Requirements spec
-  plan.jsx         # Implementation plan
-```
-
-Write new files as phases progress, then push the directory. Previous phase files remain visible as context. The user can annotate any canvas and submit one combined feedback per revision.
-
-```bash
-# Write discovery.jsx first, push and get feedback
-bunx agent-canvas push .claude/agent-canvas/${CLAUDE_SESSION_ID}/ --session ${CLAUDE_SESSION_ID} --label "Discovery"
-bunx agent-canvas watch --session ${CLAUDE_SESSION_ID}  # run_in_background: true
-
-# Later, add requirements.jsx, push again — both files visible as tabs
-bunx agent-canvas push .claude/agent-canvas/${CLAUDE_SESSION_ID}/ --session ${CLAUDE_SESSION_ID} --label "Requirements"
-bunx agent-canvas watch --session ${CLAUDE_SESSION_ID}  # run_in_background: true
-```
-
-### File Location
-
-All canvas files go in `.claude/agent-canvas/${CLAUDE_SESSION_ID}/` within the project root. Add `.claude/agent-canvas/` to `.gitignore` — these are ephemeral working files.
-
-## Choosing a Flow
-
-Determine which flow fits before starting. See `${CLAUDE_SKILL_DIR}/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/agent-canvas/${CLAUDE_SESSION_ID}/<name>.jsx`
-4. **Push the directory + tell the user**: Push with `bunx agent-canvas push .claude/agent-canvas/${CLAUDE_SESSION_ID}/ --session ${CLAUDE_SESSION_ID}` and show the `browserUrl` from the output so the user can open it
-5. **IMMEDIATELY watch in background** — run `bunx agent-canvas watch --session ${CLAUDE_SESSION_ID}` with `run_in_background: true` right after push. Never stop after pushing. The push→watch sequence is atomic: no push without a watch. You will be notified when feedback arrives — do not poll or sleep.
-6. **Read feedback** — check for annotations, answers, added context files, approval
-7. **Edit with the Edit tool and re-push + watch**, or advance to next phase
-8. **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/agent-canvas/${CLAUDE_SESSION_ID}/` 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.
+**Getting detailed docs**: Run `bunx agent-canvas instructions <topic>` for detailed documentation on any component or flow. For example: `bunx agent-canvas instructions component-mermaid` or `bunx agent-canvas instructions flow-feature`.