@frebreco/canvas 0.3.0-next.7 → 0.3.0-next.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frebreco/canvas",
-  "version": "0.3.0-next.7",
+  "version": "0.3.0-next.9",
   "description": "A multiplayer canvas for coding agents that run on your machine.",
   "license": "MIT",
   "type": "module",
@@ -18,6 +18,7 @@
   "files": [
     "bin",
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "canvas",
+  "description": "Skills canvas gives the agents it runs.",
+  "skills": "./"
+}

package/skills/code-tour/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: code-tour
+description: Give a code tour on the canvas board — a guided walk through how part of the codebase works, as one files frame people click through. Use when asked for a tour or walkthrough of code, how a feature works across files, or to onboard someone to an area.
+---
+
+A code tour is one files frame on the board whose list holds, in reading order: a guide (a
+markdown scratch file), then the **stops** — project files at the lines that matter — and
+optionally a diagram at the end. People click through it at their own pace; the thread only
+points at it.
+
+## Steps
+
+1. **Find the stops.** Read the code until you can tell the story from entry point to effect.
+   Pick 4–10 stops in the order a newcomer needs them, usually where it starts → the core → the
+   edges. A stop is one file at a tight line range (roughly 5–40 lines): the function, the branch,
+   the type that carries the idea. Only files git tracks can be shown; a stop in an ignored file
+   gets described in the guide instead. Done when each stop's range is read from the file as it
+   is now, and the stops tell the story without gaps.
+
+2. **Write the guide**, `tour-<topic>.md`: a one-paragraph overview, then one short section per
+   stop, numbered and titled like its list entry — what to look at in those lines, why it
+   matters, and how it hands over to the next stop. Name functions and types; quote lines
+   sparingly, the frame shows them. End with open questions or pitfalls if you found any.
+
+3. **Draw it**, when the flow branches or spans several components: `tour-<topic>.html`, a
+   single self-contained page (inline CSS and SVG or script) with boxes named like the stops.
+   Skip it for a straight line of calls.
+
+4. **Open the tour.** `view_board` first; retarget an existing tour frame on the same topic with
+   `update_frame` rather than opening a second one. Otherwise one `open_frame` of type `file`
+   whose `files` list is the whole tour, the guide first:
+
+   ```json
+   {
+     "type": "file",
+     "title": "Tour: login",
+     "files": [
+       { "display": "0 Guide.md", "name": "tour-login.md", "content": "…" },
+       { "display": "1 Route/login.ts", "path": "src/routes/login.ts", "start_line": 12, "end_line": 30 },
+       { "display": "2 Session/session.ts", "path": "src/auth/session.ts", "start_line": 5, "end_line": 22 },
+       { "display": "3 Diagram.html", "name": "tour-login.html", "content": "…" }
+     ]
+   }
+   ```
+
+   Number the display names like the guide's sections, so people can match them; folders are
+   worth it only for chapters of a long tour. Done when every stop in the list has its section
+   in the guide and every section its stop.
+
+5. **Reply briefly**: the tour's frame, how many stops, and the story in one or two sentences.
+   The guide carries the explanation; the thread stays short.
+
+## Walking people through it
+
+When people ask to be walked through the tour ("next", "show stop 3"), `update_frame` the tour
+frame to that stop's `path`, `start_line` and `end_line`, and explain it in your reply. Changing
+the frame makes you its occupant for the turn, so everyone following scrolls with you.
+
+## Revising
+
+Follow-up questions often deserve a stop or a section. `write_board_file` with the guide's path
+rewrites it in place. `update_frame` with `files` replaces the whole list, so send every entry,
+the new one in its place. Name the guide and diagram there by their `canvas:scratch/` paths:
+`content` would create new copies.

package/src/server/agents.ts

@@ -46,6 +46,7 @@ import type {
   SessionSnapshot,
 } from "../shared/protocol";
 import { fromAcp, pendingChanges, settingsOf } from "./agent-config";
+import { SKILLS_DIR } from "./skills";
 import { trimEvent } from "./trim-event";
 
 interface AgentDefinition extends AgentInfo {
@@ -78,6 +79,8 @@ export function detectAgents(): ReadonlyArray<AgentDefinition> {
         claudeCode: {
           options: {
             allowedTools: BOARD_TOOL_NAMES.map((name) => `mcp__${BOARD_SERVER_NAME}__${name}`),
+            // canvas's own skills; the host's stay available beside them.
+            plugins: [{ type: "local", path: SKILLS_DIR, skipMcpDiscovery: true }],
           },
         },
       },
@@ -93,6 +96,8 @@ export function detectAgents(): ReadonlyArray<AgentDefinition> {
           model: opencodeModel,
           // Shell commands ask, so a person approves anything the agent runs.
           permission: { bash: "ask" },
+          // canvas's own skills; the host's stay available beside them.
+          skills: { paths: [SKILLS_DIR] },
         }),
       },
     },

package/src/server/board-mcp.ts

@@ -13,6 +13,10 @@
  * agent hears why a file can't be shown. It listens on loopback only: agents
  * run on this machine.
  *
+ * An agent's comment (ADR 0006) gets the text of its lines here, from the
+ * shared set: the browser keeps it to find the lines again as the file
+ * changes.
+ *
  * Scratch files (ADR 0005) never reach the browser as content: a call's
  * `content` becomes a file in `.canvas/scratch/` here, and the call goes on
  * with its path. Reading and writing them needs no board, so those tools are
@@ -22,8 +26,10 @@
 import { randomBytes } from "node:crypto";
 import type { McpServer } from "@agentclientprotocol/sdk";
 import { BOARD_SERVER_NAME, BOARD_TOOLS, boardInstructions } from "../shared/board-tools";
+import { linesOf, quoteOf } from "../shared/comments";
 import type { FileContent } from "../shared/protocol";
 import type { Scratch } from "./scratch";
+import type { Skill } from "./skills";
 
 export interface BoardCall {
   readonly callId: string;
@@ -38,6 +44,8 @@ export interface BoardMcpOptions {
   readonly scratch: Pick<Scratch, "create" | "write" | "read" | "list" | "remove">;
   /** Send a call to the host's browser; false if none is connected. */
   readonly relay: (call: BoardCall) => boolean;
+  /** canvas's skills, named in the priming. */
+  readonly skills?: ReadonlyArray<Skill>;
   readonly timeoutMs?: number;
 }
 
@@ -133,7 +141,7 @@ export class BoardMcp {
               : LATEST_PROTOCOL,
           capabilities: { tools: { listChanged: false } },
           serverInfo: { name: BOARD_SERVER_NAME, version: "0.0.0" },
-          instructions: boardInstructions(sessionId),
+          instructions: boardInstructions(sessionId, this.options.skills),
         });
       case "ping":
         return reply({});
@@ -179,6 +187,7 @@ export class BoardMcp {
         delete args.content;
         delete args.name;
       } else this.checkPath(args, notes);
+      if (tool === "add_comment") this.quote(args);
       if (Array.isArray(args.files))
         args.files = args.files.map((value: unknown) => {
           if (typeof value !== "object" || value === null)
@@ -235,6 +244,26 @@ export class BoardMcp {
     }
   }
 
+  /** An agent's comment carries the text of its lines. */
+  private quote(args: Record<string, unknown>) {
+    if (typeof args.path !== "string" || !args.path.trim())
+      throw new Error("a comment needs the path of the file it is on");
+    const path = args.path.trim().replace(/^(\.\/)+/, "");
+    const file = this.options.read(path);
+    if (file.kind !== "text")
+      throw new Error(
+        `${path} can't be commented on: ${file.kind === "denied" ? file.reason : file.kind}`,
+      );
+    const start = Math.floor(Number(args.start_line));
+    const end = args.end_line === undefined ? start : Math.floor(Number(args.end_line));
+    const quote = quoteOf(file.text, start, end);
+    if (quote === null)
+      throw new Error(
+        `lines ${start}-${end} aren't in ${path}: it has ${linesOf(file.text).length} lines`,
+      );
+    Object.assign(args, { path, start_line: start, end_line: end, quote });
+  }
+
   private relay(sessionId: string, tool: string, args: Record<string, unknown>) {
     const callId = crypto.randomUUID();
     const result = new Promise<ToolResult>((resolve) => {

package/src/server/server.ts

@@ -13,6 +13,7 @@ import { AgentManager, detectAgents } from "./agents";
 import { BoardMcp } from "./board-mcp";
 import { Files } from "./files";
 import { Scratch } from "./scratch";
+import { canvasSkills } from "./skills";
 import { Store } from "./store";
 import { Terminals } from "./terminals";
 
@@ -51,6 +52,7 @@ export async function serve(options: ServeOptions) {
       host.send(JSON.stringify({ t: "board-call", ...call } satisfies ServerToClient));
       return true;
     },
+    skills: canvasSkills(),
   });
   process.on("exit", () => boardMcp.stop());
 

package/src/server/skills.ts

@@ -0,0 +1,32 @@
+/**
+ * The skills canvas gives every agent session, shipped in `skills/` beside
+ * `src/` (finding 12). The folder is a Claude Code plugin (its manifest points
+ * `skills` at itself) and an opencode skills path at once; `agents.ts` hands
+ * it to each agent, which lists the skills beside the host's own.
+ *
+ * Claude drops skill descriptions from its listing once the host has many
+ * skills, so the board priming names them too (`boardInstructions`).
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export const SKILLS_DIR = resolve(import.meta.dir, "../../skills");
+
+export interface Skill {
+  readonly name: string;
+  readonly description: string;
+}
+
+/** Every skill in `dir`, from its `SKILL.md` frontmatter. */
+export function canvasSkills(dir: string = SKILLS_DIR): ReadonlyArray<Skill> {
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && !entry.name.startsWith("."))
+    .map((entry) => {
+      const text = readFileSync(join(dir, entry.name, "SKILL.md"), "utf8");
+      const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? "";
+      const field = (key: string) => new RegExp(`^${key}: (.+)$`, "m").exec(frontmatter)?.[1];
+      return { name: field("name") ?? entry.name, description: field("description") ?? "" };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}

package/src/shared/board-tools.ts

@@ -11,11 +11,15 @@
 
 export const BOARD_TOOL_NAMES = [
   "view_board",
+  "view_frame",
   "open_frame",
   "update_frame",
   "close_frame",
   "read_board_file",
   "write_board_file",
+  "add_comment",
+  "edit_comment",
+  "delete_comment",
 ] as const;
 export type BoardToolName = (typeof BOARD_TOOL_NAMES)[number];
 
@@ -72,6 +76,33 @@ export interface UpdateFrameArgs extends Placement, FileTarget, ScratchContent,
   readonly title?: string;
   readonly url?: string;
   readonly view?: "preview" | "source";
+  /** A comment's id: show its file at its lines. */
+  readonly comment?: string;
+}
+
+export interface ViewFrameArgs {
+  readonly frame: string;
+}
+
+export interface AddCommentArgs {
+  readonly frame: string;
+  readonly path: string;
+  readonly start_line: number;
+  readonly end_line?: number;
+  readonly body: string;
+  /** The lines' text, which `canvas serve` adds (ADR 0006). */
+  readonly quote?: string;
+}
+
+export interface EditCommentArgs {
+  readonly frame: string;
+  readonly comment: string;
+  readonly body: string;
+}
+
+export interface DeleteCommentArgs {
+  readonly frame: string;
+  readonly comment: string;
 }
 
 export interface CloseFrameArgs {
@@ -180,6 +211,18 @@ export const BOARD_TOOLS: ReadonlyArray<{
       },
     },
   },
+  {
+    name: "view_frame",
+    description:
+      "Look at one frame in full. For a file frame: what it shows, its list of files, and its " +
+      "comments — people's and agents' notes on lines of its files, with ids, authors and lines. " +
+      "view_board says which frames have comments.",
+    inputSchema: {
+      type: "object",
+      properties: { frame: { type: "string", description: "Id of the frame." } },
+      required: ["frame"],
+    },
+  },
   {
     name: "open_frame",
     description:
@@ -220,6 +263,10 @@ export const BOARD_TOOLS: ReadonlyArray<{
         ...scratchContent,
         ...fileList,
         view: { type: "string", enum: ["preview", "source"] },
+        comment: {
+          type: "string",
+          description: "file: a comment's id (view_frame) — show its file at its lines.",
+        },
         url: { type: "string" },
         title: { type: "string" },
         ...placement,
@@ -264,10 +311,58 @@ export const BOARD_TOOLS: ReadonlyArray<{
       required: ["content"],
     },
   },
+  {
+    name: "add_comment",
+    description:
+      "Comment on lines of a file, in a file frame: it shows below the lines for everyone, " +
+      "whatever file the frame shows. Markdown. The frame keeps it; people read it there.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame: { type: "string", description: "Id of the file frame." },
+        path: {
+          type: "string",
+          description: "The file, relative to the project root, or canvas:scratch/<name>.",
+        },
+        start_line: { type: "integer", minimum: 1 },
+        end_line: { type: "integer", minimum: 1, description: "Default: start_line." },
+        body: { type: "string", description: "The comment, markdown." },
+      },
+      required: ["frame", "path", "start_line", "body"],
+    },
+  },
+  {
+    name: "edit_comment",
+    description: "Rewrite a comment's text. Only agents' comments: people's are theirs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame: { type: "string", description: "Id of the file frame." },
+        comment: { type: "string", description: "The comment's id (view_frame)." },
+        body: { type: "string", description: "The new text, markdown." },
+      },
+      required: ["frame", "comment", "body"],
+    },
+  },
+  {
+    name: "delete_comment",
+    description: "Remove a comment. Only agents' comments: people's are theirs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame: { type: "string", description: "Id of the file frame." },
+        comment: { type: "string", description: "The comment's id (view_frame)." },
+      },
+      required: ["frame", "comment"],
+    },
+  },
 ];
 
 /** The agent's standing context, sent as MCP server instructions. */
-export function boardInstructions(frameId: string): string {
+export function boardInstructions(
+  frameId: string,
+  skills: ReadonlyArray<{ readonly name: string; readonly description: string }> = [],
+): string {
   return `You are running inside canvas: a shared, multiplayer board that people are looking at together, live. Its frames are coding-agent sessions, files of this project, browser previews and terminals. You are the agent in frame ${frameId}; people write prompts into it and read your replies there. Several people may prompt you.
 
 Frames that sit close together form a cluster: people keep related work together that way, and your own cluster is your workspace. Within a cluster frames sit in rows; frames in a row share a height.
@@ -284,5 +379,15 @@ The ${BOARD_SERVER_NAME} tools let you see and change the board: ${BOARD_TOOL_NA
 - Scratch files hold what exists only to be shown on this board: a write-up, a diagram, an HTML visualisation. Pass the text as \`content\` (with a \`name\`) to open_frame or update_frame, or use write_board_file; canvas keeps them outside the project, as canvas:scratch/<name>. Don't write such files into the project for the board. Anything else — a temp file for your own work, a script, test data — goes wherever it would without canvas.
 - Any agent may read (read_board_file) and overwrite (write_board_file) any scratch file; view_board lists them.
 - To show several files for one topic, prefer one file frame with a list (files) over a frame per file: people click through it at their own pace. You decide the tree: display paths, folders, order, line ranges. A write-up (a scratch file) at the top and a visualisation at the bottom fit in the same list.
-- Markdown and HTML files render. HTML runs its scripts, but relative links and assets (CSS, images, other scripts) don't load, so inline them.`;
+- People (and agents) comment on lines of files in a file frame. view_board says which frames have comments; view_frame lists them, with ids. You aren't told when someone comments: look when asked to, e.g. to address feedback. add_comment leaves one of yours; edit_comment and delete_comment change agents' comments, never people's. update_frame with a comment's id shows its file at its lines. A comment is "outdated" when its lines changed since; it shows what they were.
+- Markdown and HTML files render. HTML runs its scripts, but relative links and assets (CSS, images, other scripts) don't load, so inline them.${skillsSection(skills)}`;
+}
+
+/** canvas's own skills: the agent lists them, but may have dropped their descriptions. */
+function skillsSection(
+  skills: ReadonlyArray<{ readonly name: string; readonly description: string }>,
+): string {
+  if (skills.length === 0) return "";
+  const list = skills.map((skill) => `- ${skill.name}: ${skill.description}`).join("\n");
+  return `\n\ncanvas also gives you skills for work on the board. When one fits the request, load it with your skill tool before you start:\n${list}`;
 }

package/src/shared/comments.ts

@@ -0,0 +1,48 @@
+/**
+ * Comments on the lines of a file (ADR 0006). A comment keeps the lines it
+ * was written on as text, its quote: files change under it — agents edit them
+ * live — and the quote is how it finds its lines again, or knows it can't.
+ * Pure, so `canvas serve` (which quotes agents' comments) and the browser
+ * agree on what a line is.
+ */
+
+/** A file's lines as the frames number them: a final newline ends the last line. */
+export function linesOf(text: string): string[] {
+  const lines = text.split("\n");
+  if (lines.length > 1 && lines.at(-1) === "") lines.pop();
+  return lines;
+}
+
+/** Lines `start`–`end` (1-based, inclusive) of `text`; null if the file hasn't got them. */
+export function quoteOf(text: string, start: number, end: number): string | null {
+  const lines = linesOf(text);
+  if (start < 1 || end < start || end > lines.length) return null;
+  return lines.slice(start - 1, end).join("\n");
+}
+
+/**
+ * Where a quote is now: its old place if the lines there still read the same,
+ * else the nearest place they do. null if they're gone — the comment is
+ * outdated. A quote of blank lines only stays where it was: blank lines are
+ * everywhere, finding "them" elsewhere would be a guess.
+ */
+export function relocate(
+  text: string,
+  quote: string,
+  start: number,
+): { start: number; end: number } | null {
+  const lines = linesOf(text);
+  const wanted = quote.split("\n");
+  const at = (s: number) => wanted.every((line, i) => lines[s - 1 + i] === line);
+  const found = (s: number) => ({ start: s, end: s + wanted.length - 1 });
+  const last = lines.length - wanted.length + 1;
+  if (start >= 1 && start <= last && at(start)) return found(start);
+  if (!quote.trim()) return null;
+  for (let distance = 1; distance < Math.max(start, last); distance++) {
+    if (start - distance >= 1 && start - distance <= last && at(start - distance))
+      return found(start - distance);
+    if (start + distance >= 1 && start + distance <= last && at(start + distance))
+      return found(start + distance);
+  }
+  return null;
+}