Insert SVG fragment
insert_svg_fragmentInsert an SVG fragment into a document under a parent node or the root. Use to graft composed subtrees without file operations.
Instructions
Insert an agent-composed SVG fragment under a parent (parent_id) or the document root.
When to use: grafting one composed subtree into an existing document (no file round-trip). To
REPLACE the whole document use set_document_svg; for a single typed shape use the create_*
tools.
Key params: svg is ONE element subtree (wrap several siblings in a <g>). parent_id (must
exist) sets where it lands, else the document root. unwrap (default True) controls a <svg>
root: when True the wrapper <svg> is unwrapped and its children grafted (an empty wrapper is
rejected); pass unwrap=False to KEEP an explicit nested <svg> container, inserted as-is
(still allowlist-scrubbed; an empty nested <svg> is then allowed). unwrap has no effect on a
non-<svg> root, which is always inserted intact. Same hardening as set_document_svg
(safe-parse + strict allowlist; <script>, on* handlers, javascript: hrefs, external refs
rejected; only same-document #id allowed). A real run REQUIRES a non-empty approval_token.
The original/source file is never touched.
Return shape: ComposeResult — an EditResult (operation + pre-mutation snapshot links,
reversible via restore_snapshot) extended with the post-adopt validate_document findings
(validation).
Example: insert_svg_fragment(doc_id, "<g>...</g>", parent_id="layer1", approval_token="ok");
to keep a nested container: insert_svg_fragment(doc_id, "<svg>...</svg>", unwrap=False, approval_token="ok").
Render and look before you trust this edit: render with render_preview (or live_render_view)
and inspect the result before relying on it; restore_snapshot reverts it if it is wrong.
Risk class: HIGH — requires a non-empty approval_token; without it the op is refused and
nothing is written.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| svg | Yes | ||
| doc_id | Yes | ||
| unwrap | No | ||
| parent_id | No | ||
| approval_token | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | ||
| changed | Yes | ||
| summary | No | ||
| validation | Yes | Structured, machine-readable validation result for one document. `ok` is True iff there are no `error`-severity findings. `error_count` / `warning_count` are convenience tallies over `findings`. | |
| snapshot_id | Yes | ||
| operation_id | Yes | ||
| preview_after | No | ||
| preview_before | No |