@pixerate/editor 0.103.0 → 0.104.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pixerate/editor",
-  "version": "0.103.0",
+  "version": "0.104.0",
   "description": "UI-agnostic rich text and media editing core library",
   "author": "Pixerate",
   "license": "MIT",

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

@@ -172,8 +172,9 @@ batching.
 ### 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, smart-object, fill and shape layers
-   come in as their stored pixels; Dissolve becomes Normal; effects with gradient midpoints or
+   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
@@ -187,12 +188,20 @@ batching.
    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. **`export_psd` writes the stack as it is**, in the source frame: crop and rotation are not
+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. Read its `warnings` and pass them on. The file comes back as base64 (`data`).
+   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`).
 
 ## Best practices
 
@@ -277,7 +286,7 @@ batching.
 | `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_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 and `status` (`mapped`, `approximated`, `dropped`) with `notes`, and the import `warnings`. Call before `import_psd`. |
+| `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` for smart objects) 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). 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. |

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 and Rebelle) through its agent tools - canvas and paper (generated grain, depth, colour, families from cold pressed watercolour to canvas and gesso), layers, dry-media brushes (pencil, pastel, charcoal, airbrush, marker, ink, erasers, blender, smudge, Mixer Brush) with pressure, tilt, barrel rotation and velocity, the brush library, strokes as data that replay and vary, pigment colour mixing, previews and PNG, JPEG, WebP, PSD and JSON output. Use when asked to paint, sketch, draw, shade, block in, texture a layer with paper grain, mix paint colours, vary or repeat strokes, or when paint_stroke, set_paper, list_brushes, replay_strokes, fill_layer or mix_colors are available.
+description: How to make a picture in the Pixerate paint editor (natural media in the spirit of Painter and Rebelle) through its agent tools - canvas and paper (generated grain, depth, colour, families from cold pressed watercolour to canvas and gesso), layers, dry-media brushes (pencil, pastel, charcoal, airbrush, marker, ink, erasers, blender, smudge, Mixer Brush) with pressure, tilt, barrel rotation and velocity, the brush library, strokes as data that replay and vary, mirror and kaleidoscope painting, perspective guides, tracing and reference images, colour harmonies, swatches, a mixing pad and pigment mixing, previews and PNG, JPEG, WebP, PSD and JSON output. Use when asked to paint, sketch, draw, shade, block in, texture with paper grain, mix colours, paint symmetric or in perspective, trace an image, or when paint_stroke, set_paper, replay_strokes, set_symmetry or mix_colors are available.
 ---
 
 # Paint editor
@@ -21,6 +21,10 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
 - **Strokes are data.** Every stroke is recorded (brush, colour, raw points, seed, symmetry
   copies) and gets a `strokeId`. `replay_strokes` paints recorded strokes again, exactly or
   varied. That is the main way an agent should make many similar marks.
+- **Guides** are editor state saved with the document: a symmetry guide makes every stroke paint
+  its mirror or kaleidoscope copies (one stroke), a perspective guide snaps strokes to lines
+  towards one to three vanishing points, a tracing image sits under the paint (never exported)
+  and can supply stroke colours, and reference images float beside the canvas to pick from.
 - **Undo**: one tool call that changes the painting is one undo step (`undo_paint`). Brush,
   colour, view, hand and the Mixer Brush load are editor state, not undo steps.
 
@@ -36,17 +40,25 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
    `fill_layer` gives a ground colour (flat) or a tonal layer that catches the grain
    (`grain` 0.6..1, `pressure` 0.2..0.6). Paint large masses with a big soft pastel or airbrush
    in a few long `paint_stroke`s rather than many small ones.
-4. **Mix colours before painting.** `mix_colors` predicts what paints mixed in given parts look
-   like (Kubelka-Munk: blue and yellow make green, white tints rather than greys). Use the result
-   as the stroke `color`. `set_color` makes it the default.
+4. **Plan and mix colours before painting.** `color_harmony` gives a palette around a key colour
+   (on the painter's red-yellow-blue wheel by default). `mix_colors` predicts what paints mixed
+   in given parts look like (Kubelka-Munk: blue and yellow make green, white tints rather than
+   greys); the mixing pad (`mixing_pad_stroke`, `pick_mixing_pad_color`) mixes by hand with a
+   palette knife. Keep chosen colours as swatches (`add_swatch`). Use the result as the stroke
+   `color`; `set_color` makes it the default.
 5. **Refine** with smaller brushes on new layers: pencil and ink for line, charcoal for value,
    blender or smudge to soften edges, the Mixer Brush to blend wet into wet.
-6. **Repeat and vary instead of drawing every mark.** Paint one good stroke, then
+6. **Let the guides multiply your marks.** `set_symmetry` (mirror for faces and vases,
+   kaleidoscope for mandalas and ornaments) paints every copy from one stroke;
+   `set_perspective_guide` plus `paint_stroke` with `snapToPerspective` lays converging lines for
+   buildings and roads. To copy an image's composition and colours, `set_tracing_image` with
+   `sampleColors` and paint over it.
+7. **Repeat and vary instead of drawing every mark.** Paint one good stroke, then
    `replay_strokes` it with `dx` / `dy`, `rotate`, `scale`, `flipX`, `color`, `brushId` and
    `repeat` for hatching, grass, foliage, rows, fans or spirals, in one undo step.
-7. **Check** with `render_preview` after each block of work, not after each stroke.
+8. **Check** with `render_preview` after each block of work, not after each stroke.
    `pick_color` reads exact values. Undo what made it worse.
-8. **Deliver**: `export_image` (PNG, or JPEG / WebP in a browser), `export_psd` for Photoshop,
+9. **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
@@ -123,17 +135,41 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
 | `get_mixer_brush` | Read what the Mixer Brush carries: `reservoir`, `amount` left, `pickup`. |
 | `load_mixer_brush` | Fill the Mixer Brush reservoir with a colour (keeps its pickup). |
 | `clean_mixer_brush` | Empty the pickup well (and with `emptyReservoir` the paint). |
+| `color_harmony` | Get a harmony (`kind`: complementary, split-complementary, analogous, triadic, tetradic, square, monochromatic) around `color` (default the paint colour), on the `ryb` painter's wheel (default; red ↔ green) or the `rgb` wheel (red ↔ cyan), `spread` degrees for analogous and split. Changes nothing. |
+| `list_swatches` | Read the swatches (index, colour, name). |
+| `add_swatch` | Keep a colour as a swatch (saved with the document). |
+| `remove_swatch` | Remove a swatch by `index`. |
+| `mixing_pad_stroke` | Paint on the 360 × 220 mixing pad (pad px): `tool` paint lays `color` with a pigment Mixer Brush, `knife` smears what is there and mixes it as paint. Scratch space, not the painting, no undo. |
+| `pick_mixing_pad_color` | Read the mix on the pad at `x`, `y` (averaged over `radius`, default 3); `setColor` makes it the paint colour. Null where the pad is bare. |
+| `clear_mixing_pad` | Wipe the pad. |
+| `render_mixing_pad` | See the pad as a PNG. |
 
 ### Painting and strokes
 
 | Tool | Use |
 | --- | --- |
-| `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`. Returns `layerId`, `bounds`, `dabs`, `strokeId` and for the mixer engine its `mixerLoad`. Refused on locked, hidden or group layers, with the fix in the message. |
+| `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 the mixer engine its `mixerLoad`. 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. |
 | `redo_paint` | Redo the step just undone. |
 
+### Guides
+
+| Tool | Use |
+| --- | --- |
+| `get_guides` | Read the symmetry guide (with how many copies a stroke paints), the perspective guide, the tracing image and the reference images. |
+| `set_symmetry` | `mode` off, vertical, horizontal, dual, diagonal or kaleidoscope (`segments` 2..32, `mirror`), `center` (document px, default the canvas centre), `rotation`. Every stroke after it paints its copies as one stroke; recorded strokes keep their copies when replayed. |
+| `set_perspective_guide` | One to three vanishing `points` (document px, may be off the canvas), `enabled`, `snap`. Pen strokes snap to the guide line through their start that best matches their direction (one-point also keeps horizontals and verticals, two-point verticals); `paint_stroke` snaps only with `snapToPerspective`. |
+| `set_tracing_image` | Put a PNG (`png` base64 or data URL) under the paint, fitted to the canvas or at `rect`, at `opacity` (default 0.35), with `sampleColors` to take stroke colours from it. View only: never exported. |
+| `update_tracing_image` | Change the tracing image's `opacity`, `visible`, `sampleColors` or `rect`. |
+| `clear_tracing_image` | Remove the tracing image. |
+| `add_reference_image` | Add a floating reference PNG (`name`, panel `x`, `y`, `displayWidth`). Returns its id and size. |
+| `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. |
+| `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
 
 | Tool | Use |
@@ -158,5 +194,10 @@ is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y do
   and two strokes on the same spot catch the same peaks.
 - **Big soft brushes at full flow look flat.** Lower `flow` (airbrush 0.05..0.15) and build up.
 - **JPEG and WebP need a browser**; in Node use PNG. Exports never upscale (`scale` ≤ 1).
+- **Symmetry stays on until you turn it off.** Set `mode: "off"` after the symmetric part, or
+  every later stroke is mirrored too.
+- **The tracing image is not in exports or previews of the painting alone**; paint over it on a
+  layer. Turn `sampleColors` off before painting your own colours, or strokes without `color`
+  keep taking its colours.
 - **Recorded strokes are kept in saved documents**; `save_document` with `strokes: false` when
   only the pixels matter (smaller JSON).