@pixerate/editor 0.113.0 → 0.115.0

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

@@ -0,0 +1,42 @@
+# 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. **Print documents**: `set_color_mode` `cmyk` with the press profile makes the document a
+   CMYK one: you keep editing RGB, the viewport proofs through the press, and `export_psd`
+   writes a CMYK PSD (the separation uses `intent`). Opening a CMYK PSD does this for you. Check
+   out-of-gamut colours with `set_proof_setup` `gamutWarning` before exporting.
+6. **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 and Lab are document modes (`set_color_mode`) for
+  output, not spaces you edit numbers in. Adjustment layers keep their RGB settings in a CMYK or
+  Lab PSD, where Photoshop applies them to its own channels; `export_psd` warns.
+- `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,41 @@
+# 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 files are converted to RGB through their embedded (or
+   the default coated) CMYK profile and stay in CMYK mode, Lab files stay in Lab mode, so
+   `export_psd` writes them back as they came (`set_color_mode`); 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, mode and 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-paint-editor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixerate-paint-editor
-description: How to make a picture in the Pixerate paint editor (natural media in the spirit of Painter, Rebelle and ArtRage) through its agent tools - canvas and paper (generated grain, depth, families from cold pressed watercolour to canvas), layers with painterly blend modes (watercolor, tint, highlight, shadow), dry-media brushes (pencil, pastel, charcoal, airbrush, marker, ink, erasers) with pressure, tilt, barrel rotation and velocity, blending tools (blender, smudge, Mixer Brush), brush behaviours (pick-up and mix ratios, dirty and multi-coloured brushes), the brush library, strokes that replay and vary, symmetry and perspective guides, tracing and reference images, harmonies, swatches, a mixing pad and pigment mixing, and PNG, JPEG, WebP, PSD and JSON output. Use when asked to paint, sketch, shade, blend, smudge, glaze, mix colours, paint symmetric or in perspective, trace an image, or when paint_stroke, set_paper, replay_strokes or mix_colors are available.
+description: How to paint in the Pixerate paint editor (natural media) through its agent tools - canvas and paper (generated grain, depth, families from cold pressed watercolour to canvas), layers with painterly blend modes (watercolor, tint, highlight, shadow), dry media (pencil, pastel, charcoal, airbrush, marker, ink) with pen dynamics, wet media (watercolour, gouache and oil that flow, bloom, granulate and dry), thick impasto paint lit by a movable light, blending tools (blender, smudge, Mixer Brush), brush behaviours (pick-up and mix ratios, dirty and multi-coloured brushes), the brush library, replayable strokes, symmetry and perspective guides, tracing and reference images, harmonies, swatches, a mixing pad and pigment mixing, and PNG, JPEG, WebP, PSD and JSON output. Use when asked to paint, sketch, paint in watercolour, shade, blend, smudge, glaze, mix colours, paint symmetric or in perspective, trace an image, or when paint_stroke, set_paper, replay_strokes or mix_colors are available.
 ---
 
 # Paint editor
@@ -16,7 +16,19 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
   (pressure, tilt, velocity, jitter), a **rotation** mode (`fixed`, `stroke`, `barrel`) and an
   engine: `dab` (most media), `eraser`, `mixer` (the Mixer Brush: a reservoir of paint plus paint
   it picks up), `blender` (mixes the colours under and near the tip) or `smudge` (drags paint
-  along the stroke).
+  along the stroke), `wet` (watercolour, gouache, oil and the wet tools, below), `impasto`
+  (thick paint with relief and material, below), `particle` (procedural particle brushes),
+  `bristle` (a tuft of bristles) or `sticker` (sprays editable stickers).
+- **Wet media** (`engine: "wet"`, categories `watercolor` and `wet-tool`): a stroke lays water
+  and pigment on the layer's **wet layer**, a fluid simulation that keeps running after the
+  stroke: the water spreads until its edge is pinned by the paper, carries pigment out to the
+  rim as it dries (edge darkening), drops pigment into the paper's valleys (granulation), pushes
+  pigment back where new water flows in (blooms), bleeds between touching wet colours and runs
+  downhill on a tilted canvas. Paint stays wet until it dries by itself (a few thousand steps)
+  or `dry_paint` dries it; a dried wash is fixed, so the next wash **glazes** over it. A wet
+  brush's `wet.tool` is `paint`, `water`, `dry`, `blow`, `blend`, `smudge` or `blot`; `water`,
+  `pigment` (concentration), `body` (0 transparent watercolour .. 1 opaque gouache), `strength`
+  and `rewet` set it up. Every result says whether paint is still wet (`wet` / `stillWet`).
 - **Behaviour** (`behavior`, dab and mixer brushes) is how a brush treats paint already on the
   canvas: a **pick-up ratio** (how much paint each dab lifts and carries), a **mix ratio** (how
   much of the carried paint goes into what it lays down), **dirty** (keep the carried colour into
@@ -70,7 +82,9 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
    `repeat` for hatching, grass, foliage, rows, fans or spirals, in one undo step.
 8. **Check** with `render_preview` after each block of work, not after each stroke.
    `pick_color` reads exact values. Undo what made it worse.
-9. **Deliver**: `export_image` (PNG, or JPEG / WebP in a browser), `export_psd` for Photoshop,
+9. **Watercolour** is its own way of working (see "Wet media" below): wet the paper or not,
+   lay washes light to dark, let them flow (`advance_wet_paint`), dry them (`dry_paint`), glaze.
+10. **Deliver**: `export_image` (PNG, or JPEG / WebP in a browser), `export_psd` for Photoshop,
    `save_document` to keep the painting with its strokes.
 
 ## Best practices
@@ -122,6 +136,77 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
 - **Save brushes you build** (`set_brush` then `save_brush`), and share them with
   `export_brushes` / `import_brushes`.
 
+## Wet media
+
+1. **Choose a watercolour paper** (`cold-pressed`, `rough-watercolor` for granulation and broken
+   edges, `hot-pressed` for smooth washes). Absorption, permeability and roughness of the paper
+   drive the simulation.
+2. **Plan light to dark.** Watercolour is transparent: you cannot paint light over dark (use
+   `gouache`, body 1, for that). Lay the lightest washes first.
+3. **Wet-in-wet or wet-on-dry.** `wet_paper` over an area first for soft, feathered, blooming
+   colour (skies, backgrounds); paint on dry paper for crisp edges with a darker rim.
+4. **Paint washes** with `watercolor-wash` (large, flat, very wet) in a few long strokes, then
+   shapes with `watercolor-round`, details with `watercolor-detail`. Colours touching while wet
+   bleed into each other; that is the point.
+5. **Let it flow, then dry.** `advance_wet_paint` (`seconds` 1..5) to let water spread, run and
+   bloom; `render_preview` shows the paint as it is now (wet paper looks a little darker).
+   `dry_paint` sets it where it is. Dry before glazing a second wash over a first, or the two
+   mix instead of layering.
+6. **Steer the water** with the wet tools: `add-water` (softens and lifts with `rewet`),
+   `hair-dryer` (stops a wash spreading), `blow` (pushes the water along the stroke),
+   `wet-blend` (evens out a wash), `wet-drag` (drags wet paint), `blot` (lifts wet paint: clouds,
+   highlights). `set_canvas_tilt` makes washes run downhill and very wet paint drip;
+   `set_flow_map` pushes water in a swirl, a direction or eddies.
+7. **Tune the medium** per layer with `set_wet_settings`: `granulation` (grainy pigment, needs a
+   rough paper), `edgeDarkening`, `bloom`, `bleed`, `viscosity` (runny .. thick), `evaporation`,
+   `pigmentWeight`, `pickup` (how easily dried paint lifts), `fixture` (staining).
+
+- **Saving dries the paint** (deterministically): the saved file and every export hold dried
+  pixels; the editor keeps painting wet. A dry brush, fill, merge or duplicate on a wet layer
+  dries it first (in the same undo step).
+- **Time** runs by itself in an editor on screen (`pause_wet_paint` stops it); for an agent with
+  no screen, nothing moves until `advance_wet_paint` or `dry_paint`.
+
+## Oils and thick paint
+
+- **Wet oil** (`oil-round`, `oil-flat`; any wet brush with `wet.medium: "oil"`) runs on the wet
+  simulation as a thick, slow-drying medium: it barely flows, stays wet for minutes of simulated
+  time, and the brush picks up and mixes the wet oil it meets (`behavior.pickup` / `mix`), so
+  colours blend on the canvas. A layer takes the medium's wet settings the first time it holds
+  wet paint; keep oil and watercolour on separate layers. `set_instant_dry` on makes every wet
+  stroke dry as it ends (strokes stay exactly as laid).
+- **Thick paint** (`engine: "impasto"`, category `impasto`) gives a layer relief (height) and
+  material (gloss, metallic) next to its colour, lit at render time by `set_lighting`
+  (azimuth, elevation, relief). Tools: `impasto-brush` (bristle ridges), `paint-tube` (blobs),
+  `palette-knife` (scrapes the relief flat and smears the paint), `paint-roller` (flat stippled
+  band), `gloop-pen` (glossy bead), `metallic-paint` (highlights in the paint's colour).
+- **Loading and thinner**: `wet.load` / `impasto.load` below 1 make the brush run out along a
+  long stroke (dry-brush ends); `thinner` makes paint flatter and more transparent.
+- **Light** is a view of the relief, not paint: move it (`set_lighting`) to read the texture
+  (a low elevation, 15..30°, shows brushwork best) and pick the final light before exporting.
+  `get_relief` reads a layer's relief; `flatten_relief` removes it but keeps the colour.
+- **Metallic paper**: `set_paper` `metallic` 0..1 makes the grain sparkle under the light.
+
+## Procedural brushes, bristles, stickers and stencils
+
+- **Particle brushes** (category `procedural`): `hair-strands` (strings of masses dragged behind
+  the pen: hair, fur, grass), `spring-ink` (springs that overshoot: lively ink lines),
+  `orbit-curls` (particles circling the pen: curls and spirals), `flow-fur` and `sparkle-dust`
+  (particles thrown into a swirling flow), `bead-trail` (beads along a springy path). Tune with
+  `particle` (kind, render dot / line / sequence, count, stiffness, damping, speed, gravity).
+  Draw slowly and with varying direction: the particles react to movement.
+- **Bristle brushes** (category `bristle`): `bristle-round`, `bristle-flat`, `dry-brush`. Every
+  bristle draws its own line: press harder to splay the tuft, tilt to flatten it; soft bristles
+  bend into curves at turns; a low `bristle.load` runs dry into broken streaks.
+- **Sticker spray** (category `sticker`): stamps (`star`, `leaf`, `confetti`, `flower`, `heart`,
+  `splat`, `sparkle`, `ring`, `dot`) sprayed along the stroke onto an **empty layer**, where each
+  stays an object: `list_stickers`, `update_sticker` (move, turn, resize, recolour, restamp),
+  `arrange_stickers`, `remove_stickers`. A sticker layer takes no other paint.
+- **Stencils**: `add_stencil` lays a `ruler` or `arc` (strokes that start within `snap` px follow
+  it exactly: straight lines, circles, rainbows) or a `line` / `shape` mask (paint lands only on
+  one side or inside a rect, ellipse or polygon; `invert` for outside). Stencils stay until
+  removed (`remove_stencils`); masks are recorded with each stroke so replays keep them.
+
 ## Tool reference
 
 ### Canvas and paper
@@ -195,9 +280,41 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
 | `paint_stroke` | Paint one stroke through `points` (document px; `pressure` 0..1, `t` ms, `tiltX` / `tiltY` or `altitude` / `azimuth`, `twist`) with `brushId` (default the active brush), optional per-stroke `brush` changes, `color`, `layerId`, `seed`, `snapToPerspective`. The symmetry guide adds its copies; a sampling tracing image supplies the colour when `color` is missing. Returns `layerId`, `bounds`, `dabs`, `strokeId` and, for brushes that pick up paint, `mixerLoad` (what the brush carries now). Refused on locked, hidden or group layers, with the fix in the message. |
 | `list_strokes` | Read the recorded strokes, oldest first (default the last 100): id, layer, brush, colour, point count, seed, bounds. With `ids`, their points too. |
 | `replay_strokes` | Paint recorded `strokeIds` again: exactly, or varied by `dx` / `dy` (px), `rotate` (degrees clockwise), `scale` (brush size follows), `flipX`, `origin`, `pressureScale`, `color`, `brushId`, `layerId`, `repeat` (each copy applies the variation again). One undo step. Returns the new stroke ids, bounds and layers. |
-| `undo_paint` | Undo the last step. Returns what was undone and what is next. |
+| `undo_paint` | Undo the last step (a wet stroke's undo puts the wet paint back as it was before it). Returns what was undone and what is next. |
 | `redo_paint` | Redo the step just undone. |
 
+### Wet media
+
+| Tool | Use |
+| --- | --- |
+| `get_wet_paint` | Read the wet paint: `wet`, the clock, `paused`, `speed`, `tilt`, the kernel (`backend`, `message` when it runs slower than it could) and each wet layer (`wetCells`, `wetBounds`, `activeTiles`, settings, flow map). Call after wet strokes. |
+| `advance_wet_paint` | Let time pass: `steps` (120 = one second at the default speed) or `seconds`. The paint spreads, blooms, runs and dries. Not an undo step. Returns `steps`, `clock`, `stillWet`, `layers`. Call after a group of wet strokes, before `render_preview`. |
+| `dry_paint` | Dry wet paint at once where it is (one layer with `layerId` or all, optionally inside `rect`). One undo step. Returns `dried` (layer ids and rectangles) and `stillWet`. Dry before glazing over a wash. |
+| `wet_paper` | Pre-wet the paper with clear water over `rect` (default the canvas) on a layer, `amount` 0..1, for wet-in-wet. One undo step. Returns the rectangle and `wet`. Then paint into it. |
+| `set_wet_settings` | A layer's wet settings 0..1: `viscosity`, `evaporation`, `edgeDarkening`, `pigmentWeight`, `granulation`, `pickup`, `fixture`, `bloom`, `bleed`. Saved with the document, not an undo step. Returns `params`, `stillWet`. |
+| `set_flow_map` | Push a layer's water in a pattern: `kind` linear (`angle`), swirl (`center`, `clockwise`), radial, turbulent (`scale`, `seed`) or none, at `strength`. Returns `flow`, `stillWet`. |
+| `set_canvas_tilt` | Tilt the canvas (`angle` 0..90°, `direction` downhill clockwise from the bottom): wet paint runs downhill, very wet paint drips. Returns `tilt`, `stillWet`. |
+| `pause_wet_paint` | Stop or resume time (`paused`) and set `speed` (steps per second). Editor state. |
+| `set_water_overlay` | Show where the water is (`visible`), view only. |
+| `set_instant_dry` | `on`: every wet stroke dries as it ends (same undo step); off (default) wet paint keeps moving. Returns `instantDry`. |
+
+### Thick paint and light
+
+| Tool | Use |
+| --- | --- |
+| `set_lighting` | Move the light for thick paint and metallic paper: `azimuth` (degrees clockwise from the top), `elevation` (5..90), `relief` (0..1). Nothing is repainted; not an undo step. Returns the lighting. Use a low elevation to show brushwork. |
+| `get_relief` | Read a layer's relief (`bounds`, `maxHeight` 0..255, null when flat) and the lighting. Changes nothing. |
+| `flatten_relief` | Remove a layer's relief and material, keeping its colour. One undo step. Returns whether anything was flattened. |
+
+### Stickers
+
+| Tool | Use |
+| --- | --- |
+| `list_stickers` | Read a layer's stickers bottom first: id, stamp, x, y, size, rotation, color, opacity. |
+| `update_sticker` | Change one sticker by `id`: `stamp`, `x`, `y`, `size`, `rotation`, `color`, `opacity`. One undo step. Returns it. |
+| `arrange_stickers` | Move stickers (`ids`) to the `front` or `back` of their layer. One undo step. |
+| `remove_stickers` | Delete stickers by `ids`, or all on the layer. One undo step. |
+
 ### Guides
 
 | Tool | Use |
@@ -212,6 +329,9 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
 | `list_reference_images` | Read the reference images: id, name, size, placement, visibility. |
 | `update_reference_image` | Move, resize, rename, show or hide a reference panel. |
 | `remove_reference_image` | Remove a reference image. |
+| `add_stencil` | Lay a stencil: `kind` ruler (`from`, `to`) or arc (`center`, `radius`, `startAngle`, `endAngle`) to guide strokes, line (`from`, `to`) or shape (`shape` rect / ellipse with `rect`, polygon with `points`) to mask; `mode` guide or mask, `invert`, `snap`, `feather`. Returns it with its id. |
+| `update_stencil` | Move, reshape, switch or hide (`enabled`) a stencil by `id`. |
+| `remove_stencils` | Remove stencils by `ids`, or all. |
 | `pick_reference_color` | Read a reference image's colour at its own pixel `x`, `y`; `setColor` makes it the paint colour. |
 
 ### View, input and output
@@ -223,6 +343,8 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
 | `render_preview` | See the painting (or `layerIds`) as a PNG, longest side `maxSide` (16..2048, default 512), with or without the `paper`. Render after each block of work. |
 | `export_image` | Export PNG (default), JPEG or WebP as base64, at `quality` and `scale` (≤ 1); `paper: false` gives a transparent PNG. JPEG / WebP need a browser canvas. |
 | `export_psd` | Export a PSD with every layer, the paper as a locked bottom layer, and the composite. Pigment and painterly modes are written as their nearest standard mode (`list_blend_modes` `psd`). Returns base64, size, `psb` and `warnings`. |
+| `export_time_lapse` | Repaint the painting from its recorded strokes and events as a time-lapse: `frames` (about how many), `fps`, `maxSide`, `wetStepsPerFrame` (frames while wet paint flows), `holdMs`. Returns a contact sheet image, the frame count, size, duration, a video project of the frames and the ffmpeg command that renders `timelapse.mp4`; `includeFrames` adds every frame as base64 PNG. Changes nothing. |
+| `export_high_res` | Repaint the painting from its strokes at `scale` 1..8 (brushes, grain, fills and wet events scaled): a PNG with real detail instead of upscaled pixels. Returns base64, size. Layers not painted with strokes come out empty. |
 | `save_document` | Get the document JSON (canvas, paper, layers as PNG data URLs, strokes unless `strokes: false`). |
 | `open_document` | Open a saved document JSON, replacing the painting and clearing the undo history. Returns the canvas, layers and any `problems`. |
 
@@ -255,5 +377,15 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
   `replay_strokes` move the cursor first. Results and undo are the same; it is one more reason to
   paint a few long strokes and replay them rather than many short ones. A stroke fails with "A
   stroke is in progress" while the user is painting; try it again afterwards.
+- **Wet paint keeps changing.** A preview right after a wet stroke shows it before it has
+  flowed; `advance_wet_paint` first. Paint that should stay exactly where it was laid needs
+  `dry_paint` (or a dry medium).
+- **Wet strokes on one layer interact**; washes that must not mix go on separate layers, or dry
+  the first before painting the second (glazing). At most 8 layers hold wet paint at once.
+- **Undoing far back** past the wet undo memory (512 MB by default) leaves that paint dry as it
+  looked, rather than wet.
+- **Replays repeat what was recorded**: strokes, fills, clears, flattened relief and wet events.
+  Imported pixels, merges and layer moves are not data, so `export_time_lapse` and
+  `export_high_res` start those layers empty; paint with strokes when the replay matters.
 - **Recorded strokes are kept in saved documents**; `save_document` with `strokes: false` when
   only the pixels matter (smaller JSON).

package/skills/pixerate-vector/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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, text (point, area, on a path, styles, Create Outlines), symbols and instances, CAD constraints (parallel, tangent, dimensions, auto-constrain), 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, artboards and frames with resizing constraints, connectors, fills, strokes, stacked fills and strokes with blend modes, drop shadows, glows and blurs, clipping and opacity masks, gradients (linear, radial, conic, mesh, freeform), 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
@@ -38,6 +38,14 @@ carry a live effect stack. Every command is a `vector.*` command run with `run_c
   (`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.
 
@@ -64,6 +72,17 @@ 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
@@ -151,6 +170,8 @@ Parameter details (gradient fields, effect parameters, width profiles, envelopes
 
 | Command | Use it to |
 | --- | --- |
+| `vector.traceImage` | Turn a PNG (data URL) into vector paths in one group: `threshold` mode for one-colour art (logos, scans, silhouettes; `channel: "alpha"` for cut-outs), `color` mode for a stacked path per colour (`colors` 2–32). Raise `tolerance` for fewer anchors, `cornerRoundness` 0 for sharp polygons. Place it with `x`, `y`, `width`. Returns `{ id, paths }`; check `subpaths` counts and simplify or delete specks after. |
+| `vector.addPathByDimensions` | Draw a path the way a CAD user types it: from `start`, each step `{ length, angle }` (degrees counter-clockwise on the page: 0 right, 90 up), `{ dx, dy }` or `{ x, y }`; `closed` joins the ends. Use it for exact technical outlines (brackets, floor plans, given lengths and angles) instead of computing coordinates by hand. Returns `{ id, anchors }`. |
 | `vector.addShape` | Add a `kind` `rect`, `ellipse`, `polygon` (`sides`, at least 3), `star` (`points`, `innerRatio` 0 to 1) or `line` at `x`, `y`, `width`, `height` (all required; for a line, width and height are the end's offset). `cornerRadius` and `cornerKind` give live corners; any style field and `name` apply. Uses the editor's default style for anything not given. Returns `{ id }`. |
 | `vector.addPath` | Add a path from SVG path data `d` (absolute or relative M, L, H, V, C, S, Q, T, A, Z; arcs and quadratics become cubics) in document units, with `name` and style fields; unset style comes from the editor defaults. Fails when `d` has no points. Returns `{ id }`. |
 | `vector.importSvg` | Add the shapes of SVG markup `svg` on top of the document, or replace the document with `replace: true`. Reads paths, basic shapes, groups, transforms, linear and radial gradients, `clip-path` / `mask` references (as mask groups) `<text>` (as point text: content, font, anchor and fill) and `<use>` (as instances of symbols made from what they refer to); skips images and foreign filters. |
@@ -166,6 +187,19 @@ Parameter details (gradient fields, effect parameters, width profiles, envelopes
 | `vector.setWidthProfile` | Give strokes a variable width: a `preset` (uniform, taperStart, taperEnd, taperBoth, bulge, pinch, teardrop, wave, pressure; `uniform` removes it), explicit `points`, or a parametric `taper` and / or `wave`. Returns the profile points. |
 | `vector.setWidthPoint` | Set one width point of path `id`: `index` of an existing point (from the profile `vector.setWidthProfile` returns) or none to add one at `t` (0 to 1); `left` / `right` are side widths in document units. Returns the profile. |
 
+### Gradient meshes and freeform gradients
+
+| Command | Use it to |
+| --- | --- |
+| `vector.setMeshGradient` | Fill paths with a gradient mesh: `rows` × `columns` smooth patches over their bounds, coloured per point (`colors`, row by row) or by four `corners`. Use for realistic shading (fruit, metal, skin, soft folds). Returns `{ meshes: [{ id, shading }] }`. |
+| `vector.setMeshPoint` | Move a mesh point (`index`, row by row; `x`, `y` in document units) and / or set its `color` and `opacity`; neighbouring patches bend smoothly. Returns `{ id, shading }`. |
+| `vector.setFreeformGradient` | Fill paths with a freeform gradient: colour `points` anywhere (with `spread` for pure-colour discs) and `lines` carrying colour along curves, or, with no points, four or more placed inside each path along `colors`. Use for soft, organic colour that a linear or radial gradient cannot make. Returns `{ gradients }`. |
+| `vector.addFreeformPoint` | Add a colour point at `x`, `y` (default colour: what shows there). Returns `{ id, index, shading }`. |
+| `vector.setFreeformPoint` | Move a freeform point or change its `color`, `opacity`, `spread`. Returns `{ id, shading }`. |
+| `vector.removeFreeformPoint` | Remove a freeform point (never the last); later indices shift down. Returns `{ id, shading }`. |
+| `vector.setFreeformLines` | Replace the freeform lines (point indices each curve runs through; `[]` removes them). Returns `{ id, shading }`. |
+| `vector.getShading` | Read a path's mesh or freeform fill with points in document units (the indices the edit commands take). Call it before editing points. |
+
 ### Appearance: fill and stroke stacks, blend modes, filters
 
 | Command | Use it to |
@@ -256,6 +290,26 @@ the browser's shaper they are kept but not drawn until outlines are available.
 | `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 |
@@ -310,10 +364,26 @@ 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, type, typePath). 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
 
+- Mesh and freeform fills draw as fine tiles, not SVG gradients: they cannot be edited with
+  `vector.setGradient` or as stops, and other tools see them as SVG patterns. Point indices
+  shift after `vector.removeFreeformPoint`; read them again with `vector.getShading`.
+
+- 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.