@frebreco/canvas 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreshlyBrewedCode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,50 @@
-Placeholder for `@frebreco/canvas`. See https://github.com/FreshlyBrewedCode/canvas.
+# canvas
+
+**A multiplayer canvas whose frames are coding-agent sessions, files, browser previews and
+terminals.** The agents run on one person's machine; everyone else joins peer to peer from the
+browser.
+
+```bash
+cd your-project
+bunx @frebreco/canvas serve
+```
+
+`canvas serve` prints a host link. Open it, then share the guest link from the board. Requires
+[Bun](https://bun.sh) and at least one ACP agent: `claude` (Claude Code) or `opencode`.
+
+Docs: **[canvas.frebreco.de](https://canvas.frebreco.de)** —
+[quick start](https://canvas.frebreco.de/docs/quick-start),
+[security](https://canvas.frebreco.de/docs/security),
+[architecture](https://canvas.frebreco.de/docs/architecture).
+
+> **A prototype.** canvas is proving a concept, not hardened. The host link controls agents on
+> your machine: never share it. Read [security](https://canvas.frebreco.de/docs/security) before
+> inviting anyone you would not hand a shell.
+
+## Releases
+
+| Channel  | Install                         | Web app                              |
+| -------- | ------------------------------- | ------------------------------------ |
+| `latest` | `bunx @frebreco/canvas serve`   | https://ui.canvas.frebreco.de        |
+| `next`   | `bunx @frebreco/canvas@next serve` | https://ui.canvas.frebreco.de/next |
+
+Every merge to `main` publishes a `next` pre-release; stable releases are cut by hand. Each channel
+opens the web app built from the same commit, so both halves speak the same protocol.
+
+## Development
+
+```bash
+bun install
+bun run dev                          # the web app, Vite on :4417
+bun src/cli.ts serve --dir <project> # the local server, prints a link to :4417
+bun run check                        # format, lint, typecheck, test
+```
+
+`AGENTS.md` is the repo guide; `docs/adr/` holds the decisions, `docs/findings/` the evidence,
+`site/` the landing page and docs. Commits and PR titles follow
+[Conventional Commits](https://www.conventionalcommits.org): PRs are squash-merged and their title
+decides the next version.
+
+## License
+
+MIT

package/bin/canvas.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env bun
+/**
+ * The published launcher for `canvas`. The shebang asks for `bun`, and both
+ * `bunx` and `npx` honor a bin's shebang, so this normally runs under Bun and
+ * hands straight over to the raw-TypeScript CLI.
+ *
+ * It is plain JavaScript so it can still say something useful when Node runs
+ * it anyway (`node bin/canvas.js`, or a package manager that ignores the
+ * shebang): Node cannot execute the TypeScript behind it, and a syntax error
+ * would not tell anyone that Bun is what is missing.
+ *
+ * Do not give this file a `#!/usr/bin/env node` shebang: `bunx` honors it too,
+ * which would route every `bunx @frebreco/canvas` through Node.
+ */
+
+if (typeof Bun === "undefined") {
+  console.error(
+    [
+      "",
+      "  canvas requires Bun.",
+      "",
+      "  This package ships raw TypeScript and runs on the Bun runtime.",
+      "  Install Bun:  https://bun.sh/docs/installation",
+      "  Then run:     bunx @frebreco/canvas serve",
+      "",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
+await import("../src/cli.ts");

package/package.json

@@ -1,7 +1,31 @@
 {
   "name": "@frebreco/canvas",
-  "version": "0.0.1",
-  "description": "Placeholder that reserves this name before the first real release.",
+  "version": "0.2.0",
+  "description": "A multiplayer canvas for coding agents that run on your machine.",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/FreshlyBrewedCode/canvas.git" }
+  "type": "module",
+  "bin": {
+    "canvas": "bin/canvas.js"
+  },
+  "engines": {
+    "bun": ">=1.4.1"
+  },
+  "homepage": "https://canvas.frebreco.de",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FreshlyBrewedCode/canvas.git"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@agentclientprotocol/claude-agent-acp": "^0.81.2",
+    "@agentclientprotocol/sdk": "^1.5.0",
+    "@tanstack/ai": "^0.61.0",
+    "@tanstack/ai-acp": "^0.3.17",
+    "@tanstack/ai-sandbox": "^0.5.15"
+  }
 }

package/src/cli.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+/**
+ * canvas — a multiplayer canvas for coding agents that run on your machine.
+ *
+ *   canvas serve [--dir .] [--port 4418] [--web-url URL] [--tls-host NAME]
+ *
+ * Starts the local server and prints the link that opens the board as its
+ * host. `--tls-host` serves wss:// on that name (with `.certs/dev.{crt,key}`)
+ * so a browser on another device can be the host; without it
+ * the server only listens on loopback.
+ */
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { serve } from "./server/server";
+import { defaultWebUrl } from "./server/web-url";
+
+const manifest = (await Bun.file(join(import.meta.dir, "../package.json")).json()) as {
+  version?: string;
+};
+
+const { positionals, values } = parseArgs({
+  allowPositionals: true,
+  options: {
+    dir: { type: "string", default: "." },
+    port: { type: "string", default: "4418" },
+    "web-url": {
+      type: "string",
+      default: process.env.CANVAS_WEB_URL ?? defaultWebUrl(manifest.version),
+    },
+    "tls-host": { type: "string" },
+    cert: { type: "string", default: join(import.meta.dir, "../.certs/dev.crt") },
+    key: { type: "string", default: join(import.meta.dir, "../.certs/dev.key") },
+  },
+});
+
+if (positionals[0] !== "serve") {
+  console.log("usage: canvas serve [--dir .] [--port 4418] [--web-url URL] [--tls-host NAME]");
+  process.exit(positionals.length === 0 ? 0 : 1);
+}
+
+const dir = resolve(values.dir);
+const tlsHost = values["tls-host"];
+if (tlsHost && !(existsSync(values.cert) && existsSync(values.key))) {
+  console.error(
+    `--tls-host needs a certificate: tailscale cert --cert-file ${values.cert} --key-file ${values.key} ${tlsHost}`,
+  );
+  process.exit(1);
+}
+
+const { server, room } = await serve({
+  dir,
+  port: Number(values.port),
+  hostname: tlsHost ? "0.0.0.0" : "127.0.0.1",
+  ...(tlsHost && { tls: { cert: values.cert, key: values.key } }),
+});
+
+const serverUrl = tlsHost ? `wss://${tlsHost}:${server.port}` : `ws://127.0.0.1:${server.port}`;
+// Secrets ride in the fragment, which browsers never send to the web host.
+const fragment = new URLSearchParams({
+  k: room.key,
+  pk: room.hostPublicKey,
+  server: serverUrl,
+  token: room.token,
+});
+const link = `${values["web-url"].replace(/\/$/, "")}/?room=${room.roomId}#${fragment}`;
+
+console.log(`canvas serving ${dir}`);
+console.log(`\n  open the board as host:\n  ${link}\n`);
+console.log("  keep this link to yourself — it controls agents on this machine.");
+console.log("  share the guest link from the board instead.\n");

package/src/server/agent-config.ts

@@ -0,0 +1,82 @@
+/**
+ * ACP session config options (`session/new` → `configOptions`,
+ * `session/set_config_option`, `config_option_update`) mapped to canvas's
+ * wire shape (finding 04). Agents decide which options exist — Claude Code
+ * adds `effort` and `fast` only for models that support them, opencode lists
+ * every model its providers offer — so nothing here knows specific ids.
+ */
+
+import type { SessionConfigOption } from "@agentclientprotocol/sdk";
+import type {
+  AgentConfigChoice,
+  AgentConfigOption,
+  AgentConfigValue,
+  AgentSetting,
+} from "../shared/protocol";
+
+export function fromAcp(options: ReadonlyArray<SessionConfigOption>): AgentConfigOption[] {
+  return options.map((option) => {
+    const base = {
+      id: option.id,
+      name: option.name,
+      ...(option.description && { description: option.description }),
+      ...(option.category && { category: option.category }),
+    };
+    if (option.type === "boolean")
+      return { ...base, type: "boolean", value: option.currentValue, choices: [] };
+    const choices: AgentConfigChoice[] = [];
+    for (const entry of option.options) {
+      if ("group" in entry)
+        for (const choice of entry.options)
+          choices.push({ ...choiceOf(choice), group: entry.name });
+      else choices.push(choiceOf(entry));
+    }
+    return { ...base, type: "select", value: option.currentValue, choices };
+  });
+}
+
+const choiceOf = (choice: { value: string; name: string; description?: string | null }) => ({
+  value: choice.value,
+  name: choice.name,
+  ...(choice.description && { description: choice.description }),
+});
+
+export function settingsOf(options: ReadonlyArray<AgentConfigOption>): AgentSetting[] {
+  return options.map((option) => ({
+    id: option.id,
+    name: option.name,
+    ...(option.category && { category: option.category }),
+    value: option.value,
+    label: labelOf(option, option.value),
+  }));
+}
+
+export function labelOf(option: AgentConfigOption, value: AgentConfigValue): string {
+  if (typeof value === "boolean") return value ? "on" : "off";
+  return option.choices.find((choice) => choice.value === value)?.name ?? value;
+}
+
+/**
+ * Which of the wanted settings still differ from what the agent reports, in
+ * the order to apply them: the model first, since it decides which other
+ * options exist and what they accept. Values an option does not offer (any
+ * more) are skipped rather than sent.
+ */
+export function pendingChanges(
+  options: ReadonlyArray<AgentConfigOption>,
+  wanted: ReadonlyArray<Pick<AgentSetting, "id" | "value">>,
+): Array<{ id: string; value: AgentConfigValue }> {
+  const byId = new Map(options.map((option) => [option.id, option]));
+  return wanted
+    .filter(({ id, value }) => {
+      const option = byId.get(id);
+      if (!option || option.value === value) return false;
+      return option.type === "boolean"
+        ? typeof value === "boolean"
+        : option.choices.some((choice) => choice.value === value);
+    })
+    .map(({ id, value }) => ({ id, value }))
+    .sort((a, b) => rank(byId.get(a.id)!) - rank(byId.get(b.id)!));
+}
+
+const rank = (option: AgentConfigOption) => (option.category === "model" ? 0 : 1);