Pixerate/pixerate-vector

Pixerate vector editor

The vector document is an artboard (width x height in document units, y down) holding a tree of nodes: path nodes (one or more subpaths of Bezier anchors, with fill, stroke and stroke settings), text nodes (a string set as point text, area text or along a path, painted with the same fills and strokes), instance nodes (a placed copy of a symbol) and group nodes. Groups can also be live booleans, live blends, mask groups, or carry a live effect stack. Every command is a vector.* command run with run_command / run_commands (see pixerate-agent-tools for batching with "$0.id" references, atomic: true and error codes).

• Node ids come from vector.list and from what writes return ({ id }, { ids }).
• Anchors are { nodeId, subpath, index }: subpath number within the path, then anchor number within the subpath, both from 0. Commands that take anchors default to the points selected with the direct tool; those that take ids default to the selection.
• Paint is a CSS colour, null for none, or a gradient object { type, stops: [{ offset, color, opacity?, midpoint? }], ... }.
• Appearance: a path can stack several fills and several strokes (bottom to top; all fills draw under all strokes), each with its own paint, opacity, blendMode and visible, and each stroke with its own width, alignment, dashes, caps, joins, arrowheads and profile, or a brushstroke (vector.addBrushstroke, vector.setBrushstroke, vector.listBrushes) painted along the outline with a dry or wet brush, a Mixer Brush, smudge or blender, gradient paint, seeded jitter and paper grain. Layers are addressed by index in their stack, 0 at the bottom. fill / stroke and the stroke settings of vector.setStyle are shorthands for the top layer; null clears the stack. Any node can also have a blendMode and filters (drop / inner shadow, outer / inner glow, layer blur, feather), which never change geometry.
• Masks: a mask group's first (bottom) child is its mask; the children above it show only inside the mask's outline (clip), or where it is bright (luminance) or opaque (alpha). invert swaps shown and hidden. vector.list gives a mask group a mask { type, invert, maskId, contents, enabled }; a hidden mask (enabled: false) masks nothing.
• Text has a base font (family, weight, italic, size, tracking, leading, baseline shift, underline, strike-through), optional runs that override fields over ranges (start / end in UTF-16 code units, plus a range fill), a paragraph style and a frame: point (x, y of the first baseline), area (a box it wraps in) or path (a line it follows).
• Symbols are reusable art kept with the document (vector.listSymbols), drawn by instance nodes through a transform that, unlike other nodes', may scale and skew. Editing a symbol (vector.editSymbol … vector.exitSymbolEdit) changes every instance.
• Constraints (CAD-style) keep geometric relations and dimensions between anchors, segments and round paths; they are solved after every edit, so later moves keep them.
• Frames are groups with a frame rectangle (vector.listFrames): they draw a background, clip their children and select by their rectangle; top-level frames are artboards. When a frame is resized its children follow their resizing constraints (horizontal left / right / leftRight / center / scale, vertical top / bottom / topBottom / center / scale) instead of scaling.
• Connectors are open paths with a connector whose ends are glued to other objects' sites (the middle of a side, or the centre); they are routed again after every edit, so they follow what they connect. A free end stays where it is.
• Symmetry groups draw their children plus mirrored or rotated copies. Add art to one with parentId on vector.addShape / vector.addPath; only the originals are stored and edited.
• Coordinates are document units. A rotated node stores its geometry in its own space: the bounds that vector.list reports are document-space, its d is the node's own.

Parameter details (gradient fields, effect parameters, width profiles, envelopes) are in references/commands.md.

Workflow skills

For these jobs, load the workflow skill too: it has the method, the checks between steps and the pitfalls, and uses the commands below.

• pixerate-vector-icon-set: icons on one grid, one stroke and style, crisp, as symbols and SVG.
• pixerate-vector-logo: marks from booleans, a lockup, colour variants, outlined delivery files.
• pixerate-vector-illustration: block in, gradients and stacked fills, masks, blends, shadows.

Working method

1. Read. vector.list gives the artboard size, every node depth first (id, type, name, bounds, rotation, fill, stroke, d, effects, blend and boolean info, stacks, blend mode and filters) and the selection. vector.getAppearance gives one node's full stacks and filters.
2. Plan in layers. Decide the shapes, their stacking (bottom to top) and their grouping before drawing. Start from primitives (vector.addShape) and combine them; write raw d only for curves primitives cannot make.
3. Write in batches. Put a construction sequence in one run_commands with atomic: true and a label, chaining ids ("$0.id", "$last.ids"), so it is one undo step that applies all or nothing.
4. Prefer live, expand last. Use live: true booleans, path effects, envelopes, live corners and blends while designing; bake with vector.expandAppearance, vector.expandBlend or vector.outlineStroke only when the user needs plain paths.
5. Check. vector.list again: bounds where you meant them, no stray nodes, sensible names. vector.exportSvg gives the final markup; review it, or render it if you can, before handing it over.

Best practices

• Frames for anything that resizes. Build screens, cards, buttons and banners inside a frame (vector.addFrame or vector.frameSelection), set each child's constraints with vector.setResizing (backgrounds and dividers leftRight, icons pinned to their corner, titles center), then resize with vector.setFrame to produce other sizes from one design. Export each artboard with vector.exportFrameSvg.
• Symbols for repeats. When the same art appears several times (icons in a set, trees in a scene, bullets, a logo mark), make it once and place instances (vector.makeSymbol, then vector.placeSymbol with x / y or a transform), so one edit in isolation changes them all. Give each a clear name. Use vector.setInstanceOptions fill / stroke for colour variants and hidden to drop a part, rather than detaching; detach only when one copy must diverge for good.
• Text. Use point text for labels and headlines, area text (width, height) for anything that should wrap, text on a path for badges and seals. Check overflow in the summary every text write returns: hidden lines or characters mean the box or path is too small. Keep one or two families per design (vector.listFonts lists what the shaper has; a missing family draws in a fallback and appears in missingFonts). Style ranges with vector.setTextStyle rather than splitting text into separate nodes, so it still edits as one paragraph. Create Outlines only for final artwork or logos that must not depend on fonts; keep a copy as text if it may change.
• Paths, strokes, brushstrokes, booleans, gradients, stacks, masks, shadows, connectors, constraints and vertical text: read references/best-practices.md first.
• Non-destructive first. Live booleans (vector.boolean with live: true), path effects and envelopes keep the operands editable. A destructive boolean or Pathfinder replaces its inputs; do that last, and only when asked for flat output.
• Grouping and naming. Group the parts of one object (vector.group with a name), name paths that matter (name on add), and keep the tree shallow.
• SVG hygiene. Export with precision 2 or 3 (default 3); higher only for tiny artboards. Expand effects, blends and variable-width strokes before handing SVG to tools that do not read Pixerate's data-vector-* attributes; other readers see the drawn appearance but not the live source.

Commands

Read

Command	Use it to
vector.list	Read the document: { width, height, nodes, selection, tool }. Each node has id, type, name, depth, document-space bounds, rotation (degrees clockwise), visible, locked, selected, and for paths fill, stroke, strokeWidth and d; groups list children, blend, liveBoolean, effects, mask. A mask group's bounds are its masked result. Call it first and after any batch.
vector.shapeBuilderFaces	List the regions the given paths divide the plane into: path data, area, a point inside each and the ids of paths filling it. Use the points with vector.shapeBuilder.
vector.exportSvg	Get the document as standalone SVG markup ({ svg }); precision 0 to 8 decimals (default 3).
vector.exportPdf	Get a print-ready vector PDF as a base64 data URL: one page, or one per artboard with pages: "artboards". Returns { pdf, pages, bytes, notes }; check notes (filters, opacity masks and text without loaded fonts are left out).
vector.exportLottie	Get the document (or ids) as Lottie JSON for animation players: path effects stay live as Lottie modifiers, gradients as gradient fills. Returns { lottie, notes }; read notes for what was approximated (filters, mesh gradients, text without outlines).

Create and delete

Command	Use it to
vector.traceImage	Turn a PNG (data URL) into vector paths in one group: threshold mode for one-colour art (logos, scans, silhouettes; channel: "alpha" for cut-outs), color mode for a stacked path per colour (colors 2–32). Raise tolerance for fewer anchors, cornerRoundness 0 for sharp polygons. Place it with x, y, width. Returns { id, paths }; check subpaths counts and simplify or delete specks after.
vector.mosaicImage	Stylise a PNG as mosaic tiles (cell px, shape square / circle, gap, colors): pixel art, tiled murals. Returns { id, paths }, one compound path per colour.
vector.halftoneImage	Stylise a PNG as halftone dots on a turned screen (cell, angle, ink color or null for the picture's colours): comic and pop-art looks, print effects.
vector.lowPolyImage	Stylise a PNG as low-poly triangles (cell, jitter, seed, colors): geometric portraits and backdrops.
vector.hatchImage	Stylise a PNG as engraving lines that swell where it is dark (cell spacing, angle, ink color): banknote, woodcut and line-art looks.
vector.addPathByDimensions	Draw a path the way a CAD user types it: from start, each step { length, angle } (degrees counter-clockwise on the page: 0 right, 90 up), { dx, dy } or { x, y }; closed joins the ends. Use it for exact technical outlines (brackets, floor plans, given lengths and angles) instead of computing coordinates by hand. Returns { id, anchors }.
vector.addShape	Add a kind rect, ellipse, polygon (sides, at least 3), star (points, innerRatio 0 to 1) or line at x, y, width, height (all required; for a line, width and height are the end's offset). cornerRadius and cornerKind give live corners; any style field and name apply. Uses the editor's default style for anything not given. Returns { id }.
vector.addPath	Add a path from SVG path data d (absolute or relative M, L, H, V, C, S, Q, T, A, Z; arcs and quadratics become cubics) in document units, with name and style fields; unset style comes from the editor defaults. Fails when d has no points. Returns { id }.
vector.importSvg	Add the shapes of SVG markup svg on top of the document, or replace the document with replace: true. Reads paths, basic shapes, groups, transforms, linear and radial gradients, clip-path / mask references (as mask groups) <text> (as point text: content, font, anchor and fill) and <use> (as instances of symbols made from what they refer to); skips images and foreign filters.
vector.importLottie	Add one frame of a Lottie animation (object or text) as editable groups, or replace the document (replace: true). Modifiers become live effects. Returns { ids, notes }.
vector.delete	Delete nodes (ids).
vector.rename	Rename node id to name (its name in the Layers panel). Name what you make by what it is; rename the user's layers only when asked. Returns { id, name }.

Style

Command	Use it to
vector.setStyle	Set fill, stroke, strokeWidth, strokeLinecap (butt, round, square), strokeLinejoin (miter, round, bevel), strokeDasharray, fillRule (nonzero, evenodd), strokeAlign (center, inside, outside; closed shapes only), startArrow / endArrow (triangle, arrow, open, circle, square, bar, or null), arrowAlign (extend, tip), startArrowScale / endArrowScale (multiples of stroke width, default 1), strokeWidthProfile on ids. Groups apply to every path inside. Pass at least one field.
vector.setGradient	Edit the gradient of the fill (target default) or stroke of ids: type (linear, radial, conic, reflected, diamond), stops, angle (degrees, 0 up, clockwise), cx / cy / r, explicit start / end / width / focal, units, spread, interpolation (srgb default, linear, oklab), smoothness, strokeMode, aspect, reverse. Missing fields keep their value; a solid colour becomes a gradient from it to white. Returns the gradient.
vector.setCorners	Set live corner radius (0 makes them sharp) and / or kind (round, inverted, chamfer) on anchors, else the selected points, else every corner of ids.
vector.setWidthProfile	Give strokes a variable width: a preset (uniform, taperStart, taperEnd, taperBoth, bulge, pinch, teardrop, wave, pressure; uniform removes it), explicit points, or a parametric taper and / or wave. Returns the profile points.
vector.setWidthPoint	Set one width point of path id: index of an existing point (from the profile vector.setWidthProfile returns) or none to add one at t (0 to 1); left / right are side widths in document units. Returns the profile.

Gradient meshes and freeform gradients

Command	Use it to
vector.setMeshGradient	Fill paths with a gradient mesh: rows × columns smooth patches over their bounds, coloured per point (colors, row by row) or by four corners. Use for realistic shading (fruit, metal, skin, soft folds). Returns { meshes: [{ id, shading }] }.
vector.setMeshPoint	Move a mesh point (index, row by row; x, y in document units) and / or set its color and opacity; neighbouring patches bend smoothly. Returns { id, shading }.
vector.setFreeformGradient	Fill paths with a freeform gradient: colour points anywhere (with spread for pure-colour discs) and lines carrying colour along curves, or, with no points, four or more placed inside each path along colors. Use for soft, organic colour that a linear or radial gradient cannot make. Returns { gradients }.
vector.addFreeformPoint	Add a colour point at x, y (default colour: what shows there). Returns { id, index, shading }.
vector.setFreeformPoint	Move a freeform point or change its color, opacity, spread. Returns { id, shading }.
vector.removeFreeformPoint	Remove a freeform point (never the last); later indices shift down. Returns { id, shading }.
vector.setFreeformLines	Replace the freeform lines (point indices each curve runs through; [] removes them). Returns { id, shading }.
vector.getShading	Read a path's mesh or freeform fill with points in document units (the indices the edit commands take). Call it before editing points.

Appearance: fill and stroke stacks, blend modes, filters

Command	Use it to
vector.getAppearance	Read node id's appearance: for paths fills and strokes (bottom to top, each with paint, opacity, blendMode, visible; strokes with their settings) and fillRule; for any node blendMode, opacity and filters (with ids). Call it before editing a layer by index.
vector.addFill	Add a fill layer (paint, default #808080; opacity, blendMode, visible) to ids (groups: every path inside), on top or at index (0 is the bottom). Returns each path's fill stack.
vector.updateFill	Change fill index of path nodeId: paint, opacity, blendMode, visible. Fails, changing nothing, on an index the path doesn't have. Returns the fill stack.
vector.removeFill	Remove fill index from path nodeId. Returns the remaining fills.
vector.moveFill	Move fill index of path nodeId to position to (0 is the bottom). Returns the fills.
vector.addStroke	Add a stroke layer to ids, on top or at index, with paint (default black), opacity, blendMode, visible and any stroke setting (strokeWidth, strokeAlign, strokeLinecap, strokeLinejoin, strokeDasharray, arrowheads, strokeWidthProfile); unset settings copy the current top stroke. Returns each path's stroke stack.
vector.updateStroke	Change stroke index of path nodeId: paint, opacity, blend mode, visibility, any stroke setting (null removes an arrowhead, dashes or a profile). Returns the stroke stack.
vector.removeStroke	Remove stroke index from path nodeId. Returns the remaining strokes.
vector.moveStroke	Move stroke index of path nodeId to position to (0 is the bottom, drawn first). Returns the strokes.
vector.setBlendMode	Set how whole nodes ids (paths or groups) mix with what is under them: blendMode normal, darken, multiply, color-burn, lighten, screen, color-dodge, linear-dodge, overlay, soft-light, hard-light, difference, exclusion, hue, saturation, color, luminosity. Returns each node's mode.
vector.addFilter	Add a filter type (dropShadow, innerShadow, outerGlow, innerGlow, layerBlur, feather) with params to ids, at index (default last). Returns { nodes: [{ id, filterId, filters }] }.
vector.updateFilter	Change filter filterId of nodeId: params (merged; only the keys its type takes) and enabled. Returns the node's filters.
vector.removeFilter	Remove filter filterId from nodeId. Returns the remaining filters.
vector.moveFilter	Move filter filterId of nodeId to index; later shadows draw over earlier ones. Returns the filters.

vector.setStyle, vector.addShape and vector.addPath also take whole fills / strokes arrays, to build or replace a stack in one call.

Transform and arrange

Command	Use it to
vector.transform	Move by dx, dy, scale by sx, sy (along the selection box axes; sy defaults to sx; negative flips), rotate by rotate degrees clockwise about the combined centre, or set each node to absolute angle about its own centre, applied in that order.
vector.skew	Skew by ax degrees horizontally and ay degrees vertically (each -89.9 to 89.9) about the box centre or origin.
vector.distort	Free Distort in perspective: give corners, the four new corners of the selection box (top-left, top-right, bottom-right, bottom-left) in document units, forming a convex quad. tolerance (default 0.05) controls curve fidelity. Returns the new bounds.
vector.align	Align ids on edge (left, center, right, top, middle, bottom) to their combined bounds, or to the artboard with to: "artboard" (also the default for a single node).
vector.distribute	Give three or more nodes equal gaps in direction horizontal or vertical.
vector.arrange	Change stacking order within each node's parent: front, forward, backward, back.
vector.moveLayer	Move one node id to index among its siblings (0 the bottom; default the top); parentId moves it into a group, or null to the top level. It stays put on the canvas.
vector.group	Group nodes that share a parent, with an optional name. Returns { id }.
vector.ungroup	Replace groups with their children (ungrouping a blend expands it).
vector.select	Select nodes by ids (add: true to extend; an empty list clears). Selection is the default target of most commands.

Combine

Command	Use it to
vector.boolean	Combine two or more paths by operation union, subtract (upper shapes from the lowest), intersect or exclude into one new path. With live: true the shapes become editable operands of a live boolean group instead (with a lone live group selected, its operation changes). Returns { id }.
vector.pathfinder	Run a Pathfinder operation over paths bottom to top: divide (every face its own shape), trim (hidden parts removed), merge (trim, then same-fill parts joined), crop (top shape crops the rest), outline (outlines cut into open strokes), minusBack (top minus everything below). Results replace the inputs, grouped when several. Returns { ids }.
vector.shapeBuilder	Merge the faces a pointer path touches into one shape, or delete them (and touched line pieces and edges) with erase: true. points is [[x, y], ...] in document units (one point is a click; use points from vector.shapeBuilderFaces), tolerance for edge picks. Returns counts.
vector.fillRegion	Paint bucket: fill the area visible outlines enclose around point [x, y] with a new path in the current fill (islands stay holes). gap closes gaps up to that size between loose ends. Returns { id }.
vector.outlineStroke	Turn strokes into filled shapes of exactly the painted area (alignment, caps, joins, dashes, arrowheads, width profiles included), above a copy keeping the fill. Returns the new ids.

Text

Command	Use it to
vector.listFonts	See which families the text shaper can draw and whether it gives glyph outlines (outlines); read it before choosing fonts or calling vector.createOutlines. Returns { shaper, outlines, families }.
vector.addText	Add point text (x, y: the first baseline's start), area text (x, y, width, height: wrapped in the box) or text along path (SVG path data, with start, end, flip, orientation, baseline). textOrientation: "vertical" sets point or area text in columns down and right to left (x, y the top of the first column's centre; an area fills from its right edge). font, paragraph, name, fill, stroke, strokeWidth optional; black, no stroke by default. Returns the text summary (id, orientation, lines, bounds, overflow).
vector.getText	Read a text node: text, base font, runs as { start, end, style }, paragraph, frame, orientation, fill, stroke, laid-out lines, document bounds, overflow, outlines, shaper and missing fonts. Call before editing ranges.
vector.setText	Replace [start, end) of the text with text (default the whole text; start = end inserts, "" deletes). Inserted characters take the style before them. Returns the summary.
vector.setTextStyle	Set character fields (fontFamily, fontWeight, italic, fontSize, tracking, leading, baselineShift, underline, strikethrough, upright for Latin standing upright in vertical text; null clears) and fill over [start, end); the whole text (default) changes the base font and the node's fill. Returns the summary with runs.
vector.setParagraphStyle	Set align (left, center, right, justify), autoLeading, indents and spacing for the node's paragraphs. Returns the summary.
vector.setTextFrame	Switch between point, area and path text (kind), resize an area (width, height), move the origin (x, y) or change path options. Returns the summary.
vector.setTextOrientation	Set point or area text horizontal or vertical (columns top to bottom, right to left; CJK upright, Latin turned sideways unless upright). Text on a path cannot be vertical. Returns the summary.
vector.typeOnPath	Turn path node pathId into text along it (it takes the path's place and drops its paint) with text, font, paragraph (align places it along the path) and path options. Returns the summary with the new id.
vector.createOutlines	Turn text (ids, or text inside groups; default the selection) into paths of its glyph outlines, keeping paint, effects, filters, placement and id. Needs outlines: true from vector.listFonts. Returns { ids }.

Fill, stroke, stacked layers, filters, blend modes, transforms, masks and blends work on text as on paths (vector.setStyle, vector.addFill, vector.addFilter, vector.transform, …). Path effects, envelopes and booleans act on its glyph outlines, so they need an outline shaper; with the browser's shaper they are kept but not drawn until outlines are available.

Symbols and instances

Command	Use it to
vector.listSymbols	Read the symbols: id, name, the art's node ids (for hidden), bounds around the registration point, instance ids, and which symbol is being edited.
vector.makeSymbol	Turn objects sharing a parent (ids, default the selection) into a symbol, registration point at their centre, with an instance in their place. Returns { symbolId, instanceId, symbol }.
vector.placeSymbol	Place an instance of symbolId with its registration point at x, y (default the artboard centre) or through transform (scale, rotate and skew allowed). Returns { id }.
vector.setInstanceOptions	Change instances: scaleStrokes (default true), fill / stroke overrides painting all of the art (null clears), hidden art node ids. Returns the instances as listed.
vector.replaceSymbol	Make instances (ids) draw symbolId instead, keeping placement and colour overrides. Returns { ids }.
vector.detachInstance	Break instances' link: they become plain groups of their art as drawn. Returns { ids }.
vector.editSymbol	Enter isolation mode on a symbol (its id or an instance's): every command then edits the art in symbol space (registration point at 0, 0). Returns { symbolId, nodes }.
vector.exitSymbolEdit	Leave isolation mode; the edited symbol's instances update. Returns { symbolId }.
vector.renameSymbol	Rename symbolId to name. Returns the symbol summary.
vector.deleteSymbol	Delete symbolId; fails while instances use it unless detach: true turns them into groups.

Constraints

Command	Use it to
vector.listConstraints	Read every constraint (id, kind, refs with anchor ids, value, name, evaluated value, satisfied), the parameters, the degrees of freedom left (dof, status, redundant, per path) and conflicts from the last solve.
vector.addConstraint	Add a constraint (kind, refs by { nodeId, subpath, index } or anchor id, with segment, handle or circle; value / name / axis for dimensions) and solve. Fails, changing nothing, on conflicts or redundancy, naming the others. Returns { id, constraint }.
vector.removeConstraint	Remove constraints by ids; geometry stays.
vector.setConstraintValue	Set a dimension's value (by id or name) or a named parameter (null removes a parameter); values are expressions. Returns the summary.
vector.autoConstrain	Add what a sketch nearly satisfies (tolerances distanceTolerance, angleTolerance), skipping redundant or conflicting candidates. Returns { ids }.

Frames and artboards

Command	Use it to
vector.listFrames	Read every frame: id, name, parent, whether it is an artboard (top-level), its rectangle, fill and clip, document bounds, and its children's resizing constraints. Call before resizing or exporting frames.
vector.addFrame	Add an empty artboard at x, y, width, height (white unless fill; adopt: true takes in the top-level objects it encloses). Use for screens, cards, pages and export areas. Returns the frame as listed.
vector.frameSelection	Put objects sharing a parent into a frame fitted to their bounds plus padding (no fill unless given), in their place. Use to turn finished art into a resizable component. Returns the frame as listed.
vector.setFrame	Move or resize a frame's rectangle (x, y, width, height; children follow their constraints) or change its fill / clip. Returns { frames }. Set the children's constraints first.
vector.setResizing	Set how children of a frame follow it on resize (horizontal, vertical; a missing axis keeps its value). Fails on objects not directly inside a frame. Returns { nodes: [{ id, horizontal, vertical }] }.
vector.exportFrameSvg	Export one frame as an SVG of its own size (its corner at the origin). Returns { svg, width, height }; use it per artboard instead of vector.exportSvg.

Pages and master pages

Command	Use it to
vector.listPages	Read the pages (top-level frames in order, with number, masterId, bounds) and master pages (usedBy, bounds: place master art inside them).
vector.addPage	Add a page right of the others (after, name, masterId); the first page takes the artboard's art in. Add art with parentId. Returns { id } and the pages.
vector.addMasterPage	Add a master page (assignTo page ids or "all"): art in it (parentId) shows on its pages, laid out by resizing; text can show {page} and {pages}. Use for headers, footers, page numbers, backgrounds.
vector.setPageMaster	Make pages use a master, or none with null.
vector.movePage	Reorder a page (index from 0); numbers follow.
vector.goToPage	Select a page and show it to the user.

Connectors

Command	Use it to
vector.connect	Join two objects (or free points) with a connector: start / end as { nodeId, side? } (side auto by default: the side facing the other end) or { x, y }, route straight / elbow / curved, elbow radius, gap, stroke and arrowheads (a triangle at the end by default). Use for flowcharts and diagrams instead of drawing lines. Returns the connector as listed.
vector.setConnector	Reglue an end ({ nodeId, side? }), unglue it (null), or change route, radius, gap; also turns a plain open path into a connector. Returns { connectors }.
vector.listConnectors	Read every connector: route and each end's glued object, side setting, side in use and position.
vector.listConnectionSites	Read an object's sites (top, right, bottom, left, centre) with positions and outward normals, to pick a side.

Symmetry

Command	Use it to
vector.makeSymmetry	Put objects (or, with ids: [], nothing yet) in a live symmetry group: mode vertical / horizontal / dual / diagonal / radial (copies, mirror), center, rotation. Its copies follow every edit. Use for logos, mandalas, faces, ornaments: draw one half or one wedge. Returns { id, symmetry, children }.
vector.setSymmetry	Change mode, centre, rotation, copies or mirroring. Returns { groups }.
vector.releaseSymmetry	Stop repeating; expand: true keeps the copies as real objects (to edit one side alone). Returns { ids } of the added objects.
vector.enterSymmetry	Hand the canvas to the user drawing inside a symmetry group (pen, pencil, shapes, text go in, mirrored live). Returns { id }.
vector.exitSymmetry	Stop drawing inside it.

Perspective drawing

Command	Use it to
vector.getPerspective	Read the grid (vanishingPoints, origin, gridSize, extent, visible), its planes and drawingOn.
vector.setPerspective	Set a 1-, 2- or 3-point grid: vanishing points on the horizon, the origin below where the planes meet. Returns the grid.
vector.removePerspective	Remove the grid (art stays).
vector.setPerspectivePlane	Make the rectangle, ellipse, polygon and star tools (the user's drags) draw on a plane, or flat with null.
vector.attachToPerspective	Project objects onto a plane: draw them flat next to the origin (x right, y up from it), then attach. Use for signs on walls, tiles on floors, windows. Returns { ids }.

Lenses

Command	Use it to
vector.setLens	Make closed paths lenses (type magnify, fisheye, brighten, invert, tintedGrayscale, colorAdd, colorLimit, heatMap, wireframe, transparency; amount, color) or change them. What is below shows changed inside the outline and follows every edit; bounds stay the lens's own. Use for loupes, callouts, "X-ray" wireframes, duotone windows. Returns { lenses: [{ id, lens }] }.
vector.removeLens	Make lenses plain paths again. Returns { ids }.

Masks and clipping

Command	Use it to
vector.makeClippingMask	Group two or more objects sharing a parent (ids, default the selection) into a clip group: the topmost (or maskId) becomes the mask, moved to the bottom, and the rest show only inside its outline; invert: true shows them outside it. Fails, changing nothing, on fewer than two objects, a locked one or mixed parents. Returns { id, mask: { type, invert, maskId, contents, enabled } }.
vector.makeOpacityMask	Like vector.makeClippingMask, but the mask fades the contents by its brightness (type luminance, default: white shows, black hides) or opacity (alpha). Use a gradient-filled mask for fades. Returns { id, mask }.
vector.setMaskOptions	Change mask groups ids: type clip, alpha or luminance, invert, and enabled (false turns the mask off by hiding it; true on). Pass at least one. Returns { groups: [{ id, mask }] }.
vector.releaseMask	Undo masking of groups ids: the mask goes back on top and draws as itself; the group goes unless it has filters, a blend mode or effects. Returns { ids } (the mask last).

To edit the mask's shape, use its maskId from vector.list (or the mask a write returns) with the path-editing, style and transform commands; to move the contents inside the frame, transform the ids in contents. vector.setMaskOptions with enabled: false shows the contents whole while you work, without losing the mask.

Live effects and envelopes

Command	Use it to
vector.addEffect	Add a live path effect type (trim, roundCorners, puckerBloat, twist, zigzag, wiggle, offset, merge, repeater, envelope, contour: concentric steps blending to end colours, blockShadow: the shape swept along an angle under it, a long shadow when endOpacity fades, extrude: shaded side faces making the shape a solid, parallel or toward a vanishing point, bevel: a shaded chiselled edge inside the shape) with params to ids, at index in the stack (default last). Effects apply top to bottom. Returns { effects: [{ nodeId, effectId }] }.
vector.updateEffect	Change effect effectId on nodeId: params (merged), enabled, or move it to index (0 applies first). Returns the node's effect stack.
vector.removeEffect	Remove effect effectId from nodeId.
vector.envelope	Warp with a live envelope: a preset (arc, arcLower, arcUpper, arch, bulge, shellLower, shellUpper, flag, wave, fish, rise, fisheye, inflate, squeeze, twist) with bend, horizontal, vertical (percent, -100 to 100) and orientation; or a mesh of rows x columns (1 to 16, optional control points); or topObject: true (top closed path becomes the envelope), release: true, expand: true. Reapplying changes an existing envelope.
vector.expandAppearance	Bake path effects, envelopes and live booleans of ids (and everything inside) into plain paths. Returns the ids.

Blends

Command	Use it to
vector.blend	Make a live blend of two or more paths or groups sharing a parent (bottom to top, or the order of ids with keepOrder): shape and paint morph through in-betweens. spacing steps (default; steps default 5), distance (distance default 20) or smoothColor; orientToSpine; linear for straight anchor paths; starts maps key ids to start anchors. Returns { id }.
vector.blendOptions	Change spacing, steps, distance, orientToSpine, linear of blends; in-betweens regenerate.
vector.replaceSpine	With one blend and one path given, make the path the blend's spine; keys spread along it by arc length.
vector.expandBlend	Turn blends into plain groups of editable keys and in-betweens. Returns the group ids.
vector.releaseBlend	Remove the in-betweens and give back the keys (and a replaced spine as an unpainted path). Returns their ids.

Path editing

Command	Use it to
vector.moveAnchor	Move anchor (nodeId, subpath, index) to x, y in document units, carrying its handles; curvature: true bends its two segments like the Curvature tool instead (default: the curvatureMoves editing setting, off).
vector.bendSegment	Bend segment segment (anchor segment to the next) of nodeId / subpath so the curve passes through x, y at parameter t (default 0.5).
vector.deleteAnchors	Delete anchors. keepShape (default the editor setting, on) refits the neighbours so the outline keeps its shape.
vector.join	Join open subpaths of ids, nearest ends first (ends within tolerance merge, others get a straight segment); a single open path is closed.
vector.average	Move anchors to their average: same y (axis horizontal), same x (vertical) or same point (both, default).
vector.removeRedundantPoints	Drop anchors that can go without moving the outline more than tolerance units (default 0.5).
vector.smooth	Pull handles of ids (or of anchors) towards smooth tangents by amount 0 to 1 (default 1).
vector.cut	Scissors: cut nodeId at the outline point nearest x, y, or cut at anchors. A closed path opens; an open one splits in two. Returns the ids.
vector.knife	Cut closed paths along a polyline points (at least two [x, y]) wherever it crosses them edge to edge, leaving no gap. Cuts ids, else the selection, else every path crossed. Returns the pieces.
vector.erase	Erase along a polyline points with a round eraser of diameter size (default the eraser setting, 10): fills lose the area, outlines are cut. Returns the changed ids.
vector.smudgeBrush	Push outlines along a stroke points (two or more) with a soft round brush (radius, strength 0–1): drips, tentacles, organic lobes. Returns { ids }.
vector.twirlBrush	Twirl outlines about each point by angle degrees (default 15) at the brush centre: swirls, curls.
vector.attractBrush	Pinch outlines toward each point.
vector.repelBrush	Bloat outlines away from each point.
vector.roughenBrush	Spike the outlines under the brush (seed for repeatable spikes): fur, grass, torn paper.

Brushstrokes

Command	Use it to
vector.listBrushes	List the brushes a brushstroke can use: the dry presets (pencils, pastels, charcoal, crayon, chalk, markers, inks, ballpoint, gel pen, fineliner, gradient and multi-colour brushes), wet paint (watercolour, gouache, wet oils), the Mixer Brush, smudge and blender, then saved brushes from the brush library the vector profile admits, with their sizes and builtin, plus the editor's colorScheme and colorLocked. Brushes it refuses (thick paint, particles, stickers, erasers, the wet tools) are refused by vector.addBrushstroke with the reason. A saved brush is kept in the layer, so the document renders without the library.
vector.addBrushstroke	Paint paths with a brush along their outline (brushId, size, pressure profile such as [0.2, 1, 0.2] for a taper, color, default the brush's default colour (ballpoint blue, chalk), else the path's stroke; keepColour, or a lock from vector.setColorLocked, keeps the path's colour): sketchy, hand-drawn or inked lines that stay editable. Pass a seed (any integer) so the brush gets its character, the seeded jitter and paper grain that make pencil, pastel and charcoal look real; paper picks the grain ({ pattern, seed, scale, depth }) or null turns it off. paint is gradient paint sampled dab by dab along the path ({ type: 'gradient', stops, map: { by: 'distance', length, repeat } }, lengths in document units; also pressure, direction, across-tip, random; not velocity or time). Returns the stroke stacks.
vector.setBrushstroke	Change brushstroke layer index of path id: brush (another brush without color takes its default colour, unless keepColour or the colour is locked; giving the same brushId again takes that saved brush as the library has it now), size, pressure, colour, opacity, seed (a new seed is a new take on the same stroke; null: plain dabs), paper (replaced whole; null: no grain; {}: the default sanded paper) and paint (gradient paint, replaced whole; null: the colour again). Remove it with vector.removeStroke.
vector.setColorLocked	Lock (locked: true) or unlock brushstroke colours ("Keep my colour"): while locked, vector.addBrushstroke and vector.setBrushstroke with another brush keep the path's or layer's colour instead of the brush's default; an explicit color still applies. Strokes already made are unchanged. Respect a lock the person set. Editor state, not an undo step. Returns { colorScheme, colorLocked }.
vector.setColorScheme	Set scheme light or dark: the side of light / dark default colours (chalk) that brushstrokes made from now on take. Existing strokes keep their colour. Usually the host's job. Returns { colorScheme, colorLocked }.

Give brushstrokes a seed unless you want flat, even dabs: without one a charcoal or pastel line looks like a felt pen. Use different seeds on neighbouring strokes so they do not repeat each other, and paper: null for clean ink or marker lines that should not catch grain. The grain is laid in each path's own space, so it moves with the path.

Colour along the stroke. For colour that changes along the path, give the brushstroke paint (by: 'distance' with length about the path's length and repeat: 'clamp' runs the gradient once from start to end; across-tip loads the brush with several colours side by side; pressure follows the pressure profile). A gradient as the layer colour also works: its strokeMode along runs it from each subpath's start to its end, across lays it across the tip, and within (the default) lays it over the path's box. Gradient and multi-colour presets (gradient-round, rainbow-marker) paint their own gradient; their paint stops take the layer colour.

Wet paint (watercolor-round, watercolor-wash, gouache, oil-round) bleeds, blooms and granulates in its own small wet area, then dries. That takes a few seconds per stroke, so the canvas shows the paint as laid first and swaps in the settled stroke when it is ready; SVG and PDF exports always wait for it. Prefer a handful of wet strokes to dozens of short ones.

Mixer Brush, smudge and blender act on what lies beneath the stroke: the shapes below it in the document and the path's own fills and lower strokes. Put the path above the art it should work on (vector.arrange), give it no visible stroke of its own if only the effect should show, and draw it after the shapes are final: the stroke re-renders whenever something beneath it changes. They pick up fills (solid and gradient), plain strokes and other brushstrokes; not text, placed images, filters or masks. The result is drawn over the art, so a smudge can drag colour out onto bare paper but can't wipe the art away. The Mixer Brush paints from its reservoir (the layer colour) even with nothing beneath it; a smudge or blender over nothing draws nothing.

Editor settings

Command	Use it to
vector.setEditing	Set editing behaviour: keepShapeOnDelete, curvatureMoves, pencilSmoothing (0 to 1), recognizeShapes, eraserSize, distortMode / distortSize / distortStrength (the Distort Brush tool the user drags), pencilPressure (pen, all, off). Returns the settings.
vector.getSnapOptions	Read how drawing snaps for people at the pointer: grid, objects, guides, threshold, polar angles, object snap tracking, trackPolar, polarRelative.
vector.setSnapOptions	Set those options, e.g. polarIncrement: 15 for 15° polar tracking, or a grid, before handing the canvas to the user. Moves nothing. Returns the options.
vector.setTool	Switch the interactive tool (select, direct, pen, pencil, rect, ellipse, polygon, star, line, scissors, knife, eraser, width, shapeBuilder, paintBucket, blend, gradient, envelope, type, typePath, frame, connector). Only for handing the canvas to the user in a given mode; commands do not need a tool.

Generative prompts

Only when the host registered the generation tools (they cost money; pass a fresh idempotencyKey each time, the same one only to retry).

Tool	Use it to
list_vector_art_models	See which models can make vector art: image models (traced or stylised) and text models that write SVG.
generate_vector_art	Draw from a prompt into a box (x, y, width, height); as picks how pictures become vectors (color, threshold, mosaic, halftone, lowPoly, hatch). Returns { id, ids, model, adjustments }: the art is ordinary paths in one group, ready to restyle or edit.
regenerate_vector_art	Make a generated group again in place with a new seed or prompt.

Provider effects

From createVectorEffectsToolProvider, when the host has registered an effects provider (for example Flair). Only vector effects apply here: they bring their own picture. Motion is applied in the animation editor.

Tool	Use it to
search_effects	Find effects with kind vector (lower thirds, stickers, loaders, badges).
describe_effect	Read an effect's controls, defaults and presets before adding it.
list_applied_effects	List the groups that show provider effects, with their values.
apply_effect	Add an effect's picture at rest as a selected group of editable shapes (target "document" or a parent group id), fitted into the middle of the document. Returns the group id.
update_effect	Draw an effect group again with new values (effect "picture"); its place and transform are kept, but edits to its shapes are replaced.
remove_effect	Keep the group's shapes as a plain group, detached from the effect.

Save and open

The host may add the shared document tools (see pixerate-agent-tools). A vector document is the VectorDocument (artboard size, nodes, symbols, constraints); the tool, selection and view are not part of it.

Tool	Use
get_vector_document	Take a copy of the whole vector document as { kind, formatVersion, revision, document } before a risky rewrite, or to hand it on. To read the vector document, use vector.list: it is smaller and says more. Refuses very large documents.
load_vector_document	Put back a copy from get_vector_document (its document, or the whole result). Checked first: when anything is wrong nothing changes and the error says what. One undo step (undo_vector brings the previous document back). For SVG markup use vector.importSvg.
undo_vector	Undo the last vector edit (one command, one batch or one user gesture). Returns undone (the step's name) and whether more can be undone. Fails with "Nothing to undo." when there is nothing.
redo_vector	Redo the last undone vector edit.
save_vector_document	Save the vector document under a name in the host's storage (the same name replaces that copy). Returns the key. Only listed when the host has storage. Save when the user asks, not after every edit.
list_saved_vector_documents	List saved vector documents (key, name, savedAt), newest first.
open_saved_vector_document	Replace the vector document with a saved one by key. One undo step. Ask before opening over changes the user has not saved.

Pitfalls

The most common ones are below. Read references/pitfalls.md before working with connectors, frames, masks, filters, text, symbols, constraints, blends, gradient meshes or live corners.

• With agent playback on, vector.addShape is dragged out from (x, y) to (x + width, y + height), vector.addPath is traced through its anchors, and text is clicked in and typed out. So give shapes their real place and size in the first call rather than adding them at 0, 0 and moving them after: the user watches the cursor go where the shape lands. Commands with ids visit those nodes; nothing else about the calls changes.
• d and anchor positions are in the node's own space; bounds are in document space. For rotated nodes (rotation not 0), vector.moveAnchor and vector.bendSegment take document coordinates, so compute them from the drawn position, not from d.
• Stroke widths, corner radii and effect sizes are kept when scaling: scale them yourself if the design should grow proportionally.
• vector.importSvg without replace adds on top; with replace: true it discards the current document (undoable, but confirm with the user first).
• With a stack, vector.setStyle fill / stroke and the stroke settings edit only the top layer, and fill: null / stroke: null remove every layer. Edit other layers with vector.updateFill / vector.updateStroke, by the index vector.getAppearance reports.
• A command that fails changes nothing; read its message (for example "Nothing is selected; pass ids.") and retry with the missing input.