bytespost-canvas 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bytespost
+
+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

@@ -0,0 +1,102 @@
+# bytespost-canvas
+
+> Local CLI + MCP server for the [bytespost canvas](https://app.bytespost.com) — drive a running canvas tab from your terminal or any AI agent (Claude Code, Cursor, etc.).
+
+## What it is
+
+`bytespost-canvas` runs a tiny localhost daemon (HTTP + WebSocket hub) that bridges your terminal / AI agent and a canvas tab open in your browser. Once the daemon is up and the canvas tab is connected:
+
+- The CLI sends commands (draw a rectangle, capture a screenshot, query the document, set selection, …).
+- The daemon relays them over WebSocket to the canvas page.
+- The page executes them in the live editor and streams back results (node IDs, PNG bytes, JSON document state).
+
+It also exposes an **MCP (Model Context Protocol) stdio server** so AI agents that speak MCP can talk to your canvas with no glue code.
+
+## Install
+
+```bash
+# Global install — gives you the `canvas` binary
+npm install -g bytespost-canvas
+
+# Or run without installing
+npx bytespost-canvas --help
+```
+
+Three binaries ship, all aliasing the same CLI: `canvas`, `canvas-bridge`, `canvasd`.
+
+## Quick start
+
+```bash
+# 1. Start the daemon (it stays in the foreground)
+canvas serve
+
+# 2. In your browser, open https://app.bytespost.com and edit any project.
+#    The page auto-connects to the daemon on http://127.0.0.1:7777.
+
+# 3. From any other terminal, run commands
+canvas ls                              # list connected tabs
+canvas screenshot -o canvas.png        # capture the active tab
+canvas draw rect --x 100 --y 100 --width 200 --height 120 --fill "#7c3aed"
+canvas document get                    # dump the IR JSON
+canvas select set --node-id <id>       # set selection
+```
+
+`canvas <command> --help` prints command-specific flags. `canvas --json` returns stable machine-readable JSON for any command — pipe straight into `jq`.
+
+## MCP mode (for Claude Code / Cursor / any MCP client)
+
+```bash
+canvas mcp     # speaks MCP over stdio
+```
+
+Register it in your AI agent's MCP config. Sample for Claude Code:
+
+```jsonc
+// ~/.claude/config.json
+{
+  "mcpServers": {
+    "canvas": {
+      "command": "canvas",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+The agent then sees tools for every canvas command (`canvas_draw_rect`, `canvas_screenshot`, `canvas_document_get`, …) and can compose them autonomously.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `serve` / `start` | Run the daemon (foreground). |
+| `mcp` | Run an MCP stdio server. |
+| `status` / `health` | Daemon + connected-tab health. |
+| `ls` | List open canvas tabs. |
+| `tab info` | Show tab metadata. |
+| `document get` | Dump the full document IR. |
+| `document nodes` | List node IDs by type / filter. |
+| `draw` | Create a node from a JSON spec. |
+| `draw rect / frame / text / line` | Convenience helpers for the common shapes. |
+| `node get / update / delete` | Read or mutate a single node. |
+| `select set / clear` | Drive the selection. |
+| `viewport screenshot` / `screenshot` | PNG bytes of the active tab. |
+| `viewport fit / zoom` | Pan/zoom the camera. |
+| `building` | Building-3D plugin shortcuts (wall / slab / window / door / …). |
+
+## Configuration
+
+- Daemon port: `CANVAS_BRIDGE_PORT` (default `7777`).
+- All commands accept `--tab <id>` when multiple canvas tabs are connected; with exactly one, it's optional.
+
+## Architecture (one sentence)
+
+```
+your CLI ──HTTP──> daemon ──WebSocket──> canvas tab in browser
+                       │
+                       └── MCP stdio (for AI agents)
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * canvas-bridge CLI (SLICE 1 + 2).
+ *
+ *   canvas-bridge serve                  start the daemon (blocks)
+ *   canvas-bridge health                 GET /v1/health, print JSON
+ *   canvas-bridge ls                     GET /v1/tabs
+ *   canvas-bridge screenshot -o <file>   GET /v1/screenshot, write PNG
+ *   canvas-bridge draw <json|file>       POST /v1/draw, print {nodeIds}
+ *   canvas-bridge draw rect --x ...      POST /v1/draw with a typed spec
+ *
+ * `draw` takes either an inline JSON string (a `{nodes:[...]}` body, or a bare
+ * array of specs) or a path to a .json file containing the same.
+ *
+ * Talks to the daemon over plain localhost HTTP. Intentionally tiny.
+ */
+export {};