@pixerate/editor 0.266.2 → 0.268.0

package/dist/vector/render.d.cts

@@ -571,6 +571,12 @@ export interface VectorSceneRenderOptions {
     };
     /** With `viewportSize`: groups, text and instances smaller than this many screen pixels draw as one rectangle in their main colour (default 2; 0 turns it off). */
     lod?: number;
+    /**
+     * `live` (default): wet brushstrokes show the paint as laid until they settle (re-render when
+     * `onVectorBrushstrokesSettled` fires; the controller notifies then). `settled`: settle them
+     * first, as exports must.
+     */
+    brushstrokes?: 'live' | 'settled';
 }
 /**
  * The document layer. Render the nodes inside `<g transform={transform}>` and `defs` in a

package/dist/vector/render.d.ts

@@ -571,6 +571,12 @@ export interface VectorSceneRenderOptions {
     };
     /** With `viewportSize`: groups, text and instances smaller than this many screen pixels draw as one rectangle in their main colour (default 2; 0 turns it off). */
     lod?: number;
+    /**
+     * `live` (default): wet brushstrokes show the paint as laid until they settle (re-render when
+     * `onVectorBrushstrokesSettled` fires; the controller notifies then). `settled`: settle them
+     * first, as exports must.
+     */
+    brushstrokes?: 'live' | 'settled';
 }
 /**
  * The document layer. Render the nodes inside `<g transform={transform}>` and `defs` in a

package/dist/vector/types.d.cts

@@ -1,5 +1,6 @@
 import type { GenerationProvenance } from '../generation/provenance.cjs';
 import type { CanvasGradientDef } from '../canvas/gradient.cjs';
+import type { CanvasBrushPaint } from '../canvas/brushTypes.cjs';
 import type { WarpMesh, WarpStyle } from '../geom/types.cjs';
 import type { GrainPattern } from '../paint/grain.cjs';
 import type { Brush } from '../brushes/types.cjs';
@@ -282,7 +283,20 @@ export interface VectorBrushstroke {
     seed?: number;
     /** The paper the grain comes from (with `seed`); `null` for no grain. */
     paper?: VectorBrushstrokePaper | null;
+    /**
+     * Gradient paint sampled dab by dab along the path, instead of the layer's colour (which still
+     * gives the alpha and fills `paint` stops): by distance travelled (document units), pressure,
+     * tilt, direction, across the tip or at random. Without it, a gradient layer paint is laid
+     * along, across or within the stroke (its `strokeMode`), and a brush with its own gradient
+     * paints that.
+     */
+    paint?: VectorBrushstrokePaint;
 }
+/**
+ * A brushstroke's gradient paint (the paint engine's `PaintSource`, as canvas brushed strokes take
+ * it: `CanvasBrushPaint`). The `velocity` and `time` mappings are not allowed: paths have no timing.
+ */
+export type VectorBrushstrokePaint = CanvasBrushPaint;
 /** One stroke of a path's stroke stack (`VectorStyle.strokes`): a paint plus its own stroke settings. */
 export interface VectorStrokeLayer extends VectorPaintLayer, VectorStrokeSettings {
     /** Default `paint`. See `VectorStrokeLayerKind`. */

package/dist/vector/types.d.ts

@@ -1,5 +1,6 @@
 import type { GenerationProvenance } from '../generation/provenance.js';
 import type { CanvasGradientDef } from '../canvas/gradient.js';
+import type { CanvasBrushPaint } from '../canvas/brushTypes.js';
 import type { WarpMesh, WarpStyle } from '../geom/types.js';
 import type { GrainPattern } from '../paint/grain.js';
 import type { Brush } from '../brushes/types.js';
@@ -282,7 +283,20 @@ export interface VectorBrushstroke {
     seed?: number;
     /** The paper the grain comes from (with `seed`); `null` for no grain. */
     paper?: VectorBrushstrokePaper | null;
+    /**
+     * Gradient paint sampled dab by dab along the path, instead of the layer's colour (which still
+     * gives the alpha and fills `paint` stops): by distance travelled (document units), pressure,
+     * tilt, direction, across the tip or at random. Without it, a gradient layer paint is laid
+     * along, across or within the stroke (its `strokeMode`), and a brush with its own gradient
+     * paints that.
+     */
+    paint?: VectorBrushstrokePaint;
 }
+/**
+ * A brushstroke's gradient paint (the paint engine's `PaintSource`, as canvas brushed strokes take
+ * it: `CanvasBrushPaint`). The `velocity` and `time` mappings are not allowed: paths have no timing.
+ */
+export type VectorBrushstrokePaint = CanvasBrushPaint;
 /** One stroke of a path's stroke stack (`VectorStyle.strokes`): a paint plus its own stroke settings. */
 export interface VectorStrokeLayer extends VectorPaintLayer, VectorStrokeSettings {
     /** Default `paint`. See `VectorStrokeLayerKind`. */

package/package.json

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

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

@@ -162,6 +162,7 @@ refuse.
 | `update_effect` | Make an applied effect again with new `values`, in the same place (`effect` is its instance id). |
 | `remove_effect` | Remove an applied effect: its commands, shots it alone filled and a vector effect's group. |
 | `add_vector_effect` | Add a vector effect's own picture as an artwork group (fitted into `box`) with its motion as new shots. For an effect that draws along a path (`search_effects` `accepts: ["path"]`: a signature, a route), `path: { node }` runs it along a path node and lands it on the node, `path: { text }` writes words. Use it when the effect should trace the path itself; use `follow` or a draw-on to move or reveal your own art. Returns the instance and group ids. |
+| `set_vector_effect_path` | Give a vector effect already added (`instance` from `add_vector_effect` or `list_applied_effects`) a new path in place: `path: { node }` runs it along a path node and lands it on the node, `path: { text }` writes words and keeps the picture where it was. Call it after reshaping the node an effect runs along (the path is a copy), or to switch between a node and words; clear the path with `update_effect` setting the path control to `""`. One undo step. Returns the instance, the `control` set and its new path data `value`. |
 | `list_camera_moves` | List the provider's camera moves for a `role` (`transition`: how the camera gets into a shot; `hold`: how it moves while the shot holds), with `durationMs` and `cut`. Returns `available: false` without camera moves. Call before `set_shot_camera_move`; `describe_effect` gives a move's controls and presets. |
 | `set_shot_camera_move` | Give a shot a camera move (`shot`, `role`, `move`, optional `ms` for a transition, `preset`, `values`): it is saved on the shot's camera as `in` or `during`. Returns the shot's camera and the `window` (ms) the move plays in. A wrong-role id is refused naming the moves that fit. |
 | `clear_shot_camera_move` | Remove a shot's move for a `role`, keeping its framing. Returns the shot's camera (null when nothing is left). |

package/skills/pixerate-brushes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pixerate-brushes
-description: How to find, describe, create, change, check and share brushes in the Pixerate brush library through list_brush_presets, describe_brush, create_brush, update_brush, duplicate_brush, remove_brush, check_brush, export_brushes, import_brushes and preview_brush - brushes made of facets (kind, medium and variety or tool, tip, marks, dynamics, behaviour, light, motion, colour), the built-in presets, and the host profiles that say what the paint editor, image editor, canvas and vector strokes can render. Use when asked to make, design, tweak, save, copy, delete, export, import or check a brush, find a brush for a medium (pencil, ink, watercolour, oil, airbrush, highlighter), or make a brush work in another editor.
+description: How to find, describe, create, change, check and share brushes in the Pixerate brush library through list_brush_presets, describe_brush, create_brush, update_brush, duplicate_brush, remove_brush, check_brush, export_brushes, import_brushes, preview_brush, add_brush_source and list_brush_sources - brushes made of facets (kind, medium and variety or tool, tip, marks, dynamics, behaviour, light, motion, colour), image tips and tip grain made from image sources, the built-in presets, and the host profiles that say what the paint editor, image editor, canvas and vector strokes can render. Use when asked to make, design, tweak, save, copy, delete, export, import or check a brush, make a brush from an image (a scanned mark, a leaf, a texture), give a brush grain, find a brush for a medium (pencil, ink, watercolour, oil, airbrush, highlighter), or make a brush work in another editor.
 ---
 
 # Brushes
@@ -15,13 +15,13 @@ built-in presets (read-only) and the user's brushes, shared by every editor that
 | Kind | `mark` lays a material; `tool` works on paint already down. |
 | Medium and variety | Marks: what it lays (`paint`, `ink`, `dry`, `spray`) and what kind (`oil`, `watercolor`, `gouache`, `pencil`, `charcoal`, `airbrush`, `marker`, `highlighter`…). Descriptive, for finding brushes; a wet brush whose variety is `watercolor`, `gouache` or `oil` paints that medium. |
 | Tool | Tools: `eraser`, `blender`, `smudge`, and on wet paint `water`, `dryer`, `blow`, `blot`, `wet-blend`, `wet-drag`. |
-| Tip | `shape` (`round`, `flat`, `chisel` are ellipses set by `roundness` and `angle`; `bristle` has a tuft; `stamp` takes the shape of `stamps`: an editor stamp `editor:star` or any sticker ref from `find_stickers`), size in px, hardness, spacing, opacity, flow, blend mode. |
+| Tip | `shape` (`round`, `flat`, `chisel` are ellipses set by `roundness` and `angle`; `bristle` has a tuft; `stamp` takes the shape of `stamps`: an editor stamp `editor:star`, any sticker ref from `find_stickers`, or an image source `source:<id>` from `list_brush_sources`), size in px, hardness (an image tip fades towards its edges below 1), spacing, opacity, flow, blend mode, and `grain`: texture inside each dab (`source`: a pattern such as `rough`, `canvas`, `sanded`, or `source:<id>`; `mode` `texturised` stays put on the canvas, `moving` rolls with the tip; `scale`, `depth`, `contrast`, `invert`). |
 | Marks | `continuous` dabs (default; on a stamp tip every dab is the first stamp's shape, in the paint colour), `scatter` (a spray: droplets across the tip, `density`, `size`), `particles` (strands, springs, ribbons, sparks; textured dots from the stamps) or `objects` (each mark an editable sticker, in its own colours). |
-| Dynamics | Pen feel: pressure to size and opacity, smoothing, tilt, velocity, jitter, rotation. |
+| Dynamics | Pen feel: pressure to size and opacity, smoothing, tilt, velocity, jitter (`sizeJitter`, `angleJitter` for rotation, `opacityJitter`, `scatter`), rotation, `count` (dabs per spacing step, each jittered) and `flip` (mirror dabs at random: `x`, `y`, `xy`). |
 | Behaviour | `surface` `dry`, `wet` (`wet` settings) or `thick` (`thick` impasto settings); paper `grain`; `exchange` (pick-up and mix; a `reservoir` makes a Mixer Brush); tool `strength`. |
 | Light | Light the brush gives off (`amount`), plus suggested layer `spill` and `glow`. |
 | Motion | Animation after painting (live effect paint, particle `waveSpeed`). |
-| Colour | A `default` colour, a `palette` of up to 16, `own` (always its own colour). Each is a hex or `rgba()` colour, a light / dark pair `{ light, dark }`, a gradient or effect paint. A gradient default is always painted; a solid or light / dark default becomes the editor's colour when the brush is chosen (unless the user locked theirs), resolved for the colour scheme. Canvas strokes and vector brushstrokes take it too, when they are given no colour. |
+| Colour | A `default` colour, a `palette` of up to 16, `own` (always its own colour). Each is a hex or `rgba()` colour, a light / dark pair `{ light, dark }`, a gradient or effect paint. A gradient default is always painted; a solid or light / dark default becomes the editor's colour when the brush is chosen (unless the user locked theirs), resolved for the colour scheme. Canvas strokes and vector brushstrokes take it too, when they are given no colour. Canvas and vector have the same lock (`canvas.setColorLocked`, `vector.setColorLocked`), and a canvas colour taken from a light / dark default follows the scheme like the paint editor's; vector strokes already made keep theirs. |
 
 How media map to facets: a **pencil** or **charcoal** is `dry` with high `grain` and tilt;
 **ink** is a hard round tip with pressure to size (a pen thins with velocity); **watercolour**
@@ -31,7 +31,16 @@ and **wet oil** are `paint` on `surface: 'wet'`; **impasto** is `surface: 'thick
 pressure to size); **crayon** and **chalk** are `dry` with high `grain`; a **highlighter** is
 `ink` / `highlighter`, a multiply chisel tip with a little light, `spill` radius 0, fluorescent
 yellow by default; a **stamp brush** is a `stamp` tip with continuous marks; **particle** and
-**sticker** brushes are `marks` particles or objects on a `stamp` tip.
+**sticker** brushes are `marks` particles or objects on a `stamp` tip. An **image brush** (a
+scanned charcoal mark, a leaf, a dry-brush texture) is a `stamp` tip whose stamp is an image
+source, usually with `tip.grain`, `angleJitter`, `flip` and a little `scatter` so repeats don't
+show.
+
+**Image sources** are the images tips and grain are made from, kept in the library with their
+bytes (a grey mask, at most 512 px) and their licence. `add_brush_source` makes one from a PNG:
+the marks are read from its transparency, its dark parts (a scan on paper) or its light parts
+(white on black). Library files (`export_brushes`) and saved paintings carry the sources their
+brushes name, so they paint and replay the same anywhere.
 
 ## Host profiles
 
@@ -40,10 +49,10 @@ paints without (warnings), each with a fix; lists and writes use the current hos
 
 | Host | Renders |
 | --- | --- |
-| Paint editor (`paint`) | Everything. |
-| Image editor (`image`) | Dry dabs on round, flat and chisel tips, the Mixer Brush and the eraser; no wet or thick surface, particles, objects, light or motion. Pick one with `set_brush_preset`. |
-| Canvas (`canvas`) | Dry dab brushes along a path (no tools, wet, thick, particles, objects or light); velocity is ignored. Draw with one as `canvas.drawFreehand` `brush`. |
-| Vector strokes (`vector`) | As canvas, but light brushes paint as plain colour. Draw with one as `vector.addBrushstroke` `brushId`. |
+| Paint editor (`paint`) | Everything, image tips and tip grain included. |
+| Image editor (`image`) | Dry dabs on round, flat and chisel tips, the Mixer Brush and the eraser; no wet or thick surface, particles, objects, stamp or image tips, light or motion; it paints without tip grain and `count`. Pick one with `set_brush_preset`. |
+| Canvas (`canvas`) | Dry dab brushes along a path (no tools, wet, thick, particles, objects, stamp or image tips, or light); velocity, tip grain and `count` are ignored. Draw with one as `canvas.drawFreehand` `brush`. |
+| Vector strokes (`vector`) | As canvas, plus wet paint (watercolour, gouache, wet oils: simulated in the stroke's own area, then dried), the Mixer Brush, and the smudge and blender tools (acting on the shapes beneath the stroke); light brushes paint as plain colour. The wet tools (water, hair dryer, blow, wet blend, wet drag, blot), thick paint, particles, objects and erasers are refused. Draw with one as `vector.addBrushstroke` `brushId`. |
 
 Every host lists the presets its profile admits and the library's saved brushes it admits, and
 each registers these tools with its own profile, so `list_brush_presets` shows that host's brushes.
@@ -66,7 +75,11 @@ drawn.
    in the editor (`set_brush` with the new id, then `paint_stroke`).
 5. **Tune it.** `update_brush` with the facets to change, or `unset` to drop whole facets. It
    returns the leaf paths `changed`. Built-in presets can't be changed: `duplicate_brush` first.
-6. **Share it.** `export_brushes` writes a library file; `import_brushes` adds one (version 1
+6. **From an image.** `add_brush_source` with the PNG (`channel` when `auto` picks the wrong
+   part; keep the `licence` it came with), then `create_brush` with `tip: { shape: "stamp",
+   stamps: ["source:<id>"] }` for an image tip, or `tip.grain.source` for grain.
+   `list_brush_sources` lists them and which brushes use each.
+7. **Share it.** `export_brushes` writes a library file; `import_brushes` adds one (version 1
    files of the paint editor's older brushes are migrated). `check_brush` with `host` before
    handing a brush to another editor.
 
@@ -92,6 +105,13 @@ drawn.
   to make its preview visible: choosing the brush makes that default the user's colour.
 - Stamp tips paint the sticker's shape in the paint colour; to keep a sticker's own colours, use
   `marks` objects instead.
+- Image tips: crop the image to the mark and give it a transparent or plain background, so the
+  dab is the mark and not its box. Spacing 0.2–0.4 for a continuous mark, above 1 for separate
+  prints; add `angleJitter`, `flip` and `scatter` so the same image doesn't repeat visibly.
+- Grain: `texturised` grain (default) is a texture the stroke reveals, like paper; `moving` grain
+  belongs to the tip and rolls with it (a sponge, a roller). Depth 0.4–0.7 reads as texture;
+  1 leaves only the peaks. Use `tip.grain` for the tool's texture and `behaviour.grain` for the
+  paper's.
 
 ## Pitfalls
 
@@ -107,6 +127,11 @@ drawn.
   (`editor:star`…). A ref the host's sticker library can't load is refused with the closest
   refs. Only the paint editor renders stamp tips and scatter marks; canvas, vector and the image
   editor refuse them (`check_brush` says so).
+- **Image sources.** A `source:<id>` the library doesn't have is refused, with the closest ids;
+  add it first. Replacing a source's image (`overwrite`) changes every brush that names it, but
+  not strokes already painted. Objects marks take stickers only, so an image source there is
+  dropped (`problems` says so). Brush packs are often licensed for personal use only: keep the
+  `licence` text with the source.
 - **Out-of-range values** are refused by the schema (`tip.size` is 1..2500 px); a stored brush
   is clamped on import and reported in `problems`.
 - **The paint editor paints from this library.** Its `set_brush` picks a brush by id here and
@@ -133,3 +158,5 @@ drawn.
 | `export_brushes` | Library file (pixerate-brushes v2) of the saved brushes or the `ids` given. Returns `file`, for `import_brushes`. |
 | `import_brushes` | Add a library `file` (v2, v1 migrated, or a bare list): built-in ids and taken ids are skipped unless `overwrite`. Returns `added`, `replaced`, `skipped`, `problems`. |
 | `preview_brush` | Only when the host renders previews: a sample stroke with a brush (`id`, `width`, `height`, `color`) as an image. |
+| `add_brush_source` | Add an image (`name`, `image` PNG data: URL, optional `id`, `channel` auto / alpha / darkness / lightness, `invert`, `licence`, `origin`, `overwrite`) as a source for image tips and grain. Returns `id`, `ref` (`source:<id>`), `width`, `height`, `problems`, `replaced`. Then `create_brush` / `update_brush` with the ref in `tip.stamps` or `tip.grain.source`. |
+| `list_brush_sources` | The library's image sources (`text`, `offset`, `limit`). Returns `sources` (id, ref, name, width, height, licence, origin, `usedBy` brush ids) and `total`. Call before naming a `source:` ref. |

package/skills/pixerate-brushes-design/SKILL.md

@@ -26,8 +26,9 @@ This skill is the method. `pixerate-brushes` has the full tool reference.
 
 Ask when you cannot tell from the request; say what you assumed when you can.
 
-- **Host:** which editor will use it (paint by default; canvas and vector strokes take only dry
-  dab brushes, the image editor no wet, thick or particle brushes).
+- **Host:** which editor will use it (paint by default; canvas strokes take only dry dab brushes,
+  vector strokes dry and wet dab brushes, the Mixer Brush, smudge and blender; the image editor no
+  wet, thick or particle brushes).
 - **Medium and character:** what it imitates (pencil, ink, chalk, watercolour, marker…), and
   the size, softness and texture.
 - **Colour:** a default colour or palette, or the user's own colour (the default).
@@ -53,9 +54,11 @@ Ask when you cannot tell from the request; say what you assumed when you can.
 | Situation | Approach |
 | --- | --- |
 | A colour variant of a preset | `basedOn` it, set `colour.default` (and a `palette`), keep everything else. |
-| For canvas or vector strokes | Base on a dry preset (pencil, pastel, charcoal, marker, ink); no wet surface, particles, stickers or tools; no light on canvas. |
+| For canvas strokes | Base on a dry preset (pencil, pastel, charcoal, marker, ink); no wet surface, particles, stickers or tools; no light. |
+| For vector strokes | As canvas, but a wet surface (watercolour, gouache, wet oil), the Mixer Brush and the smudge and blender tools work too; no thick paint, particles, stickers, erasers or wet tools. |
 | A brush that must work in another editor | `check_brush` with that `host`, then `create_brush` from its `degraded` brush under a new id. |
-| A texture (chalk, charcoal, dry brush) | Raise `behaviour.grain` (0.8..1) and add `dynamics.sizeJitter`; test on rough paper. |
+| A texture (chalk, charcoal, dry brush) | Raise `behaviour.grain` (0.8..1) and add `dynamics.sizeJitter`; test on rough paper. For texture that shows on any paper, give the tip its own grain: `tip.grain` `{ source: "sanded", depth: 0.6 }` (paint editor; other hosts paint without it). |
+| A brush from an image (a scanned mark, a leaf, a texture) | `list_brush_sources`, or `add_brush_source` with the PNG (keep its `licence`); then `tip` `{ shape: "stamp", stamps: ["source:<id>"] }`, spacing 0.2–0.4, `dynamics.angleJitter`, `flip` and a little `scatter`. The image as grain instead: `tip.grain.source`. Paint editor only. |
 | A light brush (neon, glow) | `light.amount`, and paint it on dark paper; a highlighter keeps `light.spill.radius` 0. |
 | A colour that depends on the background (chalk, white ink) | `colour.default` as a light / dark pair `{ light, dark }`: the editor takes the side for its colour scheme when the brush is chosen. |
 | A shape as the tip (stars, leaves, a logo) | `tip.shape` stamp with `stamps` (an editor stamp or a ref from `find_stickers`), continuous marks; it paints in the user's colour. Keep the sticker's colours with `marks` objects. Paint editor only. |
@@ -72,6 +75,11 @@ basedOn: "highlighter", colour: { default: "#ff6ec7" } }`, then `check_brush`.
 `{ id: "board-chalk", name: "Board chalk", basedOn: "chalk", colour: { default: { light:
 "#334155", dark: "#f8fafc" } } }`: white chalk in dark mode, slate on light paper.
 
+**A charcoal brush from a scan.** `add_brush_source` `{ name: "Charcoal scan", image: <PNG>,
+channel: "darkness" }` → `create_brush` `{ id: "scan-charcoal", name: "Scan charcoal", basedOn:
+"charcoal-stick", tip: { shape: "stamp", stamps: ["source:charcoal-scan"], spacing: 0.25, grain:
+{ source: "rough", depth: 0.5 } }, dynamics: { angleJitter: 0.3, flip: "xy" } }` → `preview_brush`.
+
 **Port a wet brush to vector.** `check_brush` `{ id, host: "vector" }`; `create_brush` from the
 `degraded` brush with `id` `<id>-vector`; `check_brush` again.
 
@@ -80,7 +88,8 @@ basedOn: "highlighter", colour: { default: "#ff6ec7" } }`, then `check_brush`.
 - **Starting from nothing.** A brush without `basedOn` gets engine defaults (a hard round dab);
   it rarely looks like the medium asked for.
 - **A host that refuses the base.** A wet or particle preset can't be the base of a canvas
-  brush; set `behaviour.surface` to `dry` or start from a dry preset.
+  brush, nor a thick (impasto) preset of a vector one; set `behaviour.surface` to `dry` (vector
+  also takes `wet`) or start from a dry preset.
 - **Lists replace.** Giving `colour.palette` or `tip.stamps` replaces the whole list; include
   every entry you want.
 - **Changing a built-in.** `update_brush` refuses built-ins; duplicate first.
@@ -91,3 +100,4 @@ basedOn: "highlighter", colour: { default: "#ff6ec7" } }`, then `check_brush`.
 - `create_brush`, `update_brush`, `duplicate_brush`: make and tune the brush.
 - `check_brush`: prove it works for the host, and get a degraded spec when it doesn't.
 - `preview_brush`: look at a sample stroke when the host renders previews.
+- `add_brush_source`, `list_brush_sources`: images for image tips and grain.

package/skills/pixerate-brushes-design/evals/port-to-vector.json

@@ -1,17 +1,17 @@
 {
-	"prompt": "A teammate's brush team-wash is in the library, but it won't work for vector brushstrokes. Make a copy called team-wash-vector that does, and leave theirs as it is.",
+	"prompt": "A teammate's brush team-knife is in the library, but it won't work for vector brushstrokes. Make a copy called team-knife-vector that does, and leave theirs as it is.",
 	"fixture": {
 		"editor": "brushes",
-		"setup": [{ "tool": "create_brush", "args": { "id": "team-wash", "name": "Team wash", "basedOn": "watercolor-wash", "tags": ["team"] } }]
+		"setup": [{ "tool": "create_brush", "args": { "id": "team-knife", "name": "Team knife", "basedOn": "palette-knife", "tags": ["team"] } }]
 	},
 	"checks": [
-		{ "why": "the copy works in the vector editor", "tool": "check_brush", "args": { "id": "team-wash-vector", "host": "vector" }, "expect": { "ok": true } },
-		{ "why": "the copy keeps the wash's tip", "tool": "describe_brush", "args": { "id": "team-wash-vector" }, "expect": { "brush": { "tip": { "size": 90, "roundness": 0.45 } } } },
-		{ "why": "the teammate's brush still paints wet", "tool": "describe_brush", "args": { "id": "team-wash" }, "expect": { "brush": { "behaviour": { "surface": "wet" } } } }
+		{ "why": "the copy works in the vector editor", "tool": "check_brush", "args": { "id": "team-knife-vector", "host": "vector" }, "expect": { "ok": true } },
+		{ "why": "the copy keeps the knife's tip", "tool": "describe_brush", "args": { "id": "team-knife-vector" }, "expect": { "brush": { "tip": { "size": 48, "roundness": 0.18 } } } },
+		{ "why": "the teammate's brush still lays thick paint", "tool": "describe_brush", "args": { "id": "team-knife" }, "expect": { "brush": { "behaviour": { "surface": "thick" } } } }
 	],
 	"solution": [
-		{ "tool": "check_brush", "args": { "id": "team-wash", "host": "vector" } },
-		{ "tool": "create_brush", "args": { "id": "team-wash-vector", "name": "Team wash (vector)", "basedOn": "team-wash", "behaviour": { "surface": "dry" } } },
-		{ "tool": "check_brush", "args": { "id": "team-wash-vector", "host": "vector" } }
+		{ "tool": "check_brush", "args": { "id": "team-knife", "host": "vector" } },
+		{ "tool": "create_brush", "args": { "id": "team-knife-vector", "name": "Team knife (vector)", "basedOn": "team-knife", "behaviour": { "surface": "wet" } } },
+		{ "tool": "check_brush", "args": { "id": "team-knife-vector", "host": "vector" } }
 	]
 }

package/skills/pixerate-canvas/SKILL.md

@@ -100,7 +100,14 @@ you to. Withdraw stale ones with `reject_proposal`: when the user changes what a
   stroke always looks the same, and neighbouring strokes share one sheet of paper. Pick the brush
   for the look, then the colour; for a sketch, use one or two brushes rather than all of them.
   A brush with a default colour (ballpoint blue, highlighter yellow, chalk) paints in it when
-  you pass no `color`; pass `color` to use another.
+  you pass no `color`; pass `color` to use another. Light / dark defaults (chalk) resolve for
+  the canvas's colour scheme (`canvas.setColorScheme`; the host usually matches its theme).
+- **Setting up the pen for the person, not drawing.** `canvas.selectBrush` chooses the brush the
+  person draws with by hand, as the brush picker does: it takes the brush's default colour unless
+  they locked theirs (`canvas.setColorLocked`, "Keep my colour") or you pass `keepColour`. A
+  default taken this way follows the scheme until another colour is set. Respect a lock the
+  person set; don't unlock it to change their colour. These are editor state, not undo steps,
+  and don't affect `canvas.drawFreehand`, which takes its own `brush` and `color`.
 - **Annotate with gestures, not points.** To mark up work the way a designer marks up a print,
   use the gesture commands (`canvas.circle`, `canvas.underline`, `canvas.arrow`,
   `canvas.bracket`, `canvas.strike`, `canvas.cross`, `canvas.check`) with node ids
@@ -254,6 +261,9 @@ character: seeded jitter and the paper grain they catch) and, when a width was c
 | Command | Use it to |
 | --- | --- |
 | `canvas.drawFreehand` | Draw a pen or highlighter stroke through `points` (`[x, y]` pairs in canvas units, in drawing order; one undo step). `tool` picks the defaults (`pen`: blue, width 3; `highlighter`: yellow, width 24, opacity 0.35); `color`, `width`, `opacity` override them (with a `brush` and no `color`, the brush's default colour if it has one; with a `brush`, `width` is the brush diameter and defaults to the preset's own size). Pass `brush` (a preset or saved brush id from `canvas.listBrushes`, or tip settings) to paint it with a dry brush, plus `pressure` / `tiltX` / `tiltY` profiles spread along its length (`[0.2, 1, 0.3]` swells in the middle). Add `paint` (only with `brush`) for gradient paint that changes colour along the stroke: `{ "type": "gradient", "stops": [...], "map": { "by": "distance", "length": 200 } }` (length in canvas units), or `by` `pressure`, `tilt`, `direction`, `across-tip`, `random`. Returns the node `id`, its `bounds` and the stored `brush` (with `paint` normalised: defaults filled in, colours lowercased). |
+| `canvas.selectBrush` | Choose the brush the person draws with by hand (`brushId` from `canvas.listBrushes`, or `null` for a plain vector stroke), at its own size, taking its default colour unless the colour is locked or `keepColour`. Draws nothing. Returns `{ brush, color, colorScheme, colorLocked, colorFollowsScheme }`. |
+| `canvas.setColorLocked` | Lock (`locked: true`) or unlock the hand-drawing colour ("Keep my colour"): while locked, `canvas.selectBrush` keeps it. Returns the same settings as `canvas.selectBrush`; call it (or `canvas.selectBrush`) to read whether the person locked it. |
+| `canvas.setColorScheme` | Set `scheme` `light` or `dark`: picks the side of light / dark default colours for `canvas.selectBrush` and `canvas.drawFreehand`; a colour taken from such a default follows, strokes already drawn keep theirs. Usually the host's job. Returns the same settings as `canvas.selectBrush`. |
 | `canvas.listBrushes` | Read-only: the brushes `canvas.drawFreehand` and the gestures accept as `brush`: the dry presets, then saved brushes from the brush library the canvas can paint (`id`, `name`, `category`, the brush's own `size`, which a stroke uses unless you pass `width`, and `builtin`). Call it before the first brushed stroke instead of guessing ids. |
 
 Gestures draw one hand-drawn stroke node each (one undo step) through the same path as

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

@@ -1,17 +1,19 @@
 ---
 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; 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.
+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, smart object; masks, clipping, blend modes, filters), 16/32-bit depth, colour management (profiles, proofing, CMYK, Lab), smart objects and smart filters, provider effects, layer effects, adjustments, selections and masks, Free Transform, crop, rotate, flip, painting and Mixer Brush, retouching (Clone Stamp, Healing, Spot Healing, Smudge, Dodge, Burn, Sponge, Blur, Sharpen, History Brush), undo, PSD, histogram and previews. Use when editing, grading, cropping, masking or retouching an image, adding effects, shapes or text, converting profiles or bit depth, transforming layers, or when list_layers, set_adjustments, add_layer_effect, apply_effect, transform_layer, add_text_layer, paint_stroke, clone_stamp, spot_heal, blur_stroke, sharpen_stroke, history_brush, set_bit_depth, convert_to_profile or import_psd are available.
 ---
 
 # Image editor
 
-The image editor holds a layer stack over a canvas the size of the source image. Opening an
+The image editor holds a layer stack over a canvas the size of the source image (8-, 16- or
+32-bit depth, with RGB, CMYK and Lab colour management, ICC profiles and soft proofing). Opening an
 image gives one pixel layer, **Background**, whose pixels are the source and whose `develop`
 filter holds the base adjustments (the base controls edit the develop filter of the active pixel
 layer). Adjustment layers sit above it, each through its mask, opacity and blend mode, and
 annotations are shape and type layers on top. Edits never touch the source pixels; `list_layers`
 shows the whole stack. Pixel, group and smart object layers can carry live effects; a smart
-object places contents through a transform and smart filters; shape layers hold vector paths and
+object places contents through a transform and smart filters (including provider effects, which
+also add generator and overlay effect layers); shape layers hold vector paths and
 type layers live text, re-rendered on every change. There is also an optional selection and a
 crop, rotation and flip. See `pixerate-agent-tools` for errors and batching.
 
@@ -95,9 +97,9 @@ Boxes, badges, arrows and callouts are shape layers (`add_shape_layer`), text is
 (`add_text_layer`); both stay sharp and take effects, masks and blends. Read
 [references/shapes-and-type.md](references/shapes-and-type.md) before drawing or editing either.
 
-### Layer effects
+### Layer and provider effects
 
-Live per-layer effects (shadows, glows, bevel, overlays, strokes): see `references/layer-effects.md`.
+Live per-layer styles (shadows, glows, bevel, overlays, strokes): see [references/layer-effects.md](references/layer-effects.md). Provider filter smart filters and generator / overlay effect layers (`search_effects`, `describe_effect`, `apply_effect`, `add_effect_layer`): see [references/provider-effects.md](references/provider-effects.md).
 
 ### Paths and cutout edges
 
@@ -110,13 +112,15 @@ Keep outlines as paths (`make_work_path`, `add_path`) and edit their anchors: se
 Paint on its own layer (`add_pixel_layer`), one stroke per call and one undo step, limited by a
 selection or locked transparency. Read [references/painting.md](references/painting.md) first.
 
-### Colour management
+### Bit depth and colour management
 
-Working space, profiles, soft proofing and print conversions: read [references/color-management.md](references/color-management.md).
+Switch between 8-, 16- and 32-bit (float, linear light) with `set_bit_depth` (`references/photoshop-files.md`). For working space profiles (`assign_profile`, `convert_to_profile`), soft proofing (`set_proof_setup`) and CMYK / Lab print modes (`set_color_mode`, `convert_colors`), read [references/color-management.md](references/color-management.md).
 
 ### Retouching
 
-Heal, clone, dodge and burn on layers above the photo (`sample: "current-below"`): load
+Heal and clone on layers above the photo (`sample: "current-below"`); dodge, burn, sponge, blur
+(`blur_stroke`), sharpen (`sharpen_stroke`) and History Brush (`history_brush`) change the pixels
+they touch, so run them on a duplicate. Load
 `pixerate-image-portrait-retouch`, and read [references/retouching.md](references/retouching.md) first.
 
 ### Photoshop files
@@ -136,11 +140,11 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 - **Blend modes for tone-only or colour-only changes:** `luminosity` applies a curves or
   levels layer without shifting hue or saturation; `color` applies a tint without changing
   brightness; `soft-light` / `overlay` for gentle contrast.
-- **`pigment` mixes like paint.** On a layer, a fill or a brush, `pigment` mixes the colour into
+- **`pigment` and painterly modes mix like paint.** On a layer, a fill or a brush, `pigment` mixes the colour into
   what is below as real paint would (Kubelka-Munk): blue into yellow gives green, white gives
   tints, and opacity is the share of new paint (0.5 is half and half). Use it for glazes,
-  natural colour mixing and painterly strokes; it is not a Photoshop mode, so keep it off
-  layers that must survive a PSD round trip. It costs about ten times a normal blend.
+  natural colour mixing and painterly strokes; neither `pigment` nor the painterly modes (`watercolor`, `tint`, `highlight`, `shadow`) are Photoshop modes (`export_psd` writes them as Normal), so keep them off
+  layers that must stay editable in a PSD round trip. `pigment` costs about ten times a normal blend.
 - **Name layers** (`name`) by intent ("Sky darken", "Warm skin"), so the stack stays readable.
 - **Effects, transforms and smart objects** have their own best practices in
   `references/layer-effects.md`, `references/free-transform.md` and `references/smart-objects.md`.
@@ -174,7 +178,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `measure_region` | Measure a rectangle of the composited image (`x`, `y`, `width`, `height` in natural pixels; default the crop, else the whole image) without a render: the `get_histogram` summary plus `meanColor` (hex) and `cast` (`redBlue`, `greenMagenta` in levels; within about ±4 is neutral). Check a neutral reference, skin, a background or clipping after each correction. |
 | `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 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. |
+| `export_psd` | Save the document as a PSD in its colour mode (RGB, or CMYK / Lab channels after `set_color_mode`) with its profile, at its bit depth (RGB 8, 16 or 32; CMYK and Lab 8 or 16, so a 32-bit CMYK / Lab document is written at 16 with a warning; 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; painterly blends are written as Normal too, without a warning). 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. |
@@ -381,13 +385,7 @@ The host may add the shared document tools (see `pixerate-agent-tools`). An imag
 ## Pitfalls
 
 - Agent playback (if on) opens each write's panel, then traces `points`, drags boxes or visits the layers and sliders named; results are unchanged.
-- Effects need a shape: on an empty layer they draw nothing. They cannot go on adjustment layers. A clipped layer's effects stay inside the layer it is clipped to.
-- `bevel-emboss` has no `blend` / `opacity`: it uses `highlightBlend`, `highlightOpacity`,
-  `shadowBlend` and `shadowOpacity`. Inner shadows and inner glows use `choke`, not `spread`.
-- Glows paint a colour or a gradient, never a pattern; strokes take all three. Pattern effects
-  need a pattern id from `list_layer_effects.patterns`; an unknown id paints nothing.
-- Effect angles are where the light comes *from*: 120° (top left) casts a shadow down and to
-  the right. With `useGlobalLight` true an effect's own `angle` is ignored.
+- Domain-specific pitfalls live in their references: layer styles in [references/layer-effects.md](references/layer-effects.md), provider effects in [references/provider-effects.md](references/provider-effects.md), painting and the Mixer Brush in [references/painting.md](references/painting.md), retouching in [references/retouching.md](references/retouching.md), shapes and text in [references/shapes-and-type.md](references/shapes-and-type.md), smart objects in [references/smart-objects.md](references/smart-objects.md), Free Transform in [references/free-transform.md](references/free-transform.md), colour management in [references/color-management.md](references/color-management.md), and PSD in [references/photoshop-files.md](references/photoshop-files.md).
 - A layer's `kind` cannot change; to switch kinds add a new layer and remove the old one.
   Curves points, `colorize` and colours are only set when the layer is added, so get them
   right in `add_adjustment_layer` (or replace the layer).
@@ -395,41 +393,7 @@ The host may add the shared document tools (see `pixerate-agent-tools`). An imag
   `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"`).
-  To paint a smart object's pixels, `edit_smart_object_contents` or rasterize it. A layer with
-  `locks.pixels` refuses paint.
-- Text ranges count UTF-16 code units (an emoji is two). Point text grows from its origin: centred
-  text is centred on `x`. Type cannot be distorted, put in perspective or warped; it can be scaled,
-  rotated and skewed. Where no font shaper exists (a server without one), type layers keep their
-  stored pixels and edits are refused with a reason.
-- Shape strokes are not layer-effect strokes: `stroke` on `add_shape_layer` / `update_shape`
-  follows the path (and its dashes and caps); `add_layer_effect` `stroke` outlines the rendered
-  pixels. Arrowheads belong to `line` live shapes (their `width` and `length` are pixels), not to
-  strokes. A shape drawn over an annotation migrated from an old document (a shape layer with an
-  `annotation` in `list_layers`) stops being that annotation once you edit it as a shape.
-- Shapes render up to 512 px beyond the canvas; moving one in from far outside draws it again
-  from its paths, so nothing is lost.
-- While contents are open (`edit_smart_object_contents`), `list_layers` and every tool see the
-  contents, not the document, and `export_psd` / saving write the document without the open
-  edits. Close with `close_smart_object_contents` before anything else.
-- Smart filters run over the canvas, like layer filters: a blur clamps at the canvas edge, and a
-  smart object is drawn only up to 512 px beyond the canvas. `get_transform_frame` on a smart
-  object returns the contents' rectangle (contents px) as the `frame`, and a warp `mesh` in
-  contents px.
-- `mix_colors` predicts a mix; it does not paint. To paint the mix, pass `blend: "pigment"` to
-  `paint_stroke` (in `brush`) or `fill_pixels`, or set it on a layer.
-- `pigment` has no PSD equivalent: `export_psd` writes those layers as Normal (the merged image
-  keeps the look) and says so in `warnings`, naming the layers. `import_psd` never produces it.
-  Over transparent pixels there is nothing to mix with, so it lays the colour down as Normal.
-- The Mixer Brush ignores `brush.blend` (including `pigment`; use its own `mixer.mixing` instead) and the opacity ceiling: each dab lays paint at
-  `flow × opacity` over the pixels as they are now, so overlapping dabs build up. At `flow` 1
-  each dab covers what is under it, the pickup then sees mostly the brush's own paint, and the
-  stroke drifts towards the loaded colour; lower the flow for more blending.
-- An empty, dry mixer (no reservoir, `wet` 0) paints nothing; the call succeeds with
-  `bounds: null`. A mixer stroke over transparent pixels has nothing to pick up.
+- `pigment` and the painterly blend modes (`watercolor`, `tint`, `highlight`, `shadow`) have no Photoshop mode in the image editor's PSD exporter: `export_psd` writes those layers as Normal (the merged image keeps the composited look; only `pigment` adds a warning, naming the layers). `import_psd` never produces them.
 - `export_psd` is in the source frame: a crop or rotation is not in the file (the warnings say
   so). Crop with `set_crop` only for PNG / JPEG output, or flatten the look you need first.
 - PSD opacity, fill and mask density come in as whole percents (Photoshop stores bytes), so a
@@ -444,19 +408,10 @@ The host may add the shared document tools (see `pixerate-agent-tools`). An imag
   Do not keep raising it; correct the green-magenta cast with a `colorBalance` layer instead.
 - Base `opacity` fades the whole image, not an adjustment. Base `blur` blurs a whole layer (the
   Background by default, before the adjustment layers; in older documents with blur and
-  adjustment layers, the output after them). It is not a local softening tool.
+  adjustment layers, the output after them). For local softening use `blur_stroke`.
 - New adjustment layers go above the other adjustment layers and below annotations, so they
   never tint arrows, labels or watermarks. `list_layers` shows where each one went.
 - `invert` and `threshold` are destructive-looking creative effects; never use them for a
   correction the user did not ask for. Posterize `levels` below ~8 bands visibly.
-- Transforms refuse hidden layers, layers with `locks.position` or `locks.pixels`, and adjustment,
-  annotation and group layers (transform a layer's mask with `channel: "mask"` after unlinking
-  it). A result larger than about 11 600 × 11 600 px is refused.
-- `transform_layer` scale fields are percent (100 = unchanged), not factors; `rotate` is degrees
-  clockwise. `corners` that cross or fold through the horizon are refused: keep the quad convex.
-- With a selection, `content: "auto"` (the default) moves only the selected pixels, not the
-  whole layer. Pass `content: "layer"` to move everything regardless of the selection.
-- A Background transformed smaller leaves transparent canvas around it; fill it with a layer
-  below or crop afterwards.
 - Opacity values are 0..1, not percent. Curves and levels points are 0..255 levels; levels
   `gamma` is 0.1..9.99 (1 = neutral); hue is degrees -180..180.

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

@@ -38,6 +38,7 @@ means sRGB. The viewport assumes an sRGB display and converts other working spac
   `unconvertedLayerIds`: convert inside them (`edit_smart_object_contents`) 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.
+- `export_psd` embeds the profile (the working space for RGB, the press profile for CMYK; Lab
+  files carry none); 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/free-transform.md

@@ -31,3 +31,15 @@ How to move, scale, rotate, skew, distort and warp layers, selected pixels and m
 - **Scale proportionally** unless asked to stretch: give `scaleX` and `scaleY` the same value.
   Keep the subject in frame: after a scale about `center` the layer can run past the canvas,
   which `bounds` in the result shows.
+
+## Pitfalls
+
+- Transforms refuse hidden layers, layers with `locks.position` or `locks.pixels`, and adjustment,
+  annotation and group layers (transform a layer's mask with `channel: "mask"` after unlinking
+  it). A result larger than about 11 600 × 11 600 px is refused.
+- `transform_layer` scale fields are percent (100 = unchanged), not factors; `rotate` is degrees
+  clockwise. `corners` that cross or fold through the horizon are refused: keep the quad convex.
+- With a selection, `content: "auto"` (the default) moves only the selected pixels, not the
+  whole layer. Pass `content: "layer"` to move everything regardless of the selection.
+- A Background transformed smaller leaves transparent canvas around it; fill it with a layer
+  below or crop afterwards.

package/skills/pixerate-image-editor/references/layer-effects.md

@@ -34,3 +34,13 @@ Read this before `add_layer_effect`, `update_layer_effect`, `set_global_light` o
   layer `opacity` fades the effects too.
 - **Prefer an effect over painted pixels** for shadows, glows, outlines and colour fills of a
   shape: it follows later edits and stays adjustable.
+
+## Pitfalls
+
+- Effects need a shape: on an empty layer they draw nothing. They cannot go on adjustment layers. A clipped layer's effects stay inside the layer it is clipped to.
+- `bevel-emboss` has no `blend` / `opacity`: it uses `highlightBlend`, `highlightOpacity`,
+  `shadowBlend` and `shadowOpacity`. Inner shadows and inner glows use `choke`, not `spread`.
+- Glows paint a colour or a gradient, never a pattern; strokes take all three. Pattern effects
+  need a pattern id from `list_layer_effects.patterns`; an unknown id paints nothing.
+- Effect angles are where the light comes *from*: 120° (top left) casts a shadow down and to
+  the right. With `useGlobalLight` true an effect's own `angle` is ignored.

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

@@ -43,3 +43,20 @@ Read this before `mix_colors`, a `paint_stroke` with `tool: "mixer"`, or gradien
    "gradient", stops, map }`, or `paint_stroke` `paint` for one stroke (brush only). `map.by`
    `distance` (default 300 px, mirrored) for drag-it-out colour, `pressure`, `direction`,
    `across-tip`, `random`; stops may be `"paint"` / `"secondary"` (foreground / background).
+
+## Pitfalls
+
+- `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"`).
+  To paint a smart object's pixels, `edit_smart_object_contents` or rasterize it. A layer with
+  `locks.pixels` refuses paint.
+- `mix_colors` predicts a mix; it does not paint. To paint the mix, pass `blend: "pigment"` to
+  `paint_stroke` (in `brush`) or `fill_pixels`, or set it on a layer.
+- `pigment` and the painterly blend modes (`watercolor`, `tint`, `highlight`, `shadow`) have no Photoshop mode in the image editor's PSD exporter: `export_psd` writes those layers as Normal (the merged image keeps the look; only `pigment` adds a warning, naming the layers). `import_psd` never produces them. Over transparent pixels there is nothing for `pigment` to mix with, so it lays the colour down as Normal.
+- The Mixer Brush ignores `brush.blend` (including `pigment`; use its own `mixer.mixing` instead) and the opacity ceiling: each dab lays paint at
+  `flow × opacity` over the pixels as they are now, so overlapping dabs build up. At `flow` 1
+  each dab covers what is under it, the pickup then sees mostly the brush's own paint, and the
+  stroke drifts towards the loaded colour; lower the flow for more blending.
+- An empty, dry mixer (no reservoir, `wet` 0) paints nothing; the call succeeds with
+  `bounds: null`. A mixer stroke over transparent pixels has nothing to pick up.

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

@@ -40,7 +40,7 @@
    (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
+   a browser), and `pigment` or painterly blend modes (`watercolor`, `tint`, `highlight`, `shadow`) are written as Normal (the merged image keeps their composited look; only `pigment` adds a warning, naming the layers). 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

package/skills/pixerate-image-editor/references/shapes-and-type.md

@@ -72,3 +72,17 @@ upright-Latin runs) and goes back out as vertical type. `get_text_layer` reports
 and `missingFonts` for those: if a font is missing, edits draw with a fallback, so tell the user
 before editing such text, or pick an available font with `set_text_style`. `export_psd` writes both
 kinds back as Photoshop layers; unchanged ones are written byte for byte as they were read.
+
+## Pitfalls
+
+- Text ranges count UTF-16 code units (an emoji is two). Point text grows from its origin: centred
+  text is centred on `x`. Type cannot be distorted, put in perspective or warped; it can be scaled,
+  rotated and skewed. Where no font shaper exists (a server without one), type layers keep their
+  stored pixels and edits are refused with a reason.
+- Shape strokes are not layer-effect strokes: `stroke` on `add_shape_layer` / `update_shape`
+  follows the path (and its dashes and caps); `add_layer_effect` `stroke` outlines the rendered
+  pixels. Arrowheads belong to `line` live shapes (their `width` and `length` are pixels), not to
+  strokes. A shape drawn over an annotation migrated from an old document (a shape layer with an
+  `annotation` in `list_layers`) stops being that annotation once you edit it as a shape.
+- Shapes render up to 512 px beyond the canvas; moving one in from far outside draws it again
+  from its paths, so nothing is lost.