bytespost-canvas 0.1.0

package/dist/commandRegistry.d.ts

@@ -0,0 +1,44 @@
+export type FlagType = 'boolean' | 'string' | 'number' | 'json' | 'file';
+export interface FlagSpec {
+    name: string;
+    alias?: string;
+    type: FlagType;
+    valueName?: string;
+    required?: boolean | 'when-multiple-tabs';
+    description: string;
+}
+export interface ExampleSpec {
+    command: string;
+    description?: string;
+}
+export interface AiSpec {
+    supported: boolean;
+    safety: 'read' | 'write' | 'destructive' | 'daemon';
+    operation: string;
+    context: string[];
+}
+export interface CommandSpec {
+    path: string[];
+    summary: string;
+    description: string;
+    usage: string;
+    args?: Array<{
+        name: string;
+        required?: boolean;
+        description: string;
+    }>;
+    flags?: FlagSpec[];
+    examples?: ExampleSpec[];
+    output?: string;
+    ai?: AiSpec;
+}
+export declare const GLOBAL_FLAGS: FlagSpec[];
+export declare const COMMAND_SPECS: CommandSpec[];
+export declare function findCommandSpec(positionals: string[]): {
+    spec: CommandSpec | null;
+    consumed: number;
+};
+export declare function getTopLevelCommands(): Array<{
+    name: string;
+    summary: string;
+}>;

package/dist/commandRegistry.js

@@ -0,0 +1,301 @@
+export const GLOBAL_FLAGS = [
+    { name: 'help', alias: 'h', type: 'boolean', description: 'Show command help and exit.' },
+    { name: 'json', type: 'boolean', description: 'Print stable machine-readable JSON output.' },
+    { name: 'ai', type: 'string', valueName: 'mode', description: 'Plan with the AI command compiler. Modes: plan, auto, explain.' },
+    { name: 'prompt', type: 'string', valueName: 'text', description: 'Natural-language instruction for --ai. Use -- for long free-form text.' },
+    { name: 'prompt-file', type: 'file', valueName: 'path', description: 'Read --ai instruction text from a UTF-8 file. Use - for stdin.' },
+    { name: 'dry-run', type: 'boolean', description: 'Resolve the command without mutating the canvas.' },
+    { name: 'yes', type: 'boolean', description: 'Confirm high-risk AI plans when supported.' },
+];
+const TAB_FLAG = {
+    name: 'tab',
+    type: 'string',
+    valueName: 'id',
+    required: 'when-multiple-tabs',
+    description: 'Target canvas tab. Optional only when exactly one tab is connected.',
+};
+const OUTPUT_FLAG = {
+    name: 'output',
+    alias: 'o',
+    type: 'file',
+    valueName: 'path',
+    required: true,
+    description: 'Write binary output to this file.',
+};
+const HEX_FLAG = (name, description) => ({
+    name,
+    type: 'string',
+    valueName: 'hex',
+    description,
+});
+const NUMBER_FLAG = (name, description, required = false) => ({
+    name,
+    type: 'number',
+    valueName: 'n',
+    required,
+    description,
+});
+export const COMMAND_SPECS = [
+    {
+        path: ['start'],
+        summary: 'Start the local canvas daemon.',
+        description: 'Starts the localhost daemon that browser tabs connect to over WebSocket.',
+        usage: 'canvas start',
+        examples: [{ command: 'canvasd start' }, { command: 'canvas start' }],
+        output: 'Logs the daemon URL and keeps running.',
+        ai: { supported: false, safety: 'daemon', operation: 'daemon.start', context: [] },
+    },
+    {
+        path: ['serve'],
+        summary: 'Alias for start.',
+        description: 'Compatibility alias for canvas start.',
+        usage: 'canvas serve',
+        examples: [{ command: 'canvas-bridge serve' }],
+        output: 'Logs the daemon URL and keeps running.',
+        ai: { supported: false, safety: 'daemon', operation: 'daemon.start', context: [] },
+    },
+    {
+        path: ['mcp'],
+        summary: 'Run the MCP stdio server.',
+        description: 'Exposes the same local canvas control plane as MCP tools over stdio.',
+        usage: 'canvas mcp',
+        examples: [{ command: 'canvas mcp' }],
+        output: 'MCP stdio stream.',
+        ai: { supported: false, safety: 'daemon', operation: 'daemon.mcp', context: [] },
+    },
+    {
+        path: ['status'],
+        summary: 'Show daemon and tab connection health.',
+        description: 'Checks the localhost daemon and reports how many canvas tabs are connected.',
+        usage: 'canvas status [--json]',
+        examples: [{ command: 'canvas status --json' }],
+        output: '{ canvasConnected, tabCount, version }',
+        ai: { supported: true, safety: 'read', operation: 'daemon.health', context: ['tabs'] },
+    },
+    {
+        path: ['health'],
+        summary: 'Alias for status.',
+        description: 'Compatibility alias for canvas status.',
+        usage: 'canvas health [--json]',
+        examples: [{ command: 'canvas health --json' }],
+        output: '{ canvasConnected, tabCount, version }',
+        ai: { supported: true, safety: 'read', operation: 'daemon.health', context: ['tabs'] },
+    },
+    {
+        path: ['ls'],
+        summary: 'List open canvas tabs.',
+        description: 'Lists every browser editor tab connected to the local daemon.',
+        usage: 'canvas ls [--json]',
+        examples: [{ command: 'canvas ls' }, { command: 'canvas ls --json' }],
+        output: '{ tabs: CanvasTabInfo[] }',
+        ai: { supported: true, safety: 'read', operation: 'tabs.list', context: ['tabs'] },
+    },
+    {
+        path: ['tab', 'info'],
+        summary: 'Show one tab.',
+        description: 'Prints metadata for a connected canvas tab.',
+        usage: 'canvas tab info <tab> [--json]',
+        args: [{ name: 'tab', required: true, description: 'Connected tab id from canvas ls.' }],
+        examples: [{ command: 'canvas tab info tab_abc123 --json' }],
+        output: '{ tab: CanvasTabInfo }',
+        ai: { supported: true, safety: 'read', operation: 'tabs.info', context: ['tabs'] },
+    },
+    {
+        path: ['document', 'get'],
+        summary: 'Read the active document.',
+        description: 'Returns the full active document from one canvas tab.',
+        usage: 'canvas document get --tab <tab> [--json]',
+        flags: [TAB_FLAG],
+        examples: [{ command: 'canvas document get --tab tab_abc123 --json' }],
+        output: '{ document }',
+        ai: { supported: true, safety: 'read', operation: 'document.get', context: ['document', 'selection', 'history'] },
+    },
+    {
+        path: ['document', 'nodes'],
+        summary: 'List document nodes.',
+        description: 'Returns a flattened node list with ids, types, names, parents, pages, and depth.',
+        usage: 'canvas document nodes --tab <tab> [--json]',
+        flags: [TAB_FLAG],
+        examples: [{ command: 'canvas document nodes --tab tab_abc123 --json' }],
+        output: '{ nodes: Array<{ id, type, name, parentId, pageId, depth }> }',
+        ai: { supported: true, safety: 'read', operation: 'document.nodes', context: ['document', 'selection', 'history'] },
+    },
+    {
+        path: ['draw'],
+        summary: 'Create nodes from a JSON spec.',
+        description: 'Creates one or more 2D nodes from inline JSON or a JSON file.',
+        usage: 'canvas draw --tab <tab> <json-or-file> [--json]',
+        args: [{ name: 'json-or-file', required: true, description: 'Inline JSON or path to a JSON file.' }],
+        flags: [TAB_FLAG],
+        examples: [{ command: "canvas draw --tab tab_abc123 '[{\"type\":\"rect\",\"x\":100,\"y\":100,\"w\":240,\"h\":120}]'" }],
+        output: '{ nodeIds: string[] }',
+        ai: { supported: true, safety: 'write', operation: 'node.create.batch', context: ['document', 'selection', 'viewport', 'history'] },
+    },
+    {
+        path: ['draw', 'rect'],
+        summary: 'Create a rectangle.',
+        description: 'Creates a rectangle in canvas coordinates.',
+        usage: 'canvas draw rect --tab <tab> --x <n> --y <n> --w <n> --h <n> [flags]',
+        flags: [
+            TAB_FLAG,
+            NUMBER_FLAG('x', 'Left position in canvas coordinates.', true),
+            NUMBER_FLAG('y', 'Top position in canvas coordinates.', true),
+            NUMBER_FLAG('w', 'Width.', true),
+            NUMBER_FLAG('h', 'Height.', true),
+            HEX_FLAG('fill', 'Fill color, e.g. #38bdf8.'),
+            HEX_FLAG('stroke', 'Stroke color.'),
+            NUMBER_FLAG('stroke-width', 'Stroke width.'),
+            NUMBER_FLAG('radius', 'Corner radius.'),
+            { name: 'name', type: 'string', valueName: 'text', description: 'Node name.' },
+        ],
+        examples: [{ command: "canvas draw rect --tab tab_abc123 --x 100 --y 100 --w 240 --h 120 --fill '#38bdf8'" }],
+        output: '{ nodeIds: string[] }',
+        ai: { supported: true, safety: 'write', operation: 'node.create.rect', context: ['document', 'selection', 'viewport', 'history'] },
+    },
+    {
+        path: ['draw', 'frame'],
+        summary: 'Create a frame.',
+        description: 'Creates a frame in canvas coordinates.',
+        usage: 'canvas draw frame --tab <tab> --x <n> --y <n> --w <n> --h <n> [flags]',
+        flags: [TAB_FLAG, NUMBER_FLAG('x', 'Left position.', true), NUMBER_FLAG('y', 'Top position.', true), NUMBER_FLAG('w', 'Width.', true), NUMBER_FLAG('h', 'Height.', true), HEX_FLAG('fill', 'Fill color.'), { name: 'name', type: 'string', valueName: 'text', description: 'Node name.' }],
+        examples: [{ command: "canvas draw frame --tab tab_abc123 --x 80 --y 80 --w 960 --h 540 --fill '#ffffff'" }],
+        output: '{ nodeIds: string[] }',
+        ai: { supported: true, safety: 'write', operation: 'node.create.frame', context: ['document', 'selection', 'viewport', 'history'] },
+    },
+    {
+        path: ['draw', 'text'],
+        summary: 'Create text.',
+        description: 'Creates a text node in canvas coordinates.',
+        usage: 'canvas draw text --tab <tab> --x <n> --y <n> --text <text> [flags]',
+        flags: [TAB_FLAG, NUMBER_FLAG('x', 'Left position.', true), NUMBER_FLAG('y', 'Top position.', true), { name: 'text', type: 'string', valueName: 'text', required: true, description: 'Text content.' }, NUMBER_FLAG('font-size', 'Font size.'), HEX_FLAG('color', 'Text color.'), NUMBER_FLAG('w', 'Optional fixed box width.'), { name: 'name', type: 'string', valueName: 'text', description: 'Node name.' }],
+        examples: [{ command: "canvas draw text --tab tab_abc123 --x 120 --y 140 --text 'Hello' --font-size 32" }],
+        output: '{ nodeIds: string[] }',
+        ai: { supported: true, safety: 'write', operation: 'node.create.text', context: ['document', 'selection', 'viewport', 'history'] },
+    },
+    {
+        path: ['draw', 'line'],
+        summary: 'Create a line.',
+        description: 'Creates a line in canvas coordinates.',
+        usage: 'canvas draw line --tab <tab> --x1 <n> --y1 <n> --x2 <n> --y2 <n> [flags]',
+        flags: [TAB_FLAG, NUMBER_FLAG('x1', 'Start x.', true), NUMBER_FLAG('y1', 'Start y.', true), NUMBER_FLAG('x2', 'End x.', true), NUMBER_FLAG('y2', 'End y.', true), HEX_FLAG('stroke', 'Stroke color.'), NUMBER_FLAG('width', 'Stroke width.'), { name: 'name', type: 'string', valueName: 'text', description: 'Node name.' }],
+        examples: [{ command: "canvas draw line --tab tab_abc123 --x1 0 --y1 0 --x2 200 --y2 120 --stroke '#111827'" }],
+        output: '{ nodeIds: string[] }',
+        ai: { supported: true, safety: 'write', operation: 'node.create.line', context: ['document', 'selection', 'viewport', 'history'] },
+    },
+    {
+        path: ['node', 'get'],
+        summary: 'Read one node.',
+        description: 'Gets one node by id.',
+        usage: 'canvas node get <nodeId> --tab <tab> [--json]',
+        args: [{ name: 'nodeId', required: true, description: 'Node id.' }],
+        flags: [TAB_FLAG],
+        output: '{ node }',
+        ai: { supported: true, safety: 'read', operation: 'node.get', context: ['document', 'selection', 'history'] },
+    },
+    {
+        path: ['node', 'update'],
+        summary: 'Patch one node.',
+        description: 'Applies a shallow JSON patch to one node.',
+        usage: 'canvas node update <nodeId> --tab <tab> --patch <json> [--json]',
+        args: [{ name: 'nodeId', required: true, description: 'Node id.' }],
+        flags: [TAB_FLAG, { name: 'patch', type: 'json', valueName: 'json', required: true, description: 'Shallow JSON patch.' }, { name: 'data', type: 'json', valueName: 'json', description: 'Alias for --patch.' }],
+        output: '{ updated, nodeId }',
+        ai: { supported: true, safety: 'write', operation: 'node.update', context: ['document', 'selection', 'history'] },
+    },
+    {
+        path: ['node', 'delete'],
+        summary: 'Delete one node.',
+        description: 'Deletes one node by id.',
+        usage: 'canvas node delete <nodeId> --tab <tab> [--json]',
+        args: [{ name: 'nodeId', required: true, description: 'Node id.' }],
+        flags: [TAB_FLAG],
+        output: '{ deleted, nodeId }',
+        ai: { supported: true, safety: 'destructive', operation: 'node.delete', context: ['document', 'selection', 'history'] },
+    },
+    {
+        path: ['select', 'set'],
+        summary: 'Set selection.',
+        description: 'Replaces the current selection with one node id.',
+        usage: 'canvas select set <nodeId> --tab <tab> [--json]',
+        args: [{ name: 'nodeId', required: true, description: 'Node id.' }],
+        flags: [TAB_FLAG],
+        output: '{ selectedNodeIds }',
+        ai: { supported: true, safety: 'write', operation: 'selection.set', context: ['document', 'selection', 'viewport'] },
+    },
+    {
+        path: ['select', 'clear'],
+        summary: 'Clear selection.',
+        description: 'Clears the current selection.',
+        usage: 'canvas select clear --tab <tab> [--json]',
+        flags: [TAB_FLAG],
+        output: '{ selectedNodeIds: [] }',
+        ai: { supported: true, safety: 'write', operation: 'selection.clear', context: ['selection'] },
+    },
+    {
+        path: ['viewport', 'screenshot'],
+        summary: 'Capture a PNG screenshot.',
+        description: 'Writes a PNG screenshot of one canvas tab.',
+        usage: 'canvas viewport screenshot --tab <tab> -o <file>',
+        flags: [TAB_FLAG, OUTPUT_FLAG],
+        output: 'PNG bytes written to --output.',
+        ai: { supported: true, safety: 'read', operation: 'viewport.screenshot', context: ['viewport'] },
+    },
+    {
+        path: ['screenshot'],
+        summary: 'Alias for viewport screenshot.',
+        description: 'Writes a PNG screenshot of one canvas tab.',
+        usage: 'canvas screenshot --tab <tab> -o <file>',
+        flags: [TAB_FLAG, OUTPUT_FLAG],
+        output: 'PNG bytes written to --output.',
+        ai: { supported: true, safety: 'read', operation: 'viewport.screenshot', context: ['viewport'] },
+    },
+    {
+        path: ['viewport', 'fit'],
+        summary: 'Fit viewport to document.',
+        description: 'Frames the document in the viewport.',
+        usage: 'canvas viewport fit --tab <tab> [--json]',
+        flags: [TAB_FLAG],
+        output: '{ ok: true }',
+        ai: { supported: true, safety: 'write', operation: 'viewport.fit', context: ['document', 'viewport'] },
+    },
+    {
+        path: ['viewport', 'zoom'],
+        summary: 'Set viewport zoom.',
+        description: 'Sets the 2D viewport zoom.',
+        usage: 'canvas viewport zoom --tab <tab> --to <n> [--json]',
+        flags: [TAB_FLAG, NUMBER_FLAG('to', 'Target zoom.', true)],
+        output: '{ zoom }',
+        ai: { supported: true, safety: 'write', operation: 'viewport.zoom', context: ['viewport'] },
+    },
+    {
+        path: ['building'],
+        summary: 'Create building-domain elements.',
+        description: 'Calls building design creation tools such as wall, room, slab, roof, door, window, zone, or furniture.',
+        usage: 'canvas building <wall|room|slab|roof|door|window|zone|furniture> --tab <tab> [flags]',
+        args: [{ name: 'buildingType', required: true, description: 'Building element type.' }],
+        flags: [TAB_FLAG, NUMBER_FLAG('start-x', 'Wall start x.'), NUMBER_FLAG('start-z', 'Wall start z.'), NUMBER_FLAG('end-x', 'Wall end x.'), NUMBER_FLAG('end-z', 'Wall end z.'), NUMBER_FLAG('x', 'X position.'), NUMBER_FLAG('y', 'Y position.'), NUMBER_FLAG('z', 'Z position.'), NUMBER_FLAG('w', 'Width.'), NUMBER_FLAG('d', 'Depth.'), { name: 'label', type: 'string', valueName: 'text', description: 'Label.' }, { name: 'type', type: 'string', valueName: 'text', description: 'Furniture type.' }, HEX_FLAG('color', 'Color.')],
+        examples: [
+            { command: 'canvas building wall --tab tab_abc123 --start-x 0 --start-z 0 --end-x 400 --end-z 0' },
+            { command: 'canvas building room --tab tab_abc123 --x 0 --z 0 --w 500 --d 400 --label Kitchen' },
+        ],
+        output: '{ result }',
+        ai: { supported: true, safety: 'write', operation: 'building.create', context: ['document', 'selection', 'viewport', 'history', 'building'] },
+    },
+];
+export function findCommandSpec(positionals) {
+    const matches = COMMAND_SPECS
+        .filter((spec) => spec.path.every((part, index) => positionals[index] === part))
+        .sort((a, b) => b.path.length - a.path.length);
+    const spec = matches[0] ?? null;
+    return { spec, consumed: spec?.path.length ?? 0 };
+}
+export function getTopLevelCommands() {
+    const seen = new Map();
+    for (const spec of COMMAND_SPECS) {
+        const [name] = spec.path;
+        if (name && !seen.has(name)) {
+            seen.set(name, spec.summary);
+        }
+    }
+    return Array.from(seen, ([name, summary]) => ({ name, summary })).sort((a, b) => a.name.localeCompare(b.name));
+}

package/dist/daemon.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Agent-bridge daemon (SLICE 1).
+ *
+ * Standalone Node process. It does two things:
+ *   1. Serves a tiny localhost-only HTTP API (health + screenshot).
+ *   2. Hosts a WebSocket hub at `/agent` that the browser canvas connects OUT
+ *      to at boot (a tab cannot listen for sockets, so it dials us).
+ *
+ * Each HTTP request is relayed to the connected canvas as a `BridgeCommand`
+ * over WS; we await the id-correlated `BridgeReply` and turn it into the HTTP
+ * response. localhost-only and opt-in by design.
+ */
+export interface DaemonHandle {
+    port: number;
+    close: () => Promise<void>;
+}
+export declare function resolvePort(): number;
+/**
+ * Start the daemon. Resolves once HTTP is listening. The returned handle can
+ * close both the HTTP and WS servers.
+ */
+export declare function startDaemon(port?: number): Promise<DaemonHandle>;