@frebreco/canvas 0.0.1 → 0.2.0

package/src/server/trim-event.ts

@@ -0,0 +1,74 @@
+/**
+ * What of an agent event is worth keeping. Every event is stored, and sent
+ * to the host's browser and on to every guest that joins, so bulk nobody
+ * reads costs on every load:
+ *
+ *  - a text chunk repeats the whole message so far in `content`; the thread
+ *    is folded from `delta` alone, so the repeat goes;
+ *  - images a tool returns (a screenshot the agent read) stay as a
+ *    placeholder with their size;
+ *  - tool output and arguments are cut to their start and end.
+ */
+
+import type { AgentEvent } from "../shared/protocol";
+
+/** Longest tool output or argument string kept, in characters. */
+export const TOOL_TEXT_LIMIT = 4000;
+/** Of a cut string, how much of the end is kept (a command's errors are there). */
+const TAIL = 1000;
+
+/** The tool chunk fields that carry the tool's input or output. */
+const TOOL_FIELDS = ["content", "delta", "args", "input"] as const;
+
+export function trimEvent(event: AgentEvent): AgentEvent {
+  if (event.kind !== "chunk" || !isRecord(event.chunk)) return event;
+  const chunk = event.chunk;
+  if (chunk.type === "TEXT_MESSAGE_CONTENT" && "content" in chunk) {
+    const { content: _, ...rest } = chunk;
+    return { ...event, chunk: rest };
+  }
+  if (typeof chunk.type !== "string" || !chunk.type.startsWith("TOOL_CALL_")) return event;
+  let trimmed: Record<string, unknown> | null = null;
+  for (const field of TOOL_FIELDS) {
+    const value = chunk[field];
+    if (typeof value !== "string") continue;
+    const next = cut(field === "content" ? withoutImages(value) : value);
+    if (next !== value) (trimmed ??= { ...chunk })[field] = next;
+  }
+  return trimmed ? { ...event, chunk: trimmed } : event;
+}
+
+/** The start and end of a long string, and how much is missing between them. */
+function cut(text: string): string {
+  if (text.length <= TOOL_TEXT_LIMIT) return text;
+  const head = TOOL_TEXT_LIMIT - TAIL;
+  const missing = text.length - head - TAIL;
+  return `${text.slice(0, head)}\n… ${missing} characters cut …\n${text.slice(-TAIL)}`;
+}
+
+/** Tool output is a string, JSON when it has more than text: drop image data from it. */
+function withoutImages(content: string): string {
+  if (!content.includes('"image"')) return content;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return content;
+  }
+  let found = false;
+  const walk = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(walk);
+    if (!isRecord(value)) return value;
+    if (value.type === "image") {
+      found = true;
+      const size = JSON.stringify(value).length;
+      return { type: "image", omitted: `${Math.round(size / 1024)} KB` };
+    }
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, walk(v)]));
+  };
+  const next = walk(parsed);
+  return found ? JSON.stringify(next) : content;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);

package/src/server/web-url.ts

@@ -0,0 +1,18 @@
+/**
+ * The web app a host link opens, when neither `--web-url` nor `CANVAS_WEB_URL`
+ * says otherwise. The hosted UI speaks the same `protocol.ts` as the CLI of
+ * its release channel, so the default follows the version `canvas serve` runs
+ * as: `scripts/build-release.ts` stamps it into the published `package.json`;
+ * the repo's own manifest has none, which means a checkout and the Vite dev
+ * server.
+ */
+
+export const STABLE_WEB_URL = "https://ui.canvas.frebreco.de";
+export const NEXT_WEB_URL = `${STABLE_WEB_URL}/next`;
+export const DEV_WEB_URL = "http://localhost:4417";
+
+export function defaultWebUrl(version: string | undefined): string {
+  if (!version) return DEV_WEB_URL;
+  // semver: a pre-release is anything with a `-` suffix, here `X.Y.Z-next.N`.
+  return version.includes("-") ? NEXT_WEB_URL : STABLE_WEB_URL;
+}

package/src/shared/board-tools.ts

@@ -0,0 +1,172 @@
+/**
+ * The tools an agent gets to see and change the board (finding 06), and the
+ * priming that tells it what canvas is. `canvas serve` offers them over MCP;
+ * the host's browser runs them against the board (`web/lib/board-tools.ts`).
+ *
+ * The priming goes out as MCP server instructions: every agent shows those to
+ * its model next to — never instead of — its own system prompt, and none of
+ * it enters the thread. It is static per session (Claude records the system
+ * context once); what changes lives in tool results.
+ */
+
+export const BOARD_TOOL_NAMES = [
+  "view_board",
+  "open_frame",
+  "update_frame",
+  "close_frame",
+] as const;
+export type BoardToolName = (typeof BOARD_TOOL_NAMES)[number];
+
+/** The MCP server's name, as agents prefix its tools (`mcp__canvas__…`, `canvas_…`). */
+export const BOARD_SERVER_NAME = "canvas";
+
+export type FrameKind = "file" | "browser" | "terminal" | "agent";
+export type PlaceSide = "left" | "right" | "above" | "below";
+
+export interface ViewBoardArgs {
+  readonly scope?: "cluster" | "board";
+}
+
+interface Placement {
+  /** A frame id; the new or moved frame goes beside it. */
+  readonly next_to?: string;
+  readonly side?: PlaceSide;
+}
+
+interface FileTarget {
+  readonly path?: string;
+  readonly start_line?: number;
+  readonly end_line?: number;
+}
+
+export interface OpenFrameArgs extends Placement, FileTarget {
+  readonly type: FrameKind;
+  readonly title?: string;
+  readonly url?: string;
+  readonly agent?: string;
+  readonly draft?: string;
+}
+
+export interface UpdateFrameArgs extends Placement, FileTarget {
+  readonly frame: string;
+  readonly title?: string;
+  readonly url?: string;
+  readonly view?: "preview" | "source";
+}
+
+export interface CloseFrameArgs {
+  readonly frame: string;
+}
+
+const placement = {
+  next_to: {
+    type: "string",
+    description: "Id of a frame to place it beside. Default: in your own cluster.",
+  },
+  side: {
+    type: "string",
+    enum: ["right", "left", "below", "above"],
+    description:
+      "Side of `next_to`. right/left: same row, same height. below/above: a new row. Default right.",
+  },
+};
+
+const fileTarget = {
+  path: {
+    type: "string",
+    description: "File path relative to the project root, e.g. src/auth/session.ts.",
+  },
+  start_line: { type: "integer", minimum: 1, description: "First line to show and highlight." },
+  end_line: { type: "integer", minimum: 1, description: "Last highlighted line (inclusive)." },
+};
+
+export const BOARD_TOOLS: ReadonlyArray<{
+  readonly name: BoardToolName;
+  readonly description: string;
+  readonly inputSchema: Record<string, unknown>;
+}> = [
+  {
+    name: "view_board",
+    description:
+      "See what is on the canvas board: your own cluster row by row, and the other clusters. " +
+      "Every frame is listed with its id, type, title and what it shows. Look before you add.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        scope: {
+          type: "string",
+          enum: ["cluster", "board"],
+          description: "cluster (default): your cluster in full, others summarised. board: all.",
+        },
+      },
+    },
+  },
+  {
+    name: "open_frame",
+    description:
+      "Open a new frame on the board, in your own cluster unless placed next to another frame. " +
+      "file: a project file (read-only, live), optionally at a line range which gets highlighted. " +
+      "browser: a URL, loaded by each viewer's own browser. terminal: an idle shell people can " +
+      "type into. agent: another agent session; `draft` pre-fills its prompt, a person sends it.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: { type: "string", enum: ["file", "browser", "terminal", "agent"] },
+        ...fileTarget,
+        url: { type: "string", description: "browser: an http(s) URL." },
+        agent: { type: "string", description: "agent: which agent runs it (see view_board)." },
+        draft: { type: "string", description: "agent: a prompt draft for people to send." },
+        title: { type: "string", description: "Frame title. Default: from what it shows." },
+        ...placement,
+      },
+      required: ["type"],
+    },
+  },
+  {
+    name: "update_frame",
+    description:
+      "Change a frame: point a file frame at another file or line range, switch a markdown " +
+      "or HTML file between preview and source, change a browser frame's URL, rename a frame, or move " +
+      "it next to another frame.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        frame: { type: "string", description: "Id of the frame to change." },
+        ...fileTarget,
+        view: { type: "string", enum: ["preview", "source"] },
+        url: { type: "string" },
+        title: { type: "string" },
+        ...placement,
+      },
+      required: ["frame"],
+    },
+  },
+  {
+    name: "close_frame",
+    description:
+      "Remove a frame from the board. Only close frames you opened, unless someone asks you to.",
+    inputSchema: {
+      type: "object",
+      properties: { frame: { type: "string", description: "Id of the frame to close." } },
+      required: ["frame"],
+    },
+  },
+];
+
+/** The agent's standing context, sent as MCP server instructions. */
+export function boardInstructions(frameId: 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.
+
+The ${BOARD_SERVER_NAME} tools let you see and change the board: ${BOARD_TOOL_NAMES.join(", ")}. Use them when showing something on the board helps the people you work with — e.g. asked to show the files relevant to a topic, open them as file frames at the relevant lines instead of pasting code. Don't use them when a plain answer is enough.
+
+- Look first (view_board). Reuse or retarget a frame (update_frame) rather than open a duplicate.
+- New frames go into your cluster by default; that is almost always right. Keep it to a handful per request.
+- Don't change or close frames other people opened unless asked. Frames you opened are marked as yours.
+- File frames are read-only and live: they show a file as it is on disk, so they follow your edits. Only files git doesn't ignore can be shown, never secrets.
+- A terminal frame is an idle shell for people; you cannot type into it. Run commands with your own tools.
+- An agent frame starts another agent. You can leave a draft prompt in it; only a person can send it.
+- A browser frame loads its URL in each viewer's own browser, so localhost means their machine, not this one: only the host sees a localhost URL, guests get a notice.
+- To show a page you wrote to everyone, open the HTML file as a file frame: it renders, scripts included, but relative links and assets (CSS, images, other scripts) don't load, so inline them.`;
+}

package/src/shared/layout.ts

@@ -0,0 +1,256 @@
+/**
+ * The board's layout rules, as pure geometry.
+ *
+ * Frame positions stay the only truth (the board doc stores x, y, w, h);
+ * structure is read off them:
+ *
+ *   cluster  frames within `NEAR` of each other, transitively — what people
+ *            group together belongs together
+ *   row      frames of a cluster whose top edges line up, left to right
+ *
+ * Placing a frame (by a person's drop or an agent's tool call) returns the
+ * new frame's rect and patches for the frames that make room: frames later in
+ * the row shift right, rows further down shift down. Nothing outside the
+ * anchor's cluster moves. Anything placed away from other frames stays free.
+ */
+
+export interface Rect {
+  readonly id: string;
+  readonly x: number;
+  readonly y: number;
+  readonly w: number;
+  readonly h: number;
+}
+
+export type Box = Omit<Rect, "id">;
+export type Size = Pick<Rect, "w" | "h">;
+export type Patch = { readonly id: string } & Partial<Box>;
+export type Side = "left" | "right" | "above" | "below";
+export interface Target {
+  readonly anchor: string;
+  readonly side: Side;
+}
+
+export interface Cluster<R extends Rect = Rect> {
+  /** The smallest frame id in it: stable while that frame stays. */
+  readonly id: string;
+  readonly frames: ReadonlyArray<R>;
+  /** Top to bottom; each left to right. */
+  readonly rows: ReadonlyArray<ReadonlyArray<R>>;
+  readonly bounds: Box;
+}
+
+/** Space between frames in a cluster. */
+export const GAP = 24;
+/** Frames this close (or closer) are one cluster. */
+export const NEAR = 48;
+/** Top edges this close are one row. */
+const ROW_TOLERANCE = 16;
+
+/** Empty space between two rects along each axis (0 when they overlap on it). */
+function gaps(a: Box, b: Box) {
+  return {
+    x: Math.max(0, Math.max(a.x, b.x) - Math.min(a.x + a.w, b.x + b.w)),
+    y: Math.max(0, Math.max(a.y, b.y) - Math.min(a.y + a.h, b.y + b.h)),
+  };
+}
+
+const near = (a: Box, b: Box) => {
+  const g = gaps(a, b);
+  return g.x <= NEAR && g.y <= NEAR;
+};
+
+export function clusters<R extends Rect>(rects: ReadonlyArray<R>): Cluster<R>[] {
+  const seen = new Set<string>();
+  const found: Cluster<R>[] = [];
+  for (const start of rects) {
+    if (seen.has(start.id)) continue;
+    seen.add(start.id);
+    const members = [start];
+    for (let i = 0; i < members.length; i++)
+      for (const other of rects)
+        if (!seen.has(other.id) && near(members[i]!, other)) {
+          seen.add(other.id);
+          members.push(other);
+        }
+    found.push(cluster(members));
+  }
+  return found.sort((a, b) => a.bounds.y - b.bounds.y || a.bounds.x - b.bounds.x);
+}
+
+function cluster<R extends Rect>(members: R[]): Cluster<R> {
+  const rows: R[][] = [];
+  for (const frame of [...members].sort((a, b) => a.y - b.y || a.x - b.x)) {
+    const row = rows.at(-1);
+    if (row && Math.abs(frame.y - row[0]!.y) <= ROW_TOLERANCE) row.push(frame);
+    else rows.push([frame]);
+  }
+  for (const row of rows) row.sort((a, b) => a.x - b.x);
+  const x = Math.min(...members.map((f) => f.x));
+  const y = Math.min(...members.map((f) => f.y));
+  return {
+    id: members.map((f) => f.id).sort()[0]!,
+    frames: members,
+    rows,
+    bounds: {
+      x,
+      y,
+      w: Math.max(...members.map((f) => f.x + f.w)) - x,
+      h: Math.max(...members.map((f) => f.y + f.h)) - y,
+    },
+  };
+}
+
+/** The cluster and row a frame is in. */
+export function locate<R extends Rect>(rects: ReadonlyArray<R>, id: string) {
+  for (const c of clusters(rects)) {
+    const row = c.rows.find((r) => r.some((f) => f.id === id));
+    if (row) return { cluster: c, row, frame: row.find((f) => f.id === id)! };
+  }
+  throw new Error(`no frame ${id}`);
+}
+
+const rowBottom = (row: ReadonlyArray<Rect>) => Math.max(...row.map((f) => f.y + f.h));
+
+/** Where a new frame of `size` goes next to `target.anchor`, and what moves for it. */
+export function placeNew(
+  rects: ReadonlyArray<Rect>,
+  target: Target,
+  size: Size,
+): { rect: Box; patches: Patch[] } {
+  const { cluster: c, row, frame: anchor } = locate(rects, target.anchor);
+  switch (target.side) {
+    case "right":
+    case "left": {
+      const rect = {
+        x: target.side === "right" ? anchor.x + anchor.w + GAP : anchor.x,
+        y: anchor.y,
+        w: size.w,
+        h: anchor.h,
+      };
+      const moves = (f: Rect) => (target.side === "right" ? f.x > anchor.x : f.x >= anchor.x);
+      return {
+        rect,
+        patches: row.filter(moves).map((f) => ({ id: f.id, x: f.x + size.w + GAP })),
+      };
+    }
+    case "below":
+    case "above": {
+      const y = target.side === "below" ? rowBottom(row) + GAP : row[0]!.y;
+      const from = target.side === "below" ? rowBottom(row) : y;
+      return {
+        rect: { x: anchor.x, y, w: size.w, h: size.h },
+        patches: c.frames
+          .filter((f) => f.y >= from)
+          .map((f) => ({ id: f.id, y: f.y + size.h + GAP })),
+      };
+    }
+  }
+}
+
+/**
+ * Where an agent's new frame goes: its own cluster, without running into
+ * another cluster — the end of its row, else a row under it, else under the
+ * whole cluster (taken even if it touches another cluster).
+ */
+export function placeNear(
+  rects: ReadonlyArray<Rect>,
+  selfId: string,
+  size: Size,
+): { rect: Box; patches: Patch[] } {
+  const { cluster: c, row } = locate(rects, selfId);
+  const bottom = {
+    rect: { x: c.bounds.x, y: c.bounds.y + c.bounds.h + GAP, ...size },
+    patches: [],
+  };
+  const candidates = [
+    placeNew(rects, { anchor: row.at(-1)!.id, side: "right" }, size),
+    placeNew(rects, { anchor: row[0]!.id, side: "below" }, size),
+    bottom,
+  ];
+  const inCluster = new Set(c.frames.map((f) => f.id));
+  const outside = rects.filter((f) => !inCluster.has(f.id));
+  return (
+    candidates.find(({ rect, patches }) => {
+      const moved = [rect, ...applyPatches(c.frames, patches)];
+      return !moved.some((m) => outside.some((o) => near(m, o)));
+    }) ?? bottom
+  );
+}
+
+/** A frame leaves its row: the frames after it close the gap. */
+export function lift(rects: ReadonlyArray<Rect>, id: string): Patch[] {
+  const { row, frame } = locate(rects, id);
+  return row.filter((f) => f.x > frame.x).map((f) => ({ id: f.id, x: f.x - frame.w - GAP }));
+}
+
+/** Where a frame being dragged would snap to: next to the nearest frame within reach. */
+export function snapTarget(rects: ReadonlyArray<Rect>, movingId: string): Target | null {
+  const moving = rects.find((f) => f.id === movingId);
+  if (!moving) return null;
+  const centre = (f: Box) => ({ x: f.x + f.w / 2, y: f.y + f.h / 2 });
+  const mc = centre(moving);
+  let best: { frame: Rect; distance: number; gap: number } | null = null;
+  for (const frame of rects) {
+    if (frame.id === movingId || !near(moving, frame)) continue;
+    const g = gaps(moving, frame);
+    const fc = centre(frame);
+    const distance = Math.hypot(mc.x - fc.x, mc.y - fc.y);
+    const gap = g.x + g.y;
+    if (!best || gap < best.gap || (gap === best.gap && distance < best.distance))
+      best = { frame, distance, gap };
+  }
+  if (!best) return null;
+  const fc = centre(best.frame);
+  const dx = (mc.x - fc.x) / ((best.frame.w + moving.w) / 2);
+  const dy = (mc.y - fc.y) / ((best.frame.h + moving.h) / 2);
+  const side: Side =
+    Math.abs(dx) >= Math.abs(dy) ? (dx >= 0 ? "right" : "left") : dy >= 0 ? "below" : "above";
+  return { anchor: best.frame.id, side };
+}
+
+/** Move an existing frame next to `target`: it leaves its row, then is placed like a new one. */
+export function moveFrame(rects: ReadonlyArray<Rect>, id: string, target: Target): Patch[] {
+  const frame = rects.find((f) => f.id === id);
+  if (!frame) throw new Error(`no frame ${id}`);
+  const lifted = lift(rects, id);
+  const rest = applyPatches(rects, lifted).filter((f) => f.id !== id);
+  const { rect, patches } = placeNew(rest, target, frame);
+  return merge([...lifted, ...patches, { id, ...rect }]);
+}
+
+/**
+ * Resize a frame and keep its row a row: the others take its height, the
+ * frames to its right follow its width, and rows below move with the row's
+ * bottom edge.
+ */
+export function resizeInRow(rects: ReadonlyArray<Rect>, id: string, size: Size): Patch[] {
+  const { cluster: c, row, frame } = locate(rects, id);
+  const patches: Patch[] = [{ id, w: size.w, h: size.h }];
+  if (row.length === 1) return patches;
+  const dw = size.w - frame.w;
+  for (const f of row)
+    if (f.id !== id)
+      patches.push(f.x > frame.x ? { id: f.id, x: f.x + dw, h: size.h } : { id: f.id, h: size.h });
+  const before = rowBottom(row);
+  const after = rowBottom(applyPatches(row, patches));
+  if (after !== before)
+    for (const f of c.frames)
+      if (!row.includes(f) && f.y >= before) patches.push({ id: f.id, y: f.y + after - before });
+  return patches;
+}
+
+export function applyPatches<R extends Rect>(
+  rects: ReadonlyArray<R>,
+  patches: ReadonlyArray<Patch>,
+): R[] {
+  const byId = new Map(merge(patches).map((p) => [p.id, p]));
+  return rects.map((r) => (byId.has(r.id) ? { ...r, ...byId.get(r.id) } : r));
+}
+
+/** One patch per frame; later patches win field by field. */
+function merge(patches: ReadonlyArray<Patch>): Patch[] {
+  const byId = new Map<string, Patch>();
+  for (const patch of patches) byId.set(patch.id, { ...byId.get(patch.id), ...patch });
+  return [...byId.values()];
+}