@pixerate/editor 0.266.2 → 0.267.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.267.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

@@ -21,7 +21,7 @@ built-in presets (read-only) and the user's brushes, shared by every editor that
 | 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**
@@ -43,7 +43,7 @@ paints without (warnings), each with a fix; lists and writes use the current hos
 | 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`. |
+| 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.

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,7 +54,8 @@ 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 light brush (neon, glow) | `light.amount`, and paint it on dark paper; a highlighter keeps `light.spill.radius` 0. |
@@ -80,7 +82,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.

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.

package/skills/pixerate-image-editor/references/smart-objects.md

@@ -35,3 +35,13 @@ How to work with smart objects in the image editor (see the main skill for the t
   the user may want to mask, blend or reorder them later.
 - **Linked or not**: duplicate a smart object `linked: true` for repeated elements that must stay
   identical (a logo placed twice); use `linked: false` when the copies will be edited apart.
+
+## Pitfalls
+
+- 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.

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

@@ -321,7 +321,7 @@ Listing, saving, sharing and previewing brushes are the brush library's tools (`
 | 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` facet changes (as `set_brush` takes), `color` or `paint` (a gradient for this stroke), `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. |
-| `stroke_path` | Brush SVG path data (`path`, document px; M, L, C, Q, A, Z…) with the active brush or `brushId` / `brush`, as if drawn along it by hand: each subpath one recorded stroke, sampled every `spacing` px (default 2), with a `pressure` profile spread along each subpath (`[0.2, 1, 0.2]` tapers both ends). One undo step. Returns `layerId`, `bounds`, `dabs` and `strokeIds` (for `replay_strokes`, `update_stroke`). Use it for clean curves, outlines of shapes and lettering guides instead of working out points; use `paint_stroke` when the marks need time or tilt. |
+| `stroke_path` | Brush SVG path data (`path`, document px; M, L, C, Q, A, Z…) with the active brush or `brushId` / `brush`, as if drawn along it by hand: each subpath one recorded stroke, sampled every `spacing` px (default 2), with a `pressure` profile spread along each subpath (`[0.2, 1, 0.2]` tapers both ends) and optional `speed` (px/ms, stamps each sample with `t`). With an agent director, each subpath is painted live in turn. One undo step. Returns `layerId`, `bounds`, `dabs` and `strokeIds` (for `replay_strokes`, `update_stroke`). Use it for clean curves, outlines of shapes and lettering guides instead of working out points; use `paint_stroke` when the marks need variable timing or tilt. |
 | `list_strokes` | Read the recorded strokes, oldest first (default the last 100): id, layer, brush, colour, point count, seed, bounds, `live`. With `ids`, their points too; with `layerId`, one layer's. With `live: true`, the editable strokes of stroke layers as they are now, bottom first: the ids for the stroke layer tools. |
 | `get_live_stroke` | Read the stroke the user is painting right now (layer, brush, colour, samples so far; `live: false` when none). For painting along with the user; hosts stream the samples live. |
 | `stroke_at` | Read the top-most stroke of a stroke layer that painted the pixel at `x`, `y`, or null. Use it to pick one stroke among overlapping ones. |
@@ -339,7 +339,7 @@ Listing, saving, sharing and previewing brushes are the brush library's tools (`
 
 | 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), the GPU accelerator (`engine`) and each wet layer (`wetCells`, `wetBounds`, `activeTiles`, settings, flow map). Call after wet strokes. |
+| `get_wet_paint` | Read the wet paint: `wet`, the clock, `paused`, `speed`, `tilt`, the kernel (`backend`, `message` when it runs slower than it could, e.g. on one thread because the page is not cross-origin isolated (COOP / COEP)), the GPU accelerator (`engine`) 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. |
@@ -462,7 +462,8 @@ The host may add the shared document tools (see `pixerate-agent-tools`). A paint
   keep taking its colours.
 - **Strokes take real time when the host shows your cursor.** With a director (the demo and
   editors that set `createPaintEditorToolProvider({ director })`), `paint_stroke` paints live at
-  the pace of the points' `t` (else about 1.5 px per ms, at most ~1.8 s), and `fill_layer` /
+  the pace of the points' `t` (else about 1.5 px per ms, at most ~1.8 s), `stroke_path` paints
+  each subpath in turn (paced by its `speed` when given) as one undo step, and `fill_layer` /
   `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.
@@ -470,7 +471,10 @@ The host may add the shared document tools (see `pixerate-agent-tools`). A paint
   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.
+  the first before painting the second (glazing). At most 8 layers hold wet paint at once, and the simulation holds at most 328 wet tiles (256 × 256 px each) across them; water that spreads past
+  that limit is lost (`dry_paint` frees tiles). Multi-threaded wet media needs a cross-origin isolated
+  page (COOP / COEP, for `SharedArrayBuffer`) and runs on one thread otherwise, more slowly but with
+  the same result.
 - **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.

package/skills/pixerate-paint-editor/references/wet-media.md

@@ -28,6 +28,15 @@
   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`.
+- **Extent limit (8 wet layers, 328 tiles).** The simulation holds at most 8 wet layers and 328
+  live tiles of 256 × 256 px across them (one wasm32 memory, under 4 GB). Water that spreads beyond
+  them is lost (`get_wet_paint` reports `activeTiles` per layer, so watch the total); dry
+  finished washes with `dry_paint` to free their tiles before painting another large wash.
+- **Multi-threading and COOP / COEP.** Stepping wet tiles across Web Workers needs
+  `SharedArrayBuffer`, which browsers only expose on cross-origin isolated pages
+  (`Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` or
+  `credentialless`). Without cross-origin isolation the simulation runs on one thread, more slowly
+  but with identical results, and `get_wet_paint` says why in the kernel's `message`.
 - **The GPU only draws.** With WebGPU and a large wet area (16 tiles of 256 px by default), Engine B
   shades the wet paint on the GPU; the CPU engine still computes every step, so the painting,
   `dry_paint`, saving, export and replay come out the same with it on or off. `get_wet_paint`