@pixerate/editor 0.251.0 → 0.252.0

package/dist/brushes/library.d.cts

@@ -0,0 +1,104 @@
+/**
+ * The brush library: the built-in presets plus the user's brushes, kept on any `StorageAdapter`
+ * (`createMemoryStorage`, `createLocalStorageAdapter`, `createIndexedDbAdapter`,
+ * `createOpfsAdapter`) or, without one, in memory. One library shared by every editor makes a
+ * brush saved in one show up in all of them.
+ *
+ * The user's brushes are stored as one `pixerate-brushes` version 2 file under one key. Library
+ * files of version 1 (the paint editor's flat brushes) still import: each brush is migrated.
+ */
+import type { StorageAdapter } from '../persistence/storage.cjs';
+import { type BrushHostProfile } from './profiles.cjs';
+import type { Brush, BrushKind, BrushMedium, BrushTool } from './types.cjs';
+/** The JSON file a brush library exports to and imports from. */
+export interface BrushLibraryFile {
+    format: 'pixerate-brushes';
+    version: 2;
+    brushes: Brush[];
+}
+export type BrushLibraryErrorCode = 'unknown_brush' | 'builtin' | 'exists' | 'invalid';
+/** A refusal; the message says what to do instead. */
+export declare class BrushLibraryError extends Error {
+    readonly code: BrushLibraryErrorCode;
+    constructor(code: BrushLibraryErrorCode, message: string);
+}
+export interface BrushLibraryEntry {
+    brush: Brush;
+    /** A built-in preset: it can be duplicated but not changed or removed. */
+    builtin: boolean;
+}
+export interface BrushFilter {
+    kind?: BrushKind;
+    medium?: BrushMedium;
+    variety?: string;
+    tool?: BrushTool;
+    /** Has this tag. */
+    tag?: string;
+    /** Words in the id, name, description, variety or tags (case-insensitive; every word must match). */
+    text?: string;
+    /** Only built-in presets or only the user's brushes. */
+    source?: 'builtin' | 'user';
+    /** Only brushes this host can render (`checkBrush` has no errors). */
+    profile?: BrushHostProfile;
+}
+export interface SaveBrushResult {
+    /** The brush as stored (normalised). */
+    brush: Brush;
+    /** What normalising changed. */
+    problems: string[];
+    /** It replaced a user brush of the same id. */
+    replaced: boolean;
+}
+export interface ImportBrushesResult {
+    added: string[];
+    replaced: string[];
+    skipped: string[];
+    problems: string[];
+}
+export interface BrushLibraryOptions {
+    /** Where the user's brushes are kept (default: memory only, gone on reload). */
+    storage?: Pick<StorageAdapter, 'get' | 'set'>;
+    /** Storage key prefix (default `pixerate.brushes`). */
+    namespace?: string;
+    /** The built-in presets (default `BRUSH_PRESETS`). */
+    presets?: readonly Brush[];
+}
+export interface BrushLibrary {
+    /** Built-in presets first (in library order), then the user's brushes (in the order saved). */
+    list(filter?: BrushFilter): Promise<BrushLibraryEntry[]>;
+    get(id: string): Promise<BrushLibraryEntry | null>;
+    isBuiltin(id: string): boolean;
+    /**
+     * Stores a user brush (normalised first). Refuses a built-in id and, without `overwrite`, an
+     * id already taken.
+     */
+    save(brush: unknown, options?: {
+        overwrite?: boolean;
+    }): Promise<SaveBrushResult>;
+    /** Removes a user brush; refuses a built-in one. False when there was no such brush. */
+    remove(id: string): Promise<boolean>;
+    /** Copies any brush (built-ins included) to a new user brush: `id` default `<id>-copy`, `-copy-2`…; `name` default `<name> copy`. */
+    duplicate(id: string, options?: {
+        id?: string;
+        name?: string;
+    }): Promise<Brush>;
+    /** A library file of the user's brushes, or of the given ids (built-ins included). */
+    exportFile(ids?: readonly string[]): Promise<BrushLibraryFile>;
+    /** Adds the brushes of a library file (version 1 or 2, or a bare array). Built-in ids are skipped; taken ids too, unless `overwrite`. */
+    importFile(raw: unknown, options?: {
+        overwrite?: boolean;
+    }): Promise<ImportBrushesResult>;
+    /** Called after every change. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Brushes read from a library file: `{ format: 'pixerate-brushes', version: 1 | 2, brushes }` or
+ * a bare array. Version 1 brushes are migrated (`migrateBrushV1`); every brush is normalised.
+ * Brushes without a valid id or name are skipped, and everything fixed or skipped is reported
+ * in `problems`.
+ */
+export declare function parseBrushLibrary(raw: unknown, problems?: string[]): Brush[];
+/** A brush library over `options.storage` (see the module comment). */
+export declare function createBrushLibrary(options?: BrushLibraryOptions): BrushLibrary;
+/** "Closest: a, b. " for an unknown id (shared prefix or substring), or "" when nothing is near. */
+export declare function closest(id: string, ids: readonly string[], max?: number): string;

package/dist/brushes/library.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The brush library: the built-in presets plus the user's brushes, kept on any `StorageAdapter`
+ * (`createMemoryStorage`, `createLocalStorageAdapter`, `createIndexedDbAdapter`,
+ * `createOpfsAdapter`) or, without one, in memory. One library shared by every editor makes a
+ * brush saved in one show up in all of them.
+ *
+ * The user's brushes are stored as one `pixerate-brushes` version 2 file under one key. Library
+ * files of version 1 (the paint editor's flat brushes) still import: each brush is migrated.
+ */
+import type { StorageAdapter } from '../persistence/storage.js';
+import { type BrushHostProfile } from './profiles.js';
+import type { Brush, BrushKind, BrushMedium, BrushTool } from './types.js';
+/** The JSON file a brush library exports to and imports from. */
+export interface BrushLibraryFile {
+    format: 'pixerate-brushes';
+    version: 2;
+    brushes: Brush[];
+}
+export type BrushLibraryErrorCode = 'unknown_brush' | 'builtin' | 'exists' | 'invalid';
+/** A refusal; the message says what to do instead. */
+export declare class BrushLibraryError extends Error {
+    readonly code: BrushLibraryErrorCode;
+    constructor(code: BrushLibraryErrorCode, message: string);
+}
+export interface BrushLibraryEntry {
+    brush: Brush;
+    /** A built-in preset: it can be duplicated but not changed or removed. */
+    builtin: boolean;
+}
+export interface BrushFilter {
+    kind?: BrushKind;
+    medium?: BrushMedium;
+    variety?: string;
+    tool?: BrushTool;
+    /** Has this tag. */
+    tag?: string;
+    /** Words in the id, name, description, variety or tags (case-insensitive; every word must match). */
+    text?: string;
+    /** Only built-in presets or only the user's brushes. */
+    source?: 'builtin' | 'user';
+    /** Only brushes this host can render (`checkBrush` has no errors). */
+    profile?: BrushHostProfile;
+}
+export interface SaveBrushResult {
+    /** The brush as stored (normalised). */
+    brush: Brush;
+    /** What normalising changed. */
+    problems: string[];
+    /** It replaced a user brush of the same id. */
+    replaced: boolean;
+}
+export interface ImportBrushesResult {
+    added: string[];
+    replaced: string[];
+    skipped: string[];
+    problems: string[];
+}
+export interface BrushLibraryOptions {
+    /** Where the user's brushes are kept (default: memory only, gone on reload). */
+    storage?: Pick<StorageAdapter, 'get' | 'set'>;
+    /** Storage key prefix (default `pixerate.brushes`). */
+    namespace?: string;
+    /** The built-in presets (default `BRUSH_PRESETS`). */
+    presets?: readonly Brush[];
+}
+export interface BrushLibrary {
+    /** Built-in presets first (in library order), then the user's brushes (in the order saved). */
+    list(filter?: BrushFilter): Promise<BrushLibraryEntry[]>;
+    get(id: string): Promise<BrushLibraryEntry | null>;
+    isBuiltin(id: string): boolean;
+    /**
+     * Stores a user brush (normalised first). Refuses a built-in id and, without `overwrite`, an
+     * id already taken.
+     */
+    save(brush: unknown, options?: {
+        overwrite?: boolean;
+    }): Promise<SaveBrushResult>;
+    /** Removes a user brush; refuses a built-in one. False when there was no such brush. */
+    remove(id: string): Promise<boolean>;
+    /** Copies any brush (built-ins included) to a new user brush: `id` default `<id>-copy`, `-copy-2`…; `name` default `<name> copy`. */
+    duplicate(id: string, options?: {
+        id?: string;
+        name?: string;
+    }): Promise<Brush>;
+    /** A library file of the user's brushes, or of the given ids (built-ins included). */
+    exportFile(ids?: readonly string[]): Promise<BrushLibraryFile>;
+    /** Adds the brushes of a library file (version 1 or 2, or a bare array). Built-in ids are skipped; taken ids too, unless `overwrite`. */
+    importFile(raw: unknown, options?: {
+        overwrite?: boolean;
+    }): Promise<ImportBrushesResult>;
+    /** Called after every change. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+}
+/**
+ * Brushes read from a library file: `{ format: 'pixerate-brushes', version: 1 | 2, brushes }` or
+ * a bare array. Version 1 brushes are migrated (`migrateBrushV1`); every brush is normalised.
+ * Brushes without a valid id or name are skipped, and everything fixed or skipped is reported
+ * in `problems`.
+ */
+export declare function parseBrushLibrary(raw: unknown, problems?: string[]): Brush[];
+/** A brush library over `options.storage` (see the module comment). */
+export declare function createBrushLibrary(options?: BrushLibraryOptions): BrushLibrary;
+/** "Closest: a, b. " for an unknown id (shared prefix or substring), or "" when nothing is near. */
+export declare function closest(id: string, ids: readonly string[], max?: number): string;

package/dist/brushes/profiles.d.cts

@@ -0,0 +1,85 @@
+/**
+ * Host capability profiles: what a host (the paint editor, the image editor, brushed canvas and
+ * vector strokes, later Swift) can render. `checkBrush` explains each refusal with a fix,
+ * `listPresets` filters a library down to what the host can use, and `degrade` strips the facets
+ * a host can't render and says what it dropped.
+ *
+ * A capability is `full` (rendered), `ignored` (the brush is accepted but the host paints without
+ * it: a warning) or `none` (the brush is refused: an error).
+ */
+import { type Brush, type BrushKind, type BrushMarksKind, type BrushPaint, type BrushSurface, type BrushTipShape, type BrushTool } from './types.cjs';
+export type BrushSupport = 'full' | 'ignored' | 'none';
+/** What a colour is: a solid colour, a light / dark pair, a gradient or effect paint. */
+export type BrushColourKind = 'solid' | 'dual' | 'gradient' | 'effect';
+export interface BrushHostProfile {
+    /** `paint`, `image`, `canvas`, `vector`… */
+    id: string;
+    name: string;
+    kinds: readonly BrushKind[];
+    /** Tools the host has (for `kind: 'tool'`). */
+    tools: readonly BrushTool[];
+    tipShapes: readonly BrushTipShape[];
+    marks: readonly BrushMarksKind[];
+    surfaces: readonly BrushSurface[];
+    /** Picking paint up and mixing it in (`behaviour.exchange` pickup, mix, dirty). */
+    exchange: BrushSupport;
+    /** The Mixer Brush (`behaviour.exchange.reservoir`). */
+    reservoir: BrushSupport;
+    /** Paper grain response (`behaviour.grain`). */
+    grain: BrushSupport;
+    light: BrushSupport;
+    motion: BrushSupport;
+    /** Colour kinds the brush's default colour may be (palette entries of other kinds are warned about). */
+    colours: readonly BrushColourKind[];
+    /** Velocity dynamics (needs timed input). */
+    velocity: BrushSupport;
+    /** Tilt dynamics (needs pen tilt). */
+    tilt: BrushSupport;
+}
+export interface BrushIssue {
+    /** The facet path the issue is about, e.g. `tip.shape`, `light`, `behaviour.exchange.reservoir`. */
+    facet: string;
+    /** `error`: the host can't render the brush; `warning`: it renders it without this setting. */
+    severity: 'error' | 'warning';
+    reason: string;
+    fix: string;
+}
+export interface BrushCheck {
+    /** No errors (warnings may remain). */
+    ok: boolean;
+    issues: BrushIssue[];
+}
+/** The paint editor: every facet. */
+export declare const PAINT_PROFILE: BrushHostProfile;
+/** The image editor's brush: dry dabs on pixels, its Mixer Brush and the eraser. */
+export declare const IMAGE_PROFILE: BrushHostProfile;
+/**
+ * Brushed canvas strokes: dry dab brushes along a path. Light paint needs the paint editor's
+ * light channel (glow and spill), which canvas strokes don't have, so it is refused.
+ */
+export declare const CANVAS_PROFILE: BrushHostProfile;
+/** Vector brushstrokes: dry dab brushes along a path; light brushes paint as plain colour. */
+export declare const VECTOR_PROFILE: BrushHostProfile;
+/** The built-in profiles by id. */
+export declare const BRUSH_HOST_PROFILES: Readonly<Record<string, BrushHostProfile>>;
+/** What kind of colour a `BrushPaint` is. */
+export declare function brushColourKind(paint: BrushPaint): BrushColourKind;
+/** What a brush needs from a host, and what the host does about it. */
+export declare function checkBrush(brush: Brush, profile: BrushHostProfile): BrushCheck;
+/** The presets (default: the built-in ones) a host can render, in library order. */
+export declare function listPresets(profile: BrushHostProfile, presets?: readonly Brush[]): Brush[];
+export interface DegradedBrush {
+    /** The brush with what the host can't render stripped (a copy). */
+    brush: Brush;
+    /** The errors fixed by stripping a facet. */
+    dropped: BrushIssue[];
+    /** Errors that stripping cannot fix (an unsupported kind or tool): the host still refuses it. */
+    issues: BrushIssue[];
+}
+/**
+ * The brush the host can render: facets it refuses are removed (light, motion, a reservoir, a
+ * wet or thick surface, particle or object marks, bristle and stamp tips become round, an
+ * unsupported default colour), each reported in `dropped`. A tool the host lacks can't be
+ * stripped and stays in `issues`.
+ */
+export declare function degrade(brush: Brush, profile: BrushHostProfile): DegradedBrush;

package/dist/brushes/profiles.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Host capability profiles: what a host (the paint editor, the image editor, brushed canvas and
+ * vector strokes, later Swift) can render. `checkBrush` explains each refusal with a fix,
+ * `listPresets` filters a library down to what the host can use, and `degrade` strips the facets
+ * a host can't render and says what it dropped.
+ *
+ * A capability is `full` (rendered), `ignored` (the brush is accepted but the host paints without
+ * it: a warning) or `none` (the brush is refused: an error).
+ */
+import { type Brush, type BrushKind, type BrushMarksKind, type BrushPaint, type BrushSurface, type BrushTipShape, type BrushTool } from './types.js';
+export type BrushSupport = 'full' | 'ignored' | 'none';
+/** What a colour is: a solid colour, a light / dark pair, a gradient or effect paint. */
+export type BrushColourKind = 'solid' | 'dual' | 'gradient' | 'effect';
+export interface BrushHostProfile {
+    /** `paint`, `image`, `canvas`, `vector`… */
+    id: string;
+    name: string;
+    kinds: readonly BrushKind[];
+    /** Tools the host has (for `kind: 'tool'`). */
+    tools: readonly BrushTool[];
+    tipShapes: readonly BrushTipShape[];
+    marks: readonly BrushMarksKind[];
+    surfaces: readonly BrushSurface[];
+    /** Picking paint up and mixing it in (`behaviour.exchange` pickup, mix, dirty). */
+    exchange: BrushSupport;
+    /** The Mixer Brush (`behaviour.exchange.reservoir`). */
+    reservoir: BrushSupport;
+    /** Paper grain response (`behaviour.grain`). */
+    grain: BrushSupport;
+    light: BrushSupport;
+    motion: BrushSupport;
+    /** Colour kinds the brush's default colour may be (palette entries of other kinds are warned about). */
+    colours: readonly BrushColourKind[];
+    /** Velocity dynamics (needs timed input). */
+    velocity: BrushSupport;
+    /** Tilt dynamics (needs pen tilt). */
+    tilt: BrushSupport;
+}
+export interface BrushIssue {
+    /** The facet path the issue is about, e.g. `tip.shape`, `light`, `behaviour.exchange.reservoir`. */
+    facet: string;
+    /** `error`: the host can't render the brush; `warning`: it renders it without this setting. */
+    severity: 'error' | 'warning';
+    reason: string;
+    fix: string;
+}
+export interface BrushCheck {
+    /** No errors (warnings may remain). */
+    ok: boolean;
+    issues: BrushIssue[];
+}
+/** The paint editor: every facet. */
+export declare const PAINT_PROFILE: BrushHostProfile;
+/** The image editor's brush: dry dabs on pixels, its Mixer Brush and the eraser. */
+export declare const IMAGE_PROFILE: BrushHostProfile;
+/**
+ * Brushed canvas strokes: dry dab brushes along a path. Light paint needs the paint editor's
+ * light channel (glow and spill), which canvas strokes don't have, so it is refused.
+ */
+export declare const CANVAS_PROFILE: BrushHostProfile;
+/** Vector brushstrokes: dry dab brushes along a path; light brushes paint as plain colour. */
+export declare const VECTOR_PROFILE: BrushHostProfile;
+/** The built-in profiles by id. */
+export declare const BRUSH_HOST_PROFILES: Readonly<Record<string, BrushHostProfile>>;
+/** What kind of colour a `BrushPaint` is. */
+export declare function brushColourKind(paint: BrushPaint): BrushColourKind;
+/** What a brush needs from a host, and what the host does about it. */
+export declare function checkBrush(brush: Brush, profile: BrushHostProfile): BrushCheck;
+/** The presets (default: the built-in ones) a host can render, in library order. */
+export declare function listPresets(profile: BrushHostProfile, presets?: readonly Brush[]): Brush[];
+export interface DegradedBrush {
+    /** The brush with what the host can't render stripped (a copy). */
+    brush: Brush;
+    /** The errors fixed by stripping a facet. */
+    dropped: BrushIssue[];
+    /** Errors that stripping cannot fix (an unsupported kind or tool): the host still refuses it. */
+    issues: BrushIssue[];
+}
+/**
+ * The brush the host can render: facets it refuses are removed (light, motion, a reservoir, a
+ * wet or thick surface, particle or object marks, bristle and stamp tips become round, an
+ * unsupported default colour), each reported in `dropped`. A tool the host lacks can't be
+ * stripped and stays in `issues`.
+ */
+export declare function degrade(brush: Brush, profile: BrushHostProfile): DegradedBrush;

package/dist/brushes/tools.d.cts

@@ -0,0 +1,37 @@
+/**
+ * Agent tools for a brush library (`createBrushLibraryToolProvider`): list, describe, create,
+ * update, duplicate, remove, export, import and check brushes, and preview one when the host
+ * injects a renderer. Writes are checked against the host's profile before anything is stored,
+ * and refusals name what to do instead. The provider imports no renderer: `preview_brush` is
+ * the host's.
+ */
+import type { AgentTool, AgentToolProvider } from '../tools/registry.cjs';
+import { type BrushLibrary } from './library.cjs';
+import { type BrushHostProfile } from './profiles.cjs';
+import { type Brush } from './types.cjs';
+/** A preview image of a brush: base64 data and its type. */
+export interface BrushPreviewImage {
+    data: string;
+    mimeType: string;
+}
+/** Draws a sample stroke with a brush (the host's renderer: the paint engine, a canvas…). */
+export type BrushPreviewRenderer = (brush: Brush, options: {
+    width: number;
+    height: number;
+    color: string;
+}) => BrushPreviewImage | Promise<BrushPreviewImage>;
+export interface BrushLibraryToolProviderOptions {
+    /** What this host can render (default `PAINT_PROFILE`): lists are filtered by it and writes checked against it. */
+    profile?: BrushHostProfile;
+    /** With it, `preview_brush` draws a sample stroke. */
+    renderPreview?: BrushPreviewRenderer;
+    /** Only the read tools (list, describe, export, check, preview). */
+    readOnly?: boolean;
+    /** Provider id (default `brushes`), also the tool namespace unless `namespace` is set. */
+    id?: string;
+    namespace?: string;
+}
+/** The brush library tools for one host (see the module comment). */
+export declare function createBrushLibraryTools(library: BrushLibrary, options?: BrushLibraryToolProviderOptions): AgentTool[];
+/** The brush library tools as a provider (id `brushes` by default; namespaced, so they don't meet the paint editor's brush tools). */
+export declare function createBrushLibraryToolProvider(library: BrushLibrary, options?: BrushLibraryToolProviderOptions): AgentToolProvider;

package/dist/brushes/tools.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Agent tools for a brush library (`createBrushLibraryToolProvider`): list, describe, create,
+ * update, duplicate, remove, export, import and check brushes, and preview one when the host
+ * injects a renderer. Writes are checked against the host's profile before anything is stored,
+ * and refusals name what to do instead. The provider imports no renderer: `preview_brush` is
+ * the host's.
+ */
+import type { AgentTool, AgentToolProvider } from '../tools/registry.js';
+import { type BrushLibrary } from './library.js';
+import { type BrushHostProfile } from './profiles.js';
+import { type Brush } from './types.js';
+/** A preview image of a brush: base64 data and its type. */
+export interface BrushPreviewImage {
+    data: string;
+    mimeType: string;
+}
+/** Draws a sample stroke with a brush (the host's renderer: the paint engine, a canvas…). */
+export type BrushPreviewRenderer = (brush: Brush, options: {
+    width: number;
+    height: number;
+    color: string;
+}) => BrushPreviewImage | Promise<BrushPreviewImage>;
+export interface BrushLibraryToolProviderOptions {
+    /** What this host can render (default `PAINT_PROFILE`): lists are filtered by it and writes checked against it. */
+    profile?: BrushHostProfile;
+    /** With it, `preview_brush` draws a sample stroke. */
+    renderPreview?: BrushPreviewRenderer;
+    /** Only the read tools (list, describe, export, check, preview). */
+    readOnly?: boolean;
+    /** Provider id (default `brushes`), also the tool namespace unless `namespace` is set. */
+    id?: string;
+    namespace?: string;
+}
+/** The brush library tools for one host (see the module comment). */
+export declare function createBrushLibraryTools(library: BrushLibrary, options?: BrushLibraryToolProviderOptions): AgentTool[];
+/** The brush library tools as a provider (id `brushes` by default; namespaced, so they don't meet the paint editor's brush tools). */
+export declare function createBrushLibraryToolProvider(library: BrushLibrary, options?: BrushLibraryToolProviderOptions): AgentToolProvider;

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.252.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,104 @@
+---
+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's own brush tools** (`set_brush`, `save_brush`, its `export_brushes`)
+  still work on its brushes; this library's tools are namespaced apart.
+
+## 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. 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. |