Enhance documentation

canvas.render

Render production-faithful canvas pixels into a protected PNG artifact.

canvas.render

mutation read

Use when the requested change exactly matches canvas.render; 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","anyOf":[{"anyOf":[{"type":"object","properties":{"canvasRef":{"type":"string","minLength":1},"expectedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"target":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"content"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1}},"required":["kind","pageId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"node"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"bounds"},"bounds":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","exclusiveMinimum":0},"height":{"type":"number","exclusiveMinimum":0}},"required":["x","y","width","height"],"additionalProperties":false}},"required":["kind","bounds"],"additionalProperties":false}]},"sourceState":{"default":null,"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"recording"},"recordingId":{"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)$"},"atMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["kind","recordingId","atMs"],"additionalProperties":false},{"type":"null"}]},"scale":{"default":1,"type":"number","exclusiveMinimum":0},"waitMs":{"default":1500,"description":"Additional local polling after the server returns an active job; render creation retains its existing bounded HTTP deadline.","type":"integer","minimum":0,"maximum":5000}},"required":["canvasRef","expectedVersion","target"],"additionalProperties":false},{"type":"object","properties":{"canvasRef":{"type":"string","minLength":1},"expectedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"waitMs":{"default":1500,"description":"Additional local polling after the server returns an active job; render creation retains its existing bounded HTTP deadline.","type":"integer","minimum":0,"maximum":5000},"targets":{"minItems":1,"type":"array","items":{"type":"object","properties":{"target":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"content"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1}},"required":["kind","pageId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"node"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"bounds"},"bounds":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","exclusiveMinimum":0},"height":{"type":"number","exclusiveMinimum":0}},"required":["x","y","width","height"],"additionalProperties":false}},"required":["kind","bounds"],"additionalProperties":false}]},"sourceState":{"default":null,"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"recording"},"recordingId":{"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)$"},"atMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["kind","recordingId","atMs"],"additionalProperties":false},{"type":"null"}]},"scale":{"default":1,"type":"number","exclusiveMinimum":0},"id":{"type":"string","minLength":1,"maxLength":80},"maxOutputPixels":{"description":"Optional requested pixel budget for this target.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["target","id"],"additionalProperties":false}}},"required":["canvasRef","expectedVersion","targets"],"additionalProperties":false}],"type":"object"},{"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)$"},"expectedVersion":{"anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}],"description":"Exact document version to render, or null to accept the current version."},"target":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"content"}},"required":["kind"]},{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1}},"required":["kind","pageId"]},{"type":"object","properties":{"kind":{"type":"string","const":"node"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"]},{"type":"object","properties":{"kind":{"type":"string","const":"bounds"},"bounds":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","exclusiveMinimum":0},"height":{"type":"number","exclusiveMinimum":0}},"required":["x","y","width","height"]}},"required":["kind","bounds"]}],"description":"Area to render: all authored content, one stable node id, or explicit world-space bounds."},"sourceState":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"recording"},"recordingId":{"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)$"},"atMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["kind","recordingId","atMs"]},{"type":"null"}],"description":"Recording moment to display while rendering its recording node, or null."},"scale":{"type":"number","exclusiveMinimum":0,"description":"Output pixels per canvas unit."},"outputPath":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"description":"Local PNG path, or null for a protected temporary artifact."},"overwrite":{"type":"boolean","description":"Whether an existing outputPath may be replaced."},"timeoutMs":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991,"description":"Local render polling deadline in milliseconds."},"timeoutOutcome":{"type":"string","const":"pending"},"scope":{"type":"object","properties":{"pageId":{"type":"string"},"nodeIds":{"type":"array","items":{"type":"string"}}},"required":["nodeIds"],"additionalProperties":false}},"required":["canvasId","expectedVersion","target","sourceState","scale","outputPath","overwrite","timeoutMs"]}],"type":"object"}

Example

Show example input

{
 "canvasId": "00000000-0000-4000-8000-000000000010",
 "expectedVersion": 1,
 "target": {
  "kind": "content"
 },
 "sourceState": null,
 "scale": 1,
 "outputPath": null,
 "overwrite": false,
 "timeoutMs": 120000
}

Result

Returns a typed canvas.render 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":{"kind":{"type":"string","const":"canvas-render-batch"},"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)$"},"requestedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"complete":{"type":"boolean"},"renderedPixels":{"type":"integer","minimum":0,"maximum":9007199254740991},"results":{"minItems":1,"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"target":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"content"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1}},"required":["kind","pageId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"node"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"bounds"},"bounds":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","exclusiveMinimum":0},"height":{"type":"number","exclusiveMinimum":0}},"required":["x","y","width","height"],"additionalProperties":false}},"required":["kind","bounds"],"additionalProperties":false}]},"maxOutputPixels":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"outcome":{"anyOf":[{"type":"object","properties":{"source":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","const":"available"},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"format":{"type":"string","const":"enhance-scene-json"},"code":{"type":"string"},"prototypes":{"type":"array","items":{"type":"object","properties":{"nodeId":{"type":"string"},"prototypeId":{"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)$"},"deploymentId":{"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)$"},"capability":{"type":"string","const":"canvas.read"},"canvasPath":{"type":"string"},"input":{"type":"object","properties":{"canvasRef":{"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)$"},"view":{"type":"string","const":"source"},"nodeId":{"type":"string"}},"required":["canvasRef","view","nodeId"],"additionalProperties":false},"guidance":{"type":"string"}},"required":["nodeId","prototypeId","deploymentId","capability","canvasPath","input","guidance"],"additionalProperties":false}},"guidance":{"type":"string"}},"required":["status","version","format","code","prototypes","guidance"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"unavailable"},"guidance":{"type":"string"}},"required":["status","guidance"],"additionalProperties":false}]},"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)$"},"operation":{"type":"object","properties":{"kind":{"type":"string","const":"canvas-render"},"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)$"}},"required":["kind","canvasId","jobId"],"additionalProperties":false},"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)$"},"requestedVersion":{"anyOf":[{"type":"number"},{"type":"null"}]},"loadedVersion":{"type":"number"},"target":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"content"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1}},"required":["kind","pageId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"node"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"bounds"},"bounds":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","exclusiveMinimum":0},"height":{"type":"number","exclusiveMinimum":0}},"required":["x","y","width","height"],"additionalProperties":false}},"required":["kind","bounds"],"additionalProperties":false}]},"sourceState":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","const":"recording"},"recordingId":{"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)$"},"requestedAtMs":{"type":"integer","minimum":0,"maximum":9007199254740991},"settledAtMs":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["kind","recordingId","requestedAtMs","settledAtMs"],"additionalProperties":false},{"type":"null"}]},"bounds":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","minimum":0},"height":{"type":"number","minimum":0}},"required":["x","y","width","height"],"additionalProperties":false},"width":{"type":"number"},"height":{"type":"number"},"scale":{"type":"number"},"contentType":{"type":"string","const":"image/png"},"bytes":{"type":"number"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["ASSET_UNAVAILABLE","FONT_FALLBACK","LOCAL_FONT_FALLBACK","SOURCE_FALLBACK","SCALE_REDUCED","LAYOUT_FALLBACK"]},"message":{"type":"string","minLength":1,"maxLength":500},"sourceId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["code","message","sourceId"],"additionalProperties":false}},"path":{"type":"string","minLength":1},"sensitive":{"type":"boolean","const":true},"cleanup":{"type":"string","enum":["unlink-after-use","caller-owned"]},"deleteAfter":{"type":"string"}},"required":["jobId","canvasId","requestedVersion","loadedVersion","target","sourceState","bounds","width","height","scale","contentType","bytes","warnings","path","sensitive","cleanup"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","enum":["queued","running"]},"phase":{"type":"string"},"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)$"},"requestedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"target":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"content"}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"page"},"pageId":{"type":"string","minLength":1}},"required":["kind","pageId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"node"},"nodeId":{"type":"string","minLength":1}},"required":["kind","nodeId"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"bounds"},"bounds":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number","exclusiveMinimum":0},"height":{"type":"number","exclusiveMinimum":0}},"required":["x","y","width","height"],"additionalProperties":false}},"required":["kind","bounds"],"additionalProperties":false}]},"operation":{"type":"object","properties":{"kind":{"type":"string","const":"canvas-render"},"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)$"}},"required":["kind","canvasId","jobId"],"additionalProperties":false},"pixelsDelivered":{"type":"boolean","const":false},"next":{"type":"array","items":{"type":"string"}}},"required":["state","phase","canvasId","requestedVersion","target","operation","pixelsDelivered","next"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","enum":["failed","cancelled","expired","not_confirmed","not_started"]},"operation":{"type":"object","properties":{"kind":{"type":"string","const":"canvas-render"},"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)$"}},"required":["kind","canvasId","jobId"],"additionalProperties":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"remediation":{"type":"string"},"fields":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}}},"required":["code","message","remediation"],"additionalProperties":false}},"required":["state","error"],"additionalProperties":false}]}},"required":["id","target","outcome"],"additionalProperties":false}},"next":{"type":"array","items":{"type":"string"}}},"required":["kind","canvasId","requestedVersion","complete","renderedPixels","results","next"],"additionalProperties":false},{"type":"object","properties":{"state":{"type":"string","enum":["queued","running"]},"operation":{"type":"object","properties":{"kind":{"type":"string","const":"canvas-render"},"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)$"}},"required":["kind","canvasId","jobId"],"additionalProperties":false}},"required":["state","operation"],"additionalProperties":{}},{"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)$"},"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)$"},"loadedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"contentType":{"type":"string","const":"image/png"},"bytes":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"path":{"type":"string","minLength":1},"sensitive":{"type":"boolean","const":true},"next":{"type":"array","items":{"type":"string"}}},"required":["jobId","canvasId","loadedVersion","contentType","bytes","path","sensitive","next"],"additionalProperties":{}}],"type":"object"}

Example result

Show example result

{
 "jobId": "00000000-0000-4000-8000-000000000010",
 "canvasId": "00000000-0000-4000-8000-000000000010",
 "loadedVersion": 1,
 "contentType": "image/png",
 "bytes": 68,
 "path": "/protected/render.png",
 "sensitive": true,
 "next": [
  "Inspect the PNG."
 ]
}

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

Inspect the returned image; read more structure only if the pixels reveal a discrepancy.

Versions

Compatibility: aff624b26f8dd6b7493af202c1d3a9d9b79cea464136f9467458d95fff6cfd2e.

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