Compose grid
compose_gridArrange multiple SVG documents or objects into a grid layout in a single call, with automatic scaling and cell spacing. Creates a new document or inserts into an existing one, fully reversible.
Instructions
Lay out N DIFFERENT assets in a grid (contact / spec sheet) in ONE reversible call.
When to use: building a multi-asset sheet — one cell per DIFFERENT document or object — in a
single call (no per-asset loop, no lxml subtree extract). To repeat ONE object into a grid use
tile; to graft a single composed subtree use insert_svg_fragment.
Key params: supply EXACTLY ONE source mode — doc_ids (one whole document per cell) OR
object_ids together with source_doc_id (objects from one document per cell). The grid fills
ROW-MAJOR over rows x cols cells of size cell (user units); fewer assets than cells leaves
trailing cells empty. Each asset is deep-copied (every id re-minted, intra-clone refs rewritten,
no id clashes), wrapped in a <g> translated to its cell origin and, with scale_to_fit
(default True), uniformly DOWN-scaled to fit cell - 2*padding (never upscaled).
gap/padding (default 0) space the cells. target_doc_id composes INTO an existing document;
omit it to create a new blank document sized to the whole grid. Bounded: rows*cols ≤ the
engine cell cap; the asset count must not exceed the cell count.
Return shape: ComposeGridResult — an EditResult (one operation_id + one pre-mutation
snapshot for the whole sheet, reversible via restore_snapshot) plus target_doc_id (the new
id when a blank doc was created), rows/cols, and cells (the ordered placement plan: per
asset its grid coords, new cell-group id, and a short source label).
Example: compose_grid(3, 4, 64, doc_ids=["d1","d2",...,"d12"]) lays a 12-icon system into a
3x4 sheet in one call.
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: medium (creates a new tracked document or composes into one; sources never mutated).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| gap | No | ||
| cell | Yes | ||
| cols | Yes | ||
| rows | Yes | ||
| doc_ids | No | ||
| padding | No | ||
| object_ids | No | ||
| scale_to_fit | No | ||
| source_doc_id | No | ||
| target_doc_id | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cols | Yes | ||
| rows | Yes | ||
| cells | Yes | ||
| doc_id | Yes | ||
| changed | Yes | ||
| summary | No | ||
| snapshot_id | Yes | ||
| operation_id | Yes | ||
| preview_after | No | ||
| target_doc_id | Yes | ||
| preview_before | No |