agent-canvas 0.1.16 → 0.1.18

package/bin/agent-canvas.ts

@@ -5,12 +5,14 @@ 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";
 
 function printUsage() {
   console.error(`agent-canvas — Interactive visual canvas for Claude Code
 
 Commands:
   agent-canvas install [local|global]  Install skill for Claude Code
+  agent-canvas instructions [topic]    Show usage instructions (for AI agents)
   agent-canvas push <file.jsx>         Push a canvas, open browser
   agent-canvas fetch [--session <id>]  Check for feedback (returns immediately)
   agent-canvas watch [--session <id>]  Wait for user feedback (blocks until submitted)
@@ -38,6 +40,7 @@ async function main() {
     case "push": return handlePush(rest);
     case "fetch": return handleFetch(rest);
     case "watch": return handleWatch(rest);
+    case "instructions": return handleInstructions(rest);
     case "install": return handleInstall(rest);
     case "daemon": return handleDaemon(rest);
     default:

package/bin/lib/commands/install.ts

@@ -1,5 +1,5 @@
 import { parseArgs } from "util";
-import { existsSync, mkdirSync, cpSync } from "fs";
+import { existsSync, mkdirSync, cpSync, unlinkSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
 import { PACKAGE_ROOT } from "../config.ts";
@@ -35,12 +35,12 @@ export async function handleInstall(args: string[]) {
   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));
-    }
+  cpSync(join(PACKAGE_ROOT, "skills", "canvas", "SKILL.md"), join(skillTarget, "SKILL.md"));
+
+  // Clean up files from older versions
+  for (const old of ["components.md", "flows.md"]) {
+    const p = join(skillTarget, old);
+    if (existsSync(p)) unlinkSync(p);
   }
 
   console.log(`  Skill installed to ${skillTarget}`);

package/bin/lib/commands/instructions.ts

@@ -0,0 +1,66 @@
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join } from "path";
+import { PACKAGE_ROOT } from "../config.ts";
+
+const INSTRUCTIONS_DIR = join(PACKAGE_ROOT, "bin", "lib", "instructions");
+
+export async function handleInstructions(args: string[]) {
+  const topic = args[0];
+
+  if (!topic) {
+    // Base instructions — overview
+    const overview = readFileSync(join(INSTRUCTIONS_DIR, "overview.md"), "utf-8");
+    process.stdout.write(overview);
+    return;
+  }
+
+  if (topic === "--list") {
+    printAvailableTopics(process.stdout);
+    return;
+  }
+
+  // Try exact match: topic.md
+  const file = join(INSTRUCTIONS_DIR, `${topic}.md`);
+  if (existsSync(file)) {
+    const content = readFileSync(file, "utf-8");
+    process.stdout.write(content);
+    return;
+  }
+
+  // Not found
+  console.error(`Unknown topic: ${topic}\n`);
+  printAvailableTopics(process.stderr);
+  process.exit(1);
+}
+
+function printAvailableTopics(out: NodeJS.WriteStream) {
+  const files = readdirSync(INSTRUCTIONS_DIR)
+    .filter(f => f.endsWith(".md") && f !== "overview.md")
+    .map(f => f.replace(".md", ""))
+    .sort();
+
+  const components = files.filter(f => f.startsWith("component-"));
+  const flows = files.filter(f => f.startsWith("flow-"));
+  const other = files.filter(f => !f.startsWith("component-") && !f.startsWith("flow-"));
+
+  const lines: string[] = ["## Available Detail Topics", ""];
+
+  if (components.length) {
+    lines.push("### Components");
+    for (const c of components) lines.push(`- \`${c}\``);
+    lines.push("");
+  }
+  if (flows.length) {
+    lines.push("### Flows");
+    for (const f of flows) lines.push(`- \`${f}\``);
+    lines.push("");
+  }
+  if (other.length) {
+    lines.push("### Other");
+    for (const o of other) lines.push(`- \`${o}\``);
+    lines.push("");
+  }
+
+  lines.push("Usage: `bunx agent-canvas instructions <topic>`");
+  out.write(lines.join("\n") + "\n");
+}

package/bin/lib/instructions/component-callout.md

@@ -0,0 +1,27 @@
+# Component: Callout
+
+Highlighted information block. Background-tinted, no border.
+
+## Props
+
+- `type` ("info" | "warning" | "danger" | "tip") — determines color and icon
+
+## Usage
+
+```jsx
+<Callout type="warning">
+  This will invalidate all existing sessions. Plan a maintenance window.
+</Callout>
+
+<Callout type="tip">
+  Consider using connection pooling for better performance.
+</Callout>
+
+<Callout type="danger">
+  This action is irreversible.
+</Callout>
+
+<Callout type="info">
+  Review each requirement. Annotate anything that's wrong or missing.
+</Callout>
+```

package/bin/lib/instructions/component-checklist.md

@@ -0,0 +1,17 @@
+# Component: Checklist
+
+Visual checklist. Read-only display (feedback via annotations).
+
+## Props
+
+- `items` (array of `{ label: string, checked: boolean }`)
+
+## Usage
+
+```jsx
+<Checklist items={[
+  { label: "Run migration on staging", checked: true },
+  { label: "Verify data integrity", checked: false },
+  { label: "Update API docs", checked: false },
+]} />
+```

package/bin/lib/instructions/component-choice.md

@@ -0,0 +1,27 @@
+# Component: Choice
+
+Single-select radio group.
+
+## Props
+
+- `id` (string, required) — unique, used as key in feedback
+- `label` (string, required) — question text
+- `options` (string[], required) — radio options
+- `required` (boolean) — prevents submit until answered
+
+## Usage
+
+```jsx
+<Choice id="db-choice" label="Which database?" required
+  options={["PostgreSQL", "SQLite", "MongoDB"]} />
+
+<Choice id="review-action" label="How should I proceed?" required
+  options={[
+    "Fix all critical + warnings",
+    "Fix critical only, I'll handle warnings",
+    "Don't fix anything, this was informational",
+    "Let me annotate which ones to fix"
+  ]} />
+```
+
+Appears in feedback as: `[db-choice]: PostgreSQL`

package/bin/lib/instructions/component-codeblock.md

@@ -0,0 +1,24 @@
+# Component: CodeBlock
+
+Inline code block with syntax highlighting. For code that's part of the narrative, not from a file on disk.
+
+## Props
+
+- `language` (string) — syntax highlighting language (typescript, javascript, bash, python, sql, etc.)
+
+## Usage
+
+```jsx
+<CodeBlock language="typescript">
+  interface User {
+    id: string;
+    email: string;
+  }
+</CodeBlock>
+
+<CodeBlock language="bash">
+  npm run migrate:staging
+</CodeBlock>
+```
+
+**Tip**: For showing code from an actual project file, use `<FilePreview>` instead — it shows the real file with line numbers and the user can browse it.

package/bin/lib/instructions/component-custom.md

@@ -0,0 +1,34 @@
+# Custom Components
+
+When you use the full module format (`export default function Canvas()`), you can define custom helper components. Standard components remain available without import.
+
+## Usage
+
+```jsx
+function Metric({ label, value, trend }) {
+  const color = trend === 'up' ? 'var(--color-accent-green)' : trend === 'down' ? 'var(--color-accent-red)' : 'var(--color-text-secondary)';
+  return (
+    <div style={{ display: 'flex', gap: 12, alignItems: 'baseline' }}>
+      <span style={{ color: 'var(--color-text-tertiary)', fontSize: '0.75rem' }}>{label}</span>
+      <span style={{ color, fontSize: '1.25rem', fontWeight: 600 }}>{value}</span>
+    </div>
+  );
+}
+
+export default function Canvas() {
+  return (
+    <Section title="Performance Summary">
+      <Metric label="P95 Latency" value="42ms" trend="down" />
+      <Metric label="Error Rate" value="0.3%" trend="up" />
+      <Metric label="Throughput" value="1.2k rps" trend="up" />
+    </Section>
+  );
+}
+```
+
+## Tips
+
+- Use `style={{ }}` with CSS variables for theming (see `bunx agent-canvas instructions theming`)
+- Standard components (Section, Item, etc.) are available without import even in module format
+- You can use `React.useState`, `React.useEffect`, etc. — React is available globally
+- Use `useFeedback` hook to contribute custom data to the feedback response

package/bin/lib/instructions/component-diff.md

@@ -0,0 +1,18 @@
+# Component: Diff
+
+Shows a diff view between two code snippets.
+
+## Props
+
+- `before` (string, required) — original code
+- `after` (string, required) — modified code
+- `language` (string) — syntax highlighting language
+
+## Usage
+
+```jsx
+<Diff language="typescript"
+  before={`function auth(req) {\n  return true;\n}`}
+  after={`function auth(req) {\n  const token = req.headers.authorization;\n  if (!token) throw new Error('Unauthorized');\n  return verify(token);\n}`}
+/>
+```

package/bin/lib/instructions/component-filepreview.md

@@ -0,0 +1,15 @@
+# Component: FilePreview
+
+Shows a syntax-highlighted preview of a project file. The daemon serves the file content from the project root.
+
+## Props
+
+- `path` (string, required) — relative to project root
+- `lines` ([number, number]) — line range to show. Omit for full file.
+
+## Usage
+
+```jsx
+<FilePreview path="src/auth/middleware.ts" />
+<FilePreview path="src/auth/middleware.ts" lines={[42, 87]} />
+```

package/bin/lib/instructions/component-image.md

@@ -0,0 +1,17 @@
+# Component: ImageView
+
+Displays an image from the project directory.
+
+## Props
+
+- `src` (string, required) — path relative to project root
+- `alt` (string) — alt text
+- `caption` (string) — caption displayed below image
+- `width` (number) — max width in pixels
+
+## Usage
+
+```jsx
+<ImageView src="docs/architecture.png" />
+<ImageView src="screenshots/before.png" alt="Before refactor" caption="Current state" width={600} />
+```

package/bin/lib/instructions/component-item.md

@@ -0,0 +1,43 @@
+# Component: Item
+
+The primary content block. A flexible card-like row used for tasks, findings, requirements, observations, options — anything that has a title and details.
+
+Previously called "Task" — Item is the generalized version.
+
+## Props
+
+- `id` (string) — unique ID. Required if the item should be individually addressable in feedback. Optional for informational items.
+- `label` (string, required) — item title, rendered in Inter 600
+- `badge` (string) — short label shown as a small tag. Freeform text.
+- `badgeVariant` ("default" | "success" | "warning" | "danger" | "info") — badge color. Default is neutral gray.
+- `status` ("todo" | "done" | "blocked" | "in-progress") — shows a colored dot. Alternative to badge for plan-style items.
+
+**Badge vs Status**: Use `status` for things with a workflow state (tasks in a plan). Use `badge` for categorical labels (requirement priority, review severity, component type). You can use both on the same Item if needed.
+
+**Children**: Any content — text, components, code blocks, file previews, nested items.
+
+## Usage
+
+```jsx
+{/* As a plan task */}
+<Item id="migrate-db" label="Run database migration" badge="todo">
+  Execute the migration script against staging first.
+  <CodeBlock language="bash">npm run migrate:staging</CodeBlock>
+</Item>
+
+{/* As a review finding */}
+<Item id="finding-1" label="Missing null check in auth handler" badge="critical" badgeVariant="danger">
+  The handler doesn't check for missing tokens.
+  <FilePreview path="src/auth.ts" lines={[42, 48]} />
+</Item>
+
+{/* As a requirement */}
+<Item id="req-auth" label="JWT authentication" badge="must-have" badgeVariant="danger">
+  All API endpoints must require a valid JWT token.
+</Item>
+
+{/* As an architecture component */}
+<Item label="API Gateway" badge="core" badgeVariant="info">
+  Routes requests to downstream services. Handles rate limiting.
+</Item>
+```

package/bin/lib/instructions/component-markdown.md

@@ -0,0 +1,33 @@
+# Component: Markdown
+
+Renders markdown content with full GFM support (headings, lists, tables, code blocks, links, etc.). Two modes:
+
+## Inline source — markdown as children
+
+```jsx
+<Markdown>{`
+# Summary
+
+This is **bold** and *italic*. Here's a list:
+
+- First item
+- Second item
+  - Nested item
+
+\`\`\`typescript
+const x = 42;
+\`\`\`
+`}</Markdown>
+```
+
+## File reference — loads file content at compile time
+
+```jsx
+<Markdown file="docs/architecture.md" />
+<Markdown file="CHANGELOG.md" />
+```
+
+## Props
+
+- `file` (string) — path relative to project root. Content resolved at compile time.
+- Children (string) — inline markdown source. Used when `file` is not specified.

package/bin/lib/instructions/component-mermaid.md

@@ -0,0 +1,40 @@
+# Component: Mermaid
+
+Renders a Mermaid diagram. Supports flowchart, sequence, ER, gantt, pie, and more. The daemon bundles mermaid.js with a custom dark theme matching Canvas colors.
+
+## Usage
+
+```jsx
+<Mermaid>{`
+  graph TD
+    A[Client] -->|HTTP| B(API Gateway)
+    B --> C{Auth?}
+    C -->|Valid| D[Service]
+    C -->|Invalid| E[401 Response]
+`}</Mermaid>
+```
+
+### Sequence diagram
+
+```jsx
+<Mermaid>{`
+  sequenceDiagram
+    Client->>+API: POST /login
+    API->>+DB: Find user
+    DB-->>-API: User record
+    API-->>-Client: JWT token
+`}</Mermaid>
+```
+
+### ER diagram
+
+```jsx
+<Mermaid>{`
+  erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+    PRODUCT ||--o{ LINE-ITEM : "ordered in"
+`}</Mermaid>
+```
+
+For complex diagrams, prefer Mermaid over raw SVG. Use raw `<svg>` only when Mermaid can't express what you need.

package/bin/lib/instructions/component-multichoice.md

@@ -0,0 +1,19 @@
+# Component: MultiChoice
+
+Multi-select checkboxes.
+
+## Props
+
+- `id` (string, required) — unique, used as key in feedback
+- `label` (string, required) — question text
+- `options` (string[], required) — checkbox options
+- `required` (boolean) — prevents submit until at least one selected
+
+## Usage
+
+```jsx
+<MultiChoice id="affected-areas" label="Which areas need changes?" required
+  options={["Models", "API", "Frontend", "Tests"]} />
+```
+
+Appears in feedback as: `[affected-areas]: Models, API, Tests`

package/bin/lib/instructions/component-note.md

@@ -0,0 +1,11 @@
+# Component: Note
+
+Softer than Callout. For asides, context, non-critical info.
+
+## Usage
+
+```jsx
+<Note>
+  This pattern is also used in the payment service — see src/payments/auth.ts.
+</Note>
+```

package/bin/lib/instructions/component-priority.md

@@ -0,0 +1,15 @@
+# Component: Priority
+
+Inline badge. Use inside Item labels or body text.
+
+## Props
+
+- `level` ("high" | "medium" | "low")
+
+## Usage
+
+```jsx
+<Item label="Fix the race condition">
+  <Priority level="high" /> This causes data corruption under load.
+</Item>
+```

package/bin/lib/instructions/component-rangeinput.md

@@ -0,0 +1,20 @@
+# Component: RangeInput
+
+Slider for numeric ranges or scales.
+
+## Props
+
+- `id` (string, required) — unique, used as key in feedback
+- `label` (string, required) — question text
+- `min` (number) — minimum value
+- `max` (number) — maximum value
+- `minLabel` (string) — label for minimum end
+- `maxLabel` (string) — label for maximum end
+- `required` (boolean) — prevents submit until set
+
+## Usage
+
+```jsx
+<RangeInput id="effort-tolerance" label="How much refactoring is acceptable?"
+  min={1} max={5} minLabel="Minimal changes" maxLabel="Full rewrite OK" required />
+```

package/bin/lib/instructions/component-section.md

@@ -0,0 +1,22 @@
+# Component: Section
+
+Top-level grouping. Rendered as a serif heading with generous spacing. Collapsible (chevron appears on hover).
+
+## Props
+
+- `title` (string, required) — section heading, rendered in Instrument Serif
+- `collapsed` (boolean, default false) — start collapsed
+
+## Usage
+
+```jsx
+<Section title="Phase 1: Data Migration">
+  A brief description of this section.
+
+  {/* Items, callouts, code blocks, diagrams, etc. */}
+</Section>
+
+<Section title="Advanced Details" collapsed>
+  This section starts collapsed — user clicks to expand.
+</Section>
+```

package/bin/lib/instructions/component-svg.md

@@ -0,0 +1,31 @@
+# Diagrams with Raw SVG
+
+For custom visuals that Mermaid can't express, write `<svg>` directly. Use CSS variables for colors to match the theme.
+
+## Usage
+
+```jsx
+<svg viewBox="0 0 400 200" style={{ width: '100%', maxWidth: 400 }}>
+  <rect x="10" y="10" width="120" height="50" rx="8"
+        fill="var(--color-accent-blue-muted)" stroke="var(--color-accent-blue)" strokeOpacity="0.3" />
+  <text x="70" y="40" textAnchor="middle" fill="var(--color-text-primary)" fontSize="13"
+        fontFamily="var(--font-body)">API Gateway</text>
+
+  <line x1="130" y1="35" x2="180" y2="35" stroke="var(--color-text-tertiary)" strokeWidth="1.5"
+        markerEnd="url(#arrow)" />
+
+  <rect x="180" y="10" width="120" height="50" rx="8"
+        fill="var(--color-accent-green-muted)" stroke="var(--color-accent-green)" strokeOpacity="0.3" />
+  <text x="240" y="40" textAnchor="middle" fill="var(--color-text-primary)" fontSize="13"
+        fontFamily="var(--font-body)">Auth Service</text>
+
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="6" markerHeight="6"
+            orient="auto-start-reverse">
+      <path d="M 0 0 L 10 5 L 0 10 z" fill="var(--color-text-tertiary)" />
+    </marker>
+  </defs>
+</svg>
+```
+
+Keep SVG diagrams simple. For anything with more than ~5 nodes, prefer Mermaid.

package/bin/lib/instructions/component-table.md

@@ -0,0 +1,21 @@
+# Component: Table
+
+Simple data table.
+
+## Props
+
+- `headers` (string[]) — column headers
+- `rows` (string[][]) — row data
+
+## Usage
+
+```jsx
+<Table
+  headers={["Endpoint", "Method", "Auth"]}
+  rows={[
+    ["/users", "GET", "Required"],
+    ["/users/:id", "PUT", "Owner only"],
+    ["/health", "GET", "None"],
+  ]}
+/>
+```

package/bin/lib/instructions/component-usefeedback.md

@@ -0,0 +1,33 @@
+# Hook: useFeedback
+
+Hook for custom components to contribute computed/derived data to the feedback response. Use when built-in interactive components don't cover your needs.
+
+## Signature
+
+```typescript
+useFeedback(id: string, markdown: string, options?: { label?: string; required?: boolean })
+```
+
+- `id` (string, required) — unique feedback entry identifier
+- `markdown` (string, required) — markdown included in feedback, re-evaluated each render
+- `options.label` — display label in feedback preview
+- `options.required` — blocks submit while markdown is empty
+
+Registers on mount, updates on change, unregisters on unmount.
+
+## Usage
+
+```jsx
+function ProConList() {
+  const [pros, setPros] = React.useState(["Fast builds"]);
+  const [cons, setCons] = React.useState(["New runtime"]);
+
+  useFeedback(
+    "pro-con",
+    `**Pros:** ${pros.join(", ")}\n**Cons:** ${cons.join(", ")}`,
+    { label: "Pro/Con Analysis" },
+  );
+
+  return <div>{/* UI for managing pros/cons */}</div>;
+}
+```

package/bin/lib/instructions/component-userinput.md

@@ -0,0 +1,17 @@
+# Component: UserInput
+
+Free text input.
+
+## Props
+
+- `id` (string, required) — unique, used as key in feedback
+- `label` (string, required) — question text
+- `placeholder` (string) — hint text
+- `required` (boolean) — prevents submit until filled
+
+## Usage
+
+```jsx
+<UserInput id="constraints" label="Any constraints I should know about?"
+  placeholder="e.g. must work with existing Redis setup" required />
+```