Report whether Illustrator is reachable, and what to fix if not.

CONTRACT: readOnly=True, destructive=False, idempotent=True, openWorld=False

WHEN TO USE:

• A call failed with a connection error and you need to know which link broke

• Before a session, to confirm the panel is connected

• To check whether the panel is busy rather than gone

KEY CONCEPTS: Four layers, outermost first: this server's WebSocket listener, the CEP panel's socket, Illustrator itself, and the active document. The first one that is not ok is reported as blockedAt, and the recovery steps address that link only. Layers behind a broken one read 'unknown' rather than being guessed at.

OPTIONS: probe=false (default) — instant, reads process-local state only probe=true — also round-trips a tiny read-only script to Illustrator

EXAMPLES: Instant report, no host call: {"params": {}} Also confirm Illustrator itself answers: {"params": {"probe": true}}

RESULT: data.ready is true only when every layer is up. data.blockedAt names the first broken layer, or is null. data.recovery lists the steps for it. execution reports whether this report was produced, never whether the connection is healthy — a successful report of a dead panel is a success.

NOTES:

• Never starts the server and never reconnects

• Trusted probe timeouts retire local waits and require a readiness fence; blocking names the retained job and exact job_status call

• Answers normally when Illustrator is closed, which is the point

• Without probe, the document name is last-known, not live

Create, open, list, activate, save, or close an Illustrator document.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=True

WHEN TO USE:

• Starting a new illustration (action='create')

• Opening an existing .ai file (action='open', file_path required)

• Saving current work (action='save', file_path for save-as)

• Closing the active document (action='close')

EXAMPLES: Create: {"params": {"action": "create", "width": 800, "height": 600, "color_mode": "RGB"}} Open: {"params": {"action": "open", "file_path": "C:/art/figure.ai"}} Save under a new name: {"params": {"action": "save", "file_path": "C:/art/figure_v2.ai"}} Close, saving first: {"params": {"action": "close", "save_before_close": true}}

NOTES:

• close without save_before_close=True discards unsaved changes

• open/save interact with the filesystem (openWorld)

• list exposes live document tokens without changing the shared pin

• activate requires expected_document_token and explicitly changes the pin

• save/close reject a mismatching active document; close never repins

Execute raw JavaScript/ExtendScript code in Adobe Illustrator.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=True

WHEN TO USE:

• Single one-off items, quick prototypes, or operations not covered by higher-level tools

• Full DOM access when structured tools are insufficient

• Reading document state with custom logic

• To SEE the artwork, use illustrator_observe instead: it returns the image inline with a numbered map of items, their handles and bounds, so there is no file to export, locate and open

EXECUTION CONTRACT: Your script is evaluated at the top level, not inside a function. - The value of the LAST EXPRESSION is the result. End with the value you want back, usually a JSON.stringify(...) call. - A bare return is a syntax error: "Illegal return outside of a function body". Wrap the code in a function and call it immediately when you need an early exit. - Returning an object is fine; it is serialised for you. Returning nothing is a valid outcome and is reported as data: null. Injected helper libraries are declared at the same top level, so they are in scope either way. See EXAMPLES for both forms. Top-level {ok:false}, {success:false}, or a string error field produces a warning, not an execution failure. Nested values remain opaque. Use throw or mcpFail(message, details) for an explicit failure: try { doWork(); } catch (e) { mcpFail("Label failed", {cause:String(e)}); } mcpFail throws an ordinary catchable Error; details are bounded to 2048 characters. Neither throwing nor returning an error rolls back edits. Host line numbers, when available, refer to injected host code, not necessarily to the caller's source lines. Verification is separate.

ABSTRACTION LADDER — prefer higher levels before using raw script: Level 5 — illustrator_path_boolean: boolean sculpt (unite/subtract/intersect/xor) Level 4 — illustrator_execute_task + element_create_batch: batch-create identical shapes Level 3 — illustrator_path_import_svg: import SVG d-string paths Level 2 — illustrator_execute_task + element_create: smooth curves, handles, mirror Level 1 — illustrator_execute_script (THIS tool): raw ExtendScript

DECISION RULES:

• Subtract/unite shapes — MUST use illustrator_path_boolean

• Creating >=3 identical shapes — MUST use illustrator_execute_task + element_create_batch

• setEntirePath with >12 coord pairs — STOP and use smooth:true or illustrator_path_import_svg

COORDINATE SYSTEM:

• Geometry helpers use artboard-relative coordinates: origin at the active artboard's top-left, with y increasing downward (screen space)

• Raw Illustrator DOM positions use document-space coordinates, with y increasing upward; do not assume that the active artboard starts at (0, 0)

• Units: points (1 pt = 1/72 inch)

HELPERS — ARTBOARD-RELATIVE, Y-DOWN (includes: ['geometry']): Use these to avoid manual conversion to raw document coordinates: rectXY(x, y, w, h) — rectangle at screen-space (x,y) ellipseXY(x, y, w, h) — ellipse at screen-space (x,y) lineXY(x1, y1, x2, y2) — line between screen-space points polygonXY([[x,y],...], closed)— polygon from screen-space points pointXY(x, y) — returns {left, top} for position assignments drawPathPoints(spec) — full path with handles, UUID, heap registration Example: var rect = rectXY(100, 200, 50, 30); // no -y needed

RAW DOM — DOCUMENT-SPACE, Y-UP (only when helpers are insufficient): These are API snippets to put inside a script, not tool calls. Convert an artboard-relative point before passing it to the DOM: var ab = doc.artboards[doc.artboards.getActiveArtboardIndex()].artboardRect; var position = [ab[0] + x, ab[1] - y]; // Nonzero-origin example: ab top-left (72, 720), (x, y) = (100, 200) // gives the raw DOM position [172, 520]. Rectangle: doc.pathItems.rectangle(position[1], position[0], width, height) ⚠ width & height must be POSITIVE. Negative height → shape above artboard (invisible). Ellipse: doc.pathItems.ellipse(position[1], position[0], width, height) Line: convert each artboard-relative point with the same ab-offset formula Color: var c = new RGBColor(); c.red=255; c.green=0; c.blue=0; shape.fillColor = c; Text: var tf = doc.textFrames.add(); tf.contents = "text"; tf.position = position; Grid helpers: artboardGrid(cols, rows), itemsInCell(cell, mode)

EXAMPLES: Read with a native-coordinate crop: { "params": { "script": "app.activeDocument.name;", "return_preview": true, "clip_box": [ 0, 125, 125, 0 ], "clip_space": "illustrator_native_y_up" } } Draw in artboard-relative Y-down coordinates with geometry helpers: { "params": { "script": "var r = rectXY(50, 80, 200, 100); r.fillColor = makeRGBColor(255, 0, 0); r.name;", "includes": [ "geometry" ], "description": "red banner" } } Position text from an offset artboard using raw DOM coordinates: { "params": { "script": "var doc = app.activeDocument; var ab = doc.artboards[doc.artboards.getActiveArtboardIndex()].artboardRect; var x = 100; var y = 200; var tf = doc.textFrames.add(); tf.contents = 'Offset'; tf.position = [ab[0] + x, ab[1] - y]; tf.position;", "description": "raw DOM offset-artboard placement" } } Read state back; the last expression is the result: {"params": {"script": "JSON.stringify({items: app.activeDocument.pageItems.length});"}} Return early, which needs a function wrapper: { "params": { "script": "(function () { var d = app.activeDocument; if (d.pageItems.length === 0) return 'empty'; return d.pageItems[0].name; })()" } } A readback, declared so it is not treated as an edit: { "params": { "script": "JSON.stringify({name: app.activeDocument.name});", "read_only": true } }

ELEMENT DISCOVERY:

• Use artboardGrid(cols, rows) to partition the artboard into a labeled grid

• Use itemsInCell(cell, mode) to find items in a specific grid cell

• Modes: 'containsCenter' (default) or 'intersects'

• Cell labels follow A1 scheme (letter row + number col, e.g. A1, B3)

MUTATION SAFETY:

• Each call increments a per-document mutation counter

• Failed executions decrement it again, so failures do not accumulate

• A raw script is opaque to this server, so it cannot tell which kind of change you made. Evidence is therefore requested on a backlog rule rather than on the operations performed, unlike illustrator_execute_task

• Use final_step=true on the last mutation to require final evidence

NOTES:

• When evidence is required the result carries a VERIFICATION REQUIRED block naming what to confirm, and diagnostics.evidence says whether an image was actually supplied

• return_preview=false suppresses capture but not the requirement, which is then reported unmet rather than dropped

• setEntirePath() creates corner points only; set handles after creation

• ExtendScript can access File/Folder and OS — treat as open-world

SAFETY:

• __mcp_check() watchdog: call as FIRST line inside every for/while body

• Never iterate live Illustrator collections if adding/removing items

• Use __mcp_forEachSnapshot(collection, fn) or __mcp_snapshot(collection) instead

Execute structured SOC operations or a compatibility callback pipeline.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=True

WHEN TO USE:

• Prefer params.batch for all 48 JSX operations; the nine pilot models retain stronger nested typing. {operation_index}

• Compatibility params.payload remains supported for ordered mixed sequences under payload.params.ops; it uses the same static validation pipeline.

• The payload route also accepts compatibility callback hooks: collect_fn selects a callable, while compute_fn and apply_fn are arbitrary ExtendScript callback bodies. They have the same File, Folder, and OS access as raw ExtendScript, so this tool is open-world while they exist.

• Provide exactly one of params.batch or params.payload.

EXAMPLES: One structured operation (the preferred form): { "params": { "batch": { "operations": [ { "task": "element_create", "params": { "type": "rect", "x": 40, "y": 40, "width": 200, "height": 120, "fill": { "r": 0, "g": 150, "b": 136 } } } ] } } } Several operations, stopping at the first failure: { "params": { "batch": { "operations": [ { "task": "element_create", "params": { "type": "ellipse", "x": 0, "y": 0, "width": 60, "height": 60, "id": "dot" } }, { "task": "element_modify", "targets": { "type": "id", "ids": [ "dot" ] }, "params": { "x": 120 } } ], "stopOnError": true } } } Validate a batch without applying it: { "params": { "batch": { "operations": [ { "task": "element_create", "params": { "type": "star", "x": 100, "y": 100, "numPoints": 5, "outerRadius": 40, "innerRadius": 18 } } ], "mode": "validate" } } } Create a layer through the compatibility route: {"params": {"payload": {"task": "layer_create", "params": {"name": "Background"}}}} Create a layer, then a rectangle on it, in one batch: { "params": { "batch": { "operations": [ { "task": "layer_create", "params": { "name": "Background" } }, { "task": "element_create", "params": { "type": "rect", "x": 0, "y": 0, "width": 800, "height": 600, "layer": "Background" } } ], "stopOnError": true } } }

TARGET SELECTORS: {type: "selection"} — current selection (default) {type: "layer", layer: "Layer 1"} — all items on layer {type: "query", itemType: "PathItem", pattern: "axis_*"} — pattern match {type: "all", recursive: true} — all items in document {type: "id", ids: ["A1", "A2"]} — stable MCP ID targeting

OPTIONS: batch.stopOnError and payload.options.stopOnError stop after the first failed operation. They preserve earlier edits and do not provide transactional rollback. payload.options.mode and stopOnError are honored by the default structured SOC route. trace is honored by both structured and callback routes. payload.options.kind, skipCollect, minCreated, idPolicy, and the deprecated assignIds alias are callback-pipeline controls. The default SOC route forces kind="creation", resolves per-op targets, and has no apply callback. retry, idempotency, and timeout are compatibility fields that still validate but are currently ignored by this executor. It does not call the retry wrapper or use payload.options.timeout as its host deadline. dryRun — NOT SUPPORTED; rejected before execution. It could not prevent mutation (batch ops run during compute) and reported otherwise. To inspect without changing anything, use query_items, preflight_check, or get_document. rollback, snapshot, and recompute — NOT SUPPORTED; enabled requests are rejected before host dispatch. Explicit false/null disabled forms remain valid. Unknown task, payload, batch, operation, option, and nested retry fields are rejected. Use stopOnError instead of the internal strict spelling.

RESULT: structuredContent carries the canonical result object: execution status, data, effects, verification, recovery, warnings and truncation. isError reflects the EXECUTION outcome only — a failed or unavailable visual check never turns a successful edit into a tool error.

NOTES:

• With the default SOC executor (no custom compute function), the server injects payload.options.kind="creation" so outer collection is skipped while each operation resolves its own targets. Callers may omit kind.

• Both SOC routes validate the complete operation tree before dispatch. Availability, required fields, broad types, enums and unknown keys are checked from the shared contract. Pilot nested models remain stronger.

• Path handles and mirror modifiers normalize once for single operations, batch operations and compound children. Runtime fields and targets stay deferred; stopOnError does not promise rollback or successful assertions.

• Static request limits: 1000 operations, JSON depth 32, selector depth 16, 10000 expanded items and 100000 expanded geometry points. Dynamic values remain subject to host limits when evaluated.

• For boolean ops use illustrator_path_boolean, not execute_task

• For raw SVG path data use illustrator_path_import_svg

Export the active document to PNG or JPG. Native SVG and PDF are refused.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=True

WHEN TO USE:

• Generating raster output (PNG, JPG) with optional scale factor

• Native SVG is disabled: live export changed the source file association

• Getting visual feedback by setting return_image=True (PNG/JPG only)

• NOT for looking at your work in progress. Exporting writes a file to disk and overwrites whatever was there. To see the artwork, call illustrator_observe: it returns the image inline together with a numbered map of items, their handles and their bounds, with no file to create, locate and open. Export when you want a deliverable

EXAMPLES: PNG at twice the size: {"params": {"file_path": "C:/out/fig.png", "format": "png", "scale": 2.0}} PDF refusal; use a separate working copy with Illustrator PDF save: {"params": {"file_path": "C:/out/fig.pdf", "format": "pdf"}} SVG refusal after source-association failure; use a separate working copy: {"params": {"file_path": "C:/out/fig.svg", "format": "svg"}} PNG of the artboard, returned inline as well: {"params": {"file_path": "C:/out/fig.png", "return_image": true, "artboard_only": true}} Refuse rather than overwrite an existing file: {"params": {"file_path": "C:/out/fig.png", "format": "png", "overwrite": "fail"}} Keep the old file and write beside it: {"params": {"file_path": "C:/out/fig.png", "overwrite": "version"}}

NOTES:

• artboard_only=True clips export to artboard; a pre-check warns if nothing is on it

• Native PDF is temporarily disabled because saveAs changes source state

• Native SVG is temporarily disabled after a measured source-association failure

• return_image returns base64 image bytes as ImageContent for visual verification

• An existing file is resolved before dispatch per overwrite, so Illustrator is never asked to confirm a replacement. Its Replace Files prompt is modal and would hang the host until a person clicked it

• overwrite='replace' retains a unique sibling backup until completion

• Unknown completion retains the backup; use illustrator_job_status with finalize_export=true on the returned jobId after completion is established

• Backup ownership is in-memory; after server restart use manual recovery

Get complete document information and structure as a JSON tree.

CONTRACT: readOnly=True, destructive=False, idempotent=True, openWorld=False

WHEN TO USE:

• Understanding canvas state before writing modification scripts

• Inspecting layers, items, positions, and properties

• Getting Illustrator application info (scope='app')

• This reports structure, not appearance. For what the page looks like, call illustrator_observe; for whether it is fit to export, call illustrator_preflight_check

OPTIONS: scope: 'document' (default), 'app', or 'both' max_items: items per layer, 1-5000 (default 200) max_layers: layers to return, 1-200 (default 50) offset: skip first N items per layer (for paging) layer_name / layer_index: filter to single layer

EXAMPLES: Document structure: {"params": {}} Application info, with no document open: {"params": {"scope": "app"}} One layer, paginated: {"params": {"layer_name": "Layer 1", "offset": 200, "max_items": 200}} Symbol definitions and instances, without placing anything: {"params": {"scope": "symbols"}} One symbol, names and counts only: {"params": {"scope": "symbols", "symbol_name": "icon-star", "symbol_contents": false}}

NOTES:

• If a layer is truncated, response includes truncated=true and nextOffset

• scope='both' returns {document: {...}, app: {...}}

Undo or redo actions in Illustrator.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=False

WHEN TO USE:

• Reverting mistakes (action='undo', count=N)

• Restoring undone changes (action='redo')

• Saving/restoring named checkpoints for recovery

EXAMPLES: Undo three steps: {"params": {"action": "undo", "count": 3}} Save a checkpoint before risky work: {"params": {"action": "checkpoint_save", "name": "before_boolean"}} Restore it: {"params": {"action": "checkpoint_restore", "name": "before_boolean"}} List checkpoints: {"params": {"action": "checkpoint_list"}}

NOTES:

• Checkpoints capture MCP-managed items only (those with @mcp:id)

• checkpoint_restore is mutate-in-place; may require multiple undo to revert

• undo/redo change document state (destructive)

Inspect a retained Illustrator job; optionally finalize its export files.

CONTRACT: readOnly=False, destructive=True, idempotent=True, openWorld=True

WHEN TO USE:

• After illustrator_execute_task returned an unknown/timeout outcome.

• To inspect a retained job by its jobId before considering a retry.

RESULT: Returns the Python record immediately for queued/running jobs. For an unresolved terminal record, queries the bounded host ledger when the CEP panel is available and idle, then mirrors a completed outcome locally.

EXAMPLES: Reconcile a job whose reply was lost: {"params": {"jobId": "job_7f3a91c2"}}

NOTES:

• This tool never re-executes the original request.

• Default inspection never changes files. finalize_export=true explicitly finalizes the selected export's owned backup after known completion. This can restore a destination or delete its backup, and is idempotent. Unknown completion retains both paths. In-memory ownership is lost on process restart; remaining backups then require manual recovery.

• Explicit finalization succeeds only for verified output or restored backup. Conflict, pending completion/cleanup, and failure return failed execution with the retained file state; ordinary inspection may still successfully report those states.

• A reset, expired record, missing finalizer, or busy host remains unknown.

Capture coordinated visual evidence and precise follow-up handles.

CONTRACT: readOnly=False, destructive=False, idempotent=True, openWorld=True

WHEN TO USE:

• Inspecting current artwork before or after managed edits

• Obtaining raw or annotated previews and an annotation-to-handle map

• Capturing a high-resolution crop without a dummy mutation

OPTIONS: mode: raw, annotated, or both clip_box: optional targeted crop in artboard-relative screen coordinates max_items: annotation-map cap; omissions are reported explicitly

RESULT: Returns image content plus context, timing, annotation map, handle expiry, managed runtime generation, omissions, and preservation verification.

EXAMPLES: Compact annotated evidence and handles: {"params": {"mode": "annotated", "detail": "summary", "map_detail": "compact"}} Look at the page and get handles for what is on it: {"params": {"mode": "both"}} Crop to a region, in artboard-relative points: {"params": {"mode": "raw", "clip_box": [0, 0, 200, 120]}} Compare every artboard on one contact sheet: {"params": {"artboards": "all"}} Three specific boards, on a checkerboard: {"params": {"artboards": [0, 2, 5], "background": "checkerboard"}}

NOTES:

• Handles are document/session scoped and never stamp notes

• A sampled fingerprint is not used as a document revision

• The coordinator prevents managed mutations from interleaving with capture

Perform boolean operations (subtract, unite, intersect, xor) on paths.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=False

WHEN TO USE:

• Combining shapes (unite), cutting holes (subtract), finding overlaps (intersect)

• Any shape sculpting that needs boolean geometry

PIPELINE:

1. Extract geometry from Illustrator paths (ExtendScript)

2. Flatten Bezier curves if present (Python)

3. Run boolean operation via Clipper (Python)

4. Reconstruct result as PathItem or CompoundPathItem (ExtendScript)

5. Delete originals on success (if delete_originals=True)

EXAMPLES: Unite: {"params": {"operation": "unite", "subject": "body_id", "clip": ["wing_id"]}} Subtract a hole: {"params": {"operation": "subtract", "subject": "plate_id", "clip": ["hole_id"]}}

NOTES:

• Operates on fill geometry only — strokes are ignored (warning emitted)

• Simple results produce PathItem; shapes with holes produce CompoundPathItem

• Each operand is an MCP ID or a selector resolving exactly one path.

• Untagged paths use handle selectors from query/observe; notes are not stamped.

• Duplicate/overlapping operands and stale handles are refused before commit.

Import an SVG path d attribute into the active document.

CONTRACT: readOnly=False, destructive=False, idempotent=False, openWorld=False

WHEN TO USE:

• Importing existing SVG path data (d strings) into Illustrator

• Complex outlines, organic shapes, arcs described in SVG syntax

EXAMPLES: A curve: {"params": {"d": "M 10 50 C 20 20, 80 20, 90 50 Z"}} Filled red: {"params": {"d": "M 0 0 L 100 0 L 100 100 Z", "fill": {"r": 255, "g": 0, "b": 0}}} Stroked with no fill: { "params": { "d": "M 0 0 L 50 50 L 100 0", "stroke": { "r": 0, "g": 0, "b": 0, "width": 2 }, "fill": false } } With an explicit id for later targeting: {"params": {"d": "M 0 0 L 100 0 L 100 100 Z", "id": "triangle"}}

NOTES:

• Parses SVG d string server-side, converts arcs to cubic Beziers

• Safety limits: 50,000 chars, 5,000 segments, 100 subpaths, +/-100,000 coords

• Returned bounds are [left, top, right, bottom] in Illustrator's native Y-up space

• For new shapes prefer illustrator_execute_task + element_create with smooth:true

• fill/stroke: None=leave default, False=force off, {r,g,b}=force color

• id: must be unique; collision with existing @mcp:id raises an error

Place an external file (EPS, AI, PDF, image) into the document.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=True

WHEN TO USE:

• Importing raster images (PNG, JPG) into Illustrator

• Placing vector files (EPS, AI, PDF, SVG)

• Vectorizing raster images via Image Trace (trace=True)

KEY CONCEPTS: linked=True (drafting) — file updates automatically when source changes linked=False (final) — file is embedded and fully editable embed_editable=True — opens PDF, copies content as editable vectors (slower) trace=True — place raster, then run Image Trace to vectorize

EXAMPLES: Place a linked image: {"params": {"file_path": "C:/img/photo.png", "x": 100, "y": 50, "linked": true}} Place and auto-trace: {"params": {"file_path": "C:/img/photo.png", "trace": true, "trace_preset": "6 Colors"}}

NOTES:

• trace + expand=True: editable paths, higher DOM complexity

• trace + expand=False: live trace PluginItem, lighter but limited editability

• High-complexity images may produce >2000 paths (warning emitted)

• Reads external files from filesystem (openWorld)

Perform observational validation on the active document.

CONTRACT: readOnly=True, destructive=False, idempotent=True, openWorld=False

WHEN TO USE:

• Before export to catch common issues

• Validating document state after a series of modifications

KEY CONCEPTS: Checks for: items outside artboard bounds, zero-size items, empty text frames, locked layers/items. Does NOT modify the document.

EXAMPLES: Check supplied publication thresholds: { "params": { "publication": { "output_width_mm": 89, "min_font_pt": 5, "min_stroke_pt": 0.25, "min_image_ppi": 300 } } } Check the active artboard before exporting: {"params": {}} Check one artboard, counting any overlap as on-artboard: {"params": {"artboard_index": 0, "policy": "intersects"}}

NOTES:

• Returns ok=true only when the scan ran and found no non-info issues

• Locked layers/items are reported as info and do not fail the check

• If the scan cannot be read back, the result is an error with diagnostics.scan_status='unavailable' — never a passing check

Query items using the Task Protocol with declarative target selection.

CONTRACT: readOnly=True, destructive=False, idempotent=True, openWorld=False

WHEN TO USE:

• Finding items by type, name pattern, or location before modification

• Inspecting current selection

• Listing all items on a layer or in the document

TARGET SELECTORS: {type: "selection"} — current selection (default) {type: "layer", layer: "Layer 1"} — all items on layer {type: "all", recursive: true} — all items in document {type: "query", itemType: "PathItem", pattern: "axis_*"} — filter by type/name

EXAMPLES: Require exactly one matching text label: { "params": { "targets": { "type": "query", "contents": "alpha-helix", "expect": { "count": 1 } } } } Every path whose name starts with axis_: {"params": {"targets": {"type": "query", "itemType": "PathItem", "pattern": "axis_*"}}} Everything on a named layer: {"params": {"targets": {"type": "layer", "layer": "Layer 1"}}}

NOTES:

• Returns ItemRef plus an expiring handle for exact untagged follow-up edits

• Handle issuance never writes item.note or item.name

• Set include_trace=True for debugging

Set or clear a reference image on a locked background layer for tracing.

CONTRACT: readOnly=False, destructive=True, idempotent=True, openWorld=True

WHEN TO USE:

• Preparing a reference image overlay before manual or automated tracing

• Clearing a previous reference (action="clear")

KEY CONCEPTS: Places image on a dedicated 'reference' layer at the bottom of the stack. Layer is locked, dimmed, and non-printable to prevent accidental edits. Calling again with the same file replaces the previous reference (idempotent).

EXAMPLES: Set a dimmed tracing reference: {"params": {"action": "set", "file_path": "C:/ref/sketch.png", "opacity": 50}} Legacy set (still accepted): {"params": {"file_path": "C:/ref/sketch.png"}} Clear the reference layer: {"params": {"action": "clear"}}

NOTES:

• Clear deletes the reference layer; omit file_path, opacity and fit

• Empty calls now reject; migrate old empty clears to action="clear"

• Legacy nonempty file_path without action still means set

• Uses the active artboard for fit/center calculations

• Extracts dominant colors from reference image if Pillow is available