Enhance documentation

canvas.writeHtml

Design an editable screen or visual group from HTML and CSS. Use review none for a fast commit, then render after the intended edits.

↓ Markdown

canvas.writeHtml

mutation write

Use when the requested change exactly matches canvas.writeHtml; read the current state first when a version or identifier may have changed.

Before calling

Authenticate as the accountable Enhance person.
Use only resource identifiers returned by an earlier capability result or supplied by the person.
Reuse clientToken only when retrying this exact mutation input.

Input

Show complete JSON Schema

{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"canvasId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"pageId":{"description":"Page from the complete canvas URL; the destination must belong to this page.","type":"string","minLength":1},"selectionNodeIds":{"description":"Selected node IDs from the canvas URL; restrict the destination to this selection.","type":"array","items":{"type":"string","minLength":1}},"targetNodeId":{"type":"string","minLength":1,"description":"Stable container id for insert-children, or subtree root id for replace."},"mode":{"type":"string","enum":["insert-children","replace"],"description":"Insert the compiled group inside the target, or replace the target subtree."},"html":{"type":"string","minLength":1,"description":"Exactly one safe top-level HTML/CSS visual group to compile into editable nodes."},"idPrefix":{"description":"Optional namespace for generated IDs. Choose a fresh prefix for each new import or replacement; reuse only for an identical retry.","type":"string","minLength":1},"baseVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"review":{"description":"Use none to return the committed edit without rendering; omission preserves combined review.","type":"string","enum":["none","render"]},"renderOutputPath":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Local review PNG path, or null for a protected temporary artifact."},"overwriteRender":{"type":"boolean","description":"Whether an existing renderOutputPath may be replaced."},"renderScale":{"type":"number","exclusiveMinimum":0,"description":"Review PNG pixels per canvas unit."},"renderTimeoutMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local import and review-render polling deadline in milliseconds."}},"required":["canvasId","targetNodeId","mode","html","baseVersion","renderOutputPath","overwriteRender","renderScale","renderTimeoutMs"]}

Example

Show example input

{
 "canvasId": "00000000-0000-4000-8000-000000000010",
 "targetNodeId": "root",
 "mode": "insert-children",
 "html": "<div layer-name=\"Ready\" style=\"display:flex;flex-direction:column;gap:16px;padding:24px;width:360px;background:#fff\"><h1 style=\"font-size:24px\">Today</h1><p>Three tasks ready to start</p><div style=\"padding:16px;background:#eef2ff\">Review the design</div></div>",
 "review": "none",
 "idPrefix": "example",
 "baseVersion": 1,
 "renderOutputPath": null,
 "overwriteRender": false,
 "renderScale": 1,
 "renderTimeoutMs": 120000
}

Result

Returns a typed canvas.writeHtml result from the Enhance API without transport-specific prose.

Show complete result JSON Schema

{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"type":"object","properties":{"canvasId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"mutationCommitted":{"type":"boolean","const":true},"previousVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"rootNodeId":{"type":"string"},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"affected":{"type":"object","properties":{"inserted":{"type":"number"},"changed":{"type":"number"},"removed":{"type":"number"}},"required":["inserted","changed","removed"],"additionalProperties":false},"createdNodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"component":{"type":"string"}},"required":["id","name","component"],"additionalProperties":false}},"removedNodeIds":{"type":"array","items":{"type":"string"}},"next":{"type":"array","items":{"type":"string"}}},"required":["canvasId","mutationCommitted","previousVersion","version","removedNodeIds"],"additionalProperties":{}},{"type":"object","properties":{"state":{"type":"string","const":"pending"},"canvasId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"phase":{"type":"string"},"status":{"type":"object","properties":{"tool":{"type":"string","const":"capability_query"},"arguments":{"type":"object","properties":{"capability":{"type":"string","const":"canvas.render.getImport"},"input":{"type":"object","properties":{"jobId":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"}},"required":["jobId"],"additionalProperties":false}},"required":["capability","input"],"additionalProperties":false}},"required":["tool","arguments"],"additionalProperties":false}},"required":["state","canvasId","jobId","phase","status"],"additionalProperties":false}]}

Example result

Show example result

{
 "canvasId": "00000000-0000-4000-8000-000000000010",
 "mutationCommitted": true,
 "previousVersion": 1,
 "version": 2,
 "rootNodeId": "example_ready_0001",
 "jobId": "00000000-0000-4000-8000-000000000010",
 "affected": {
  "inserted": 4,
  "changed": 0,
  "removed": 0
 },
 "insertedNodeIds": [
  "example_ready_0001",
  "example_text_0002",
  "example_text_0003",
  "example_text_0004"
 ],
 "affectedBounds": {
  "x": 0,
  "y": 0,
  "width": 360,
  "height": 180
 },
 "removedNodeIds": []
}

Recovery

BAD_REQUEST: correct the named fields and call again.
UNAUTHORIZED: restore Enhance authentication, then retry once.
FORBIDDEN or NOT_FOUND: check the supplied resource and selection; do not substitute unrelated content. Ask for corrected access or scope if needed.
CONFLICT: read the current resource, merge the intended change, and retry with its version.
INTERNAL: run Enhance diagnostics, report the failure, and stop repeating the call.

Continue with

Reuse the committed version for the next edit. Render the affected screen when the requested visual change is ready to review.

Versions

Compatibility: 849f01471f6f3eedda1b6cdf8df7d2abde2e000728fe5a1547c35f791a5d1c04.

Minimum tested versions: Enhance CLI and MCP runtime 0.1.40, plugin 1.0.38, Node.js 24. No older floor is published.