@pixerate/editor 0.112.0 → 0.114.0

package/skills/pixerate-image-editor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixerate-image-editor
-description: How to colour-correct, composite and retouch a photo in the Pixerate image editor through its agent tools - layers (pixel, adjustment, group, shape, type, annotation and smart object layers with masks, clipping, blend modes, opacity and fill; merge, flatten, filters), smart objects (non-destructive transforms, smart filters, linked contents), vector shape layers (live shapes, arrows, paths, path operations, fills and strokes), live type layers, live layer effects, base adjustments, adjustment layers, selections and masks, Free Transform, crop, rotate, flip, Mixer Brush, undo, PSD, histogram and previews. Use when asked to edit, grade, correct, crop, straighten or mask an image, add a shadow, glow or outline, transform or warp a layer, draw a shape or arrow, add or edit text, make a smart object, or open or save a PSD, or when list_layers, set_adjustments, add_layer_effect, transform_layer, add_shape_layer, add_text_layer, convert_to_smart_object, paint_stroke, import_psd or render_preview are available.
+description: How to colour-correct, composite and retouch a photo in the Pixerate image editor through its agent tools - layers (pixel, adjustment, group, shape, type, annotation and smart object layers; masks, clipping, blend modes, merge, filters), smart objects and smart filters, shape and type layers, layer effects, adjustments, selections and masks, Free Transform, crop, rotate, flip, painting and the Mixer Brush, retouching (Clone Stamp, Healing Brush, Spot Healing, Smudge, Dodge, Burn, Sponge), undo, PSD, histogram and previews. Use when asked to edit, grade, correct, crop, straighten or mask an image, remove a blemish or spot, clone, dodge or burn, add a shadow, glow or outline, transform or warp a layer, draw a shape or arrow, add or edit text, make a smart object, or open or save a PSD, or when list_layers, set_adjustments, add_layer_effect, transform_layer, add_shape_layer, add_text_layer, paint_stroke, clone_stamp, spot_heal, import_psd or render_preview are available.
 ---
 
 # Image editor
@@ -183,39 +183,22 @@ drawing or editing either.
    false` and `cleanEachStroke: false`, start with `load_mixer_brush`, read the brush with
    `get_mixer_brush` when unsure, and reset it with `clean_mixer_brush`.
 
+### Colour management
+
+The working space, Assign / Convert to Profile with intents, soft proofing with a gamut warning
+and colour conversions for print briefs: read [references/color-management.md](references/color-management.md).
+### Retouching
+
+Clone Stamp, Healing Brush, Spot Healing, Smudge, Dodge, Burn and Sponge: retouch on an empty
+layer with `sample: "current-below"`, pick `spot_heal` for small spots, `heal_brush` for larger
+flaws and `clone_stamp` to copy exactly, and keep strokes short and soft. Read
+[references/retouching.md](references/retouching.md) before retouching.
+
 ### Photoshop files
 
-1. **Inspect before opening.** `inspect_psd` lists every layer with the type it would become and
-   a status: `mapped` (held exactly), `approximated` (type, fill and shape layers come in as their
-   stored pixels; linked smart objects as their stored pixels; Photoshop smart filters other than
-   Box Blur are kept but not drawn; Dissolve becomes Normal; effects with gradient midpoints or
-   smoothness, noise gradients, glow jitter, legacy bevels or patterns missing from the file are
-   drawn approximately) or
-   `dropped` (Brightness/Contrast, Exposure, Channel Mixer, Gradient Map, Selective Color and
-   Color Lookup adjustments). Tell the user what would be lost before `import_psd` when anything
-   is not `mapped`.
-2. **Layer effects come in live**: every Photoshop layer style maps to an effect you can read
-   with `list_layer_effects` and change as usual, with the file's patterns (listed in
-   `list_layer_effects.patterns`) and its global light. An effects block the editor cannot read
-   is kept and written back by `export_psd`, but not drawn; the warnings say so.
-3. **`import_psd` replaces the document** (one undo step). CMYK, Lab, grayscale, indexed, 16-bit
-   and 32-bit files are converted to 8-bit RGB, and ICC profiles are ignored; the warnings say
-   so. Afterwards work with `list_layers` as usual: there is no Background source image, every
-   pixel comes from the layers.
-4. **Smart objects come in live**: embedded contents (a PSB opens as a nested document you can
-   edit with `edit_smart_object_contents`, a PNG as raster contents), the placement and warp, the
-   smart filters and the filter mask; the layer shows Photoshop's own pixels until you change it.
-   JPEG, TIFF and SVG contents are decoded only in a browser, so elsewhere such a smart object
-   cannot be transformed (the error says so). Photoshop filters we do not model stay in the list
-   (kind `psd`): hide, reorder, re-blend or remove them, and `export_psd` writes them back.
-5. **`export_psd` writes the stack as it is**, in the source frame: crop and rotation are not
-   applied, layer filters and depth masks are baked, annotation layers are rasterized (only in
-   a browser). Effects are written as Photoshop layer styles: an effects block opened from a PSD
-   goes back byte for byte while its effects are unchanged, and the patterns effects use (the
-   built-in ones too) are embedded. Only the first outer glow, inner glow, bevel, satin and
-   pattern overlay of a layer fit in a PSD. Smart objects are written as smart objects (an
-   unchanged one byte for byte); a Develop smart filter has no Photoshop filter and is left out of
-   the list (the pixels still show it). Read its `warnings` and pass them on. The file comes back as base64 (`data`).
+`inspect_psd` before `import_psd`, then work with `list_layers`; `export_psd` writes the stack
+in the source frame at the document's bit depth, colour mode and profile. Read
+[references/photoshop-files.md](references/photoshop-files.md) before opening or saving a PSD.
 
 ## Best practices
 
@@ -297,11 +280,11 @@ drawing or editing either.
 | `get_selection` | Read the active selection: `empty`, `bounds` (natural pixels), `area` in pixels, `percent` of the image and a description. Check it after every select or modify step and before masking: a wand that covered 90% of the image is the wrong selection. |
 | `list_layers` | Read the layer stack bottom to top as a tree: id, type (`pixel`, `adjustment`, `group`, `shape`, `annotation`, `smart`; smart objects add their `contents`, `smartFilters` and `filterMask`; shapes a `shape` summary of component ops and kinds and paint types, and `annotation` when migrated from one), name, document `bounds` of pixel layers, visibility, opacity, `fillOpacity`, blend, `clipped`, locks, a `mask` summary, an `effects` summary (master switch, scale, effect ids and kinds), pixel-layer `filters` (the Background's `develop` filter is the base adjustments), adjustment `kind` and `params`, group `children`, and which layer is `active`. Call it to understand a document with more than the Background before changing it; adjustment layer ids work with every adjustment-layer tool. |
 | `list_layer_effects` | Read one layer's effects: `enabled` (master switch), `scale` (Scale Effects), `margin` (px they reach beyond the shape), `fromPsd`, and every effect with `id`, `kind`, `label` and all its settings. Also returns the `globalLight`, the `patterns` pattern effects can use and the effect `kinds`. Call before changing effects you did not add. |
-| `get_image_info` | Read the geometry: source `image` size, `crop` box (source pixels, or null), `rotation` degrees, `flipH` / `flipV`, the `output` size after crop and rotation, the layer count and `canUndo` / `canRedo`. Call before cropping or selecting so coordinates are right. |
+| `get_image_info` | Read the geometry: source `image` size, `crop` box (source pixels, or null), `rotation` degrees, `flipH` / `flipV`, the `output` size after crop and rotation, `bitDepth` (8, 16 or 32), the layer count and `canUndo` / `canRedo`. Call before cropping or selecting so coordinates are right. |
 | `get_histogram` | Judge exposure numerically: per channel and luminance `mean`, `p1` and `p99` (0..255), and `clipping` percent at pure black and white per channel. Reads the last render, so call `render_preview` first. `bins` (16, 32, 64 or 256) adds the counts. Cheaper than another image for checking a tonal change. |
 | `render_preview` | See the edited image (crop, adjustments, layers, annotations) as a PNG, or with `layerId` one layer alone. `maxSide` 16..2048 px, default 512. Images cost tokens: render after a group of edits, use 512 for overall look and 1024+ to judge clipping, edges and masks. Fails in environments without rendering. |
 | `inspect_psd` | Read a PSD / PSB (`data` base64) without opening it: size, `depth`, `colorMode`, `resolution`, every layer bottom first with `psdKind`, the `type` it would become (`smart`, `shape` and `type` for Photoshop smart objects, shapes and text) and `status` (`mapped`, `approximated`, `dropped`) with `notes`, and the import `warnings`. Call before `import_psd`. |
-| `export_psd` | Save the document as an 8-bit RGB PSD (PSB above 30000 px) with layers, groups, adjustment layers and masks. Returns `data` (base64), `size` in bytes, `psb` and `warnings` (crop or rotation not applied, filters and depth masks baked, annotations rasterized or left out, Pigment blends written as Normal). Shape and type layers are written as real Photoshop shape and type layers. Changes nothing. |
+| `export_psd` | Save the document as an RGB PSD at its bit depth (PSB above 30000 px) with layers, groups, adjustment layers and masks. Returns `data` (base64), `size` in bytes, `psb` and `warnings` (crop or rotation not applied, filters and depth masks baked, annotations rasterized or left out, Pigment blends written as Normal). Shape and type layers are written as real Photoshop shape and type layers. Changes nothing. |
 | `get_transform_frame` | Before a transform: what it would move (`content`, `moved`: pixels, mask, selection), its `frame` (document bounds of the content), `corners` (top-left, top-right, bottom-right, bottom-left) and `center`. `meshColumns` / `meshRows` also return an identity warp `mesh` over the frame to edit for `warp_layer`. Changes nothing. |
 | `get_smart_object` | Read a smart object: `contents` (`id` shared by linked instances, `name`, `kind` raster or document, `width` / `height`, `decoded`, `fileType`, `linkedPath`, `instances`), `placement` (`corners`, `warp` in contents px, `interpolation`, and when `affine` the `scaleX` / `scaleY` in percent of the contents, `rotate`, `skewX`, `center`, `bounds`) and `smartFilters` (`enabled`, `filters` bottom to top with ids, settings, `blend`, `opacity`; kind `psd` is a Photoshop filter kept but not drawn; the filter `mask`). Call before changing a smart object. |
 | `list_fonts` | Read the font families type layers can use here (generic families always work) and which shaper draws them. Call before choosing a font. |
@@ -326,6 +309,7 @@ drawing or editing either.
 | `set_crop` | Crop to `x`, `y`, `width`, `height` in source pixels of the un-rotated image (see `get_image_info`). Non-destructive; refused if the box leaves the image. For an aspect ratio, compute the largest box of that ratio inside the image and centre it on the subject. Returns the geometry. |
 | `reset_crop` | Remove the crop and show the whole image again. |
 | `set_rotation` | Set the absolute rotation in degrees clockwise (-360..360). Quarter turns keep every pixel; small angles straighten a horizon but add transparent corners to crop away. Returns the geometry. |
+| `set_bit_depth` | Image › Mode: `depth` 8, 16 or 32 (float, linear light). Up costs nothing; down rounds the layers' extra precision away (32 → 16 clips colour above 1). One undo step. Returns `bitDepth` and `changedLayerIds`. |
 | `flip_image` | Mirror the image `horizontal` (left-right) or `vertical`. Avoid flipping images with text, logos or recognisable places. |
 | `undo_image` | Undo the last edit (one tool call is one step). Returns `canUndo` / `canRedo`. |
 | `redo_image` | Redo the edit you just undid. |
@@ -390,6 +374,21 @@ drawing or editing either.
 | `get_mixer_brush` | Read-only. The Mixer Brush settings and what it carries (`reservoir` #rrggbb or null, `amount` left 0..1, `pickup` #rrggbb or null). Call it before a mixer stroke with `loadEachStroke: false`. |
 | `load_mixer_brush` | Fill the Mixer Brush reservoir with `color` (default the foreground), amount 1; keeps the pickup. View state, not an undo step. Use before strokes with `loadEachStroke: false`. Returns the load. |
 | `clean_mixer_brush` | Empty the Mixer Brush pickup well (`emptyReservoir: true` also drops the loaded paint, so it only smears). View state, not an undo step. Returns the load. |
+| `get_color_profile` | Read-only. The document's profile (`name`, `builtin` id or null, `colorSpace`, `srgb`), the Proof Setup or null, and the built-in profiles. |
+| `assign_profile` | Make the document's numbers mean colours in `profile` (built-in id or `icc:<base64>`; RGB only). The look changes, pixels do not. One undo step. Returns the profile. |
+| `convert_to_profile` | Convert pixel layers into `profile` keeping their look (`intent`, `bpc`), then assign it. One undo step. Returns the profile, `convertedLayerIds` and `unconvertedLayerIds` (shape, type, effects, smart objects). |
+| `set_proof_setup` | Soft-proof the viewport through `profile` (`intent`, `bpc`, `simulatePaper`, `gamutWarning`), or `off: true`. View state. Returns the setup. |
+| `convert_colors` | Read-only. `colors` #rrggbb from the document's profile (or `from`) to `to`: channel `values` 0..1 (CMYK, RGB, grey), `hex` for RGB, and `lab`. |
+| `clone_stamp` | Copy pixels from the clone source along `points`: each point paints what is at point + offset (source − first point, whole px). `source` `{x, y}` sets the source for this stroke (else the current one, see `set_clone_source`); `aligned` keeps the offset for later strokes; `sample` current \| current-below \| all; `brush` `{size, hardness, spacing, opacity, flow, smoothing, pressureSize, pressureOpacity}`; `layerId`, `channel` (a mask clones from itself). One undo step. Returns the layer, channel, `bounds`, dabs and `clone` `{offset, source, aligned}`. Call `set_clone_source` or pass `source` first. |
+| `heal_brush` | As `clone_stamp`, then blends the cloned texture into the colour and light around the stroke (Poisson seamless cloning, when the stroke ends). Use for blemishes, wrinkles, dust and seams where the surroundings have the right tone. Returns as `clone_stamp`. |
+| `spot_heal` | Remove what `points` cover with no source: `type` proximity-match (default: copies the best matching nearby patch, then heals it in) or smooth (fills from the edges). `sample`, `brush`, `layerId`, `channel`. One undo step. Returns the layer, channel, `bounds`, dabs and `spotHeal` `{offset}` (null for a smooth fill). |
+| `smudge` | Drag colour along `points` like a finger in wet paint; `strength` 0..1 (default 0.5) is how far. Works on masks too. One undo step. Returns the layer, channel, `bounds` and dabs. |
+| `dodge` | Lighten what `points` cover, most in `range` shadows \| midtones \| highlights, at `exposure` 0..1 (overlaps in one stroke never exceed it); `protectTones` keeps hue and saturation. Alpha kept. One undo step. Returns the layer, channel, `bounds` and dabs. |
+| `burn` | As `dodge`, darkening. |
+| `sponge` | Desaturate (`mode` desaturate, default) or saturate what `points` cover; `vibrance` damps clipping; passes compound, `brush.flow` sets each pass's strength. Pixels only. One undo step. Returns the layer, channel, `bounds` and dabs. |
+| `get_retouch_options` | Read-only. The retouching defaults (`aligned`, `sample`, `spotType`, `range`, `exposure`, `protectTones`, `spongeMode`, `vibrance`, `strength`) and the `cloneSource` `{x, y, offset}` or null. Call before a clone or heal stroke without `source`. |
+| `set_retouch_options` | Set those defaults (view state, not an undo step); each stroke tool can override them per call. Changing `aligned` clears the kept offset. Returns the options. |
+| `set_clone_source` | Set the clone source `{x, y}` in document px (the Alt-click), or remove it with `clear: true`. View state. The next `clone_stamp` / `heal_brush` fixes the offset from its first point. Returns the source. |
 | `fill_pixels` | Fill the selection (or the canvas without one / with `useSelection: false`) on pixels or a mask with `color`, `opacity`, `blend`. Returns the changed bounds. |
 | `mix_colors` | Read-only. Mix 1 to 16 `colors` (`{color: #rrggbb, weight, strength?}`) like paint (Kubelka-Munk over reflectance spectra). Returns `mixed` (#rrggbb), `rgbLerp` (the plain RGB average, for comparison) and the normalised `weights`. Call it before `paint_stroke` / `fill_pixels` to pick a paint colour. |
 | `clear_pixels` | Remove the selected pixels (alpha to 0; a transparency-locked layer or a mask gets the background colour). Returns the changed bounds. |
@@ -413,6 +412,7 @@ drawing or editing either.
   `locks` only when the user wants that layer changed.
 - `merge_down`, `merge_visible` and `flatten_image` merge annotation layers only in a browser
   (they need a canvas); elsewhere they fail and say so.
+- Retouching pitfalls (empty layers, sources, what ignores opacity): see references/retouching.md.
 - `paint_stroke`, `fill_pixels` and `clear_pixels` need a visible pixel layer (or a layer with a
   raster mask and `channel: "mask"`); adjustment, group, shape, type, annotation and smart object layers can
   only be painted through their masks (and a smart object through `channel: "filter-mask"`).

package/skills/pixerate-image-editor/references/color-management.md

@@ -0,0 +1,37 @@
+# Colour management
+
+The document has a colour profile, its working space: the colours its RGB numbers mean. Missing
+means sRGB. The viewport assumes an sRGB display and converts other working spaces for display.
+
+## Working method
+
+1. **Read first**: `get_color_profile` gives the document's profile, any Proof Setup, and the
+   built-in profiles (`srgb`, `display-p3`, `adobe-rgb-compat`, `prophoto-compat`,
+   `linear-srgb`, `rec2020`, grey, `lab-d50`, `coated-cmyk`).
+2. **Assign or convert?** `assign_profile` when the numbers are right but the profile is wrong
+   or missing (a file saved without its profile): the look changes, the numbers do not.
+   `convert_to_profile` to move the image into another space keeping its look (for a wide-gamut
+   edit, convert to `display-p3` or `prophoto-compat`; for the web, convert to `srgb`). Each is one
+   undo step.
+3. **Pick the intent**: `relative` (default) for photos, keeping in-gamut colours exact and
+   clipping the rest; `perceptual` when much of the image is out of gamut and smoothness matters
+   more than exactness; `saturation` for charts and logos; `absolute` only for proofing a paper
+   colour. Keep black point compensation on unless asked.
+4. **Soft proof before printing**: `set_proof_setup` with `coated-cmyk` (or the printer's
+   profile as `icc:<base64>`), `gamutWarning: true` to grey out colours the press cannot hit;
+   look with `capture_view`; adjust (lower saturation in the greyed areas); then `off: true`.
+5. **Numbers for a print brief**: `convert_colors` gives CMYK percentages (values × 100) and
+   Lab for any `#rrggbb`, without changing the document.
+
+## Pitfalls
+
+- The working space must be RGB: CMYK, grey and Lab profiles are for proofing and
+  `convert_colors` here.
+- `convert_to_profile` converts pixel layers (and the source image). Shape and type colours,
+  layer effects and smart objects keep their numbers and are listed in `unconvertedLayerIds`:
+  check them and recolour if the look matters.
+- Images opened from a URL or file in the browser arrive already converted to sRGB by the
+  browser, so their own profile is not kept; PSDs keep theirs (resource 1039).
+- `export_psd` always embeds the profile; PNG and JPEG exports embed it when it is not sRGB.
+- The first proof or conversion with `coated-cmyk` builds that profile, which takes a second or
+  two.

package/skills/pixerate-image-editor/references/photoshop-files.md

@@ -0,0 +1,39 @@
+# Photoshop files
+
+1. **Inspect before opening.** `inspect_psd` lists every layer with the type it would become and
+   a status: `mapped` (held exactly), `approximated` (type, fill and shape layers come in as their
+   stored pixels; linked smart objects as their stored pixels; Photoshop smart filters other than
+   Box Blur are kept but not drawn; Dissolve becomes Normal; effects with gradient midpoints or
+   smoothness, noise gradients, glow jitter, legacy bevels or patterns missing from the file are
+   drawn approximately) or
+   `dropped` (Brightness/Contrast, Exposure, Channel Mixer, Gradient Map, Selective Color and
+   Color Lookup adjustments). Tell the user what would be lost before `import_psd` when anything
+   is not `mapped`.
+2. **Layer effects come in live**: every Photoshop layer style maps to an effect you can read
+   with `list_layer_effects` and change as usual, with the file's patterns (listed in
+   `list_layer_effects.patterns`) and its global light. An effects block the editor cannot read
+   is kept and written back by `export_psd`, but not drawn; the warnings say so.
+3. **`import_psd` replaces the document** (one undo step). 16- and 32-bit files keep their
+   depth (`get_image_info.bitDepth`); CMYK, Lab, grayscale and indexed files are converted to
+   RGB; an RGB file's ICC profile becomes the document's colour profile. The warnings say what
+   changed. `export_psd` writes at the document's depth and embeds its profile. Change the depth
+   with `set_bit_depth`: 16-bit for smooth gradients and strong grades, 32-bit for linear-light
+   HDR (layers blend in linear light there). Adjustment layers, blend modes, merges and the
+   exported merged image keep the depth; layer effects, layer filters, painting and transforms
+   still work in 8 bits on what they change, so grade a deep file with adjustment layers rather
+   than repainting it when the depth matters. Afterwards work with `list_layers` as usual: there
+   is no Background source image, every pixel comes from the layers.
+4. **Smart objects come in live**: embedded contents (a PSB opens as a nested document you can
+   edit with `edit_smart_object_contents`, a PNG as raster contents), the placement and warp, the
+   smart filters and the filter mask; the layer shows Photoshop's own pixels until you change it.
+   JPEG, TIFF and SVG contents are decoded only in a browser, so elsewhere such a smart object
+   cannot be transformed (the error says so). Photoshop filters we do not model stay in the list
+   (kind `psd`): hide, reorder, re-blend or remove them, and `export_psd` writes them back.
+5. **`export_psd` writes the stack as it is**, in the source frame: crop and rotation are not
+   applied, layer filters and depth masks are baked, annotation layers are rasterized (only in
+   a browser). Effects are written as Photoshop layer styles: an effects block opened from a PSD
+   goes back byte for byte while its effects are unchanged, and the patterns effects use (the
+   built-in ones too) are embedded. Only the first outer glow, inner glow, bevel, satin and
+   pattern overlay of a layer fit in a PSD. Smart objects are written as smart objects (an
+   unchanged one byte for byte); a Develop smart filter has no Photoshop filter and is left out of
+   the list (the pixels still show it). Read its `warnings` and pass them on. The file comes back as base64 (`data`).

package/skills/pixerate-image-editor/references/retouching.md

@@ -0,0 +1,36 @@
+# Retouching
+
+1. **Retouch on a new empty layer** above the photo with `sample: "current-below"` (or `"all"`):
+   `clone_stamp`, `heal_brush` and `spot_heal` then paint onto that layer and the photo stays
+   untouched, so a bad stroke is easy to mask or erase. Smudge, Dodge, Burn and Sponge change the
+   pixels they touch, so run them on a duplicate (`duplicate_layer`) instead.
+2. **Pick the tool by the job.** A small spot or blemish on skin, sky or a wall: `spot_heal` with
+   a brush a little larger than the spot (`proximity-match` copies a nearby patch; `smooth` fills
+   from the edges and suits flat areas). A larger flaw, or one next to an edge: `heal_brush` from a
+   clean source of the same texture; it takes the colour and light around the stroke, so the source
+   may be lighter or darker. Copy exactly (a repeat, a straight line, an edge): `clone_stamp`.
+3. **Sources and offsets.** `set_clone_source` (or `source` on the stroke) is the Alt-click. The
+   first stroke fixes the offset = source − its first point; with `aligned` (default) later strokes
+   keep it, so the source moves with the brush; with `aligned: false` every stroke restarts at the
+   source point. The result's `clone.offset` and `clone.source` say what was used. Choose a source
+   that is clean for the whole length of the stroke: the stroke samples what was there before it,
+   never what it just painted.
+4. **Use soft, short strokes** (`brush.hardness` 0..0.5, a size just over the flaw), and check each
+   with `capture_view` on the area (scale 2..4). Several small strokes heal better than one long one.
+5. **Dodge and burn gently**: `exposure` 0.1..0.3, `range: "midtones"` for skin and form,
+   `"highlights"` / `"shadows"` to lift or deepen only those tones. A stroke never goes past its
+   exposure where its dabs overlap; another stroke builds on it. `protectTones` (default) keeps hue
+   and saturation. `sponge` with `mode: "desaturate"` takes colour out (a colour cast on teeth or
+   eyes), `saturate` adds it; passes compound, so use a low `brush.flow`.
+6. **Smudge** drags colour along the stroke like a finger in wet paint (`strength` how far); for
+   blending paint colours use the Mixer Brush instead.
+
+## Pitfalls
+
+- The retouching tools need a source to be useful: `clone_stamp` / `heal_brush` refuse without a
+  clone source, and with `sample: "current"` an empty layer has nothing to copy (the stroke then
+  changes nothing). Sample `current-below` or `all` to retouch onto an empty layer.
+- `heal_brush` and `spot_heal` show a plain clone or a dark trail while a person draws and blend
+  when the stroke ends; through the tools the result is already blended.
+- `dodge`, `burn`, `sponge` and `smudge` ignore `brush.opacity` (exposure, flow and strength set
+  their strength) and `brush.blend`. The Sponge refuses masks, which have no colour.

package/skills/pixerate-vector/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: pixerate-vector
-description: How to draw and edit vector artwork in the Pixerate vector editor through its vector.* commands - adding shapes and SVG paths, fills, strokes, stacked fills and strokes with blend modes, drop shadows, glows and blurs, clipping masks and opacity masks, gradients (linear, radial, conic, Oklab interpolation), stroke alignment, arrowheads, variable-width and tapered strokes, live corner radii, boolean operations and Pathfinder (unite, subtract, divide, trim), Shape Builder, paint bucket, live path effects (trim paths, repeater, zig zag, offset), envelope warps and free distort, blends and morphing, anchor editing (join, smooth, simplify, scissors, knife, eraser), align, distribute, group, stacking order, and SVG import and export. Use when creating an icon, logo, illustration, glyph, badge or any Bezier path artwork, or editing an SVG in a Pixerate vector editor.
+description: How to draw and edit vector artwork in the Pixerate vector editor through its vector.* commands - adding shapes and SVG paths, text (point, area, on a path, styles, Create Outlines), symbols and instances, CAD constraints (parallel, tangent, dimensions, auto-constrain), artboards and frames with resizing constraints, connectors, fills, strokes, stacked fills and strokes with blend modes, drop shadows, glows and blurs, clipping masks and opacity masks, gradients (linear, radial, conic, Oklab), stroke alignment, arrowheads, variable-width and tapered strokes, live corner radii, boolean operations and Pathfinder (unite, subtract, divide, trim), Shape Builder, paint bucket, path effects (trim, repeater, zig zag, offset), envelope warps and free distort, blends and morphing, anchor editing (join, smooth, simplify, knife, eraser), align, distribute, group, and SVG import and export. Use when creating an icon, logo, illustration, glyph, badge or any Bezier path artwork, or editing an SVG in a Pixerate vector editor.
 ---
 
 # Pixerate vector editor
 
 The vector document is an artboard (`width` x `height` in document units, y down) holding a tree
 of **nodes**: `path` nodes (one or more subpaths of Bezier anchors, with fill, stroke and stroke
-settings) and `group` nodes. Groups can also be live booleans, live blends, mask groups, or
+settings), `text` nodes (a string set as point text, area text or along a path, painted with
+the same fills and strokes), `instance` nodes (a placed copy of a symbol) and `group` nodes. Groups can also be live booleans, live blends, mask groups, or
 carry a live effect stack. Every command is a `vector.*` command run with `run_command` / `run_commands` (see
 `pixerate-agent-tools` for batching with `"$0.id"` references, `atomic: true` and error codes).
 
@@ -28,6 +29,23 @@ carry a live effect stack. Every command is a `vector.*` command run with `run_c
   inside the mask's outline (`clip`), or where it is bright (`luminance`) or opaque (`alpha`).
   `invert` swaps shown and hidden. `vector.list` gives a mask group a `mask`
   `{ type, invert, maskId, contents, enabled }`; a hidden mask (`enabled: false`) masks nothing.
+- **Text** has a base `font` (family, weight, italic, size, tracking, leading, baseline shift,
+  underline, strike-through), optional runs that override fields over ranges (`start` / `end`
+  in UTF-16 code units, plus a range `fill`), a `paragraph` style and a `frame`: `point` (x, y
+  of the first baseline), `area` (a box it wraps in) or `path` (a line it follows).
+- **Symbols** are reusable art kept with the document (`vector.listSymbols`), drawn by `instance`
+  nodes through a transform that, unlike other nodes', may scale and skew. Editing a symbol
+  (`vector.editSymbol` … `vector.exitSymbolEdit`) changes every instance.
+- **Constraints** (CAD-style) keep geometric relations and dimensions between anchors, segments
+  and round paths; they are solved after every edit, so later moves keep them.
+- **Frames** are groups with a `frame` rectangle (`vector.listFrames`): they draw a background,
+  clip their children and select by their rectangle; top-level frames are **artboards**. When a
+  frame is resized its children follow their **resizing constraints** (horizontal `left` /
+  `right` / `leftRight` / `center` / `scale`, vertical `top` / `bottom` / `topBottom` / `center` /
+  `scale`) instead of scaling.
+- **Connectors** are open paths with a `connector` whose ends are glued to other objects' sites
+  (the middle of a side, or the centre); they are routed again after every edit, so they follow
+  what they connect. A free end stays where it is.
 - Coordinates are document units. A rotated node stores its geometry in its own space: the
   `bounds` that `vector.list` reports are document-space, its `d` is the node's own.
 
@@ -54,6 +72,39 @@ Parameter details (gradient fields, effect parameters, width profiles, envelopes
 
 ## Best practices
 
+- **Diagrams with connectors.** Lay the boxes out first, then `vector.connect` them (in one
+  `run_commands` batch) rather than drawing lines: connectors stay attached when boxes move, and
+  `route: "elbow"` with a small `radius` reads well in flowcharts. Leave sides `auto` unless a
+  connector must leave a particular side.
+
+- **Frames for anything that resizes.** Build screens, cards, buttons and banners inside a frame
+  (`vector.addFrame` or `vector.frameSelection`), set each child's constraints with
+  `vector.setResizing` (backgrounds and dividers `leftRight`, icons pinned to their corner, titles
+  `center`), then resize with `vector.setFrame` to produce other sizes from one design. Export each
+  artboard with `vector.exportFrameSvg`.
+
+- **Constraints for precise, editable geometry.** For technical drawings, diagrams, floor plans or
+  any shape that must keep exact relations, draw it roughly, run `vector.autoConstrain`, then add
+  the dimensions that matter (`vector.addConstraint` distance / angle / radius) and name them so
+  related sizes follow one another (`vector.setConstraintValue` with expressions like `w / 2`).
+  Check `vector.listConstraints` `dof`: aim for `fully` on parts that must not drift; `over`
+  means some constraints repeat others. Prefer few, meaningful constraints over many.
+
+- **Symbols for repeats.** When the same art appears several times (icons in a set, trees in a
+  scene, bullets, a logo mark), make it once and place instances (`vector.makeSymbol`, then
+  `vector.placeSymbol` with `x` / `y` or a `transform`), so one edit in isolation changes them all.
+  Give each a clear name. Use `vector.setInstanceOptions` `fill` / `stroke` for colour variants and
+  `hidden` to drop a part, rather than detaching; detach only when one copy must diverge for good.
+
+- **Text.** Use point text for labels and headlines, area text (`width`, `height`) for anything
+  that should wrap, text on a path for badges and seals. Check `overflow` in the summary every
+  text write returns: hidden lines or characters mean the box or path is too small. Keep one or
+  two families per design (`vector.listFonts` lists what the shaper has; a missing family draws
+  in a fallback and appears in `missingFonts`). Style ranges with `vector.setTextStyle` rather
+  than splitting text into separate nodes, so it still edits as one paragraph. Create Outlines
+  only for final artwork or logos that must not depend on fonts; keep a copy as text if it may
+  change.
+
 - **Clean paths.** Use the fewest anchors that describe the shape: anchors at extrema (top,
   bottom, left, right of a curve) and at true corners, handles horizontal or vertical at extrema,
   each handle about a third of its segment. Run `vector.removeRedundantPoints` after
@@ -61,7 +112,8 @@ Parameter details (gradient fields, effect parameters, width profiles, envelopes
   keeps the outline by refitting neighbours.
 - **Live corners over drawn arcs.** Give rectangles, polygons and stars a `cornerRadius`
   (`vector.addShape`) or set it with `vector.setCorners`; the anchors stay sharp and editable and
-  radii shrink to fit short sides. Keep one radius scale across a design.
+  radii shrink to fit short sides. Keep one radius scale across a design. For app icons and UI
+  cards use `smoothing` (about 0.6) on `vector.setCorners` for continuous, squircle corners.
 - **Non-destructive first.** Live booleans (`vector.boolean` with `live: true`), path effects
   and envelopes keep the operands editable. A destructive boolean or Pathfinder replaces its
   inputs; do that last, and only when asked for flat output.
@@ -118,9 +170,10 @@ Parameter details (gradient fields, effect parameters, width profiles, envelopes
 
 | Command | Use it to |
 | --- | --- |
+| `vector.addPathByDimensions` | Draw a path the way a CAD user types it: from `start`, each step `{ length, angle }` (degrees counter-clockwise on the page: 0 right, 90 up), `{ dx, dy }` or `{ x, y }`; `closed` joins the ends. Use it for exact technical outlines (brackets, floor plans, given lengths and angles) instead of computing coordinates by hand. Returns `{ id, anchors }`. |
 | `vector.addShape` | Add a `kind` `rect`, `ellipse`, `polygon` (`sides`, at least 3), `star` (`points`, `innerRatio` 0 to 1) or `line` at `x`, `y`, `width`, `height` (all required; for a line, width and height are the end's offset). `cornerRadius` and `cornerKind` give live corners; any style field and `name` apply. Uses the editor's default style for anything not given. Returns `{ id }`. |
 | `vector.addPath` | Add a path from SVG path data `d` (absolute or relative M, L, H, V, C, S, Q, T, A, Z; arcs and quadratics become cubics) in document units, with `name` and style fields; unset style comes from the editor defaults. Fails when `d` has no points. Returns `{ id }`. |
-| `vector.importSvg` | Add the shapes of SVG markup `svg` on top of the document, or replace the document with `replace: true`. Reads paths, basic shapes, groups, transforms, linear and radial gradients, and `clip-path` / `mask` references (as mask groups); skips text, images, foreign filters and `use`. |
+| `vector.importSvg` | Add the shapes of SVG markup `svg` on top of the document, or replace the document with `replace: true`. Reads paths, basic shapes, groups, transforms, linear and radial gradients, `clip-path` / `mask` references (as mask groups) `<text>` (as point text: content, font, anchor and fill) and `<use>` (as instances of symbols made from what they refer to); skips images and foreign filters. |
 | `vector.delete` | Delete nodes (`ids`). |
 
 ### Style
@@ -179,6 +232,70 @@ arrays, to build or replace a stack in one call.
 | `vector.fillRegion` | Paint bucket: fill the area visible outlines enclose around `point` `[x, y]` with a new path in the current fill (islands stay holes). `gap` closes gaps up to that size between loose ends. Returns `{ id }`. |
 | `vector.outlineStroke` | Turn strokes into filled shapes of exactly the painted area (alignment, caps, joins, dashes, arrowheads, width profiles included), above a copy keeping the fill. Returns the new ids. |
 
+### Text
+
+| Command | Use it to |
+| --- | --- |
+| `vector.listFonts` | See which families the text shaper can draw and whether it gives glyph outlines (`outlines`); read it before choosing fonts or calling `vector.createOutlines`. Returns `{ shaper, outlines, families }`. |
+| `vector.addText` | Add point text (`x`, `y`: the first baseline's start), area text (`x`, `y`, `width`, `height`: wrapped in the box) or text along `path` (SVG path data, with `start`, `end`, `flip`, `orientation`, `baseline`). `font`, `paragraph`, `name`, `fill`, `stroke`, `strokeWidth` optional; black, no stroke by default. Returns the text summary (`id`, lines, bounds, overflow). |
+| `vector.getText` | Read a text node: text, base font, runs as `{ start, end, style }`, paragraph, frame, fill, stroke, laid-out lines, document bounds, `overflow`, `outlines`, shaper and missing fonts. Call before editing ranges. |
+| `vector.setText` | Replace `[start, end)` of the text with `text` (default the whole text; `start` = `end` inserts, `""` deletes). Inserted characters take the style before them. Returns the summary. |
+| `vector.setTextStyle` | Set character fields (`fontFamily`, `fontWeight`, `italic`, `fontSize`, `tracking`, `leading`, `baselineShift`, `underline`, `strikethrough`; null clears) and `fill` over `[start, end)`; the whole text (default) changes the base font and the node's fill. Returns the summary with runs. |
+| `vector.setParagraphStyle` | Set `align` (left, center, right, justify), `autoLeading`, indents and spacing for the node's paragraphs. Returns the summary. |
+| `vector.setTextFrame` | Switch between point, area and path text (`kind`), resize an area (`width`, `height`), move the origin (`x`, `y`) or change path options. Returns the summary. |
+| `vector.typeOnPath` | Turn path node `pathId` into text along it (it takes the path's place and drops its paint) with `text`, `font`, `paragraph` (`align` places it along the path) and path options. Returns the summary with the new id. |
+| `vector.createOutlines` | Turn text (`ids`, or text inside groups; default the selection) into paths of its glyph outlines, keeping paint, effects, filters, placement and id. Needs `outlines: true` from `vector.listFonts`. Returns `{ ids }`. |
+
+Fill, stroke, stacked layers, filters, blend modes, transforms, masks and blends work on text as
+on paths (`vector.setStyle`, `vector.addFill`, `vector.addFilter`, `vector.transform`, …). Path
+effects, envelopes and booleans act on its glyph outlines, so they need an outline shaper; with
+the browser's shaper they are kept but not drawn until outlines are available.
+
+### Symbols and instances
+
+| Command | Use it to |
+| --- | --- |
+| `vector.listSymbols` | Read the symbols: id, name, the art's node ids (for `hidden`), bounds around the registration point, instance ids, and which symbol is being edited. |
+| `vector.makeSymbol` | Turn objects sharing a parent (`ids`, default the selection) into a symbol, registration point at their centre, with an instance in their place. Returns `{ symbolId, instanceId, symbol }`. |
+| `vector.placeSymbol` | Place an instance of `symbolId` with its registration point at `x`, `y` (default the artboard centre) or through `transform` (scale, rotate and skew allowed). Returns `{ id }`. |
+| `vector.setInstanceOptions` | Change instances: `scaleStrokes` (default true), `fill` / `stroke` overrides painting all of the art (null clears), `hidden` art node ids. Returns the instances as listed. |
+| `vector.replaceSymbol` | Make instances (`ids`) draw `symbolId` instead, keeping placement and colour overrides. Returns `{ ids }`. |
+| `vector.detachInstance` | Break instances' link: they become plain groups of their art as drawn. Returns `{ ids }`. |
+| `vector.editSymbol` | Enter isolation mode on a symbol (its id or an instance's): every command then edits the art in symbol space (registration point at 0, 0). Returns `{ symbolId, nodes }`. |
+| `vector.exitSymbolEdit` | Leave isolation mode; the edited symbol's instances update. Returns `{ symbolId }`. |
+| `vector.renameSymbol` | Rename `symbolId` to `name`. Returns the symbol summary. |
+| `vector.deleteSymbol` | Delete `symbolId`; fails while instances use it unless `detach: true` turns them into groups. |
+
+### Constraints
+
+| Command | Use it to |
+| --- | --- |
+| `vector.listConstraints` | Read every constraint (id, kind, refs with anchor ids, value, name, evaluated value, satisfied), the parameters, the degrees of freedom left (`dof`, `status`, `redundant`, per path) and conflicts from the last solve. |
+| `vector.addConstraint` | Add a constraint (`kind`, `refs` by `{ nodeId, subpath, index }` or anchor id, with `segment`, `handle` or `circle`; `value` / `name` / `axis` for dimensions) and solve. Fails, changing nothing, on conflicts or redundancy, naming the others. Returns `{ id, constraint }`. |
+| `vector.removeConstraint` | Remove constraints by `ids`; geometry stays. |
+| `vector.setConstraintValue` | Set a dimension's value (by id or name) or a named parameter (`null` removes a parameter); values are expressions. Returns the summary. |
+| `vector.autoConstrain` | Add what a sketch nearly satisfies (tolerances `distanceTolerance`, `angleTolerance`), skipping redundant or conflicting candidates. Returns `{ ids }`. |
+
+### Frames and artboards
+
+| Command | Use it to |
+| --- | --- |
+| `vector.listFrames` | Read every frame: id, name, parent, whether it is an artboard (top-level), its rectangle, fill and clip, document bounds, and its children's resizing constraints. Call before resizing or exporting frames. |
+| `vector.addFrame` | Add an empty artboard at `x, y, width, height` (white unless `fill`; `adopt: true` takes in the top-level objects it encloses). Use for screens, cards, pages and export areas. Returns the frame as listed. |
+| `vector.frameSelection` | Put objects sharing a parent into a frame fitted to their bounds plus `padding` (no fill unless given), in their place. Use to turn finished art into a resizable component. Returns the frame as listed. |
+| `vector.setFrame` | Move or resize a frame's rectangle (`x`, `y`, `width`, `height`; children follow their constraints) or change its `fill` / `clip`. Returns `{ frames }`. Set the children's constraints first. |
+| `vector.setResizing` | Set how children of a frame follow it on resize (`horizontal`, `vertical`; a missing axis keeps its value). Fails on objects not directly inside a frame. Returns `{ nodes: [{ id, horizontal, vertical }] }`. |
+| `vector.exportFrameSvg` | Export one frame as an SVG of its own size (its corner at the origin). Returns `{ svg, width, height }`; use it per artboard instead of `vector.exportSvg`. |
+
+### Connectors
+
+| Command | Use it to |
+| --- | --- |
+| `vector.connect` | Join two objects (or free points) with a connector: `start` / `end` as `{ nodeId, side? }` (side `auto` by default: the side facing the other end) or `{ x, y }`, `route` straight / elbow / curved, elbow `radius`, `gap`, stroke and arrowheads (a triangle at the end by default). Use for flowcharts and diagrams instead of drawing lines. Returns the connector as listed. |
+| `vector.setConnector` | Reglue an end (`{ nodeId, side? }`), unglue it (`null`), or change `route`, `radius`, `gap`; also turns a plain open path into a connector. Returns `{ connectors }`. |
+| `vector.listConnectors` | Read every connector: route and each end's glued object, side setting, side in use and position. |
+| `vector.listConnectionSites` | Read an object's sites (top, right, bottom, left, centre) with positions and outward normals, to pick a `side`. |
+
 ### Masks and clipping
 
 | Command | Use it to |
@@ -233,10 +350,22 @@ contents whole while you work, without losing the mask.
 | Command | Use it to |
 | --- | --- |
 | `vector.setEditing` | Set editing behaviour: `keepShapeOnDelete`, `curvatureMoves`, `pencilSmoothing` (0 to 1), `recognizeShapes`, `eraserSize`, `pencilPressure` (pen, all, off). Returns the settings. |
-| `vector.setTool` | Switch the interactive tool (select, direct, pen, pencil, rect, ellipse, polygon, star, line, scissors, knife, eraser, width, shapeBuilder, paintBucket, blend, gradient, envelope). Only for handing the canvas to the user in a given mode; commands do not need a tool. |
+| `vector.getSnapOptions` | Read how drawing snaps for people at the pointer: grid, objects, guides, threshold, polar `angles`, object snap `tracking`, `trackPolar`, `polarRelative`. |
+| `vector.setSnapOptions` | Set those options, e.g. `polarIncrement: 15` for 15° polar tracking, or a grid, before handing the canvas to the user. Moves nothing. Returns the options. |
+| `vector.setTool` | Switch the interactive tool (select, direct, pen, pencil, rect, ellipse, polygon, star, line, scissors, knife, eraser, width, shapeBuilder, paintBucket, blend, gradient, envelope, type, typePath, frame, connector). Only for handing the canvas to the user in a given mode; commands do not need a tool. |
 
 ## Pitfalls
 
+- A connector's geometry is regenerated after every edit while an end is glued: editing its
+  anchors directly does not stick. Unglue the end (`vector.setConnector` with `null`) or change
+  `route` instead. Connectors cannot be glued to connectors.
+
+- Scaling a frame (`vector.scale`, the selection handles) lays its children out by their
+  constraints, so it is a resize, not a zoom; group the frame (or scale its children) to scale the
+  art itself. A frame clips by default: objects moved outside it disappear (`clip: false` shows
+  them). Moving an object over a frame does not put it inside; use `vector.frameSelection` or
+  `adopt`.
+
 - The `d` in `vector.list` draws live corners cut, which adds anchors. On a path with corner
   radii, anchor indices counted from `d` do not match the stored anchors; count anchors on a path
   without corners, or clear corners first.
@@ -267,5 +396,25 @@ contents whole while you work, without losing the mask.
 - Filters and blend modes are drawn, not geometry: bounds, snapping, booleans and Outline Stroke
   ignore them. A node's blend mode and filter isolate its layers, so layer blend modes inside a
   node with a filter mix only with the node's own layers. Background blur is not available.
+- Text positions are code units: an emoji or other character outside the Basic Multilingual
+  Plane counts 2. Take ranges from `vector.getText` rather than counting characters yourself.
+- Scaling text scales its font size (by the square root of the area change) and an area box per
+  axis; it is never stretched. Skew is not kept on text.
+- Without an outline shaper (`vector.listFonts` `outlines: false`), text exports as SVG `<text>`
+  positioned character by character; other viewers need the same fonts installed. Create Outlines
+  (with an outline shaper) when the SVG must look the same everywhere.
+- An instance's `transform` may scale; its art's strokes scale with it unless `scaleStrokes: false`.
+  Transform commands act on the instance, not the art: edit the art with `vector.editSymbol`.
+- While a symbol is being edited (`vector.listSymbols` `editing`), `vector.list` lists its art, not
+  the document. Always finish with `vector.exitSymbolEdit`. A symbol cannot contain an instance
+  of itself (directly or through another symbol).
+- Constraint refs to anchors give them stable ids; later anchor edits keep them, but rebuilding a
+  path (booleans, Outline Stroke, Expand) drops them, and constraints on missing anchors are
+  removed. `segment` means the straight line between two anchors, even when the segment is curved;
+  `tangent` / `smooth` on one anchor act on its handles.
+- After any edit the solver moves the rest of the geometry to keep the constraints; the anchors
+  you just moved move least. A fixed or fully constrained part will not move: remove or change a
+  constraint first.
+- `vector.typeOnPath` consumes the path. Duplicate it first if the path should stay visible.
 - A command that fails changes nothing; read its message (for example "Nothing is selected; pass
   ids.") and retry with the missing input.