@pixerate/editor 0.251.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/dist/tools/skill-evals.d.cts

@@ -20,7 +20,7 @@ export interface SkillEvalCheck extends SkillEvalToolCall {
 }
 export interface SkillEval {
     prompt: string;
-    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture | CanvasEvalFixture;
+    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture | CanvasEvalFixture | BrushesEvalFixture;
     checks: SkillEvalCheck[];
     solution: SkillEvalToolCall[];
 }
@@ -116,6 +116,13 @@ export interface CanvasEvalFixture {
     /** Tool calls that prepare the canvas (components, instances), run in order. */
     setup?: SkillEvalToolCall[];
 }
+export interface BrushesEvalFixture {
+    editor: 'brushes';
+    /** The host profile the brush library tools run for: paint (default), image, canvas or vector. */
+    host?: 'paint' | 'image' | 'canvas' | 'vector';
+    /** Tool calls that prepare the library (saved or imported brushes), run in order. */
+    setup?: SkillEvalToolCall[];
+}
 /** One eval file of a skill. */
 export interface SkillEvalFile {
     skill: string;

package/dist/tools/skill-evals.d.ts

@@ -20,7 +20,7 @@ export interface SkillEvalCheck extends SkillEvalToolCall {
 }
 export interface SkillEval {
     prompt: string;
-    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture | CanvasEvalFixture;
+    fixture: SpreadsheetEvalFixture | ImageEvalFixture | VectorEvalFixture | PaintEvalFixture | VideoEvalFixture | ChartEvalFixture | DiagramEvalFixture | RichTextEvalFixture | AnimationEvalFixture | GenerationEvalFixture | EffectEvalFixture | CanvasEvalFixture | BrushesEvalFixture;
     checks: SkillEvalCheck[];
     solution: SkillEvalToolCall[];
 }
@@ -116,6 +116,13 @@ export interface CanvasEvalFixture {
     /** Tool calls that prepare the canvas (components, instances), run in order. */
     setup?: SkillEvalToolCall[];
 }
+export interface BrushesEvalFixture {
+    editor: 'brushes';
+    /** The host profile the brush library tools run for: paint (default), image, canvas or vector. */
+    host?: 'paint' | 'image' | 'canvas' | 'vector';
+    /** Tool calls that prepare the library (saved or imported brushes), run in order. */
+    setup?: SkillEvalToolCall[];
+}
 /** One eval file of a skill. */
 export interface SkillEvalFile {
     skill: string;

package/package.json

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

package/skills/README.md

@@ -30,6 +30,7 @@ model and its general practice.
 | [`pixerate-color`](pixerate-color/SKILL.md) | Colour inspection, WCAG accessibility and contrast optimization, CVD simulation, palette audits, harmonies, and OKLab/OKLCH blends. |
 | [`pixerate-typography`](pixerate-typography/SKILL.md) | Fonts and fallback stacks, font loading, modular type scales and hierarchies, fluid sizes, readability and type-aware contrast audits, text segmentation, the font picker. |
 | [`pixerate-stickers`](pixerate-stickers/SKILL.md) | Sticker libraries: finding stickers by ref (`provider:id`), categories, tags, tintable art and licences, for the editors that spray or place them. |
+| [`pixerate-brushes`](pixerate-brushes/SKILL.md) | The shared brush library: brushes made of facets (medium, tip, marks, dynamics, behaviour, light, motion, colour), the presets, host profiles for paint, image, canvas and vector, and creating, checking and sharing brushes. |
 
 ## Workflow skills
 
@@ -51,6 +52,7 @@ request like "clean up this export" finds it.
 | [`pixerate-paint-watercolour`](pixerate-paint-watercolour/SKILL.md) | Paint (`pixerate-paint-editor`) | Watercolour paper, light to dark with the paper's white kept, wet-in-wet and wet-on-dry washes, drying before glazing, steering the water. |
 | [`pixerate-paint-oil-impasto`](pixerate-paint-oil-impasto/SKILL.md) | Paint (`pixerate-paint-editor`) | A toned ground, thin block-in to thick paint, pigment mixing, impasto relief and its light. |
 | [`pixerate-paint-sketch-to-finish`](pixerate-paint-sketch-to-finish/SKILL.md) | Paint (`pixerate-paint-editor`) | Sketch, ink, flats under the lines, clipped shading and light, one named layer per pass. |
+| [`pixerate-brushes-design`](pixerate-brushes-design/SKILL.md) | Brushes (`pixerate-brushes`) | From a description to a saved brush: the nearest preset, only the facets that change, checked for the host that will use it, previewed. |
 | [`pixerate-video-social-cut`](pixerate-video-social-cut/SKILL.md) | Video (`pixerate-video-editor`) | Vertical or square reframes that fill the frame, the hook first, platform lengths, titles in the safe area. |
 | [`pixerate-video-colour-grade`](pixerate-video-colour-grade/SKILL.md) | Video (`pixerate-video-editor`) | Correct and match shots, then one look on an adjustment clip; LUTs at moderate strength with skin protected. |
 | [`pixerate-video-montage`](pixerate-video-montage/SKILL.md) | Video (`pixerate-video-editor`) | Selects on the beat, varied pacing, short transitions with handles, music under everything and a clean ending. |

package/skills/pixerate-brushes/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: pixerate-brushes
+description: How to find, describe, create, change, check and share brushes in the Pixerate brush library through list_brush_presets, describe_brush, create_brush, update_brush, duplicate_brush, remove_brush, check_brush, export_brushes, import_brushes and preview_brush - brushes made of facets (kind, medium and variety or tool, tip, marks, dynamics, behaviour, light, motion, colour), the built-in presets, and the host profiles that say what the paint editor, image editor, canvas and vector strokes can render. Use when asked to make, design, tweak, save, copy, delete, export, import or check a brush, find a brush for a medium (pencil, ink, watercolour, oil, airbrush, highlighter), or make a brush work in another editor.
+---
+
+# Brushes
+
+A brush is made of **facets** that say what it is and how it behaves, not which engine draws it.
+Only `id`, `name`, `kind` and `tip.shape` are required; every other field takes the default of
+the engine the facets pick, so a brush stores only what makes it what it is. The library holds the
+built-in presets (read-only) and the user's brushes, shared by every editor that paints.
+
+| Facet (field) | What it holds |
+| --- | --- |
+| 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). |
+| 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. |
+
+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.
+
+## Host profiles
+
+Each host renders a part of this. `check_brush` says what a host refuses (errors) and what it
+paints without (warnings), each with a fix; lists and writes use the current host.
+
+| Host | Renders |
+| --- | --- |
+| Paint editor (`paint`) | Everything. |
+| Image editor (`image`) | Dry dabs on round, flat and chisel tips, the Mixer Brush and the eraser; no wet or thick surface, particles, objects, light or motion. |
+| Canvas (`canvas`) | Dry dab brushes along a path (no tools, wet, thick, particles, objects or light); velocity is ignored. |
+| Vector strokes (`vector`) | As canvas, but light brushes paint as plain colour. |
+
+## Working method
+
+1. **Find the nearest brush.** `list_brush_presets` with `medium`, `variety`, `kind` or `text`.
+   It lists only what this host can render (`all: true` lists the rest with `renderable`).
+2. **Read it.** `describe_brush` for the full spec, the engine it resolves to and its check.
+3. **Make a brush.** `create_brush` with a new `id`, a `name`, `basedOn` the nearest preset and
+   only the facets that change (objects merge; lists replace). Read `problems` (values clamped or
+   dropped) and `warnings`. A brush the host can't render is refused and nothing is saved.
+4. **Look at it.** `preview_brush` when the host has a renderer; otherwise paint a test stroke
+   in the editor (`set_brush` with the new id, then `paint_stroke`).
+5. **Tune it.** `update_brush` with the facets to change, or `unset` to drop whole facets. It
+   returns the leaf paths `changed`. Built-in presets can't be changed: `duplicate_brush` first.
+6. **Share it.** `export_brushes` writes a library file; `import_brushes` adds one (version 1
+   files of the paint editor's older brushes are migrated). `check_brush` with `host` before
+   handing a brush to another editor.
+
+## Best practices
+
+- Start from the nearest preset and change two or three facets; a brush from nothing gets
+  engine defaults that rarely suit a medium.
+- Test on the paper and colour the brush will be used on: grain response and glazes look
+  different on smooth and rough paper.
+- Give light brushes dark paper, and give highlighters a `light.spill` radius of 0 so the
+  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
+  always paint their own (a rainbow marker).
+
+## 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`.
+- **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
+  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
+
+- `pixerate-brushes-design`: from a description ("a soft pink highlighter", "chalk for the
+  canvas") to a saved, checked brush.
+
+## Tool reference
+
+| 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`. |
+| `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`. |
+| `check_brush` | Check a brush (`id`, or an unsaved `brush` spec) for a `host` (paint, image, canvas, vector). Returns `ok`, `issues` (facet, severity, reason, fix) and, when refused, `degraded`. |
+| `export_brushes` | Library file (pixerate-brushes v2) of the saved brushes or the `ids` given. Returns `file`, for `import_brushes`. |
+| `import_brushes` | Add a library `file` (v2, v1 migrated, or a bare list): built-in ids and taken ids are skipped unless `overwrite`. Returns `added`, `replaced`, `skipped`, `problems`. |
+| `preview_brush` | Only when the host renders previews: a sample stroke with a brush (`id`, `width`, `height`, `color`) as an image. |

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

@@ -0,0 +1,88 @@
+---
+name: pixerate-brushes-design
+description: The brush design workflow in the Pixerate brush library - turning a description ("a soft pink highlighter", "chalk for canvas strokes", "make this brush work in the vector editor") into a saved brush, by picking the nearest preset, changing only the facets that matter, checking it against the host that will use it and previewing it. Use when asked to make, design, customise, adapt or port a brush, or when create_brush, check_brush or list_brush_presets are available. Load with pixerate-brushes, which lists every tool.
+metadata:
+  kind: workflow
+  reference: pixerate-brushes
+---
+
+# Designing a brush
+
+A brush is a preset with a few facets changed. The presets already hold good settings for each
+medium (pencil grain, ink velocity, watercolour water), so the fastest good brush starts from
+the nearest one and changes two or three facets: the colour, the tip, how it feels. What a brush
+may use depends on the editor that will paint with it: check it against that host before saving.
+
+This skill is the method. `pixerate-brushes` has the full tool reference.
+
+## Goal and quality bar
+
+- The brush is saved under a clear `id` and `name`, with a truthful `medium` and `variety`.
+- `check_brush` for the host it is for returns `ok: true`; any warnings are understood.
+- It differs from its base preset only where the request asks (`describe_brush` shows it).
+- Built-in presets are untouched.
+
+## Inputs to confirm
+
+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).
+- **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).
+
+## Working method
+
+1. **Find the base.** `list_brush_presets` with `medium` or `variety`, or `text`. Pick the
+   closest; `describe_brush` it to read its facets.
+   **Check:** the base's `check` is `ok` for the target host (or `check_brush` with `host`).
+2. **Create from it.** `create_brush` with a new `id`, `name`, `basedOn` and only the facets
+   that change: `variety` for what it is now, `colour.default` / `colour.palette`, `tip`
+   (size, hardness, roundness, angle), `dynamics`, `behaviour.grain`.
+   **Check:** `problems` is empty or understood; nothing refused.
+3. **Check it for the host.** `check_brush` with `id` and `host`. A refusal names the facet and
+   fix; its `degraded` brush is a good next spec.
+   **Check:** `ok: true`.
+4. **Look at it.** `preview_brush` when available; then `update_brush` to tune (each call
+   returns the paths `changed`).
+   **Check:** `describe_brush` shows the intended facets.
+
+## Decision table
+
+| 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. |
+| 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 change to a built-in | `duplicate_brush`, then `update_brush` the copy. |
+
+## Recipes
+
+**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 } }`.
+
+**Port a wet brush to vector.** `check_brush` `{ id, host: "vector" }`; `create_brush` from the
+`degraded` brush with `id` `<id>-vector`; `check_brush` again.
+
+## Pitfalls
+
+- **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.
+- **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.
+
+## Tools used
+
+- `list_brush_presets`, `describe_brush`: find the base preset and read its facets.
+- `create_brush`, `update_brush`, `duplicate_brush`: make and tune the brush.
+- `check_brush`: prove it works for the host, and get a degraded spec when it doesn't.
+- `preview_brush`: look at a sample stroke when the host renders previews.

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

@@ -0,0 +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.",
+	"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 } } } } }
+	],
+	"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" } }
+	]
+}

package/skills/pixerate-brushes-design/evals/pink-highlighter.json

@@ -0,0 +1,15 @@
+{
+	"prompt": "Make me a pink highlighter brush, saved as pink-highlighter, that behaves like the built-in highlighter but starts out pink.",
+	"fixture": { "editor": "brushes" },
+	"checks": [
+		{ "why": "a saved brush, not a built-in", "tool": "describe_brush", "args": { "id": "pink-highlighter" }, "expect": { "builtin": false, "check": { "ok": true } } },
+		{ "why": "still a highlighter: multiply chisel ink with no spill", "tool": "describe_brush", "args": { "id": "pink-highlighter" }, "expect": { "brush": { "medium": "ink", "variety": "highlighter", "tip": { "shape": "chisel", "blend": "multiply" }, "light": { "spill": { "radius": 0 } } } } },
+		{ "why": "it starts out pink", "tool": "describe_brush", "args": { "id": "pink-highlighter" }, "expect": { "brush": { "colour": { "default": { "$expr": "(([r, g, b]) => r > 200 && b > 120 && g < r - 60)([1, 3, 5].map((i) => parseInt(v.slice(i, i + 2), 16)))" } } } } },
+		{ "why": "the built-in highlighter is untouched", "tool": "describe_brush", "args": { "id": "highlighter" }, "expect": { "brush": { "colour": { "default": "#fff200" } } } }
+	],
+	"solution": [
+		{ "tool": "list_brush_presets", "args": { "variety": "highlighter" } },
+		{ "tool": "create_brush", "args": { "id": "pink-highlighter", "name": "Pink highlighter", "basedOn": "highlighter", "colour": { "default": "#ff6ec7" } } },
+		{ "tool": "check_brush", "args": { "id": "pink-highlighter" } }
+	]
+}