Merge main into feat/editable-flares

This commit is contained in:
dotCooCoo
2026-11-15 06:55:47 -08:00
458 changed files with 36345 additions and 2489 deletions
+501 -81
View File
@@ -1,6 +1,6 @@
# VectorCraft MCP server
> **Last updated:** 2026-11-14 · **Change:** Pencil ignores Smart Guides and Snap to Point and shows no Smart Guides, #7252; no response-shape change. Previously: Pencil continuation, straight-line and closing cursors; scores and estimates unchanged; no response-shape change. Previously: Snap to Point with Smart Guides off draws no Smart Guides labels or lines, #7250; no response-shape change. Previously: Envelopes: a top object's side whose pieces are all one curve split at anchors follows that curve's parameter (#7097); existing response shapes retained.
> **Last updated:** 2026-11-14 · **Change:** `text.setFormat {composer}` and paragraph styles also take `standardSingleLine` and `standardEveryLine` (#4935); existing values and responses unchanged. Previously: Pencil ignores Smart Guides and Snap to Point and shows no Smart Guides, #7252; no response-shape change. Previously: Pencil continuation, straight-line and closing cursors; scores and estimates unchanged; no response-shape change. Previously: Snap to Point with Smart Guides off draws no Smart Guides labels or lines, #7250; no response-shape change. Previously: Envelopes: a top object's side whose pieces are all one curve split at anchors follows that curve's parameter (#7097); existing response shapes retained.
>
> Tech Circuit update (2026-11-14): three original procedural brushes; ten built-in brush libraries (G5).
@@ -246,6 +246,21 @@ the suite) keep the agent to the folders you give it:
without a path of a document whose own format is SVG or SVGZ), `file.exportAs`, and the SVG Options dialog's
Show Code. A file given as another URL (`https://…`) is not checked. The document keeps the link, and the
person at the keyboard exports it as stored.
- The same SVG and SVGZ outputs are refused with "a linked image file is outside the read roots", which names no
file or folder, when the file would name a linked image's file outside the read roots (a path, a `file:` URL,
or a relative path taken from the document's folder). An `<image>` names the file with `images: "link"`, and
with `embed` when the document holds no pixels for the image. An image colorized with a solid fill names
no file when its pixels are gray (the file gets the colorized pixels) or missing (the file leaves it out).
With `preserveEditing`, the document the SVG carries names every linked image and placed file, the relative
paths kept of them and each data set's image, in every symbol, pattern, graph design and brush, used or not,
colorized or not, and a stored brush entry that does not read as a brush is refused too, since its links
cannot be checked. Otherwise the images of the art the file writes,
in opacity masks and in the symbols, patterns and brushes that art uses, are checked: hidden layers and
objects only with `hiddenLayers` (a save keeps them unless it is `false`), and template layers and the
layer of opacity-mask or symbol editing mode never. `selectedOnly` and `document.exportSelection` check the
selected objects only, and `clipboard.exportSvg` checks the copied objects, following a relative path from
the document they came from while it is open; in a frame a request drives, Copy then puts no SVG on the
system clipboard. An image whose pixels the document holds exports embedded, and a URL is not checked.
- `plugin.list`, `plugin.safeMode`, `file.recovery.*` and `ui_inspect`'s `scriptReport` leave out the paths
outside the read roots, also those the person or an earlier request put there. In `plugin.list`, the plug-in
folder last loaded is `null` in `folder.folder`, and a failed file in `folder.failed` and a plug-in's `source`
@@ -846,9 +861,13 @@ given), `threeD.mapGraphic`,
do not use the Appearance panel's active row. When the first object given is design art, rows and effects given with
`aligned: true` are rows of its stack in `appearance.setItem`, `appearance.removeItem`, `appearance.duplicateItem`,
`transparency.set` with an `item`, `effect.apply`, `appearance.addEffect` and the other `effect.*` commands that edit,
move or remove an effect: each other object edits the row or effect equal to it, and an object without one is left as
it is. When no object has one, `appearance.setItem` and `appearance.removeItem` leave the document as it is, as they do
for a row no object has, and the other commands are an error. `appearance.moveItem`, `effect.move` and
move or remove an effect, `paint.setFill`, `paint.setStroke`, `paint.invert`, `paint.complement`, `paint.lastColor` and
`paint.lastGradient` with an `item`, `stroke.set`, `stroke.setAdvanced`, `paint.editGradient`, `paint.setGradientGeom` and the `paint.freeform.*` commands
that edit points and lines: each other object edits the row or effect equal to it, and an object without one is left
as it is. When no object has one, `appearance.setItem` and `appearance.removeItem` leave the document as it is, as they
do for a row no object has, and the other commands are an error. The paint, stroke and gradient commands are also an
error when the art's row is not the kind of row they edit, and `paint.editGradient`, `paint.setGradientGeom` and the
`paint.freeform.*` commands without `stroke` edit the kind of the art's row. `appearance.moveItem`, `effect.move` and
`appearance.duplicateItem` with `to` are an error when the art's stack differs from the other objects', and
`appearance.duplicateItem` with `to` is also an error when two or more other objects are given, as it is without the
art. To change the art, edit the design with `graph.design`.
@@ -945,7 +964,8 @@ them in the Swatches panel does); give colour group names instead to reorder the
in the app runs `paint.setFill` (or `paint.setStroke`, the active proxy) with `ids: [the object under the pointer]`.
The Swatches panel menu's commands: `swatch.addUsedColors {selection?, global?}`, `swatch.unused` (a query: the
names Select All Unused selects; a spot swatch counts as used while an image placed from a DCS file has a plate of
its ink), `swatch.merge {names}` (the first is kept), `swatch.ungroup {name}` and
its ink), `swatch.merge {names}` (the first is kept; gradient stops linked to the others drop their process
plates), `swatch.ungroup {name}` and
`swatch.sortByKind`.
`brush.move {name | names, to?, type?}` reorders brushes among the brushes of their type, as dragging one onto
another of its type in the Brushes panel does. `to` is an index among the brushes of that type in `brush.list`
@@ -1060,6 +1080,11 @@ styles and brushes.
`color.removeProfile`, `view.proofSetup`, `view.proofColors`, `view.overprintPreview`, `view.separationsPreview` and
`swatch.setSpot` reject a param of the wrong type, such as `"bpc": "no"`, `"on": 1`, `"to": 5` or `"colors": "#fff"`,
and change nothing. Omitting a param or giving null keeps its default.
The Separations panel's Assign rows (where Edit › Assign Profile… goes) act on the profile of the document's color
mode: Don't Color Manage This Document runs `edit.assignProfile` with null for that model (no profile, so the colors
show through the working space), Working RGB or Working CMYK with the working space's name (that profile stays
assigned when the working space changes), and Profile with another profile of that kind. A choice the document
already has runs nothing, and the other model's profile stays as it is.
SVG import keeps what the canvas edits live. `<pattern>` becomes a pattern swatch. A `<symbol>` with `<use>` becomes a
symbol (named after its `data-name`, else its id) with an instance per `<use>`; a `<use>` that shows it differently
@@ -1129,7 +1154,8 @@ gradient meshes whose every point is at 0% opacity, and paths without effects wh
An image or a mesh with a Crop Marks effect, or with a Vector Halftone effect that makes dots, is measured.
Such objects in the art of a symbol are left out of its instances too, and an instance whose symbol holds nothing
else is left out. In the art of a dynamic symbol, an object that an instance's fill, stroke or opacity makes
the plot draw is measured.
the plot draw is measured. The art of an instance that goes through 9-slice guides is placed through them first, and
such objects are then left out of the placed art.
A document whose only visible art is left out is refused, and Export As refuses an HP-GL plot of it before the save
dialog. A PDF of that page, from either command, carries no Preserve Editing data; when Preserve Editing is on (as it
is in VectorCraft Default), the export comes back with a warning that says so. A `.ai` export with
@@ -1297,8 +1323,10 @@ opens at its size in points, the file's numbers times the `UserUnit` (one above
such a page opens from that data at the page's size.
`linkPages: true` (File › Open's Import PDF dialog: Import PDF pages as links) opens each page `pages` picks as a
placed document linked to that page of the file, as `file.place` with `link` places one, instead of as editable art.
Each page gets an artboard of its `cropTo` box (`bounding`: its art's bounds), in a row from the left 36 pt apart, and
a layer named after the page (`Page 2`). The document opens in CMYK when most of those pages are painted mostly in
Each page gets an artboard of its `cropTo` box (`bounding`: its art's bounds; a blank page gets its crop box), in a row from the left 36 pt apart, and
a layer named after the page (`Page 2`). A PDF-compatible `.ai` with `cropTo: "crop"` gets its trim boxes, as it does
when it opens as art. A page on its trim box shows its bleed box round the artboard, and the pages give the document
their bleed; the artboards are then 36 pt apart plus the bleed on both sides. The document opens in CMYK when most of those pages are painted mostly in
CMYK, unless `colorMode` names a mode. All the pages' objects share one copy of the file. The Links panel lists each
page, and `links.embed` makes a page editable art.
`document.open` refuses `linkPages` for a file that is not a PDF or a PDF-compatible `.ai`, for a file given as
@@ -1639,10 +1667,18 @@ preferences (the folder the desktop app uses, so both see the same ones; `VECTOR
command, so `edit.colorSettings {"cmyk": "…"}` or a preset's output intent can name it in a later run. The
copy is what counts: the original may move or be deleted. `color.removeProfile {name}` forgets a profile and its
copy (not while it is a working space).
- **Color Settings** (`edit.colorSettings`): the RGB and CMYK working spaces, intent and black point
compensation go into `Color Settings.json` when they change, and are the active settings again at the next
start, after the profiles above are registered (#6335). Saved settings that name a profile that is no longer
there, or a damaged file, leave the defaults (logged), and the next change writes over the file.
- **Color Settings** (`edit.colorSettings`): the RGB and CMYK working spaces, intent, black point
compensation and color management policies go into `Color Settings.json` when they change, and are the active
settings again at the next start, after the profiles above are registered (#6335). Saved settings that name a
profile that is no longer there, or a damaged file, leave the defaults (logged), and the next change writes over
the file; settings saved without policies take the default, `preserveEmbedded`. `rgbPolicy` (`off`,
`preserveEmbedded`, `convert`) and `cmykPolicy` (the same and `preserveNumbers`) decide what `document.open`,
`file.newFromTemplate` and `file.revert` do with an RGB or CMYK profile the file is tagged with that is not the
working space: keep it, take it off and keep the color numbers (`off`, `preserveNumbers`), or convert the colors
of that model into the working space with the intent and black point compensation and take it off (`convert`; a
profile that is not available stays). The reply's `warnings` name each profile, and a document a policy changed
opens with unsaved changes. A profile that is the working space stays whatever the policy. `document.open`'s
`colorMode` converts the colors after the policies, through the profiles the document keeps.
`edit.assignProfile` tags the document only: colors show and convert through the profiles it assigns, and the
working spaces and the file stay as they are. The profiles in use are those of the document in front, after
`file.new`, `document.open`, `document.activate`, `file.close`, `file.revert`, `edit.undo`, `edit.redo` and a
@@ -1797,6 +1833,15 @@ and the action still plays. `Session::replay` plays a journal the same way. The
hides the dock, no panel is checked, and the panel shows again with the dock in its earlier place; the toolbar and the
Control bar stay as they are.
While Tab or Shift+Tab hides the panels, resting the pointer for 0.3 s on a 6 pt band along the left or right edge of
the area below the bars shows the panels docked on that side of the canvas, over the canvas's edge; the canvas keeps its
size, so the art does not move. They hide again once the pointer has been away from them for 0.3 s, and stay while a
flyout opened from them, a menu or a pressed button is open. Floating panels, the toolbar and the Control bar stay
hidden, and Tab or Shift+Tab shows the panels for good. `window.panels.peek {side: "left" | "right"}` shows them as the
pointer does, `{side: null}` hides them, and `ui.docking`'s `peek` names the side shown (null for none). The command
refuses another side, a side with no docked panel, panels that are not hidden and Presentation Mode, and changes
nothing.
The export commands limit those keys. `document.export`, `document.exportSelection`, `document.serialize`, `app.export`
and `file.export` refuse a key that no format takes. They accept a key that only another format takes and do not use
it: `{"format": "pdf", "quality": 80}` writes the PDF, and the reply's `warnings` name the key
@@ -1975,8 +2020,9 @@ and `type.fractionalWidths`; `flip` in `type.dynamicTextPreset`; `remove` and `o
These commands refuse a string or another value that is not a number with `` `radius` must be a number, not "2" ``,
naming the key, and change nothing: `radius` in `shape.rectangle`; `sides` and `rotation` in `shape.polygon`;
`radius2`, `points` and `rotation` in `shape.star`; `diameter`, `opacity`, `brightness`, `growth`, `fuzziness`,
`rays`, `longest`, `rayFuzziness`, `rotation`, `rings`, `largest`, `x2`, `y2`, `direction`, `pathLength` and `seed`
in `shape.flare`; `decay` and `segments` in `shape.spiral`; `rows` and `columns` in `shape.rectangularGrid`; `concentric`
`rays`, `longest`, `rayFuzziness`, `rotation`, `rings`, `largest`, `x2`, `y2`, `direction`, `pathLength`, `seed` and
`ringSeed` in `shape.flare` (`seed` must also be a whole number of at least 0, and `ringSeed` a whole number from
0 to 2^53 - 1); `decay` and `segments` in `shape.spiral`; `rows` and `columns` in `shape.rectangularGrid`; `concentric`
and `radial` in `shape.polarGrid`; `size` and the `width`, `height` and `fitMinPercent` of `area` in `text.create`;
`size` and `fitMinPercent` in `text.createInPath`; `start`, `end`, `size`, `tracking`,
`baselineShift`, `hScale`, `vScale`, `rotation` and `strokeWidth` in `text.setRangeStyle`; `strokeWidth` in `text.setStyle`; `start` and `end` in
@@ -2571,6 +2617,9 @@ The rest of this section is VectorCraft's own rules:
`The Scripts folder cannot be read`.
- A listed file is checked again when it is chosen. A file that is gone, is no longer a `.js` or `.jsx` file under
the folder, or is or lies behind a link ends with `the script is no longer in the Scripts folder`, and nothing runs.
The file is read once for that check, and the text that read checked is the text that runs; its `#include` lines
and `$.evalFile` read in the folder that read found. `script.run {path, installed: true}` runs a listed script the
same way.
- The web build has no Scripts folder, and neither has a run with `VECTORCRAFT_NO_PREFS` set.
`script.listInstalled {}` returns the same listing: `{folder, scripts: [{path, label, folders}], truncated,
@@ -2706,6 +2755,16 @@ A click with the Selection tool on a guide selected with objects runs `select.ke
The key guide goes when it leaves the selection or no object is left selected, and an object key replaces it (and the other way round).
It returns `{key}`, the key object's id or null, with `guide`, the key guide's index, when a guide is the key.
`document.inspect` (the `inspect_document` tool) reports the key object as `key`, null without one, and the key guide as `keyGuide`.
`select.key {id, anchor: [subpath, anchor]}` makes an anchor point selected with Direct Selection the key anchor, while at least one other point (or a path selected whole) is selected too.
`select.anchors` with mode `add` or `toggle` and one point makes that point the key anchor when it selects it; a Shift-click on an anchor with Direct Selection runs it, and a plain click still selects that point alone.
Aligning to the key, `object.align` moves the other selected points to the key anchor's x or y and the key anchor stays put; a pixel-aligned path is then snapped to the pixel grid, as after any other edit.
`object.distribute {spacing}` and `object.distributeSpacing {spacing}` keep the key anchor in place and put the other points `spacing` apart, outward from it, in their order along the axis.
With `to: "selection"` or `"artboard"`, `object.align`, `object.distribute` and `object.distributeSpacing` do not treat the key anchor as the key: it moves with the other points, as without a key anchor.
The key anchor goes when it is deselected or deleted, when it is the only point left selected, when `select.key {}` cancels it, and when a key object or key guide replaces it.
An anchor that is not a selected anchor point (a selected segment's end is not one) is an error, and the key stays as it was.
The result has `keyAnchor: {id, anchor}` with a key anchor, and `document.inspect` reports it as `keyAnchor`.
The canvas draws the key anchor as a larger filled square in a frame, and the Align panel and the Control bar then name the Align To choice Align to Key Anchor.
The `ui.pointer` and `pointer_gesture` replies list it as `key` beside `selection`.
The command palette lists `select.key` as Cancel Key Object and runs it without an id.
@@ -2802,7 +2861,26 @@ group selected on its own, or, for `symbolInstance`, an object that is not a sym
leaves the selection empty. A selected object that is hidden or locked, inside a hidden or locked group or layer, on a
template layer, on a locked artboard while nothing is isolated, or outside the isolated group is passed over. New art,
such as a symbol instance just placed, is not passed over for being on a locked artboard while it stays selected. When
the selection holds no other object, they return the error "nothing selected".
the selection holds no other object, they return the error "nothing selected". `appearanceAttribute {item?}` takes
the fill or stroke at appearance item `item`, or the Appearance panel's active item when the call gives none or null; a
value that is not a whole number of 0 or more fails with "`item` must be a whole number" and leaves the selection as it
was.
`select.similar {by?}` is the Control bar's Select Similar Objects button and the Select Similar Options menu beside it
([help](https://help.adobe.com/archive/en_US/illustrator/cs5/illustrator_cs5_help.pdf#page=165)). It selects the
objects like the first selected object by `by` and returns `{count, by}`. `by` is `fillColor`, `fillAndStroke`,
`strokeColor`, `strokeWeight`, `opacity`, `blendingMode`, `appearance`, `graphicStyle`, `shapeType` or
`symbolInstance`, which runs the `select.same.*` command of that name, or `all`, which selects the objects whose fill
and stroke colors, stroke weight, opacity and blending mode all match (tints, compound paths and Live Paint faces as
`select.same.fillColor`); Select › Reselect repeats `all` as `all`. The menu's items, their order and what `all`
compares are VectorCraft's own. A `by` given is kept for the session once the selection is made, and the menu checks
it; without `by` the command uses the kept one, `all` until one is given. Any other `by` is an error that keeps the
selection and the kept attribute, and an error of the `select.same.*` command it runs (for example "the selection has
no graphic style") keeps the kept attribute too. It needs a selection and records no undo step; the journal records the
attribute used, so a recorded action repeats it, and a script run that fails puts the kept attribute back. The button
and the menu show while something is selected and the
Object Options group is on, at the right end of the bar after the X, Y, W and H fields. They take only the room the
other controls leave, so the bar leaves them out, together, before any other control.
`select.object.allOnSameLayers` selects the objects on the layers and sublayers of the selected objects that can be
selected. A selected object that is hidden or locked, inside a hidden or locked group or layer, on a template layer, on
@@ -2933,6 +3011,38 @@ changes neither option. Behavior reference: [View artwork](https://helpx.adobe.c
{"name":"invoke_menu","arguments":{"command":"ui.navigatorPanelOptions","params":{"color":"Light Blue","solidDashes":true}}}
```
## Info panel
`info.readout` takes no params and returns what Window › Info shows for the selection and the tool in use:
`{tool, width?, height?, readout?}`. `tool` is the active tool's id. `width` and `height` are the sides of the
selection's bounding box in points (of the box around the anchors selected with Direct Selection when there are
some), measured as the `usePreviewBounds` preference says, and are left out with nothing selected. `readout` is left
out unless the tool has something of its own to show:
- `{kind: "drag", dx, dy, distance, angle}` while the Selection, Direct Selection or Group Selection tool moves the
selection, or the Gradient tool draws a gradient vector on the art.
- `{kind: "scale", width, height}` during a Scale tool drag, in percent.
- `{kind: "rotate", center, angle}` and `{kind: "reflect", center, angle}` during a Rotate or Reflect tool drag.
`angle` is the angle turned, as `object.rotate` takes it, or the angle of the reflection axis, as `object.reflect`
takes its `axis`. Both are in degrees counter-clockwise.
- `{kind: "shear", center, axis, angle}` during a Shear tool drag. `axis` is 0 for a horizontal shear and 90 for a
vertical one, and `angle` is the shear angle in degrees, as `object.shear` takes it.
- `{kind: "brush", brush}` while the Paintbrush is the tool. `brush` is the brush it paints with, or null.
Lengths are in points. A drag's `angle` is in degrees counter-clockwise from the x axis. `center` is the center of the
selection's bounding box as the drag has carried it, in document coordinates. A param is an error. In the app's panel, X and Y show the
pointer's position from the rulers' zero point, or `center` during a Rotate, Reflect or Shear tool drag. W and H show
the selection's size, `dx` and `dy` during a drag (with the distance and the angle under them), or the Scale tool's
percentages. The Zoom tool adds the view's magnification and the Paintbrush its brush's name. Several selected objects
show only the fill, stroke and type values they share, and Show Options adds a tint's swatch and percentage and the
name of a gradient's swatch. The number formats, the rows shown between drags and the Direct Selection and Group
Selection readouts are VectorCraft's own. Behavior reference: the Info panel overview in the
[archived user guide](https://web.archive.org/web/20220911143322/https://helpx.adobe.com/pdf/cs6/illustrator_reference.pdf#page=76).
```json
{"name":"run_command","arguments":{"command":"info.readout","params":{}}}
```
## Tools panel placement
By default the docked Tools panel sits at the window's left edge, outside any panels docked on the left.
@@ -3094,7 +3204,9 @@ number. `guide.add {vertical, pos, artboard?}` makes one (the x of a
vertical guide, the y of a horizontal one, in points) → `{index}`. With `artboard` (an artboard's index) it is an
artboard guide: it runs across that artboard only, moves with it (`artboard.move`, a pure move in
`artboard.setProps`, `artboard.rearrange`), scales with it (`artboard.setProps {scaleArt}`), is copied with it (`artboard.duplicate`, `artboard.move {copy}`) and is
deleted with it (`artboard.delete`); without, a canvas guide runs across the whole canvas. `guide.list` →
deleted with it (`artboard.delete`); without, or with null, a canvas guide runs across the whole canvas. An `artboard`
that is not a whole number of 0 or more fails with "`artboard` must be a whole number", and an index past the last
artboard with `no such artboard`; neither adds a guide. `guide.list` →
`[{index, id, vertical, pos, selected, artboard?, layer?, hidden, locked, shown, editable}…]` (`artboard` only for
artboard guides; `id` is the guide's node and `layer` the layer it is on; `hidden` and `locked` are its own state,
`shown` and `editable` also take its layer into account). `layer.setProps {ids: [id…], visible?, locked?}` hides or
@@ -3273,9 +3385,12 @@ already walks Image Trace. Short agent entry points:
`brush.duplicate {name, newName?} | {names}`, `brush.freehand {…path.freehand params, brush?}`,
`object.expandBrush {ids?}`. `brush.freehand` draws the plain path when `brush` is left out or null. It refuses a
`brush` that is not a string with "`brush` must be a string", a name that no brush in the document has (an empty
name included) with "no brush named `<name>`", and a `style` other than "pencil" or "brush"; the document does not
change and no undo step is recorded. The Paintbrush skips a tool brush or current brush that has been deleted and
paints with the other, or draws the plain path when neither is in the document. A document or brush
name included) with "no brush named `<name>`", a `style` other than "pencil" or "brush", a `brush` for a path
with no stroke (a continued or redrawn path without one, or a new filled "pencil" path while the stroke is None)
with "cannot apply brush `<name>`: path has no stroke", and a key that neither `path.freehand` nor `brush` names
with "unknown parameter"; the document does not change and no undo step is recorded. A stroke drawn with a brush
is one undo step: Undo removes the path and its brush together. The Paintbrush skips a tool brush or current
brush that has been deleted and paints with the other, or draws the plain path when neither is in the document. A document or brush
library file whose brushes repeat a name is read with the first brush of that name as stored and each later one
numbered with the first "`<name>` 2", "`<name>` 3"… the file does not have; strokes of the name keep the first
brush. `brush.new`,
@@ -3331,7 +3446,12 @@ already walks Image Trace. Short agent entry points:
`variable.makeTextDynamic`, `variable.makeVisibilityDynamic`, `variable.makeImageDynamic`, `variable.makeGraphDynamic`
(`variable.bind` and `variable.makeTextDynamic` refuse type that already has another text variable and name it),
`variable.unbind`, `variable.rename`, `variable.delete`, `variable.highlight` (image values are file paths, graph
values CSV as `graph.setData`). `variable.lock {locked?}` (Lock Variables) locks or unlocks the variables;
values CSV as `graph.setData`). `variable.rename {name, newName?, kind?}` is Variable Options: it renames a
variable, changes its kind, or both, in one undo step, and adds none when the name and kind are the ones it has.
A kind change unbinds each object that can't hold the new kind (a text variable keeps type with no other text
variable, an image variable keeps image objects, a graph variable keeps graph roots, a visibility variable keeps
every object; locks and hidden layers don't unbind anything) and drops the variable's values in every data set.
That rule is VectorCraft's own. `variable.lock {locked?}` (Lock Variables) locks or unlocks the variables;
without `locked` it toggles, and the lock is saved with the document. While the variables are locked,
`variable.define`, `variable.delete`, `variable.rename`, the four `variable.make…Dynamic` commands and a
`variable.loadLibrary` that would delete or define a variable (below) fail with "variables are locked";
@@ -3340,7 +3460,14 @@ already walks Image Trace. Short agent entry points:
without a kind VectorCraft reads is listed with `kind: "unknown"`: it takes no values, and `variable.bind`
refuses it. When an opened `.ai`'s layers are read, the objects it binds to its text, visibility and image
variables come in bound when they are of the variable's kind, locked and hidden objects included, and
`variable.list` counts them in `bindings`.
`variable.list` counts them in `bindings`. `variable.sort {by: name|object|type|none, descending?}` sorts the
Variables panel's list, as a click on its Variables, Objects or type column header does (a second click on the
same header sends `descending: true`): by variable name, by the name of the bound object, or by type in
VectorCraft's order (text, image, graph, visibility, then unknown); `none` is the order the variables were
defined in. Names compare without regard to case; by object, unbound variables come first and variables bound
to several objects last, and ties go by name. Another `by` value, or a `descending` that is not true or false,
is an error. The sort is panel state, not saved and not an undo step; `variable.list` lists the variables in
that order and reports it as `sort: {by, descending}`.
- Data sets: `dataset.list`, `dataset.new {name, values?}`, `dataset.set {name, newName?, values?}` (`newName` also
renames the row, in the same undo step; Edit Data Set's Name field sends it), `dataset.rename`,
`dataset.delete`, `dataset.capture`, `dataset.update`, `dataset.select {name}`, `dataset.next` /
@@ -3708,6 +3835,16 @@ already walks Image Trace. Short agent entry points:
black ring around a white disc around a black dot, black gets two groups. `layer.releaseToLayers` on the expanded group then
gives each group a sublayer. A trace made with `autoGrouping` is refused. Expanding by color also refuses a trace
with a live Pathfinder effect.
An Abutting trace with Fills (not Flat Logo) also holds a group named `Seam Fills` under its paths: for each color, a
stroke 1.5 image pixels wide (at the image's larger scale, when it is stretched more one way) with butt caps and round joins along the edges where a filled path of that color meets a
filled path drawn after it, in that color (a gradient path's stroke takes its gradient). Without it, a renderer that
anti-aliases each path on its own shows a light hairline along every shared edge. The traced paths and their shared
edges are the same with or without it, and edges against the image's border, a transparent area or a color left out
get no stroke. A trace whose paths have more than half of the trace's anchor limit (8,000,000, 2,000,000 on the web)
has no seam fills, so that paths and seam fills together stay within the limit. Both Expand commands keep the group, and `byColor` leaves it under every color's group. The strokes
are separate objects: after Expand, recoloring, moving or deleting a traced path leaves them as they are, and deleting
the group removes them. The reply's
`paths` and `anchors` count the traced paths only.
With `keepColors` in `params`, the reply's `warnings` name each listed color that no traced color matches, and say
when nothing was traced.
`imageTrace.presets.save {name?, newName?, preset?, enhanced?, params?}` saves tracing settings as a preset kept with
@@ -3823,8 +3960,13 @@ already walks Image Trace. Short agent entry points:
arrives and is its own undo step. `match` is the paint the face or edge had before the first of the double-click's
two clicks or the triple-click's three that painted it, or before the double-click when the triple-click's double-click
reached it, so the clicks before the last do not change what it matches;
a first click that made the Live Paint group counts when the face it filled is the clicked face. Hidden faces and edges are not painted. An edge takes the
paint and weight in its topmost stroke that is shown, or in a new stroke above the others when it has none. These rules
a first click that made the Live Paint group counts when the face it filled is the clicked face. Hidden faces and edges are not painted. A face that
the Bucket fills has all its fills replaced by one fill with the paint, shown, fully opaque and blending normally, in the
place of its topmost fill; its strokes, their order and the face's own visibility, opacity and blending mode stay as
they are. An edge that it strokes has all its strokes replaced the same way by one stroke with the paint and weight,
which keeps the dashes, caps, joins and arrowheads of the edge's topmost shown stroke (of its topmost stroke when every
stroke is hidden), and its fills stay as they are. A part with no fill or stroke gets a fill below its strokes or a stroke
above its fills. A fill or stroke of none leaves one row of none, so no fill or stroke of the part draws. These rules
for what faces and edges join and what paints match are VectorCraft's own. The help page describes the gestures:
https://helpx.adobe.com/illustrator/desktop/paint-and-fill/learn-painting-basics/paint-with-the-live-paint-bucket-tool.html.
`livePaint.fill {scope}` and `livePaint.strokeEdge {scope}` take `scope` as `"one"` (the default), `"connected"` or
@@ -3848,8 +3990,9 @@ already walks Image Trace. Short agent entry points:
error. With `ids`, at a point on a hidden face it fills the face there of another Live Paint group among the
objects; otherwise it returns an error and does not merge the objects.
A Live Paint command that changes nothing records no undo step, keeps the redo steps, leaves a saved document saved
and replies as usual: `livePaint.fill` (a click, or a Bucket drag) when every face it reaches already has the paint,
`livePaint.strokeEdge` when the topmost shown stroke of each edge it reaches already has the paint and the width,
and replies as usual: `livePaint.fill` (a click, or a Bucket drag) when every face it reaches already has one fill, shown,
fully opaque, blending normally and with the paint (or no fill, for none), `livePaint.strokeEdge` when every edge it
reaches already has one such stroke with the paint and the width (at any width for none, or no stroke),
`livePaint.gapOptions` (and the Gap Options
dialog's OK) when every group already has the options and `closeGaps` finds no gap, and `livePaint.make` or
`livePaint.merge` given one Live Paint group alone, which they select. Such a fill or stroke also leaves the recent
@@ -4087,6 +4230,26 @@ it as a path. Extrude & Bevel (Classic), Revolve (Classic) and Rotate (Classic)
{"name":"run_command","arguments":{"command":"effect.setParams","params":{"index":0,"item":null,"params":{"shadow":true,"shadowPosition":"below","shadowDistance":10,"shadowBounds":150}}}}
```
## 3D render mode
Revolve, Extrude & Bevel, Inflate and Rotate take `render`, an object whose `mode` is `"shaded"` (the default) or
`"wireframe"` (**Window › 3D and Materials** › Render Settings › Wireframe), set with `effect.apply` or
`effect.setParams` in one undo step. In wireframe mode the effect stays live and draws the edges of the faces it
builds instead of its shaded surface: each edge once, in the paths [Expand as Wireframes](#expand-as-wireframes)
gives for the 3D effect, with a 0.5 pt black stroke, round joins and no fill (VectorCraft's own choice), and no shadow or graphics.
The edges are drawn whatever the opacity, blending mode or opacity mask of the fills, strokes and group members; the
object's own opacity, blending mode and opacity mask apply to them as a whole.
Geometry effects after the 3D effect reshape the drawn edges. Expand as Wireframes reshapes each face before it
joins the edges, so with such an effect its paths can differ from the drawn ones. The mode is saved in the native file, SVG and PDF exports
draw the edges, and `effect.expandAppearance` keeps them as paths. Past 1,000,000 edges the source path is drawn, as
it is for a solid past its limits. A `render` that is not an object, a key other than `mode`, another mode, and
`render` on Extrude & Bevel (Classic), Revolve (Classic) or Rotate (Classic) are refused before the document
changes. See [three-d.md](three-d.md#3d-and-materials-panel).
```json
{"name":"run_command","arguments":{"command":"effect.setParams","params":{"index":0,"item":null,"params":{"render":{"mode":"wireframe"}}}}}
```
## 3D object type
`effect.setParams {index: int, threeDType: "plane" | "extrude" | "revolve" | "inflate", params?, item?, ids?, aligned?}`
@@ -4199,6 +4362,13 @@ is tall), `bevelInside` (false adds the bevel around the shape, true carves it i
- `shadingColor`: `black` (the default), `custom` (darkens toward `shadingCustom`, a `#rrggbb` color) or `none` (the
paint is kept and only the highlight lightens it). `drawHiddenFaces` also draws the faces turned away from the
viewer, behind the others.
- `preserveSpotColors` (default false) is the Lighting tab's Preserve Spot Colors checkbox. When it is on, a fill or
stroke linked to a spot or global swatch stays linked on every face, so a spot color prints on its own plate in
separations and PDF. The highlight lowers the swatch's tint, and a face that darkens gets black at the shade's
strength over the swatch, multiplied and overprinting. These rules for drawing the shading are VectorCraft's own. The
option does nothing while `shadingColor` is `custom`, since a custom shading color cannot keep a spot color
([Preserve Spot Color](https://help.adobe.com/archive/en_US/illustrator/cs5/illustrator_cs5_help.pdf#page=260)).
Unlinked colors, gradients, patterns and the Wireframe surface draw as they do with it off.
The defaults are VectorCraft's own. An unknown parameter, a number out of range, a flag that is not true or false, or
an unknown surface or shading color is refused with an error and the document is not changed.
@@ -4215,8 +4385,8 @@ for a full turn, and draws every face, back to front, with the classic surfaces.
0..360, default 360), `cap` (true closes the profile's open ends, false leaves the surface hollow), `offset` (points,
0..1000, default 0; the axis's distance from the profile, so a value above 0 makes a ring), `edge` (`left`, the
default, or `right`: the edge of the profile's bounds the axis is at), `rotationX/Y/Z` and `perspectiveAngle` as
above, and `surface`, the lights, `ambient`, `highlightIntensity`, `highlightSize`, `blendSteps`, `shadingColor` and
`shadingCustom` as Extrude & Bevel (Classic) takes them. It has no `drawHiddenFaces`. The effect also goes on a group
above, and `surface`, the lights, `ambient`, `highlightIntensity`, `highlightSize`, `blendSteps`, `shadingColor`,
`shadingCustom` and `preserveSpotColors` as Extrude & Bevel (Classic) takes them. It has no `drawHiddenFaces`. The effect also goes on a group
or layer, whose members turn about one shared axis, or on a fill or stroke. The public documentation describes the
dialog ([Create 3D objects](https://helpx.adobe.com/illustrator/desktop/special-effects-styles/create-3d-graphics/create-3d-objects.html))
and its Angle (0 to 360), Cap, Offset (0 to 1000) and Left Edge or Right Edge settings
@@ -4235,8 +4405,8 @@ changed.
3D (Classic) › Rotate (Classic)…. It turns every fill and stroke as one flat plane about the center of the object's
bounds, as `threeD.rotate` does, each in its own paint, and draws the plane from either side. Parameters:
`rotationX/Y/Z` and `perspectiveAngle` as above; `surface` (`diffuse`, the default, lights the art softly, and
`none` keeps the paint unlit); and the lights, `ambient`, `blendSteps`, `shadingColor` and `shadingCustom` as Extrude &
Bevel (Classic) takes them. It has no highlight, no `drawHiddenFaces` and no shadow. The effect also goes on a group
`none` keeps the paint unlit); and the lights, `ambient`, `blendSteps`, `shadingColor`, `shadingCustom` and
`preserveSpotColors` as Extrude & Bevel (Classic) takes them. It has no highlight, no `drawHiddenFaces` and no shadow. The effect also goes on a group
or layer, whose members turn about one shared center, or on a fill or stroke. The public documentation describes the
dialog's Position and Surface settings
([Rotate objects in 3D](https://helpx.adobe.com/illustrator/desktop/special-effects-styles/create-3d-graphics/rotate-objects-in-3d.html)),
@@ -4334,7 +4504,11 @@ stay tints), `scaleTints` (every colour becomes a tint as light, relative to the
darker than the row's average become tints and shades) or `hueShift` (the most saturated colour takes the new colour,
the others turn by the same hue). `limitTo` snaps new colours to a swatch library's nearest colour;
`recolor.randomize {map, order?, saturationBrightness?, seed?}` shuffles or varies new colours; a row with
`exclude: true` keeps its colours. With `limitTo`, a row's `tint` (a percentage, default 100) gives the art
`exclude: true` keeps its colours. A row's `from` may be an empty list: the row recolors nothing, adds no library swatch with
`limitTo` and gives `group` no color, and `recolor.randomize` and `recolor.weigh` keep it. A row without `from`, or with
a current color that is not a color, is refused. With art selected, the Recolor Artwork dialog's New Row button (beside
Merge) adds such a row above the first selected row, or at the top, with that row's new color, and selects it; Shift-click another row and Merge to move its colors into it. An
empty row does not count toward Colors. With `limitTo`, a row's `tint` (a percentage, default 100) gives the art
linked to the global or spot swatch its new color is that share of its tint; `tint` must be a number. `recolor.randomize`
moves a row's `tint` with its new color and removes it from a color it changes, and moves a row's `model` with its new color. `swatch.editGroup {group, colors, rename?}` rewrites a colour group in one undo
step (art linked to its global swatches follows), and `recolor.apply` with `group` recolours the art and rewrites the
@@ -4862,6 +5036,14 @@ and `height`, so a new `hSpacing` changes the tile's width. `pattern.options` st
`object.pattern.edit` edits the pattern that fills or strokes a selected object, and `pattern.options` changes the
pattern being edited; each returns an error when there is no such pattern. `pattern.delete` requires `name`.
With `pattern.options {moveTileWithArt: true}` (Move Tile with Art), a move of all of the tile art in pattern editing
mode moves the tile by the same offset: `object.move`, `object.nudge`, `object.transform` with a translation, and drags
with the Selection tool. A move of only some of the art, a move of direct-selected anchors, a copy, a rotation and a
scale leave the tile where it is. The option is off for a new pattern and works the same with `sizeTileToArt` on. These
details are VectorCraft's own rules; the help page says only that the option moves the tile along with the art
(<https://helpx.adobe.com/illustrator/desktop/paint-and-fill/create-and-edit-patterns/edit-patterns.html>).
`pattern.list` reports it as `moveTileWithArt`. A `pattern.options` call that changes nothing records no undo step.
```json
{"name":"run_command","arguments":{"command":"pattern.options","params":{"showSwatchBounds":true}}}
{"name":"run_command","arguments":{"command":"prefs.set","params":{"key":"patternTileEdgeColor","value":"#ff4f4f"}}}
@@ -5389,17 +5571,30 @@ SVG Filter (New, Edit, Delete, Import…), and from the Appearance panel it edit
The canvas, raster export, printing and PDF draw the filter with the object as its source graphic, its user space
starting at `origin` (`[x, y]` in points, `[0, 0]` by default) with its units `scale` points (1 by default), its
object bounding box the drawn object's, and at the Document Raster Effects resolution when the view is finer. The
axes along `axes` (`[a, b, c, d]`: one unit along the filter's x axis points `[a, b]` in the document and one along
its y axis `[c, d]`, before `scale`; absent or `[1, 0, 0, 1]`, the document's axes, and `effect.setParams` sets them
back with `[1, 0, 0, 1]`, since the commands refuse `null`; each number -1000 to 1000 and `a·d - b·c` at least
0.001 from 0, or the command refuses it), its object bounding box the drawn object's, and at the Document Raster Effects resolution when the view is finer. The
filter runs on coarser pixels when a morphology radius or kernel unit would span more than 32 of them, or a standard
deviation more than 512. An effect whose XML these rules refuse (from a file or a script) is not drawn or exported. The
deviation more than 512. With `axes`, the filter runs on pixels lined up with its own axes, so offsets, blurs and the
region run along them, and the result is drawn onto the object's pixels through `axes`; those pixels are about as fine
along each axis as the object's and coarser when there would be more than 4 times as many, or when a radius, kernel
unit or standard deviation would span more than 32 or 512 of them. The object's box is then
its box in that user space: a region measured against it, and a region or primitive lengths in `objectBoundingBox`
units, are measured against that box. Moving, turning, scaling or skewing the object moves `origin` with it and
leaves `axes` as they are, and `scale` too unless Scale Strokes & Effects scales it. An effect whose XML or `axes` these rules refuse (from a file or a script) is not drawn or exported. The
filter is drawn and written rebuilt from its filter elements and their filter attributes alone, without comments,
text, descriptions or other attributes. An image in a filter is drawn only when its bytes are a PNG, JPEG, GIF or WebP
within the pixel limit. A filter region in user space given in percentages is measured against the object's box (x
and y from its top-left corner), and one in em or ex or left out takes the default region of that box (10% beyond
each side); these are VectorCraft's own rules. Scale Strokes & Effects scales
`scale`. SVG export writes the filter as a `<filter>` element when it is the object's last effect, its only pixel
effect and `scale` is 1 (with a region measured against the object's box, its only raster effect), with the object in a
group that places the filter's user space and such a region written in user units. The filter is written in SVG 1.1
`scale`. SVG export writes the filter as a `<filter>` element when it is the object's last effect and its only pixel
effect (with a region measured against the object's box, its only raster effect) and SVG import can store its user
space again (`scale` and `axes` together within the import limits below), with the object in a
group that places the filter's user space and such a region written in user units. When `scale` isn't 1 or the effect
has `axes`, that group's transform is the filter's user space and the object is written in document coordinates in a
group inside the filter whose transform is the inverse, so its strokes keep their widths; SVG import reads that back
as the same `scale`, `origin` and `axes`. The filter is written in SVG 1.1
terms: `feImage`'s reference as `xlink:href`; each `feDropShadow` as the blur, offset, flood, composite and merge that
[Filter Effects](https://www.w3.org/TR/filter-effects-1/#feDropShadowElement) gives as its equivalent; colors as
`#rrggbb` with a flood color's alpha in `flood-opacity`; `image-rendering` as `optimizeSpeed` or `optimizeQuality`;
@@ -5411,9 +5606,12 @@ whose `flood-color` is `currentColor` or with `primitiveUnits="objectBoundingBox
its shadows are expanded, has no SVG 1.1 form. Neither does a filter whose written form, with its region and id, is
one SVG import would not read, such as one longer than 64 KB. In that case, otherwise, and with the SVG Tiny 1.2 profile, the object
becomes an image. SVG import keeps a filter that the live effects (Drop Shadow, the
glows, Gaussian Blur, Feather) can't express as an `svg.filter` effect holding the filter's XML, with `scale` and
`origin` from the object's user space, unless that user space is turned, skewed or scaled past 0.001 to 1000 points
to a unit, or the filter is styled by the document's style sheets: such a filter is left out with a warning. The native format keeps the document's filters and the effects.
glows, Gaussian Blur, Feather) can't express as an `svg.filter` effect holding the filter's XML, with `scale`,
`origin` and, when the object's user space is turned, skewed or scaled unevenly (a `rotate`, `skewX`, `skewY`, uneven
`scale` or `matrix` transform), `axes` from that user space, so the filter runs in the element's user space as
[SVG 1.1](https://www.w3.org/TR/SVG11/filters.html#FilterEffectsRegion) defines it. A filter is left out with a
warning when that user space is scaled past 0.001 to 1000 points to a unit (the square root of its area scale), its
`axes` would pass the limits above, or the filter is styled by the document's style sheets. The native format keeps the document's filters and the effects.
```json
{"name":"run_command","arguments":{"command":"svgFilter.define","params":{"xml":"<filter id=\"Soft\"><feGaussianBlur stdDeviation=\"2\"/></filter>"}}}
@@ -5519,11 +5717,28 @@ moves that point alone as the focal point, with or without Shift (Shift keeps th
focal points stay highlighted where it left them; Escape during a drag puts the path back and keeps them, and
switching to another tool clears them.
`path.eraseRegion` (the Eraser) takes a variation mode for each of its tip's values, as the variation menus of
Eraser Tool Options set them ([Erase paths using the Eraser
tool](https://helpx.adobe.com/illustrator/desktop/draw-shapes-and-paths/modify-paths/erase-paths-using-eraser-tool.html)):
`angleMode` with `angleVariation` (degrees, 0 to 180), `roundnessMode` with `roundnessVariation` (percent, 0 to 100)
and `sizeMode` with `sizeVariation` (points, 0 or more), each `"fixed"` (the default), `"random"`, `"pressure"`,
`"tilt"`, `"bearing"` or `"rotation"`. A value that varies takes up to its variation either way. Random draws one
value for the drag. Pressure goes from the value less the variation where the pen presses lightest to the value plus
it where the pen presses hardest. Tilt goes from less with the pen lying flat to more with it upright. Bearing and
Rotation go from less at −180° to more at 180° of the way the pen leans or its barrel turns. The tip at each point of
the drag takes what the pen read there (the points' pressure, tilt and rotation, as `path.freehand` takes them); a
drag without that reading, such as a mouse drag, erases at the value itself. One Random value per drag, which way
Tilt, Bearing and Rotation run, and the value itself without a reading are VectorCraft's own rules.
The command refuses another mode, and a variation below 0 or past its range, and erases nothing. In the desktop app
the Eraser's tip outline at the pointer takes the angle, roundness and size the pen gives while it erases.
`tool.setOption {tool: "eraser"}` takes the same keys.
These commands refuse a string or another value that is not a number with `` `dy` must be a number, not "10" ``,
naming the key; the document does not change and no undo step is recorded: `t`, `dx` and `dy` in
`path.reshapeSegment` and `object.blend.spine.reshapeSegment`; `x`, `y` and `t` in `path.curvatureEdit`; `x` and `y`
in `path.convertAnchor`; `t` in `path.insertAnchor`; `fidelity` and the `within` of `redraw` in `path.freehand` (and in
`brush.freehand`, which runs it); `size`, `sizeVariation`, `angle` and `roundness` in `path.eraseRegion`;
`brush.freehand`, which runs it); `size`, `sizeVariation`, `angle`, `angleVariation`, `roundness` and
`roundnessVariation` in `path.eraseRegion`;
`size`, `sizeVariation`, `angle`, `roundness` and `fidelity` in `path.blob`; `width` in `path.eraseSegments`;
`radius` and `fidelity` in `path.smoothRegion`; `tolerance` in `path.joinScrub`; `dx` and `dy` in `path.moveAnchors`;
and `dx`, `dy`, `tol` and `radius` in `path.reshape`. A null is read as a key left out. `path.convertAnchor` refuses
@@ -5686,7 +5901,17 @@ the colour bars are process, spot and black-tint patches. Layers whose Print opt
The Output and Advanced sections convert colours and write real text. `output: {conversion, destination}` converts
every colour into the destination profile's model (`destination`; CMYK of another profile too) or only the colours of
the other model (`preserveNumbers`: colours already in it keep their numbers); grey stays grey, images are converted
too and printer's marks are not. The destination is any profile `edit.colorSettings` lists (default: the document's
too and printer's marks are not. With `destination` and an sRGB destination, a gray or RGB image that carries an
ICC profile is converted from that profile to sRGB with the color settings' intent and written without
it, at 16 bits a sample when it has them, is not resampled or recompressed and the file is PDF 1.5 or later (an image
whose profile the color engine can't read, or whose pixels can't be decoded, keeps its profile, with a warning); without
conversion it keeps its profile. With `destination` and a CMYK destination, or an RGB one other than sRGB that images
are converted to, an RGB image that carries an ICC profile is converted from that profile to sRGB with the same intent
and then to the destination, instead of having its numbers read as sRGB (a profile the color engine can't read leaves
them read as sRGB, with a warning); a gray image keeps its profile, as gray is not converted. An RGB destination other
than sRGB that is the document's own RGB profile leaves RGB colors and RGB images as they are, so a tagged RGB image keeps its profile
there.
`preserveNumbers` still reads an image's numbers as sRGB. The destination is any profile `edit.colorSettings` lists (default: the document's
for its colour mode). `profiles` (`all`, `destination`, or `taggedSource` for a document assigned profiles with
`edit.assignProfile`) writes colours in ICC-based spaces with their profiles embedded: CMYK with the destination's or
the document's CMYK profile, RGB as sRGB, grey with the sRGB tone curve (PDF/A, PDF/X-3 and PDF/X-4 files are
@@ -5915,8 +6140,12 @@ below 3 or above 1000 counts as 3 or 1000, and a fractional or negative `sides`
Without `artboard`, or with an index the document doesn't have, it aligns them to the artboard under the center of the
selection, or to the first artboard when no artboard is under the center. With `to: "selection"` or `"key"`,
`object.align` does not use `artboard`. `select.allOnArtboard {artboard?}` (Select › All on Active Artboard) selects
the objects on artboard `artboard`, or on the first artboard when the call gives none; an index the document doesn't
have is an error.
the objects on artboard `artboard`, or on the first artboard when the call gives none or null. A value that is not a
whole number of 0 or more fails with "`artboard` must be a whole number", and an index the document doesn't have with
`no such artboard`; either leaves the selection as it was. `select.font {family, style?, scope?}` (Select Text
by Font) takes `scope: {artboards: [index…]}` the same way: an entry that is not a whole number fails with
"`scope.artboards` must contain whole numbers" before any entry is looked up, and an index the document doesn't have
fails with `no such artboard`.
`object.distribute {to: "artboard", artboard?}` and `object.distributeSpacing {to: "artboard", artboard?}` (the
Distribute Objects and Distribute Spacing buttons with Align to Artboard) use the same artboard as `object.align`.
@@ -5930,14 +6159,15 @@ With `to: "selection"` or `"key"`, or without `to`, `object.distribute` and `obj
keep the first and last objects where they are, and `object.distribute` without `spacing` moves nothing with fewer than
three objects. With `spacing` and a key object, `object.distribute` and `object.distributeSpacing` do not use `to`;
with a key guide, `to` decides whether the guide is the key. With anchor points selected (Direct Selection), both commands space the points
among themselves and do not use `to` or `artboard`.
among themselves and do not use `artboard`; with `to: "selection"` or `"artboard"`, the key anchor is not the key, and
all the points are spaced as without one.
`object.distribute {spacing}` (the Distribute Objects buttons while the selection has a key object, `select.key`) keeps
the key object where it is, with the compound path or selected group that contains it. It places the objects' lines
(left edges, centers or right edges; top edges, centers or bottom edges) `spacing` points apart, outward from the key
object's line, in their order on that line. With `spacing: 0`, every object ends on the key object's line. Two objects
are enough. Without a key object or key guide, or with anchor points selected, `object.distribute` does not use
`spacing`. A `spacing` that is not a number is an error.
are enough. Without a key object, key guide or key anchor, `object.distribute` does not use `spacing`; with anchor
points selected, it uses `spacing` only with a key anchor (`select.key {id, anchor}`). A `spacing` that is not a number is an error.
`object.distribute` and `object.distributeSpacing` space the selected ruler guides across the axis (vertical guides
for the horizontal options, horizontal guides for the vertical ones) with the selected objects, as items with no size
@@ -6393,6 +6623,22 @@ Reset Rotate View is the command `view.rotateReset`:
the angle the selected objects share (`selectionRotation` in `document.inspect`, 0 when their angles differ), so their
bounding box is square to the window. It returns `{angle}`, and with nothing selected it returns "nothing selected".
`view.statusBarShow` (desktop app, the Show menu that a click on the status bar's info field opens) chooses what that
field shows, with `show` set to one of these values:
- `artboardName`: the name of the artboard the status bar's navigator shows.
- `currentTool`: the name of the tool in use. This is the default.
- `dateTime`: the date and time, as `2026-11-15 14:03`. The desktop app shows local time, and the web build shows UTC
with ` UTC` after it.
- `undos`: the active document's undo and redo step counts, as `Undos: 3 Redos: 1`.
- `colorProfile`: the profile the active document's colors use. That is the profile assigned for its color mode
(Edit › Assign Profile), or that mode's working space (Edit › Color Settings) when none is assigned or the
assigned one is not available.
It returns the value set. The choice is kept with the UI state. A missing or other `show` fails with
``` `show` must be one of artboardName, currentTool, dateTime, undos, colorProfile ``` and leaves the choice as it was.
Without a document, the readouts that need one show a dash.
The Smart Guides preferences (Preferences › Smart Guides) apply to `pointer_gesture` with Smart Guides on (the
default view) and to the mouse; they change what the tools show and how far a target pulls, and only Construction
Guides change where a snapped point lands:
@@ -6812,7 +7058,8 @@ where it is.
`window.control.options {group, visible?}` (desktop app) turns a group of the Control bar's options on (`visible:
true`), off (`false`) or toggles it (omitted), and returns `{group, visible}`. The groups are `snapping` (the Snapping
menu), `anchors` (Convert and Anchors), `toolOptions` (the active tool's options), `objectOptions` (Isolate Selected
Object or Exit Isolation Mode, the envelope controls and the symbol instance controls), `imageOptions` (a selected
Object or Exit Isolation Mode, the envelope controls, the symbol instance controls and Select Similar Objects),
`imageOptions` (a selected
image's or Image Trace object's controls), `fillStroke` (the fill and stroke chips, Stroke and its weight and width
profile), `opacity`, `graphicStyle` (Style, Recolor Artwork and Global Edit Options), `character`, `paragraph`,
`verticalAlignment` (area type's vertical alignment), `alignDistribute`, `transform` (the Transform link and the X/Y/W/H
@@ -6940,6 +7187,25 @@ with `pointer_gesture` (a click places at 100% with the top-left corner there, a
`file.place.info` refuse, of the keys each one takes, a `link`, `replace` or `template` that is not true or false and a `thumbnail` that is not a
number, naming the key, and place nothing; null is the same as leaving the key out.
In the app, `file.place` asks for a file's import options before placing it: a text file without `text` (Text Import
Options), a DXF drawing without `dxf` (DXF Import Options), a PDF, `.ai` or `.ait` file with several pages or a
password and no `page` (Place PDF), and a PSD or PSB file embedded without `layers` that has two layers or more or
slices (Place PSD). `showImportOptions: false` places such a file without asking, with the options last confirmed in
its dialog: the text options, the DXF fit, lineweight, centering and layer choices with the drawing at 1:1 in its own
unit, and the PSD conversion, hidden-layer and Import Slices choices. A PDF is placed on page 1 (or `page`) and its
crop box, and an encrypted PDF given no
`password` still asks for the password. A `showImportOptions` that is not true or false is refused, and nothing is placed. The
Place dialog (File › Place, or `file.place {paths}`) has a Show Import Options checkbox after Link, Template and
Replace ([Place multiple files in a document](https://helpx.adobe.com/illustrator/desktop/add-and-import-files/import-other-file-types/place-multiple-files-in-a-document.html)).
It is on by default and saved with the preferences. On, each file that has import options asks for them before it is
placed, also each file of the place cursor when it is clicked or dragged (Cancel leaves that file unplaced). A click on
a PDF or DXF file places it as its options place it with `at` at the center of the box the click gave (a PDF's page at
its own size, a DXF drawing at its scale, or on the artboard there when fitted or not centered), and a drag to any other
size fits it into the dragged box (a drag to exactly the file's queued size gives the place tool the same box as a click and
is placed as one). Off, each
file is placed with the options last confirmed for its format. The default, and the options a file is placed with
when the checkbox is off, are VectorCraft's own choices.
```json
{"name":"run_command","arguments":{"command":"file.place","params":{"path":"/tmp/photo.jpg","at":[300,200]}}}
{"name":"run_command","arguments":{"command":"file.place","params":{"name":"logo.svg","dataBase64":"PHN2Zy…","rect":[0,0,100,100]}}}
@@ -6959,6 +7225,11 @@ added is reused), which the pasted objects follow. Linked colours show the docum
spot colour as its Spot Colors option says). The result reports `{ids, added, merged, renamed: [{kind, from,
to}]}`.
`edit.pasteWithoutFormatting` sets the labels of a pasted graph in a new graph's label character style and
paragraph attributes, keeping each label's alignment and where it starts. The pasted graph no longer keeps its labels' character and
paragraph formats, so a later `graph.setData` or `graph.setType` sets the labels the same way. The rest of the
graph's art is pasted as it was copied.
A global or spot swatch whose name the document gives another colour is a conflict: `clipboard.conflicts` lists
them, and `swatchConflict` answers: `"merge"` (the default: the objects take the document's swatch), `"add"` (the
pasted swatch comes in renamed) or one answer per name. Pasting back into the document the objects came from uses
@@ -8022,7 +8293,10 @@ or in `options` (`file.formatOptions {format}` lists them with their values):
- `separateArtboards: true` also writes each artboard of `range` (`"1-3, 5"`, default `"all"`) to
`<name>-<artboard>.<ext>` beside the file: that artboard and the art touching it. The result's `files` lists every
file written, the master file first (without a path: `files: [{name, dataBase64}]`). 3 artboards give 4 files.
- `includeLinked: true` keeps linked images' own pixels in the file (they stay linked), not just the previews.
- `includeLinked: true` keeps linked images' own pixels in the file (they stay linked), not just the previews. Linked
images in the art of the stored brushes count as those in the layers do, and an image key that the layers or a
brush's art shows embedded keeps its pixels either way. A `version` older than the current one saves the placed
documents in a brush's art as groups of the art they show.
- `embedProfiles` (default true) carries the ICC profiles the document is tagged with that were loaded from files;
opening the file installs them where they are missing (a warning names one that can't be used).
- `pdfCompatible`: native files (default true) also carry a PDF of every artboard (`pdf` in the file). This makes saves
@@ -8348,6 +8622,65 @@ flattened picture every PSD file carries: Bitmap, Grayscale, Duotone, Indexed, R
A document with transparency keeps it. `file.place {path}` links the file like any image (`links.update` reads it
again when it changes); Multichannel files are refused.
`file.place` with `layers: true` embeds a PSD or PSB file's layers as objects instead, and `hiddenLayers: true`
brings the hidden layers in, hidden. The
[PSD import options](https://helpx.adobe.com/illustrator/desktop/add-and-import-files/import-from-other-apps/photoshop-import-options.html)
offer the conversion and the hidden layers only for a file that is opened or embedded, and a linked file shows its
flat image. The rest are VectorCraft's own rules:
- The layers are read as `document.open` reads them (below) and placed as one group named after the file. A layer
becomes an image and a layer group becomes a group, each with the layer's name, visibility, opacity, blend mode
and opacity mask. A Pass Through group is not isolated; a group in any other mode is.
- The group takes the place the merged image would take: `at` centers the file's canvas and `rect` fits it. When
layers reach past the canvas, hidden layers included, the group is a clip group whose clipping path is the canvas.
- The layers are never linked. With `layers: true`, `link` is false unless it is given, and `link: true` is an
error.
- `hiddenLayers: true` without `layers: true` is an error.
- A file without layers is embedded as its merged image, and so is a file whose layers are all left out, with the
import's warnings. A file whose layers can't be read is embedded as its merged image with a warning.
- `file.place.queue` and `file.place.info` take `layers` and `hiddenLayers` too.
`document.psdInfo` reads a PSD or PSB file without opening it: its `format` (`psd` or `psb`), the canvas `width`
and `height` in pixels, and the counts `layers` (group markers left out), `hiddenLayers`, `groups` and `slices`
(the slices `importSlices` brings in). A file without layer records, or whose layer records can't be read, has
`layers: 0`; a file without slices, or whose slices can't be read, has `slices: 0`. A file that is not a PSD or PSB
file is an error.
`importSlices` brings a PSD or PSB file's slices in as user slices (Object › Slice), which Save for Web exports.
The [PSD import options](https://helpx.adobe.com/illustrator/desktop/add-and-import-files/import-from-other-apps/photoshop-import-options.html)
keep the slices a file holds, and offer it only for a file that is opened or embedded. The slices are read from
image resource 1050 as the
[Photoshop File Formats Specification](https://www.adobe.com/devnet-apps/photoshop/fileformatashtml/) describes it,
in version 6 and in the descriptor of versions 7 and 8. The rest are VectorCraft's own rules:
- `document.open` takes `importSlices`, default true, with the layers as objects and with `layers: false` alike.
The slices lie over the canvas, each clipped to it.
- `file.place` takes `importSlices`, default true when the file is embedded and false when it is linked;
`importSlices: true` with a linked file is an error. The slices move and scale with the placed art, in the same
undo step, and the reply lists their ids in `slices`. `file.place.info` counts them in `slices`, and
`file.place.queue` takes `importSlices` too.
- Each slice keeps its name, its type (Image or No Image), its link, target, message, alternative text and
background color, and a No Image slice keeps its cell text (plain text escaped as HTML). Text alignment isn't
read. A slice that follows a layer comes in as a user slice over the rectangle the file stores for it.
- Slices the file generated automatically are left out: the document lays out its own auto slices around the
others. A slice wholly outside the canvas, or without a size, is left out with a warning, and so are slices that
can't be read; the file's art comes in either way. A file without slices brings no warning.
In the app, File › Open of a PSD or PSB file with two or more layers, or with slices, shows PSD Import Options:
Convert Layers to Objects (with Import Hidden Layers) or Flatten Layers to a Single Image, and Import Slices, which
is offered only for a file with slices and applies to either choice. File › Place shows the same dialog for such a
file placed without Link, and so does a file dropped on the canvas with Shift held. The dialog starts from the
choices made last, at first Convert Layers to Objects without hidden layers, with Import Slices. A file with fewer
than two layers and no slices, a file placed with Link, and `document.open` and `file.place` run as commands don't
show it. Several files placed together without Link load the place cursor without asking, and each PSD or PSB file
among them comes in with the choices made last.
```json
{"name":"run_command","arguments":{"command":"file.place","params":{"path":"/tmp/poster.psd","layers":true,"hiddenLayers":true}}}
{"name":"run_command","arguments":{"command":"document.psdInfo","params":{"path":"/tmp/poster.psd"}}}
{"name":"run_command","arguments":{"command":"document.open","params":{"path":"/tmp/poster.psd","importSlices":false}}}
```
A PSD or PSB file that names a clipping path (the saved path its clipping path resource names, in the
[published PSD file format specification](https://www.adobe.com/devnet-apps/photoshop/fileformatashtml/)) places, and
opens as its merged image (`layers: false`, a file with no layers, or a file whose layers can't be read), inside a clip group whose clipping
@@ -8356,7 +8689,8 @@ that can be edited or released. `file.place` answers `image`, the id of the imag
[import options help page](https://helpx.adobe.com/illustrator/desktop/add-and-import-files/import-from-other-apps/photoshop-import-options.html)
says that a file imported as one flattened image keeps the document's clipping path when it has one. `links.update`
and `links.relink` read the file's pixels again and leave the clip group and its clipping path as they are. Files that name no clipping path, or name a path
they don't have, come in as a plain image.
they don't have, come in as a plain image. `file.place` with `replace` on such a clip group puts a new image, clipped or
not, at the scale and rotation of the image in the group.
`document.open` converts a PSD or PSB file's layers to objects. In
[PSD import options](https://helpx.adobe.com/illustrator/desktop/add-and-import-files/import-from-other-apps/photoshop-import-options.html),
@@ -8406,8 +8740,7 @@ Each layer's pixels must fit the memory allowed for one image, and the pixels of
canvases the merges make, must together fit eight times that; a file past either limit opens as its merged image,
with a warning. The canvases one step of a merge holds at once must also fit the memory allowed for one image; when
they don't, the layer that needed the merge comes in alone, with a warning: in the Normal mode, or as a layer of its
own instead of clipped. File › Open in the app has no PSD import options dialog: it converts the layers and leaves
hidden layers out.
own instead of clipped.
```json
{"name":"run_command","arguments":{"command":"document.open","params":{"path":"/tmp/poster.psd","hiddenLayers":true}}}
@@ -8838,6 +9171,11 @@ Appearance panel's Characters row, not the characters' formatting) go on paths o
below the Characters row on one path under the glyph paths, the others on one path over them, in their order and with
their opacity, blend mode, effects and stroke settings. Their gradients that are not placed are fixed to the type's
layout box, as the canvas paints them, so one gradient spans every glyph. The group itself has no fills or strokes.
It takes the type object's name, opacity, blend mode, Isolate Blending, Opacity & Mask Define Knockout Shape, opacity
mask and effects. The effects (the object's own, which apply to the type as a whole) keep their order, settings and
hidden state and stay live on the group; none of them is copied onto the glyph paths. Geometry effects on the group
(Warp, Free Distort, Transform) move its placed gradients with the whole outline, as they do on the type, not with each
glyph.
`object.expand` outlines type with this command, so Fill and Stroke expand those paths' gradients, patterns and strokes.
`type.createOutlines` (Type › Create Outlines) and `effect.expandAppearance` (when it outlines type, as Expand
@@ -9264,13 +9602,20 @@ as outlines.
`fwid`, `hwid`, `twid` or `qwid` ([feature list](https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist)),
or `"default"`, the font's default glyphs. A character holds one form at a time, so setting one replaces another. The
text keeps its characters, and a character the font has no glyph of that form for keeps its own. Runs that differ only
in their form are shaped as one piece of text. The form is saved only when it is not `"default"`, character styles
carry it, PDF draws the glyphs the canvas draws, and live SVG text writes it in `font-feature-settings`. Another value
is refused with `` `glyphForm` must be one of "traditional", … ``. One undo step, and a `text.setFormat` call that
gives the form the characters already have records none. With Show East Asian Options on, the Glyphs panel menu lists
the ten forms and Revert To Default Forms: a form is checked when every selected character has it, choosing it again
does nothing, and it is disabled when none of the faces that draw the selected text, fallback faces included, has a
feature for it.
in their form are shaped as one piece of text. A form other than `"default"` also takes away the characters' glyph
choice (`text.setGlyphAlternate`), which would otherwise keep drawing its own glyph; `"default"` keeps it. The four
width forms set the characters on a fixed width, so Proportional Metrics (`palt`) is not applied with them and the
font's pair kerning (`kern`, `apkn`) is turned off, in shaping and in SVG output (`font-kerning: none`);
`proportionalMetrics` and `kerning` keep their values. The form is saved only when it is not `"default"`, character
styles carry it, PDF draws the glyphs the canvas draws, and live SVG text writes it in `font-feature-settings`. Another
value is refused with `` `glyphForm` must be one of "traditional", … ``. One undo step, and a `text.setFormat` call
that gives the form the characters already have records none. With Show East Asian Options on, the Glyphs panel menu
lists the ten forms and Revert To Default Forms. They act on the Type tool's selected range, all the text of the object
at a caret, or all the text of the selected type objects. A form is checked when every one of those characters has
it, and choosing it again does nothing unless one of them has a glyph choice, which the form takes away. A form is
disabled when none of the faces that draw the selected text, fallback faces included, has a feature for it: a `GSUB` feature, or for the width
forms a `GSUB` or `GPOS` feature
([fwid](https://learn.microsoft.com/en-us/typography/opentype/spec/features_fj#tag-fwid)).
```json
{"name":"run_command","arguments":{"command":"text.setRangeStyle","params":{"id":12,"start":0,"end":3,"glyphForm":"jis78"}}}
@@ -9295,8 +9640,19 @@ value out of range, a scale on another class, an unknown class or key, a name th
characters, shared by two fonts (in any case) or the name of an installed font, and a part set in a composite font are
each refused with an error, and nothing changes. A document keeps at most 256.
`custom` lists a font's custom character sets
([Customize characters in a composite font](https://web.archive.org/web/20220911143322/https://helpx.adobe.com/pdf/cs6/illustrator_reference.pdf#page=348)),
each `{name, characters?, font?, style?, size?, baseline?, hScale?, vScale?}`. A set sets the characters it lists in
its own font, style, size, baseline and scales, ahead of their class; a value left out is the `kanji` part's. When two
sets list a character, the later set sets it. A set's name is trimmed and unique in its font in any case. Its
characters are each listed once, none a control character or past U+FFFF. A set may list no characters, and then sets
none. A font keeps at most 64 sets and a set at most 8,192 characters, VectorCraft's own limits. A set name that is
empty or shared, a character listed twice or not allowed, `scaleAtCenter` on a set, or an unknown key is refused with
an error, and nothing changes.
Type set in a composite font names it as its family (`text.setStyle {font: "My Composite"}`), and the font menus list
composite fonts first. The layout sets each character in its class's font, a letter and its combining marks together.
composite fonts first. The layout sets each character in its custom set's or its class's font, a letter and its
combining marks together.
A composite font taken out of the document leaves its type naming it, and the type shows as missing. Composite fonts
are saved with the document. SVG and legacy `.ai` write type in one of the document's composite fonts as outlines, and
SVG, PDF, EPS and legacy `.ai` export draw it in the font's parts also when the document was read without an open app.
@@ -9309,18 +9665,25 @@ parts its characters are drawn in, and `missingGlyphs` counts the characters tha
characters are drawn in. `text.glyphAlternates` lists the alternates of a character from its part's font.
`type.compositeFonts.export {path?, names?, fonts?}` writes the document's composite fonts (all, or those `names`
lists), or the `fonts` given, to a `.vccomposite` file; without `path` it returns the file's text as `data`.
lists), or the `fonts` given, to a `.vccomposite` file; without `path` it returns the file's text as `data`. Fonts
whose file would be larger than 4 MB, the most Import reads, are refused with an error.
`type.compositeFonts.import {path | data | dataBase64, apply?}` reads a file of at most 4 MB. With `apply` (the
default) its fonts join the document's, replacing a font of the same name, as one undo step; with `apply: false` it
only returns them. Opening a `.vccomposite` file imports it.
Type › Composite Fonts… (shown with Show East Asian Options) opens the Composite Fonts dialog on the document's fonts:
Font picks one, and a table sets each class's font, style, size, baseline and scales. New adds a font based on the one
picked, Delete Font takes it out, Import… adds the fonts of a file and Export… writes the one picked. OK runs
`type.compositeFonts.set` with every font as one undo step; a refused font keeps the dialog open.
Font picks one, and a table sets each class's and each custom set's font, style, size, baseline and scales. New adds a
font based on the one picked, Delete Font takes it out, Import… adds the fonts of a file and Export… writes the one
picked. Custom shows the font's custom character sets: Character Set picks one, New adds a set based on the one picked,
Delete Set takes it out, and Name renames it. Character › Direct Entry adds the characters typed, and Character ›
Unicode adds the characters of hexadecimal codes (`3042`, `U+3042`, several separated by spaces or commas); Add skips
characters the set already lists. Delete takes the character picked out of the set. OK runs `type.compositeFonts.set`
with every font as one undo step; a refused font keeps the dialog open. `ui.dialog.set` takes `custom`, `entry` and
`char` (the index of the character picked in the set) as soon as the dialog opens.
```json
{"name":"run_command","arguments":{"command":"type.compositeFonts.set","params":{"fonts":[{"name":"My Composite","parts":{"kanji":{"font":"Source Han Sans"},"roman":{"font":"Source Sans 3","size":95,"baseline":-2},"numerals":{"font":"Source Sans 3"}}}]}}}
{"name":"run_command","arguments":{"command":"type.compositeFonts.set","params":{"fonts":[{"name":"My Composite","parts":{"kanji":{"font":"Source Han Sans"}},"custom":[{"name":"Marks","characters":"※〒","font":"Source Sans 3","size":90}]}]}}}
```
## Optical Margin Alignment
@@ -10079,7 +10442,7 @@ The `paraStyleOptions` dialog exposes `name`, `section` (`general`, `basic`, `ta
100000 pt); it is disabled at 256 stops or when a stop is already at that position. Delete Tab removes the selected
stop, and Clear All Tabs leaves the style with no stops, which it then sets. OK sorts the stops by
position; of two stops at one position it keeps the one edited last.
- Composition: `composer` (`singleLine` or `everyLine`) and the `roman_hanging` checkbox.
- Composition: `composer` (`singleLine`, `everyLine`, `standardSingleLine` or `standardEveryLine`) and the `roman_hanging` checkbox.
- Hyphenation: the `hyphenate` checkbox, `words_longer_than`, `after_first`, `before_last`, `hyphen_limit`,
`hyphenation_zone` and the `hyphenate_capitalized` checkbox. The options are inactive while Hyphenation is off, and
Hyphenation Zone is inactive with the Every-line Composer.
@@ -10461,11 +10824,18 @@ same dialog, and its OK also draws a flare there. While the center is dragged ou
pointer's document y grows adds one degree per document point to `shape.flare`'s `rotation` (it turns
only the rays), decreasing y subtracts the same rate, and unchanged y leaves it. This application rate is independent of event frequency; Shift held keeps
the turn as it is. Space held keeps the turn as well. Once the center drag has passed its starting distance, and in the
drag that places the rings' end point, Space held moves the flare at its current size. The Artboard tool's are the active artboard's Artboard Options
drag that places the rings' end point, Space held moves the flare at its current size. In the center drag, Up and Down
Arrow add and remove rays, and Ctrl (Command on macOS; `mods.cmd`) keeps the center's diameter as the last drag showed
it while the drag sizes the halo: the halo's radius keeps the ratio to the pointer's distance that it had when the key
went down, through `growth` within 0 to 300 %. Letting the key go sizes the center with the drag again, and the flare
keeps the new `growth`. While the rings' end point is placed, Up and Down Arrow add and remove rings (0 to 50; with
Rings off they do nothing), and each press of backquote (the ~ key; a pointer event's `backquote` turning true) sends a
new `ringSeed`, which moves the rings along the path and keeps their count and sizes. Each new flare starts from the
options' counts and growth, without a `ringSeed`. The Artboard tool's are the active artboard's Artboard Options
(dialog `artboardOptions`; the Artboard tool's active artboard while it is in use, else the window's; its `x` and `y`
are the artboard's top-left corner in document points, while the dialog shows X and Y at the reference point the
Transform panel uses, counted from the ruler origin), a graph tool's
the selected graph's Graph Type (an error without one), a Symbolism tool's the Symbolism Tools Options (dialog
the selected graph's Graph Type (dialog `graphType`, described below; an error without one), a Symbolism tool's the Symbolism Tools Options (dialog
`symbolismOptions`: `diameter` in points, `intensity` and `density` 1–10, one brush for the eight tools) and the
Magic Wand tool's its panel. `ui.newArtboard` (Alt-click on the Artboards panel's New Artboard) opens Artboard Options
for a new artboard, with `new: true` and the name, position and size that `artboard.new {}` would give it. OK runs
@@ -10474,6 +10844,31 @@ for a new artboard, with `new: true` and the name, position and size that `artbo
default name, "Artboard N" for the Nth artboard.
A canvas-click dialog also has `preview` (initially on): tentative settings draw at the remembered click, Reset refreshes that preview, and Cancel discards it without persisting settings. OK accepts one flare as one Undo step. Toolbar-only options draw no artwork.
Object › Graph › Type… (`graph.setType` without params) and a double-click on a graph tool open Graph Type (dialog
`graphType`) for the selected graph, or for the series picked in it with Group Selection. Its fields are the options
`graph.setType {}` returns, under the command's names for them. `legend`, `pieLegend`, `piePosition`, `pieSort`,
`firstRowInFront`, `firstColumnInFront` and `filledLines` are held for every type, so a type picked in the dialog shows
the options it uses. `overrideValues` and `rightOverrideValues` are Override Calculated Values of the left (or only)
value axis and of the right one. While one is on, OK sends `axisMin`, `axisMax` and `ticks` (or `rightAxisMin`,
`rightAxisMax` and `rightTicks`), and the dialog fills the ones the graph lacks with the values the axis would be
calculated with for the type, value axis and Separate Scales the dialog shows.
One that was on and is turned off sends `null`, `null` and `0`, and one left off sends none of the three. `__page` is the
page the dialog shows: `options` (Graph Options), `valueAxis` (Value Axis, or Left Axis while the value axis is on both
sides), `rightAxis` (Right Axis, with the value axis on both sides) or `categoryAxis` (column, stacked column, bar,
stacked bar, line and area graphs); a pie graph has the `options` page alone, and a page the type picked lacks shows
`options`. With series picked, `type` and `valueAxis` (`left` or `right`) go to those series and the other options to
the whole graph, as the command applies them; `type` or `valueAxis` is `null` while the picked series differ in it, and
OK then leaves each series as it is. OK runs `graph.setType` with the fields: `legend` for every type but pie,
and the three pie options for a pie graph. When the selection changed while the dialog was open, it also sends `id`, and
`seriesIndexes` while series are picked and a `type` or `valueAxis` goes to them, so it changes the graph and the series
the dialog opened on. A value axis side without a scale of its own (the right side without Separate Scales, or with
Separate Scales a side that no series is on) shows the tick values of the scale drawn on it, and its Override Calculated
Values is dimmed. A value of `axisMin`, `axisMax` or `ticks` (or of the right axis' three) that is not a number is sent
as it is, and `graph.setType` refuses it. With nothing changed it closes without a step of history. An overridden value
axis whose maximum is not more than its minimum is the error "Maximum must be more than Minimum." and the dialog stays
open. The types the dialog dims for picked series (those that cannot go in the graph), the options it dims for a type
and the pages it lists are VectorCraft's own rules.
```json
{"name":"run_command","arguments":{"command":"tool.setOption","params":{"tool":"flare","values":{"rays":24,"ringsOn":false}}}}
```
@@ -11048,9 +11443,17 @@ of the group in the Layers panel (`layer.move`).
## Paragraph composer
`text.setFormat {ids?, composer: "singleLine"|"everyLine"}` sets how a text object's lines are broken (the Paragraph
panel menu's Single-line and Every-line Composer; stored in the paragraph attributes as `para.composer`, saved only
when it is Single-line). Every-line, the default, picks the breaks of the whole paragraph together in area type:
`text.setFormat {ids?, composer: "singleLine"|"everyLine"|"standardSingleLine"|"standardEveryLine"}` sets how a text
object's lines are broken and whether complex scripts are shaped (the Paragraph panel menu's four composers: Middle
Eastern & South Asian Single-line and Every-line, and Standard Single-line and Every-line; stored in the paragraph
attributes as `para.composer`, saved only when it is not Every-line, which is the default and what all type used before the
Standard composers existed). `singleLine` and `everyLine` shape Indic, Arabic and Hebrew type with the font's layout
tables, as all type is set; `standardSingleLine` and `standardEveryLine` break lines the same way but set such type
glyph by glyph as the font maps its characters (no conjuncts, reordering, mark placement or joining forms), for legacy
fonts that keep a script on Latin character codes. The scripts a Standard composer leaves unshaped are Indic, Arabic and the
other joining scripts (Syriac, N'Ko, Mongolian, Adlam…) and Hebrew; Latin, Greek, Cyrillic, CJK, Thai and the rest keep their
kerning and ligatures under every composer. Letters left unshaped do not join, so Insert Kashidas adds no tatweel between them. An older VectorCraft cannot open a file that uses a Standard composer. `.ai`, EPS and PDF files carry no composer.
Every-line, the default, picks the breaks of the whole paragraph together in area type:
justified text gets even word spacing, ragged text (left, centre or right aligned) an even rag, so it may move a word
that fits to the next line to avoid a lone short word on the last line or a full line next to a short one.
Single-line fills each line as far as it goes. Point type and type on a path have no line width, so both composers
@@ -11070,8 +11473,10 @@ new height and broken again in the room there. When that leaves the taller chara
set at its own height where the room there is no narrower, with the words before that character that fit there, and
otherwise stays where it was placed.
The UI command `type.lineComposer` (Cmd+Alt+Shift+C, in remote mode `press_key {key: "C", mods: {cmd: true, alt: true,
shift: true}}` or `invoke_menu`) sets `singleLine` when every paragraph of the selected type (or every paragraph the
Type tool's selection touches) uses Every-line, else `everyLine`, and returns the composer it set.
shift: true}}` or `invoke_menu`) sets the Single-line form when every paragraph of the selected type (or every paragraph the
Type tool's selection touches) uses an Every-line one, else the Every-line form. Paragraphs that all use a Standard composer
keep it (`standardSingleLine` or `standardEveryLine`); any other mix takes the Middle Eastern & South Asian one (`singleLine`
or `everyLine`). It returns the composer it set.
```json
{"name":"run_command","arguments":{"command":"text.setFormat","params":{"ids":[7],"composer":"singleLine"}}}
@@ -11180,7 +11585,11 @@ that starts with `/version`) without changing anything. Give exactly one of `pat
the set's name (`set`, else the file's name, else empty), its `version`, and its `actions`, each with its `name` and
`steps`. A step lists its `name` (the file's `/internalName`), its `label` (the `/localizedName` it is shown with, or
null when it has none or it is blank), `on` (false when the file sets `/isOn 0`), `params` (how many recorded values it
has) and its `line`. `unread` lists the tokens the reader skipped, with their lines. The reader stops at 8 MiB, 16 open
has), `values` and its `line`. `values` lists the step's recorded values in order, each as `{key, type, value, bytes?}`:
the block's `/key` and `/type` (null when it has none), and its `/value` when that is a whole number, or text in
parentheses or hexadecimal text that is UTF-8, with `bytes` giving the text's length in bytes; any other value, and text
that is not UTF-8, is null. Only the first 100,000 recorded values in the set are listed, so a step's `values` can be
shorter than its `params`. `unread` lists the tokens the reader skipped, with their lines. The reader stops at 8 MiB, 16 open
blocks, 1,000 actions, 10,000 steps in an action and 100,000 steps in the set, and cuts names at 1,024 bytes. It sets
`truncated` when it reaches one of these limits, when the text ends inside a block or a value or after a field's name,
when `/actionCount`, `/eventCount` or a step's `/parameterCount` differs from the actions, steps or recorded values read
@@ -11195,8 +11604,12 @@ label, in English or in the interface language, in any case and without a final
that label and that command is directly in a top menu, can be recorded in actions, is what its menu bar item runs with
no values and opens no dialog (Group, Ungroup). A submenu's items, file and document commands, Paste, Undo, Redo and
add-on commands are never matched. The step runs with no params, and a step that is off in the file is excluded from
playback. Other steps are left out, including every step with no label and every step recorded with values (recorded
menu items too). The reply lists the first 1,000 in `skipped` (`{action, step}`, the step by its label, else its name),
playback. A Set Selection step, found by its `/internalName` whatever its label, comes in as a Select Object step
(`select.byNote` with `{note, caseSensitive, wholeWord}`) when it has exactly three recorded values: the note (key
`text`, 1952807028, of type `ustring`, UTF-8), Whole Word (key `word`, 2003792484) and Case Sensitive (key `case`,
1667330917), each of type `boolean` and 0 or 1. The note loses its leading and trailing spaces and must then be 1 to
1,024 bytes long. A Set Selection step with any other values is left out; no option is filled in. Other steps are left
out, including every other step with no label and every other step recorded with values (recorded menu items too). The reply lists the first 1,000 in `skipped` (`{action, step}`, the step by its label, else its name),
`leftOut` counts them, and the status bar says how many were left out. An action with no name is called `Action N`, by
its place in the file. Function keys and colors are not read. A file marked `truncated` is refused, and no set is added.
Text that starts `/version` and is not an action set gives "not an action set file". Tokens in `unread` do not stop a
@@ -11215,9 +11628,10 @@ Plug-ins › Artwork Cleanup and in its panel (`window.panel {panel: "artworkCle
`addon.cleanup.simplify {tolerance?, protectCorners?, ids?}` removes the anchors each selected path can do without and
refits the handles beside each one, so the outline keeps its shape. `tolerance` runs from 1 to 100 (20 by default); the
outline stays within tolerance × 0.02 pt of where it was, measured against the original outline, so removals don't add
up. With `protectCorners`, anchors where the path turns by more than 30° stay. Open ends always stay. Locked and hidden
paths, and paths in locked or hidden groups, are left out. It reports the anchor counts `before` and `after`, as one
undo step.
up. With `protectCorners`, anchors where the path turns by more than 30° stay. Open ends always stay. From the
selection, locked and hidden paths, and paths in locked or hidden groups, are left out. With `ids`, it also takes the
locked and hidden paths of the objects, groups and layers the ids name, but not paths on a locked artboard. It reports
the paths it took as `ids` and their anchor counts `before` and `after`, as one undo step when a path changed.
The health check looks for issues in the selection, or in the whole document while nothing is selected (`scope:
"selection"|"document"` picks one). Locked and hidden objects, and the insides of live or generated art (blends,
@@ -11251,13 +11665,17 @@ envelopes, graphs, symbols), are left out.
`addon.cleanup.deepUngroup {includeClipGroups?, ids?}` takes apart every level of grouping in the selection. Clipping
groups stay whole unless `includeClipGroups` is true; their clipping paths then become plain paths. Objects keep the
opacity of the groups they were in. Locked and hidden groups stay whole, and locked and hidden objects stay locked or
hidden and are left out of the selection.
opacity of the groups they were in. From the selection, locked and hidden groups stay whole. With `ids`, it also takes
apart the locked and hidden groups the ids name and the groups inside the groups and layers they name (a named layer
stays a layer), but not groups on a locked artboard; an object of a hidden group becomes hidden, and an object of a
locked group becomes locked. Locked and hidden objects stay locked or hidden and are left out of the selection.
`addon.cleanup.rejoin {gap?, ids?}` welds the selected open paths whose ends lie within `gap` (0 to 6 pt, 0.1 by
default) back into paths. Each end joins one other end: where several are in reach, the one the path turns least to go
on into. Pieces may run either way, and a chain whose ends meet closes. Each new path takes the place and paint of its
topmost piece.
topmost piece. With `ids`, it also takes locked and hidden open paths, but not paths on a locked artboard. Only pieces
that are alike in being hidden and in being locked (by themselves or by a group or layer above them) join, and locked
and hidden paths it makes are not selected.
```json
{"name":"run_command","arguments":{"command":"addon.cleanup.check","params":{"scope":"document"}}}
@@ -11873,8 +12291,10 @@ overlapping the artboard or the centre on it), `inside` (the bounds wholly withi
straddling two touching artboards is inside neither) or `outside` (on none of them). It looks at the objects Select All
takes, or the isolated container's in isolation mode, so hidden and locked objects, objects on hidden, locked or template
layers and art held by a locked artboard are left out. Bounds are geometric, a symbol instance's measured by its art. It
returns the `count` selected. An empty list, an index with no artboard, a value that isn't an index, or another
relation is an error, and the selection is left as it was.
returns the `count` selected. An empty list, an index with no artboard (`no such artboard`), a value that isn't a list
("`artboards` must be a list of artboard indices"), an entry that isn't a whole number of 0 or more ("`artboards` must
contain whole numbers", checked before any entry is looked up), or another relation is an error, and the selection is
left as it was.
```json
{"name":"run_command","arguments":{"command":"addon.select.byArtboards","params":{"artboards":[2,6,11],"relation":"inside"}}}