@pixerate/editor 0.255.0 → 0.257.0

package/dist/vector/index.js

@@ -26,7 +26,7 @@ import {
   traceField,
   traceVectorImage,
   vectorTraceContours
-} from "../chunk-VUKUTT2W.js";
+} from "../chunk-4M4E3N6X.js";
 import {
   applyHomography,
   homographyFromPoints,
@@ -53,7 +53,7 @@ import {
   reverseMorphContour,
   subpathToMorphContour,
   turnMorphContour
-} from "../chunk-HYWRU5VX.js";
+} from "../chunk-IXQZHCOF.js";
 import {
   DEFAULT_VECTOR_FONT,
   IDENTITY_MATRIX,
@@ -528,10 +528,10 @@ import {
   withVectorStrokes,
   withVectorTargetPaint,
   zigzagPaths
-} from "../chunk-AF23QK5F.js";
+} from "../chunk-YQ4PQTBB.js";
 import {
   snapshotBrushLibrary
-} from "../chunk-JVRLGV3C.js";
+} from "../chunk-SMTUQWGY.js";
 import "../chunk-APX63ILU.js";
 import {
   createProvenance
@@ -599,8 +599,10 @@ import "../chunk-M2TPMYJE.js";
 import {
   hexToRgba
 } from "../chunk-2WPNAGHI.js";
-import "../chunk-7272D3K2.js";
-import "../chunk-YBAPT7NL.js";
+import "../chunk-2EUW2XZX.js";
+import "../chunk-E2V5DA3W.js";
+import "../chunk-VR6OGHU5.js";
+import "../chunk-JC2SHA4A.js";
 import "../chunk-MHLU6GRJ.js";
 import "../chunk-6ONMQ6WF.js";
 

package/dist/video-editor/index.cjs

@@ -189,8 +189,10 @@ var _chunkM5GLQQWGcjs = require('../chunk-M5GLQQWG.cjs');
 var _chunkDWJJI6RTcjs = require('../chunk-DWJJI6RT.cjs');
 require('../chunk-4ZC5QJE2.cjs');
 require('../chunk-A6QWKBJP.cjs');
-require('../chunk-EUIDTZNQ.cjs');
-require('../chunk-TFF2GTGN.cjs');
+require('../chunk-I3Y2Q3PM.cjs');
+require('../chunk-MEGSQUQO.cjs');
+require('../chunk-MLLTWAXH.cjs');
+require('../chunk-SXQHWXEL.cjs');
 require('../chunk-5UEFBM2M.cjs');
 require('../chunk-IPJ3TEYR.cjs');
 

package/dist/video-editor/index.js

@@ -189,8 +189,10 @@ import {
 } from "../chunk-5UJHB3BW.js";
 import "../chunk-M2TPMYJE.js";
 import "../chunk-2WPNAGHI.js";
-import "../chunk-7272D3K2.js";
-import "../chunk-YBAPT7NL.js";
+import "../chunk-2EUW2XZX.js";
+import "../chunk-E2V5DA3W.js";
+import "../chunk-VR6OGHU5.js";
+import "../chunk-JC2SHA4A.js";
 import "../chunk-MHLU6GRJ.js";
 import "../chunk-6ONMQ6WF.js";
 

package/package.json

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

package/skills/pixerate-brushes/SKILL.md

@@ -15,20 +15,23 @@ 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` lays stickers), size in px, hardness, spacing, opacity, flow, blend mode. |
-| Marks | `continuous` dabs (default), `particles` (strands, springs, ribbons, sparks) or `objects` (each mark an editable sticker). |
+| 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. |
+| 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. |
 | 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). A gradient default is always painted; a solid one is a suggestion. |
+| 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. |
 
 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**
 and **wet oil** are `paint` on `surface: 'wet'`; **impasto** is `surface: 'thick'`; an
-**airbrush** is `spray`, soft and low flow; a **highlighter** is `ink` / `highlighter`, a
-multiply chisel tip with a little light and `spill` radius 0; **particle** and **sticker**
-brushes are `marks` particles or objects on a `stamp` tip.
+**airbrush** is `spray`, soft and low flow; a **spray can** is `spray` with `marks` scatter; a
+**ballpoint**, **gel pen** or **fineliner** is `ink` with a small hard tip (a fineliner without
+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.
 
 ## Host profiles
 
@@ -74,16 +77,23 @@ drawn.
   glow stays on the stroke.
 - Keep `variety` truthful (it is how people find the brush) and add `tags` for the job
   (`lettering`, `foliage`).
-- Use `colour.palette` for suggested colours and `colour.own` only for brushes that must
+- Give a brush a `colour.default` only when the medium has a typical colour (blue ballpoint,
+  yellow highlighter): choosing the brush sets it as the user's colour. Use a light / dark pair
+  when the right colour depends on the background (white chalk on a dark board, graphite on
+  paper), and a `palette` for the other usual colours. `colour.own` only for brushes that must
   always paint their own (a rainbow marker).
+- Stamp tips paint the sticker's shape in the paint colour; to keep a sticker's own colours, use
+  `marks` objects instead.
 
 ## Pitfalls
 
 - **A facet the host refuses.** `create_brush` and `update_brush` refuse it with the facet and
   fix; `check_brush` returns `degraded`, the brush with those facets stripped, to start from.
 - **Ids.** Built-in ids can't be reused or changed; a taken id is refused (update it instead).
-- **Stamps.** Particle marks lay only the editor's stamps (`editor:star`…); sticker (`objects`)
-  marks take any sticker ref from `find_stickers`.
+- **Stamps.** Any marks take any sticker ref from `find_stickers`, or an editor stamp
+  (`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).
 - **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
@@ -101,8 +111,8 @@ drawn.
 | Tool | Use |
 | --- | --- |
 | `list_brush_presets` | Find brushes this host renders: `kind`, `medium`, `variety`, `tool`, `tag`, `text`, `source` (all, builtin, user), `all`, `offset`, `limit`. Returns `brushes` (id, name, builtin, kind, medium, variety or tool, category, engine, tip, size, marks, surface, light) and `total`. Call first. |
-| `describe_brush` | One brush by `id`: its full facet `brush`, `builtin`, `engine`, `category` and `check` for this host. Unknown ids are refused with the closest ones. |
-| `create_brush` | Save a new brush: `id`, `name`, optional `basedOn`, and the facets (to keep an editor's current brush, pass the `brush` its `get_brush` returns). Normalised and checked for this host; refused brushes save nothing. Returns `id`, `brush`, `engine`, `problems`, `warnings`. |
+| `describe_brush` | One brush by `id`: its full facet `brush` (with its `colour`: default, palette, own), `builtin`, `engine`, `category` and `check` for this host (stamp stickers included). Unknown ids are refused with the closest ones. |
+| `create_brush` | Save a new brush: `id`, `name`, optional `basedOn`, and the facets, `colour` included (to keep an editor's current brush, pass the `brush` its `get_brush` returns). Normalised and checked for this host (and its sticker library, for stamp tips); refused brushes save nothing. Returns `id`, `brush`, `engine`, `problems`, `warnings`. |
 | `update_brush` | Change a saved brush: facets to merge in, `unset` facets to drop. Refuses built-ins (duplicate first) and changes the host can't render. Returns `brush`, `changed` paths, `problems`, `warnings`. |
 | `duplicate_brush` | Copy any brush, built-ins included, to a saved brush (`newId` default `<id>-copy`, `name`). Returns the new `id` and `brush`; then `update_brush` it. |
 | `remove_brush` | Delete a saved brush for good (export it first to keep a copy). Built-ins are refused. Returns `removed`. |

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

@@ -57,6 +57,9 @@ Ask when you cannot tell from the request; say what you assumed when you can.
 | 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. |
+| 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. |
+| A spray can or mist | `basedOn` `spray-can`, or `medium` spray with `marks` scatter (`density`, `size`). Paint editor only. |
 | A change to a built-in | `duplicate_brush`, then `update_brush` the copy. |
 
 ## Recipes
@@ -64,8 +67,9 @@ Ask when you cannot tell from the request; say what you assumed when you can.
 **A pink highlighter.** `create_brush` `{ id: "pink-highlighter", name: "Pink highlighter",
 basedOn: "highlighter", colour: { default: "#ff6ec7" } }`, then `check_brush`.
 
-**Chalk for canvas strokes.** On the canvas host, `create_brush` `{ id: "chalk", name: "Chalk",
-basedOn: "soft-pastel", variety: "chalk", behaviour: { grain: 1 }, dynamics: { sizeJitter: 0.12 } }`.
+**Chalk on a blackboard, for canvas strokes.** On the canvas host, `create_brush`
+`{ id: "board-chalk", name: "Board chalk", basedOn: "chalk", colour: { default: { light:
+"#334155", dark: "#f8fafc" } } }`: white chalk in dark mode, slate on light paper.
 
 **Port a wet brush to vector.** `check_brush` `{ id, host: "vector" }`; `create_brush` from the
 `degraded` brush with `id` `<id>-vector`; `check_brush` again.

package/skills/pixerate-brushes-design/evals/canvas-chalk.json

@@ -1,15 +1,15 @@
 {
-	"prompt": "I'm drawing brushed strokes on the canvas. Make a soft, grainy chalk brush with the id chalk that the canvas can actually use.",
+	"prompt": "I'm drawing brushed strokes on the canvas, on a dark blackboard in dark mode and on paper in light mode. Make a grainy chalk brush with the id board-chalk that the canvas can use: near-white chalk in dark mode, a dark slate on light backgrounds.",
 	"fixture": { "editor": "brushes", "host": "canvas" },
 	"checks": [
-		{ "why": "the canvas can render it", "tool": "check_brush", "args": { "id": "chalk", "host": "canvas" }, "expect": { "ok": true } },
-		{ "why": "a dry chalk", "tool": "describe_brush", "args": { "id": "chalk" }, "expect": { "brush": { "kind": "mark", "medium": "dry", "variety": "chalk" } } },
-		{ "why": "it catches the paper grain strongly", "tool": "describe_brush", "args": { "id": "chalk" }, "expect": { "brush": { "behaviour": { "grain": { "$min": 0.8 } } } } },
-		{ "why": "soft-edged", "tool": "describe_brush", "args": { "id": "chalk" }, "expect": { "brush": { "tip": { "hardness": { "$max": 0.6 } } } } }
+		{ "why": "the canvas can render it", "tool": "check_brush", "args": { "id": "board-chalk", "host": "canvas" }, "expect": { "ok": true } },
+		{ "why": "a dry chalk", "tool": "describe_brush", "args": { "id": "board-chalk" }, "expect": { "brush": { "kind": "mark", "medium": "dry", "variety": "chalk" } } },
+		{ "why": "it catches the paper grain strongly", "tool": "describe_brush", "args": { "id": "board-chalk" }, "expect": { "brush": { "behaviour": { "grain": { "$min": 0.8 } } } } },
+		{ "why": "its default colour is a light / dark pair: light chalk on dark, dark on light", "tool": "describe_brush", "args": { "id": "board-chalk" }, "expect": { "brush": { "colour": { "default": { "$expr": "typeof v === 'object' && /^#[c-f]/i.test(v.dark) && /^#[0-6]/i.test(v.light)" } } } } }
 	],
 	"solution": [
-		{ "tool": "list_brush_presets", "args": { "medium": "dry" } },
-		{ "tool": "create_brush", "args": { "id": "chalk", "name": "Chalk", "basedOn": "soft-pastel", "variety": "chalk", "behaviour": { "grain": 1 }, "dynamics": { "sizeJitter": 0.12 } } },
-		{ "tool": "check_brush", "args": { "id": "chalk", "host": "canvas" } }
+		{ "tool": "list_brush_presets", "args": { "variety": "chalk" } },
+		{ "tool": "create_brush", "args": { "id": "board-chalk", "name": "Board chalk", "basedOn": "chalk", "colour": { "default": { "light": "#334155", "dark": "#f8fafc" } } } },
+		{ "tool": "check_brush", "args": { "id": "board-chalk", "host": "canvas" } }
 	]
 }

package/skills/pixerate-canvas/SKILL.md

@@ -94,8 +94,9 @@ you to. Withdraw stale ones with `reject_proposal`: when the user changes what a
   use the preset's own size (`canvas.listBrushes` gives it); pass it only to make the mark finer
   or bolder.
 - **Brush character.** Each preset draws with its own character: charcoal and pastel are broad and
-  grainy (they catch the paper's tooth), pencil is fine and slightly grainy, ink, marker and brush
-  pen are clean, the airbrush is a soft spray. The grain and jitter are seeded per stroke, so a
+  grainy (they catch the paper's tooth), as are crayon and chalk; pencil is fine and slightly
+  grainy; ink, marker, brush pen, ballpoint, gel pen and fineliner are clean (the fineliner keeps
+  one width), the airbrush is a soft spray. The grain and jitter are seeded per stroke, so 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.
 - **Annotate with gestures, not points.** To mark up work the way a designer marks up a print,

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

@@ -314,7 +314,7 @@ in the source frame at the document's bit depth, colour mode and profile. Read
 | `sample_color` | The Eyedropper: read the composite colour at a document point (`size` averages a square; default 1 px) and, unless `setForeground` is false, make it the paint foreground. Use it to match a colour already in the image before painting or retouching. Fails outside the canvas or on transparent pixels. Returns `color` and `foreground`. |
 | `sample_gradient` | Read the composite along a line (`start` → `end`, document pixels) and fit the fewest gradient stops to it (`tolerance` OKLab ΔE, `maxStops`, `sampleSize` averaging, `snapStep`). Changes nothing. Returns a linear `gradient` (angle of the line, oklab), its `css` and `pointsRead`. Use it to match a sky, a backdrop or a light falloff before painting a gradient or styling one. |
 | `get_paint` | Read-only. What the brush paints (`paint`), the foreground and background colours, the brush settings, and `brushPreset` (the preset they came from, null once changed by hand). |
-| `set_brush_preset` | Paint with a brush from the brush library: `id` from `list_brush_presets` (the image host lists only what it can paint). Sets the paint tool it needs (`brush`, `mixer` for a Mixer Brush, `eraser`), its brush and mixer settings and a brush's own gradient. Refuses wet, thick, particle, sticker and light brushes with the reason. Returns `tool`, `brush`, `mixer`, `paint`, `warnings` (e.g. paper grain, which the image editor paints without). Then `paint_stroke` with that tool. |
+| `set_brush_preset` | Paint with a brush from the brush library: `id` from `list_brush_presets` (the image host lists only what it can paint: pencils, pastels, charcoal, crayon, chalk, markers, ink pens, ballpoint, gel pen, fineliner, the airbrush, the Mixer Brush, erasers). Sets the paint tool it needs (`brush`, `mixer` for a Mixer Brush, `eraser`), its brush and mixer settings, a brush's own gradient, and its default colour as the foreground (`keepColour` keeps yours; `colorScheme` picks the side of a light / dark colour). Refuses wet, thick, particle, sticker and light brushes with the reason. Returns `tool`, `brush`, `mixer`, `paint`, `warnings` (e.g. paper grain, which the image editor paints without). Then `paint_stroke` with that tool. |
 | `get_mixer_brush` | Read-only. The Mixer Brush settings and what it carries (`reservoir` #rrggbb or null, `amount` left 0..1, `pickup` #rrggbb or null). Call it before a mixer stroke with `loadEachStroke: false`. |
 | `load_mixer_brush` | Fill the Mixer Brush reservoir with `color` (default the foreground), amount 1; keeps the pickup. View state, not an undo step. Use before strokes with `loadEachStroke: false`. Returns the load. |
 | `clean_mixer_brush` | Empty the Mixer Brush pickup well (`emptyReservoir: true` also drops the loaded paint, so it only smears). View state, not an undo step. Returns the load. |

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

@@ -11,6 +11,9 @@ seed: its grain is a height map (peaks and valleys) that grain-responsive brushe
 is never part of a layer. Coordinates are document pixels, (0, 0) top-left, y down. See
 `pixerate-agent-tools` for errors, namespacing and batching.
 
+- **Brush colours.** Choosing a brush with a default colour (highlighter yellow, ballpoint
+  blue, chalk light or dark for the colour scheme) makes it the paint colour, unless the colour is
+  locked (`set_color` `locked`). Set the colour after choosing the brush, or lock it first.
 - **Brushes** come from the shared brush library (`pixerate-brushes`: `list_brush_presets`,
   `create_brush`, `preview_brush`…) and are made of facets: a tip (size, hardness, spacing, angle,
   roundness, opacity, flow, blend), dynamics (pressure, tilt, velocity, jitter, a **rotation**
@@ -101,58 +104,32 @@ the pitfalls, and uses the tools below.
 
 ## Best practices
 
-- **Big to small, dark to light (or light to dark), one decision per layer.** Name layers by
-  purpose ("Underpainting", "Shadows", "Line"). Lower a layer's `opacity` instead of repainting.
-- **Pressure is your value control** on grainy media: points with `pressure` 0.2..0.4 give
-  texture-catching, broken marks; 0.8..1 fills the grain. Vary pressure along a stroke (swell in
-  the middle, lighten at the ends) for natural marks.
-- **Give points a time `t`** (milliseconds, about 8..16 ms apart for natural speed) when using an
-  ink or brush pen: velocity dynamics thin fast strokes. Without `t` there is no velocity effect.
-- **Tilt** (`altitude` near 0.3..0.6 radians with an `azimuth`) turns a pencil into broad side
-  shading; upright points draw a fine line.
-- **Space points** about a third of the brush size apart or closer; the brush fills in dabs
-  between them. Long smooth curves need more points than straight lines.
-- **Use `rotation: "stroke"`** for flat tips (pastel, charcoal, chisel marker) so the mark turns
-  with the path; `fixed` for calligraphic nibs.
+- **Big to small, dark to light (or light to dark), one decision per layer.** Name layers by purpose ("Underpainting", "Shadows", "Line"). Lower a layer's `opacity` instead of repainting.
+- **Pressure is your value control** on grainy media: points with `pressure` 0.2..0.4 give texture-catching, broken marks; 0.8..1 fills the grain. Vary pressure along a stroke (swell in the middle, lighten at the ends) for natural marks.
+- **Give points a time `t`** (milliseconds, about 8..16 ms apart for natural speed) when using an ink or brush pen: velocity dynamics thin fast strokes. Without `t` there is no velocity effect.
+- **Tilt** (`altitude` near 0.3..0.6 radians with an `azimuth`) turns a pencil into broad side shading; upright points draw a fine line.
+- **Space points** about a third of the brush size apart or closer; the brush fills in dabs between them. Long smooth curves need more points than straight lines.
+- **Use `rotation: "stroke"`** for flat tips (pastel, charcoal, chisel marker) so the mark turns with the path; `fixed` for calligraphic nibs.
 - **Blending tools**:
-  - `blender`: `strength` 0.3..0.6 for soft transitions, `distance` 0.2..0.5 (fraction of the
-    tip) for how far colours travel. Keep `mixing: "pigment"` for painterly blends; `rgb`
-    blends like a soft blur. Work along an edge in short strokes rather than over everything.
-  - `smudge`: `length` near 0.9 drags paint far (long streaks), 0.5 short pushes; `strength`
-    0.5..0.8. `mixing: "pigment"` (the `wet-smudge` preset) smears colours into each other like
-    wet paint.
+  - `blender`: `strength` 0.3..0.6 for soft transitions, `distance` 0.2..0.5 (fraction of the tip) for how far colours travel. Keep `mixing: "pigment"` for painterly blends; `rgb` blends like a soft blur. Work along an edge in short strokes rather than over everything.
+  - `smudge`: `length` near 0.9 drags paint far (long streaks), 0.5 short pushes; `strength` 0.5..0.8. `mixing: "pigment"` (the `wet-smudge` preset) smears colours into each other like wet paint.
   - Mixer Brush: blend with flow 0.3..0.6; at full flow it paints only its own colour.
-- **Pick-up and mix ratios**: `pickup` 0.3..0.7 with `mix` 0.4..0.7 gives a brush that drags
-  the colours it crosses into its own; `dirty: true` keeps them for the next stroke (wipe with
+- **Pick-up and mix ratios**: `pickup` 0.3..0.7 with `mix` 0.4..0.7 gives a brush that drags the colours it crosses into its own; `dirty: true` keeps them for the next stroke (wipe with
   `clean_mixer_brush`). Keep `pickup` 0 for clean, predictable colour.
-- **Multi-colour**: give 2..8 `colors` (or none for the paint and secondary colours). `tip` mode
-  with a flat tip and `rotation: "stroke"` paints ribbons; `softness` 0.3..0.7 keeps the stripes
-  readable. `dab` mode with `order: "sequence"` and `length` 5..20 walks through a palette;
+- **Multi-colour**: give 2..8 `colors` (or none for the paint and secondary colours). `tip` mode with a flat tip and `rotation: "stroke"` paints ribbons; `softness` 0.3..0.7 keeps the stripes readable. `dab` mode with `order: "sequence"` and `length` 5..20 walks through a palette;
   `random` for foliage and confetti.
-- **Pigment for paint, multiply for markers**: tip `blend: "pigment"` mixes subtractively on the
-  canvas; `multiply` darkens where marker strokes overlap. Pigment layers are written as Normal
-  to PSD (the export warns).
+- **Pigment for paint, multiply for markers**: tip `blend: "pigment"` mixes subtractively on the canvas; `multiply` darkens where marker strokes overlap. Pigment layers are written as Normal to PSD (the export warns).
 - **Painterly layer modes do the glazing for you** (`update_layer` `blend`, or a brush tip):
-  - `watercolor`: the layer is a transparent wash. Washes multiply wavelength by wavelength, so
-    each glaze darkens and blue over yellow makes green. White is clear: paint glazes on a
-    layer over the underpainting, at opacity 0.4..0.8.
-  - `tint`: recolours what is below (its hue and chroma) and keeps its lightness, gently near
-    white and black. Use it to warm or cool a whole passage.
-  - `highlight`: adds coloured light that rolls off towards white instead of clipping. Use it
-    for glints and glow; black does nothing.
-  - `shadow`: shades as if light were blocked, coloured by the layer (paint shadows in a cool
-    blue-violet), never crushing to black. White does nothing.
-
-  PSD has none of them: `export_psd` writes the nearest standard mode (watercolor and shadow
-  as Multiply, tint as Color, highlight as Screen) and warns; the merged image stays exact.
-- **Grow the canvas instead of starting big** with `extend_canvas` (pixels per side; nothing
-  painted moves relative to anything else). Adding `left` or `top` shifts every coordinate you
-  hold by (+left, +top): re-read `list_layers` or use the returned `rect`. Dry wet paint first.
+  - `watercolor`: the layer is a transparent wash. Washes multiply wavelength by wavelength, so each glaze darkens and blue over yellow makes green. White is clear: paint glazes on a layer over the underpainting, at opacity 0.4..0.8.
+  - `tint`: recolours what is below (its hue and chroma) and keeps its lightness, gently near white and black. Use it to warm or cool a whole passage.
+  - `highlight`: adds coloured light that rolls off towards white instead of clipping. Use it for glints and glow; black does nothing.
+  - `shadow`: shades as if light were blocked, coloured by the layer (paint shadows in a cool blue-violet), never crushing to black. White does nothing.
+
+  PSD has none of them: `export_psd` writes the nearest standard mode (watercolor and shadow as Multiply, tint as Color, highlight as Screen) and warns; the merged image stays exact.
+- **Grow the canvas instead of starting big** with `extend_canvas` (pixels per side; nothing painted moves relative to anything else). Adding `left` or `top` shifts every coordinate you hold by (+left, +top): re-read `list_layers` or use the returned `rect`. Dry wet paint first.
   `set_canvas` only crops or grows at the bottom-right.
-- **Save brushes you build** in the brush library: `create_brush` with `basedOn` and the facets
-  you changed (or `get_brush` then `create_brush` with its `brush`), and share them with
-  `export_brushes` / `import_brushes`. A saved brush shows in every editor that shares the
-  library; `set_brush` its id to paint with it.
+- **Save brushes you build** in the brush library: `create_brush` with `basedOn` and the facets you changed (or `get_brush` then `create_brush` with its `brush`), and share them with
+  `export_brushes` / `import_brushes`. A saved brush shows in every editor that shares the library; `set_brush` its id to paint with it.
 
 Which facet sets which engine setting: [references/brush-facets.md](references/brush-facets.md).
 
@@ -272,6 +249,17 @@ is a canvas coordinate: read [references/canvas-hosted.md](references/canvas-hos
 | `get_paper` | Read every setting of the current paper (pattern, seed, scale, tiling, depth, shading, dry and wet tuning, and `metallic`, `backlight`, `backlightColor` when set). |
 | `set_paper` | Change the paper: `preset`, then any of `color`, `depth` (0..1), `scale` (0.25..8), `seed` (another sheet), `pattern`, `tiling`, `shading`, `dry` / `wet` tuning (`contrast` 0..3, `invert`), `metallic`, `backlight` (0..1, light from behind: glazes glow, opaque paint blocks; preset `stained-glass`) and `backlightColor`. Affects new strokes' grain and how the paper shows; strokes already painted keep their pixels. Returns the paper. |
 
+### Suggesting paint
+
+Contributing while the user paints: suggest, don't paint. Read [references/painting-alongside.md](references/painting-alongside.md).
+
+| Tool | Use |
+| --- | --- |
+| `propose_paint` | Suggest paint as a ghost the user accepts or dismisses: `title`, `rationale`, `ops` (`stroke` with points and a dry brush, `wash` over its layer, `echo` of stroke ids moved / turned / scaled / repeated) and where its new layer goes (`place` top, bottom or above `layerId`). Returns the proposal id, the ghost's `bounds` and the strokes it echoes. Use it for contributions the user didn't ask for. |
+| `list_paint_proposals` | Read the pending paint proposals: id, title, rationale, who proposed it, op kinds, placement, bounds, the strokes it echoes and any since removed (`missing`), and whether accepting is allowed. Call before accepting or rejecting. |
+| `accept_paint_proposal` | Paint a pending proposal on a new layer as one undo step recorded as the proposer's (`proposalId`). Only when the user said yes. Returns the layer id, stroke ids and undo step name. Refuses when a stroke it echoes is gone. |
+| `reject_paint_proposal` | Dismiss a pending proposal (`proposalId`); nothing changes. Use it to withdraw a suggestion that no longer fits. Returns the id and title. |
+
 ### Layers
 
 | Tool | Use |
@@ -307,7 +295,7 @@ Listing, saving, sharing and previewing brushes are the brush library's tools (`
 | Tool | Use |
 | --- | --- |
 | `mix_colors` | Predict a mix: `colors` with `weight` parts (and optional tinting `strength`), `model` `pigment` (default, Kubelka-Munk: what pigment blends, the Mixer Brush, pigment blending tools and the pad do) or `rgb` (what normal blending and rgb mixing do). Returns `mixed` by the model plus `pigment` and `rgbLerp` for comparison. Changes nothing. Use it to choose stroke colours. |
-| `set_color` | Set the default paint `color` (and `secondaryColor`); back to one colour after gradient paint or effect paint. |
+| `set_color` | Set the default paint `color` (and `secondaryColor`); back to one colour after gradient paint or effect paint. `locked: true` keeps it when you choose a brush with a default colour (by default choosing the highlighter makes your colour its yellow). Returns both colours and `locked`. |
 | `set_paint` | Set the paint: one colour, or gradient paint (`stops`, `space`, `map`, `softness`; see Gradient paint). Ends effect paint. Errors say what is wrong (unsorted stops, a bad mapping). Returns `paint`, `color`, `secondaryColor`. |
 | `pick_color` | Read the colour at `x`, `y`: of the painting with its paper, or of one layer (with alpha). |
 | `get_mixer_brush` | Read what the brush carries: the Mixer Brush `reservoir` and `amount` left, and `pickup` (paint picked up, kept by dirty brushes). |

package/skills/pixerate-paint-editor/references/painting-alongside.md

@@ -0,0 +1,19 @@
+# Painting alongside the user
+
+When the user is painting and you contribute on your own initiative, **suggest, don't paint**:
+`propose_paint` shows your idea as a ghost over the canvas, and the user accepts or dismisses it.
+Accepted, it lands on a new layer of its own as one undo step recorded as yours, and the user's
+active layer stays theirs. Paint directly only when asked to.
+
+- **Play to what agents do well**: a `wash` (a warm ground with `place: "bottom"`, a glaze over a
+  passage), an `echo` of the user's own strokes (grass along the horizon, rain, hatching, a
+  repeated motif: `list_strokes` for the ids, then `dx` / `dy` / `rotate` / `scale` / `repeat`),
+  or a few deliberate `stroke`s. Not a stroke-by-stroke rendering of a subject.
+- **Small and complementary.** One idea per proposal, with a `title` that says what it adds and a
+  `rationale` that says why it fits what the user just painted.
+- **Dry brushes only** (dab, particle, bristle or mixer without pickup). Suggestions are previewed
+  and painted on their own layer, which wet paint, thick paint and pickup can't do.
+- **Withdraw what no longer fits** with `reject_paint_proposal`; an echo whose strokes the user
+  removed can't be accepted (`missing` in `list_paint_proposals`).
+
+The tools are `propose_paint`, `list_paint_proposals`, `accept_paint_proposal` and `reject_paint_proposal` (see SKILL.md, Suggesting paint).

package/skills/pixerate-vector/SKILL.md

@@ -373,7 +373,7 @@ contents whole while you work, without losing the mask.
 
 | Command | Use it to |
 | --- | --- |
-| `vector.listBrushes` | List the brushes a brushstroke can use: the dry presets (pencils, pastels, charcoal, markers, inks), then saved brushes from the brush library the vector profile admits, with their sizes and `builtin`. Brushes it refuses (wet, thick, particles, stickers, tools) are refused by `vector.addBrushstroke` with the reason. A saved brush is kept in the layer, so the document renders without the library. |
+| `vector.listBrushes` | List the brushes a brushstroke can use: the dry presets (pencils, pastels, charcoal, crayon, chalk, markers, inks, ballpoint, gel pen, fineliner), then saved brushes from the brush library the vector profile admits, with their sizes and `builtin`. Brushes it refuses (wet, thick, particles, stickers, tools) are refused by `vector.addBrushstroke` with the reason. A saved brush is kept in the layer, so the document renders without the library. |
 | `vector.addBrushstroke` | Paint paths with a brush along their outline (`brushId`, `size`, `pressure` profile such as [0.2, 1, 0.2] for a taper, `color`): sketchy, hand-drawn or inked lines that stay editable. Pass a `seed` (any integer) so the brush gets its character, the seeded jitter and paper grain that make pencil, pastel and charcoal look real; `paper` picks the grain (`{ pattern, seed, scale, depth }`) or `null` turns it off. Returns the stroke stacks. |
 | `vector.setBrushstroke` | Change brushstroke layer `index` of path `id`: brush, size, pressure, colour, opacity, `seed` (a new seed is a new take on the same stroke; null: plain dabs) and `paper` (replaced whole; null: no grain; {}: the default sanded paper). Remove it with `vector.removeStroke`. |