enhancedocs
For agentsOpen Enhance ↗
Reference / canvas.arrange

Enhance documentation

canvas.arrange

Arrange explicit canvas objects through native measured layout and one revision-checked commit.

↓ Markdown

canvas.arrange

mutation write

Use when the requested change exactly matches canvas.arrange; 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":{"canvasRef":{"type":"string","minLength":1},"baseVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"waitMs":{"default":1500,"description":"Additional polling after the initial server call; this does not bound initial native preparation time.","type":"integer","minimum":0,"maximum":5000},"changes":{"minItems":1,"type":"array","items":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"position"},"nodeId":{"type":"string","minLength":1},"parentPosition":{"type":"object","properties":{"x":{"type":"number"},"y":{"type":"number"}},"required":["x","y"],"additionalProperties":false}},"required":["kind","nodeId","parentPosition"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"resize"},"nodeId":{"type":"string","minLength":1},"size":{"type":"object","properties":{"width":{"type":"number","exclusiveMinimum":0},"height":{"type":"number","exclusiveMinimum":0}},"additionalProperties":false}},"required":["kind","nodeId","size"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"relative-position"},"nodeId":{"type":"string","minLength":1},"referenceNodeId":{"type":"string","minLength":1},"side":{"type":"string","enum":["above","below","left","right"]},"gap":{"type":"number","minimum":0},"align":{"type":"string","enum":["start","center","end"]}},"required":["kind","nodeId","referenceNodeId","side","gap","align"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"move"},"nodeIds":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}},"targetNodeId":{"type":"string","minLength":1},"position":{"type":"string","enum":["before","inside","after"]}},"required":["kind","nodeIds","targetNodeId","position"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"group"},"nodeIds":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}},"label":{"type":"string","minLength":1}},"required":["kind","nodeIds"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"ungroup"},"nodeIds":{"minItems":1,"type":"array","items":{"type":"string","minLength":1}}},"required":["kind","nodeIds"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"label"},"nodeId":{"type":"string","minLength":1},"label":{"type":"string","minLength":1}},"required":["kind","nodeId","label"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"visibility"},"nodeId":{"type":"string","minLength":1},"visible":{"type":"boolean"}},"required":["kind","nodeId","visible"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","const":"lock"},"nodeId":{"type":"string","minLength":1},"locked":{"type":"boolean"}},"required":["kind","nodeId","locked"],"additionalProperties":false}]}}},"required":["canvasRef","baseVersion","changes"],"additionalProperties":false}

Example

Show example input 
{
 "canvasRef": "00000000-0000-4000-8000-000000000010",
 "baseVersion": 1,
 "changes": [
  {
   "kind": "position",
   "nodeId": "screen",
   "parentPosition": {
    "x": 40,
    "y": 40
   }
  }
 ]
}

Result

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

Show complete result JSON Schema 
{"$schema":"https://json-schema.org/draft/2020-12/schema","anyOf":[{"oneOf":[{"type":"object","properties":{"outcome":{"type":"string","const":"no_op"},"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)$"},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"verification":{"type":"object","properties":{"rendered":{"type":"boolean","const":false}},"required":["rendered"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"required":["outcome","canvasId","version","verification","warnings"],"additionalProperties":false},{"type":"object","properties":{"outcome":{"type":"string","const":"committed"},"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)$"},"mutationId":{"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)$"},"previousVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"version":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"operation":{"type":"object","properties":{"kind":{"type":"string","const":"canvas-mutation"},"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)$"},"mutationId":{"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)$"},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["kind","canvasId","mutationId","fingerprint"],"additionalProperties":false},"identities":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"sourceNodeId":{"type":"string","minLength":1},"nodeId":{"type":"string","minLength":1}},"required":["sourceNodeId","nodeId"],"additionalProperties":false}},"complete":{"type":"boolean"},"total":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["entries","complete","total"],"additionalProperties":false},"affected":{"type":"object","properties":{"insertedNodeIds":{"type":"array","items":{"type":"string","minLength":1}},"changedNodeIds":{"type":"array","items":{"type":"string","minLength":1}},"removedNodeIds":{"type":"array","items":{"type":"string","minLength":1}},"complete":{"type":"boolean"},"total":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["insertedNodeIds","changedNodeIds","removedNodeIds","complete","total"],"additionalProperties":false},"verification":{"type":"object","properties":{"rendered":{"type":"boolean","const":false}},"required":["rendered"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"required":["outcome","canvasId","mutationId","previousVersion","version","operation","affected","verification","warnings"],"additionalProperties":false}],"type":"object"},{"type":"object","properties":{"kind":{"type":"string","const":"canvas-preparation"},"operation":{"type":"object","properties":{"kind":{"type":"string","const":"canvas-preparation"},"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)$"},"mutationId":{"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)$"},"fingerprint":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["kind","canvasId","jobId","mutationId","fingerprint"],"additionalProperties":false},"state":{"type":"string","enum":["queued","running","succeeded","failed","cancelled","expired"]},"phase":{"type":"string","enum":["queued","claimed","grant","navigate","document","sources","fonts","layout","target","capture","serialize","compile","commit","upload","complete"]},"requestedVersion":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"failure":{"anyOf":[{"type":"object","properties":{"reason":{"type":"string","enum":["VERSION_CHANGED","TARGET_NOT_FOUND","TARGET_INVALID","OUTPUT_TOO_LARGE","READINESS_TIMEOUT","SOURCE_FAILED","BROWSER_CRASH","CAPTURE_FAILED","CONVERSION_FAILED","PREPARATION_FAILED","UPLOAD_FAILED","WORKER_UNAVAILABLE","CANCELLED","EXPIRED","INTERNAL"]},"phase":{"type":"string","enum":["queued","claimed","grant","navigate","document","sources","fonts","layout","target","capture","serialize","compile","commit","upload","complete"]},"message":{"type":"string","minLength":1,"maxLength":500},"retryable":{"type":"boolean"},"sourceId":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["reason","phase","message","retryable","sourceId"],"additionalProperties":false},{"type":"null"}]},"outcome":{"type":"string","const":"not_confirmed"},"prepared":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}}},"required":["kind","operation","state","phase","requestedVersion","failure","outcome","prepared","warnings"],"additionalProperties":false}],"type":"object"}

Example result

Show example result 
{
 "outcome": "no_op",
 "canvasId": "00000000-0000-4000-8000-000000000010",
 "version": 1,
 "verification": {
  "rendered": false
 },
 "warnings": []
}

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

  • Read the affected canvas resource to confirm the result.

Versions

Compatibility: 5eb6d88d19ff145ba0ececcca9a25fe44afc7e5f158dee7d796d2a6a2036f038.

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