@pixerate/editor 0.252.0 → 0.253.0

package/dist/paint-editor/serialize.d.cts

@@ -9,11 +9,14 @@
  * as new assets keyed by layer id without breaking older readers (see `PaintDocumentExtensions`).
  */
 import { type ImageEditorAssetStore, type SerializedLayer } from '../image-editor/layers/serialize.cjs';
-import { type RecordedStroke } from './strokes.cjs';
+import { strokeToJSON } from './strokes.cjs';
 import { type PaintDocumentState } from './document.cjs';
 import { type PaperSettings } from './paper.cjs';
 export declare const PAINT_FORMAT: "pixerate-paint";
-export declare const PAINT_SCHEMA_VERSION: 1;
+/** 2: recorded strokes keep facet brushes (version 1 documents, with flat engine brushes, still load). */
+export declare const PAINT_SCHEMA_VERSION: 2;
+/** A recorded stroke as a document stores it (`strokeToJSON`). */
+export type SerializedStroke = ReturnType<typeof strokeToJSON>;
 /** Where a host keeps layer PNGs outside the JSON (the image editor's asset store contract). */
 export type PaintAssetStore = ImageEditorAssetStore;
 /**
@@ -34,8 +37,8 @@ export interface SerializedPaintDocument {
     /** Asset id → PNG data URL (or an external reference). */
     assets: Record<string, string>;
     activeLayerId: string | null;
-    /** Recorded strokes (strokes are data), oldest first; missing when saved without them. */
-    strokes?: RecordedStroke[];
+    /** Recorded strokes (strokes are data), oldest first, each brush a facet `Brush`; missing when saved without them. */
+    strokes?: SerializedStroke[];
     /** Everything else (document-level state of later phases), written back as read. */
     [extension: string]: unknown;
 }

package/dist/paint-editor/serialize.d.ts

@@ -9,11 +9,14 @@
  * as new assets keyed by layer id without breaking older readers (see `PaintDocumentExtensions`).
  */
 import { type ImageEditorAssetStore, type SerializedLayer } from '../image-editor/layers/serialize.js';
-import { type RecordedStroke } from './strokes.js';
+import { strokeToJSON } from './strokes.js';
 import { type PaintDocumentState } from './document.js';
 import { type PaperSettings } from './paper.js';
 export declare const PAINT_FORMAT: "pixerate-paint";
-export declare const PAINT_SCHEMA_VERSION: 1;
+/** 2: recorded strokes keep facet brushes (version 1 documents, with flat engine brushes, still load). */
+export declare const PAINT_SCHEMA_VERSION: 2;
+/** A recorded stroke as a document stores it (`strokeToJSON`). */
+export type SerializedStroke = ReturnType<typeof strokeToJSON>;
 /** Where a host keeps layer PNGs outside the JSON (the image editor's asset store contract). */
 export type PaintAssetStore = ImageEditorAssetStore;
 /**
@@ -34,8 +37,8 @@ export interface SerializedPaintDocument {
     /** Asset id → PNG data URL (or an external reference). */
     assets: Record<string, string>;
     activeLayerId: string | null;
-    /** Recorded strokes (strokes are data), oldest first; missing when saved without them. */
-    strokes?: RecordedStroke[];
+    /** Recorded strokes (strokes are data), oldest first, each brush a facet `Brush`; missing when saved without them. */
+    strokes?: SerializedStroke[];
     /** Everything else (document-level state of later phases), written back as read. */
     [extension: string]: unknown;
 }

package/dist/paint-editor/sticker-tools.d.cts

@@ -1,5 +1,5 @@
 /**
- * Agent tools for stickers: stamps sprayed with a sticker brush (`paint_stroke`, list_brushes
+ * Agent tools for stickers: stamps sprayed with a sticker brush (`paint_stroke`, list_brush_presets
  * category sticker) stay objects on their layer, which these tools list, move, turn, resize,
  * recolour, reorder and delete, find by point (`sticker_at`), and places new ones exactly (`add_stickers`). Each change is one undo step and redraws the layer.
  */

package/dist/paint-editor/sticker-tools.d.ts

@@ -1,5 +1,5 @@
 /**
- * Agent tools for stickers: stamps sprayed with a sticker brush (`paint_stroke`, list_brushes
+ * Agent tools for stickers: stamps sprayed with a sticker brush (`paint_stroke`, list_brush_presets
  * category sticker) stay objects on their layer, which these tools list, move, turn, resize,
  * recolour, reorder and delete, find by point (`sticker_at`), and places new ones exactly (`add_stickers`). Each change is one undo step and redraws the layer.
  */

package/dist/paint-editor/strokes.d.cts

@@ -2,8 +2,13 @@
  * Strokes as data. Every committed stroke is recorded with the brush, colour, raw pen samples,
  * jitter seed and symmetry copies it was painted with, so it replays to the same pixels, and can
  * be replayed moved, scaled, rotated, recoloured or with another brush (`replay_strokes`).
+ *
+ * In memory a stroke keeps its brush as the engine painted it. Saved, the brush is a facet brush
+ * (`strokeToJSON`, documents of version 2); strokes saved with the flat engine brush (version 1)
+ * still read, and both replay to the same pixels.
  */
 import { type PaintBrush } from './brushes.cjs';
+import type { Brush } from '../brushes/types.cjs';
 import type { PenPoint, StrokeCopy } from './engine.cjs';
 import type { MixerLoad } from '../paint/exchange.cjs';
 import { type Stencil } from './stencils.cjs';
@@ -46,7 +51,11 @@ export declare function invertAffine(m: Affine): Affine;
 export declare function mapPenPoint(m: Affine, p: PenPoint): PenPoint;
 /** An affine copy as the engine's `StrokeCopy`. */
 export declare function affineCopy(m: Affine): StrokeCopy;
-/** A recorded stroke read from JSON, or `null` when it is not one. */
+/** A recorded stroke as saved: plain JSON with its brush as a facet brush. */
+export declare function strokeToJSON(stroke: RecordedStroke): Omit<RecordedStroke, 'brush'> & {
+    brush: Brush;
+};
+/** A recorded stroke read from JSON (its brush version 1 or 2), or `null` when it is not one. */
 export declare function normalizeBrushStroke(raw: unknown): RecordedStroke | null;
 /** The bounding box of a stroke's points. */
 export declare function strokeBounds(points: readonly PenPoint[]): {

package/dist/paint-editor/strokes.d.ts

@@ -2,8 +2,13 @@
  * Strokes as data. Every committed stroke is recorded with the brush, colour, raw pen samples,
  * jitter seed and symmetry copies it was painted with, so it replays to the same pixels, and can
  * be replayed moved, scaled, rotated, recoloured or with another brush (`replay_strokes`).
+ *
+ * In memory a stroke keeps its brush as the engine painted it. Saved, the brush is a facet brush
+ * (`strokeToJSON`, documents of version 2); strokes saved with the flat engine brush (version 1)
+ * still read, and both replay to the same pixels.
  */
 import { type PaintBrush } from './brushes.js';
+import type { Brush } from '../brushes/types.js';
 import type { PenPoint, StrokeCopy } from './engine.js';
 import type { MixerLoad } from '../paint/exchange.js';
 import { type Stencil } from './stencils.js';
@@ -46,7 +51,11 @@ export declare function invertAffine(m: Affine): Affine;
 export declare function mapPenPoint(m: Affine, p: PenPoint): PenPoint;
 /** An affine copy as the engine's `StrokeCopy`. */
 export declare function affineCopy(m: Affine): StrokeCopy;
-/** A recorded stroke read from JSON, or `null` when it is not one. */
+/** A recorded stroke as saved: plain JSON with its brush as a facet brush. */
+export declare function strokeToJSON(stroke: RecordedStroke): Omit<RecordedStroke, 'brush'> & {
+    brush: Brush;
+};
+/** A recorded stroke read from JSON (its brush version 1 or 2), or `null` when it is not one. */
 export declare function normalizeBrushStroke(raw: unknown): RecordedStroke | null;
 /** The bounding box of a stroke's points. */
 export declare function strokeBounds(points: readonly PenPoint[]): {

package/dist/paint-editor/tools.d.cts

@@ -1,7 +1,7 @@
 /**
  * Agent tools for the paint editor (`createPaintEditorToolProvider`). Strict schemas, every
  * argument described, all four annotations. Each write is one undo step (or editor state, said so)
- * and returns what it changed; ids come from the read tools (`list_layers`, `list_brushes`,
+ * and returns what it changed; ids come from the read tools (`list_layers`, the brush library's `list_brush_presets`,
  * `list_papers`, `list_strokes`).
  */
 import type { AgentToolProvider } from '../tools/registry.cjs';

package/dist/paint-editor/tools.d.ts

@@ -1,7 +1,7 @@
 /**
  * Agent tools for the paint editor (`createPaintEditorToolProvider`). Strict schemas, every
  * argument described, all four annotations. Each write is one undo step (or editor state, said so)
- * and returns what it changed; ids come from the read tools (`list_layers`, `list_brushes`,
+ * and returns what it changed; ids come from the read tools (`list_layers`, the brush library's `list_brush_presets`,
  * `list_papers`, `list_strokes`).
  */
 import type { AgentToolProvider } from '../tools/registry.js';

package/dist/paint-editor/ui.d.cts

@@ -10,7 +10,7 @@
  */
 import type { MixerLoad } from '../paint/exchange.cjs';
 import { type BlendModeInfo } from '../raster/blend.cjs';
-import type { ImpastoTool, PaintBrush, PaintBrushInput, WetMediumKind, WetTool } from './brushes.cjs';
+import type { ImpastoTool, WetMediumKind, WetTool } from './brushes.cjs';
 import type { PaintEditorController } from './controller.cjs';
 import type { PenPoint } from './engine.cjs';
 import { type Point2 } from './guides.cjs';
@@ -133,15 +133,8 @@ export declare function guideOverlay(controller: PaintEditorController, drag?: {
     to: Point2;
     kind: GuideOverlayKind;
 }>;
-/** One slider of a panel: a path into the brush (or paper) settings. */
-export interface SliderControl {
-    path: string;
-    label: string;
-    min: number;
-    max: number;
-    step: number;
-}
-export declare const BRUSH_SLIDERS: readonly SliderControl[];
+export { BRUSH_SLIDERS, brushEngineControls, multiColorSliders, patchBrushValue, type BrushEngineControls, type SliderControl } from './brush-controls.cjs';
+import type { SliderControl } from './brush-controls.cjs';
 export declare const PAPER_SLIDERS: readonly SliderControl[];
 /** Reads `a.b` from an object. */
 export declare function readPath(obj: unknown, path: string): number;
@@ -174,47 +167,6 @@ export interface BlendMenuGroup {
  */
 export declare const BLEND_MENU_GROUPS: readonly BlendMenuGroup[];
 /** The engine-specific part of the brush panel: which sliders and toggles the active brush has. */
-export interface BrushEngineControls {
-    /** Section heading. */
-    title: string;
-    sliders: readonly SliderControl[];
-    /** Where the RGB / pigment choice is stored, or `null` when the engine has none. */
-    mixingPath: 'behavior.mixing' | 'blender.mixing' | 'smudge.mixing' | null;
-    /** The dirty-brush toggle (`behavior.dirty`). */
-    dirty: boolean;
-    /** The multi-colour controls (`behavior.multicolor`; the panels show the brush gradient, `brush.paint`, instead). */
-    multicolor: boolean;
-    /** Load / Clean buttons and a swatch of what the brush carries. */
-    load: boolean;
-    /** The wet tool menu (`wet.tool`, `WET_TOOLS`) and medium menu (`wet.medium`, `WET_MEDIA`). */
-    wetTool?: boolean;
-    /** The impasto tool menu (`impasto.tool`, `IMPASTO_TOOLS`). */
-    impastoTool?: boolean;
-    /**
-     * The particle menus: kind and render (`particle.kind`, `particle.render`), ribbon pairs
-     * (`particle.ribbonPairs`), and the textured-dot stamps, order and rotation
-     * (`particle.dotTextures` up to `MAX_DOT_TEXTURES` of `STAMP_KINDS`, `dotTextureOrder`, `dotRotation`).
-     */
-    particleMenus?: boolean;
-    /** The sticker picker for the brush's stickers (`sticker.stamps`, refs from the sticker library; `toggleStickerRef`). */
-    stickerStamps?: boolean;
-    /** Light paint: the "light follows pressure" toggle (`light.pressure`); the Light slider is in `sliders`. */
-    light?: boolean;
-}
-/**
- * The controls the active brush's engine adds to the brush panel (`null` for the eraser):
- * blender strength and blend distance; smudge strength and length; the Mixer Brush's pick-up,
- * mix and load; a dab brush's pick-up and mix ratios. Every engine but the eraser has an RGB /
- * pigment choice; dab and mixer brushes also have the dirty and multi-colour controls. Pick-up
- * and mix always go through `behavior`, which keeps a Mixer Brush's `mixer` block in sync.
- */
-export declare function brushEngineControls(brush: Pick<PaintBrush, 'engine'> & {
-    wet?: PaintBrush['wet'];
-}): BrushEngineControls | null;
-/** The multi-colour sliders for a mode: softness, and dabs per colour in `dab` mode. */
-export declare function multiColorSliders(mode: string): readonly SliderControl[];
-/** A brush change setting `path` (e.g. `smudge.mixing`, `behavior.dirty`) to any value, keeping the rest of its block. */
-export declare function patchBrushValue(brush: PaintBrush, path: string, value: unknown): PaintBrushInput;
 /** What the brush carries (picked-up paint, else loaded paint) as #rrggbb, or `null` when it is clean and empty. */
 export declare function brushLoadColor(load: MixerLoad): string | null;
 /** Sample sizes (square, in pad pixels) for picking from the mixing pad. */

package/dist/paint-editor/ui.d.ts

@@ -10,7 +10,7 @@
  */
 import type { MixerLoad } from '../paint/exchange.js';
 import { type BlendModeInfo } from '../raster/blend.js';
-import type { ImpastoTool, PaintBrush, PaintBrushInput, WetMediumKind, WetTool } from './brushes.js';
+import type { ImpastoTool, WetMediumKind, WetTool } from './brushes.js';
 import type { PaintEditorController } from './controller.js';
 import type { PenPoint } from './engine.js';
 import { type Point2 } from './guides.js';
@@ -133,15 +133,8 @@ export declare function guideOverlay(controller: PaintEditorController, drag?: {
     to: Point2;
     kind: GuideOverlayKind;
 }>;
-/** One slider of a panel: a path into the brush (or paper) settings. */
-export interface SliderControl {
-    path: string;
-    label: string;
-    min: number;
-    max: number;
-    step: number;
-}
-export declare const BRUSH_SLIDERS: readonly SliderControl[];
+export { BRUSH_SLIDERS, brushEngineControls, multiColorSliders, patchBrushValue, type BrushEngineControls, type SliderControl } from './brush-controls.js';
+import type { SliderControl } from './brush-controls.js';
 export declare const PAPER_SLIDERS: readonly SliderControl[];
 /** Reads `a.b` from an object. */
 export declare function readPath(obj: unknown, path: string): number;
@@ -174,47 +167,6 @@ export interface BlendMenuGroup {
  */
 export declare const BLEND_MENU_GROUPS: readonly BlendMenuGroup[];
 /** The engine-specific part of the brush panel: which sliders and toggles the active brush has. */
-export interface BrushEngineControls {
-    /** Section heading. */
-    title: string;
-    sliders: readonly SliderControl[];
-    /** Where the RGB / pigment choice is stored, or `null` when the engine has none. */
-    mixingPath: 'behavior.mixing' | 'blender.mixing' | 'smudge.mixing' | null;
-    /** The dirty-brush toggle (`behavior.dirty`). */
-    dirty: boolean;
-    /** The multi-colour controls (`behavior.multicolor`; the panels show the brush gradient, `brush.paint`, instead). */
-    multicolor: boolean;
-    /** Load / Clean buttons and a swatch of what the brush carries. */
-    load: boolean;
-    /** The wet tool menu (`wet.tool`, `WET_TOOLS`) and medium menu (`wet.medium`, `WET_MEDIA`). */
-    wetTool?: boolean;
-    /** The impasto tool menu (`impasto.tool`, `IMPASTO_TOOLS`). */
-    impastoTool?: boolean;
-    /**
-     * The particle menus: kind and render (`particle.kind`, `particle.render`), ribbon pairs
-     * (`particle.ribbonPairs`), and the textured-dot stamps, order and rotation
-     * (`particle.dotTextures` up to `MAX_DOT_TEXTURES` of `STAMP_KINDS`, `dotTextureOrder`, `dotRotation`).
-     */
-    particleMenus?: boolean;
-    /** The sticker picker for the brush's stickers (`sticker.stamps`, refs from the sticker library; `toggleStickerRef`). */
-    stickerStamps?: boolean;
-    /** Light paint: the "light follows pressure" toggle (`light.pressure`); the Light slider is in `sliders`. */
-    light?: boolean;
-}
-/**
- * The controls the active brush's engine adds to the brush panel (`null` for the eraser):
- * blender strength and blend distance; smudge strength and length; the Mixer Brush's pick-up,
- * mix and load; a dab brush's pick-up and mix ratios. Every engine but the eraser has an RGB /
- * pigment choice; dab and mixer brushes also have the dirty and multi-colour controls. Pick-up
- * and mix always go through `behavior`, which keeps a Mixer Brush's `mixer` block in sync.
- */
-export declare function brushEngineControls(brush: Pick<PaintBrush, 'engine'> & {
-    wet?: PaintBrush['wet'];
-}): BrushEngineControls | null;
-/** The multi-colour sliders for a mode: softness, and dabs per colour in `dab` mode. */
-export declare function multiColorSliders(mode: string): readonly SliderControl[];
-/** A brush change setting `path` (e.g. `smudge.mixing`, `behavior.dirty`) to any value, keeping the rest of its block. */
-export declare function patchBrushValue(brush: PaintBrush, path: string, value: unknown): PaintBrushInput;
 /** What the brush carries (picked-up paint, else loaded paint) as #rrggbb, or `null` when it is clean and empty. */
 export declare function brushLoadColor(load: MixerLoad): string | null;
 /** Sample sizes (square, in pad pixels) for picking from the mixing pad. */

package/dist/paint-editor/wet-tools.d.cts

@@ -1,6 +1,6 @@
 /**
  * Agent tools for wet media (watercolour and gouache on a simulated wet layer). Wet strokes are
- * painted with `paint_stroke` and a wet brush (`list_brushes` category `watercolor` or
+ * painted with `paint_stroke` and a wet brush (`list_brush_presets` variety `watercolor` or
  * `wet-tool`); these tools read and steer the wet paint. Every result says whether paint is still
  * wet. Settings (wet parameters, flow maps, tilt) are saved with the document but are not undo
  * steps; drying and wetting the paper are.

package/dist/paint-editor/wet-tools.d.ts

@@ -1,6 +1,6 @@
 /**
  * Agent tools for wet media (watercolour and gouache on a simulated wet layer). Wet strokes are
- * painted with `paint_stroke` and a wet brush (`list_brushes` category `watercolor` or
+ * painted with `paint_stroke` and a wet brush (`list_brush_presets` variety `watercolor` or
  * `wet-tool`); these tools read and steer the wet paint. Every result says whether paint is still
  * wet. Settings (wet parameters, flow maps, tilt) are saved with the document but are not undo
  * steps; drying and wetting the paper are.

package/package.json

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

package/skills/pixerate-brushes/SKILL.md

@@ -80,8 +80,10 @@ paints without (warnings), each with a fix; lists and writes use the current hos
   marks take any sticker ref from `find_stickers`.
 - **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's own brush tools** (`set_brush`, `save_brush`, its `export_brushes`)
-  still work on its brushes; this library's tools are namespaced apart.
+- **The paint editor paints from this library.** Its `set_brush` picks a brush by id here and
+  lays facets over it without saving; `create_brush` / `update_brush` store one. A paint host
+  registers these tools with its own preview (`createPaintBrushLibraryToolProvider`), so the
+  paint editor has no list, save, export, import or thumbnail tools of its own.
 
 ## Workflow skills
 
@@ -94,7 +96,7 @@ paints without (warnings), each with a fix; lists and writes use the current hos
 | --- | --- |
 | `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. Normalised and checked for this host; refused brushes save nothing. Returns `id`, `brush`, `engine`, `problems`, `warnings`. |
+| `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`. |
 | `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-paint-editor/SKILL.md

@@ -11,25 +11,27 @@ 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.
 
-- **Brushes** are library presets (`list_brushes`): a tip from the shared engine (size,
-  hardness, spacing, angle, roundness, opacity, flow, blend), a **grain** response, pen dynamics
-  (pressure, tilt, velocity, jitter), a **rotation** mode (`fixed`, `stroke`, `barrel`) and an
-  engine: `dab` (most media), `eraser`, `mixer` (the Mixer Brush: a reservoir of paint plus paint
+- **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**
+  mode `fixed`, `stroke` or `barrel`), behaviour (paper **grain** response, pick-up, wet or thick
+  surface), marks, light, motion and colour. `set_brush` chooses one and lays facet changes over
+  it; `get_brush` reads it with the engine it paints with: `dab` (most media), `eraser`, `mixer` (the Mixer Brush: a reservoir of paint plus paint
   it picks up), `blender` (mixes the colours under and near the tip) or `smudge` (drags paint
   along the stroke), `wet` (watercolour, gouache, oil and the wet tools, below), `impasto`
   (thick paint with relief and material, below), `particle` (procedural particle brushes),
   `bristle` (a tuft of bristles) or `sticker` (sprays editable stickers).
-- **Wet media** (`engine: "wet"`, categories `watercolor` and `wet-tool`): a stroke lays water
+- **Wet media** (engine `wet`: `behaviour.surface` `wet`, and the wet tools; categories `watercolor` and `wet-tool`): a stroke lays water
   and pigment on the layer's **wet layer**, a fluid simulation that keeps running after the
   stroke: the water spreads until its edge is pinned by the paper, carries pigment out to the
   rim as it dries (edge darkening), drops pigment into the paper's valleys (granulation), pushes
   pigment back where new water flows in (blooms), bleeds between touching wet colours and runs
   downhill on a tilted canvas. Paint stays wet until it dries by itself (a few thousand steps)
   or `dry_paint` dries it; a dried wash is fixed, so the next wash **glazes** over it. A wet
-  brush's `wet.tool` is `paint`, `water`, `dry`, `blow`, `blend`, `smudge` or `blot`; `water`,
-  `pigment` (concentration), `body` (0 transparent watercolour .. 1 opaque gouache), `strength`
-  and `rewet` set it up. Every result says whether paint is still wet (`wet` / `stillWet`).
-- **Behaviour** (`behavior`, dab and mixer brushes) is how a brush treats paint already on the
+  brush paints, or is a tool (`tool` `water`, `dryer`, `blow`, `blot`, `wet-blend`, `wet-drag`);
+  `behaviour.wet` `water`, `pigment` (concentration), `body` (0 transparent watercolour .. 1
+  opaque gouache) and `rewet`, and `behaviour.strength`, set it up. Every result says whether paint is still wet (`wet` / `stillWet`).
+- **Behaviour** (`behaviour.exchange`, dab and mixer brushes) is how a brush treats paint already on the
   canvas: a **pick-up ratio** (how much paint each dab lifts and carries), a **mix ratio** (how
   much of the carried paint goes into what it lays down), **dirty** (keep the carried colour into
   the next stroke) and **multi-colour** (`tip`: several colours side by side across the tip;
@@ -147,8 +149,12 @@ the pitfalls, and uses the tools below.
   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** (`set_brush` then `save_brush`), and share them with
-  `export_brushes` / `import_brushes`.
+- **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).
 
 ## Wet media
 
@@ -178,12 +184,12 @@ inner glow, shadows, stroke, bevel, satin and overlays, as in the image editor
 
 - **Particle brushes** (category `procedural`; ribbons, flames and bokeh are in `light`):
   `hair-strands`, `spring-ink`, `orbit-curls`, `flow-fur`, `sparkle-dust`, `bead-trail`. Tune
-  with `particle`: kind (string, spring, orbit, flow, elastic, fuzzy), render (dot, line,
-  sequence, ribbon), waves and textured dots; read [references/particle-brushes.md](references/particle-brushes.md).
+  with `marks` (kind `particles`): physics (string, spring, orbit, flow, elastic, fuzzy), render
+  (dot, line, sequence, ribbon), waves and textured dots (`tip.stamps`); read [references/particle-brushes.md](references/particle-brushes.md).
   Draw slowly and with varying direction: the particles react to movement.
 - **Bristle brushes** (category `bristle`): `bristle-round`, `bristle-flat`, `dry-brush`. Every
   bristle draws its own line: press harder to splay the tuft, tilt to flatten it; soft bristles
-  bend into curves at turns; a low `bristle.load` runs dry into broken streaks.
+  bend into curves at turns; a low `tip.bristle.load` runs dry into broken streaks.
 - **Sticker spray** (category `sticker`): stickers by ref (`editor:star`, `editor:leaf`… or any
   from the host's library: `find_stickers`; tintable ones take the paint colour) sprayed onto an
   **empty layer**, each staying an object:
@@ -289,16 +295,12 @@ is a canvas coordinate: read [references/canvas-hosted.md](references/canvas-hos
 
 ### Brushes
 
+Listing, saving, sharing and previewing brushes are the brush library's tools (`pixerate-brushes`), registered by the host next to these.
+
 | Tool | Use |
 | --- | --- |
-| `list_brushes` | Read the library (built-in and saved): id, name, category, engine, size, grain response, rotation, `wetCapable`, `pickup`, `dirty`, `gradient` (has its own gradient paint), `multicolor` mode, `builtin`; plus the active brush id and whether it is edited. |
-| `get_brush` | Read every setting of a brush, or of the active brush as edited (no `id`), including `paint` (its own gradient, or null) and `strokePaint` (what its next stroke paints). Read before changing a brush you did not build. |
-| `set_brush` | Choose the active brush (`id`) and / or change it: `tip` (size px, hardness, spacing, angle, roundness, opacity, flow, smoothing, pressureSize, pressureOpacity, blend), `grain`, `pressureSmoothing`, `rotation`, `dynamics` (minSize, pressureFlow, tiltSize, tiltRoundness, tiltOpacity, velocitySize, velocityOpacity, jitters, scatter), `engine`, `mixer`, `loadsColor`, `behavior` (pickup, mix, dirty, mixing; multicolor is the older form of `paint`), `paint` (the brush's own gradient, or null for the editor's paint), `blender` (strength, distance, mixing), `smudge` (strength, length, mixing). Editor state. Returns the brush. |
-| `save_brush` | Store the active brush in the user library under `id` (lowercase, digits, dashes) and `name`. Built-in ids are refused. |
-| `remove_brush` | Delete a user brush. Built-in brushes cannot be removed. |
-| `export_brushes` | Get a brush library file (JSON) of `ids`, or of every user brush. |
-| `import_brushes` | Add the brushes of a library file to the user library; taken ids are skipped unless `replace`. Returns `added`, `skipped`, `problems`. |
-| `render_brush_thumbnail` | See what a brush does: a PNG of a test stroke (S-curve, pressure swelling and fading) on the current paper. Cheaper than painting and undoing. |
+| `get_brush` | Read a brush as facets (`brush`), or the active brush as edited (no `id`), with the `engine` and `category` it paints with, `builtin` (an unchanged preset) and `strokePaint` (what its next stroke paints). Read before changing a brush you did not build. |
+| `set_brush` | Choose the active brush (`id`, from `list_brush_presets`) and / or lay facets over it: `tip`, `marks`, `dynamics`, `behaviour`, `light`, `motion`, `colour` (objects merge, lists replace; marks of another kind replace the marks), `unset` facets to drop. Editor state, not saved: `create_brush` stores a brush. Returns `brush` (facets), `engine` and `problems` (values clamped). The old flat fields (`particle`, `impasto`, `behavior`…) are refused. |
 
 ### Colour
 
@@ -329,10 +331,10 @@ is a canvas coordinate: read [references/canvas-hosted.md](references/canvas-hos
 
 | Tool | Use |
 | --- | --- |
-| `paint_stroke` | Paint one stroke through `points` (document px; `pressure` 0..1, `t` ms, `tiltX` / `tiltY` or `altitude` / `azimuth`, `twist`) with `brushId` (default the active brush), optional per-stroke `brush` changes, `color` 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. |
+| `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. |
 | `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. |
 | `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. |
-| `update_stroke` | Change a stroke on a stroke layer: `brushId` (keeps its size), `brush` settings, `color`, `paint` (null drops a gradient), `seed`. Redraws exactly. One undo step. Returns the stroke and the changed `bounds`. |
+| `update_stroke` | Change a stroke on a stroke layer: `brushId` (keeps its size), `brush` facets (as `set_brush` takes), `color`, `paint` (null drops a gradient), `seed`. Redraws exactly. One undo step. Returns the stroke and the changed `bounds`. |
 | `edit_stroke_points` | Replace a stroke's `points`, or `transform` it (`dx`, `dy`, `scale`, `rotate`, `flipX`, about its centre or `origin`). One undo step. Returns the stroke with its points and the changed `bounds`. |
 | `reorder_stroke` | Move a stroke to `index` in its stroke layer (0 = bottom). One undo step. Returns the order. |
 | `remove_strokes` | Delete strokes from stroke layers (their eraser). One undo step. Returns the ids and `bounds`. |

package/skills/pixerate-paint-editor/references/brush-facets.md

@@ -0,0 +1,30 @@
+# Brush facets in the paint editor
+
+`set_brush`, `paint_stroke` `brush` and `update_stroke` `brush` take the brush library's facets
+(see `pixerate-brushes`). `get_brush` returns a brush as facets plus the `engine` it paints with.
+The engine's flat settings (`particle`, `impasto`, `behavior`, `paint`…) are not arguments any
+more; this is where each one went.
+
+| Engine setting | Facet |
+| --- | --- |
+| Tip size, hardness, spacing, angle, roundness, opacity, flow, blend | `tip` |
+| Smoothing, pressure, tilt, velocity, jitter, scatter, rotation | `dynamics` |
+| Grain, pick-up and mix (behavior), blender and smudge strength | `behaviour` (`grain`, `exchange`, `strength`, `distance`, `length`, `mixing`) |
+| Mixer Brush reservoir | `behaviour.exchange.reservoir` (`load`, `refill`, `loadsColour`) |
+| Wet engine (medium, water, pigment, body…) | `behaviour.surface` `wet` and `behaviour.wet` |
+| Impasto (thickness, gloss, metallic, rim, clarity…) | `behaviour.surface` `thick` and `behaviour.thick` |
+| Particle settings | `marks` `{ kind: 'particles', physics, render, count… }`; textured dots are `tip.stamps` on a `stamp` tip |
+| Sticker spray | `marks` `{ kind: 'objects', density… }` and `tip.stamps` (sticker refs) |
+| Bristles | `tip.shape` `bristle` and `tip.bristle` |
+| A brush's own gradient (paint) | `colour.default` (a gradient); `unset: ['colour']` drops it |
+| Light | `light` (`amount`, `pressure`) |
+
+## Examples
+
+- A softer, bigger airbrush for one stroke: `paint_stroke` `{ brushId: "airbrush", brush: { tip:
+  { size: 80, hardness: 0 } }, points }`.
+- A dirty round that picks up more: `set_brush` `{ id: "dirty-round", behaviour: { exchange: {
+  pickup: 0.5, mix: 0.6 } } }`.
+- Elastic ribbons with star dots: `set_brush` `{ id: "spring-ink", tip: { shape: "stamp", stamps:
+  ["editor:star"] }, marks: { kind: "particles", physics: "elastic", render: "ribbon" } }`.
+- A brush's own gradient off again: `set_brush` `{ unset: ["colour"] }`.

package/skills/pixerate-paint-editor/references/gradient-paint.md

@@ -4,7 +4,7 @@ Paint that changes colour as the stroke goes: give a gradient where a colour wou
 
 1. **`set_paint`** with `{ type: "gradient", stops, map }` makes it the paint for every following
    stroke (`set_color` goes back to one colour); `paint_stroke` `paint` overrides it for one stroke;
-   a brush can carry its own (`set_brush` `paint`, presets `gradient-round`, `pressure-ombre`,
+   a brush can carry its own (`set_brush` `colour.default`, presets `gradient-round`, `pressure-ombre`,
    `rainbow-marker`, `gradient-wash`).
 2. **Choose the mapping by what the stroke should do**: `distance` (default, 300 px then
    `mirror` back) for "drag it out" colour; `pressure` for light-to-heavy shading in one stroke;

package/skills/pixerate-paint-editor/references/light-paint.md

@@ -18,8 +18,8 @@ particle ones are tuned in [particle-brushes.md](particle-brushes.md)).
   `strength` 0..2 (default 1). It is not an undo step and repaints nothing; it shows the
   painting as committed, so a stroke's spill appears when the stroke ends. It spills onto
   everything below, paper included, so it reads best on dark paper (`set_paper` colour).
-- **Glassy beads** (impasto): `impasto.rim` makes a bead's light stronger at its edges, where its
-  surface turns away (backlit glass); `impasto.clarity` lets the middle of a bead show the layers
+- **Glassy beads** (impasto): `behaviour.thick.rim` (engine `impasto.rim`) makes a bead's light stronger at its edges, where its
+  surface turns away (backlit glass); `behaviour.thick.clarity` lets the middle of a bead show the layers
   below while its edges stay solid. `glow-gel` uses both: paint loops with a distance-mapped
   gradient (`set_paint`) for glowing glass tubes.
 - **Crossings.** Beads on one layer fuse where they cross (their heights combine by maximum), so

package/skills/pixerate-paint-editor/references/oils.md

@@ -11,7 +11,7 @@
   (azimuth, elevation, relief). Tools: `impasto-brush` (bristle ridges), `paint-tube` (blobs),
   `palette-knife` (scrapes the relief flat and smears the paint), `paint-roller` (flat stippled
   band), `gloop-pen` (glossy bead), `metallic-paint` (highlights in the paint's colour).
-- **Loading and thinner**: `wet.load` / `impasto.load` below 1 make the brush run out along a
+- **Loading and thinner**: `behaviour.wet.load` / `behaviour.thick.load` below 1 make the brush run out along a
   long stroke (dry-brush ends); `thinner` makes paint flatter and more transparent.
 - **Light** is a view of the relief, not paint: move it (`set_lighting`) to read the texture
   (a low elevation, 15..30°, shows brushwork best) and pick the final light before exporting.

package/skills/pixerate-paint-editor/references/particle-brushes.md

@@ -1,12 +1,15 @@
 # Particle brushes
 
-Particle brushes (`engine: 'particle'`) make marks with a small simulation driven by the pen. They
+Particle brushes (`marks` kind `particles`; engine `particle`) make marks with a small simulation driven by the pen. They
 are seeded and stepped by distance, so the same points and `seed` paint the same pixels and
 replays are exact. Their marks are ordinary coverage: opacity, blend modes, locks, stencils,
 symmetry, gradient paint, effect paint and light paint all work as for a dab brush. Change them
-with `set_brush` `particle` (missing fields keep their values); `get_brush` returns them all.
+with `set_brush` `marks` `{ kind: 'particles', … }` (missing fields keep their values; the
+engine's `particle.kind` is `marks.physics`, its textured dots `tip.stamps` on a `stamp` tip,
+`dotTextureOrder` / `dotRotation` are `marks.stampOrder` / `marks.stampRotation`, `waveSpeed` is
+`motion.waveSpeed`); `get_brush` returns them all.
 
-## Kinds (`particle.kind`)
+## Kinds (`marks.physics`)
 
 | Kind | Motion | Good for |
 | --- | --- | --- |
@@ -21,7 +24,7 @@ with `set_brush` `particle` (missing fields keep their values); `get_brush` retu
 `elastic` and `fuzzy` damp their strands enough to stay together at any setting; a `string` with
 low damping and high stiffness can still swing wildly, which is part of its look.
 
-## Renders (`particle.render`)
+## Renders (`marks.render`)
 
 - `dot`: a mark at every step; `line`: each particle's path as a line; `sequence`: beads spaced
   by `interval` along each path.
@@ -59,7 +62,7 @@ light paint; see [light-paint.md](light-paint.md) for spill and the light-painti
 
 ## Best practice
 
-- Check a setting with `render_brush_thumbnail` before painting with it.
+- Check a setting with `preview_brush` (the brush library) before painting with it.
 - Change one thing at a time: kind for the motion, render for the look, then waves and textures.
 - Many `flow` particles with long `life` in a `ribbon` are slow (every pair of live particles is
   a band each step): keep `count` × `life` low (count 3..6, life ≤ 0.4).

package/skills/pixerate-paint-oil-impasto/SKILL.md

@@ -67,7 +67,7 @@ This skill is the method. `pixerate-paint-editor` has the full tool reference an
 | Blobs of paint straight from the tube | `paint-tube` |
 | A glossy bead or line | `gloop-pen` |
 | A glowing, glassy bead (a neon or glass tube) | `glow-gel` (light paint with rim and clarity, on dark paper; one loop per layer where they cross) |
-| Dry, broken strokes over texture | `dry-brush`, or a lower `impasto.load` |
+| Dry, broken strokes over texture | `dry-brush`, or a lower `behaviour.thick.load` |
 | A metallic highlight | `metallic-paint` |
 | Paint that stays exactly as laid | `set_instant_dry` on |
 

package/skills/pixerate-stickers/SKILL.md

@@ -19,7 +19,7 @@ none, it is the editor's own stamps (`editorStickers()`: `editor:dot`, `editor:s
 2. **Check.** `describe_sticker` when the choice matters: its licence (and the attribution line
    it asks for), dominant colours, variants and outline.
 3. **Use.** Pass refs to the editor that places them: in the paint editor, a sticker brush
-   (`set_brush` `sticker.stamps`, then `paint_stroke`) sprays them and `add_stickers` places
+   (`set_brush` `tip.stamps`, then `paint_stroke`) sprays them and `add_stickers` places
    them exactly. In the vector, image and canvas editors, `insert_sticker` puts one in (`x`,
    `y` centre, `width`): vector, a group of editable paths; image, a pixel layer; canvas, a
    shape node from its outline in one colour. A provider's art loads before it is drawn.

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

@@ -300,7 +300,7 @@ and every write tool is refused with the reason.
 
 | Tool | Use it to |
 | --- | --- |
-| `search_effects` | Find effects: words in `query`, filtered by `kind`, `category`, `use` (filter, overlay for clips; transition; generator, title) or `accepts: ["path"]` (effects that draw along a path you give). Returns ids, names, uses, whether they are transparent or loop, and their length. Camera moves (`kind` camera) are listed but go on clips with `set_clip_camera_move`, not `apply_effect`. Call `describe_effect` next. |
+| `search_effects` | Find effects: words in `query`, filtered by `kind`, `category`, `use` (filter, overlay for clips; transition; generator, title) or `accepts: ["path"]` (effects that draw along a path you give). Returns ids, names, uses, whether they are transparent or loop, and their length. Camera moves (`kind` camera) are listed but go on clips with `set_clip_camera_move`, not `apply_effect`. Timing effects (`kind` timing: speed changes, reverses, freezes, echoes) are listed but cannot be applied to clips yet (`appliesHere` false). Call `describe_effect` next. |
 | `describe_effect` | Read one effect's `controls` (a strict JSON Schema: names, types, ranges, units), `defaults`, `presets` and `inputs`, and whether it `appliesHere` (as a clip effect). Use the names and ranges for values. |
 | `list_applied_effects` | See the effects in the project per clip, in order: clip effects (`fx1`...), an effect clip's own effect (`generator`) and an effect transition (`transition`), with their saved values and `available` (false when the provider lacks it: drawn as a placeholder). |
 | `apply_effect` | Add a filter or overlay effect to a clip's stack (`target` clip id, `effect`, `values`, `index`, `enabled`, `opacity`). Effects run in order on the clip's picture before its grade and placement. Returns the effect's new id and the clip's effects. |