Canvas Writing

canvas_write belongs to the Canvas group in the WebMCP contract. It draws one continuous literal-Unicode stroke into the Projection layer. For Markdown, ANSI, or other material input, use canvas_render.

Position and content

{ "at": [100, 50], "content": "ABC\nDE", "style": { "color": "red" } }

at is the required starting [x,y] in original Cell coordinates. For a Slide Scene, pass pageId to target a specific named page; otherwise the active page is used. Both coordinates and the resulting endpoints must be safe integers. Content determines the footprint; there is no input width, height, or scale.

The local MCP also accepts a file path instead of inline content:

{ "at": [100, 50], "sourceRef": ".chardesk/generated/result.txt" }

sourceRef is resolved by the local MCP and its UTF-8 text is forwarded as the stroke. content and sourceRef are mutually exclusive. This lets a local script produce output once and write it to Canvas without the agent copying the output into a second tool call. Browser-only WebMCP calls must provide content.

canvas_render follows the same contract with source and sourceRef, then applies the selected format (raw, ansi, or markdown).

Non-whitespace graphemes overwrite existing Cells. Whitespace is transparent and does not erase existing content. style applies one brush style to the entire stroke. Use canvas_erase to clear a rectangle and canvas_fill to style existing characters without changing them. Slide overflow rejects the complete stroke before mutation.

Only Projection Cells persist; the literal input is not retained as editable source. This is not a source-document write API.

Result and verification

The response contains an optional canvasId, bounds: [x,y,width,height], and Cell counts for writtenCells and transparent whitespace. Content with no written positions returns bounds: null without creating history. Writes commit as one independently undoable operation and do not change the user's camera, cursor, or selection. A Canvas or Slide switch during rendering cancels the write; renderer failures never partially write.

Use returned bounds as the viewport of Canvas reading. Its coordinate rulers and sampled symbols are generated output, not write payloads. Invalid input, missing Canvas, unavailable runtime, source-backed content, Slide overflow, and execution failures return explicit error codes. Local CLI reader pages do not register this write tool.

Authorities

• Tool definition
• Text command
• Verification