@pixerate/editor 0.251.0 → 0.253.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/patch.d.cts

@@ -0,0 +1,23 @@
+/**
+ * Facet patches: a partial brush laid over another (`mergeBrushPatch`), the schema of one for
+ * tools (`BRUSH_PATCH_PROPERTIES`), and the leaf paths two brushes differ in (`changedBrushPaths`).
+ * The library tools and the paint editor's `set_brush` / `paint_stroke` share them, so a patch
+ * means the same everywhere.
+ */
+import type { JsonSchema } from '../tools/schema.cjs';
+import type { Brush } from './types.cjs';
+/** A brush's facets, any of them, as a patch takes them (the tip's `shape` may be left out). */
+export type BrushPatch = {
+    [K in Exclude<keyof Brush, 'id'>]?: K extends 'tip' ? Partial<Brush['tip']> : Brush[K];
+};
+/** The schema of every facet except `id` and `name`, as tool arguments (a patch may leave out `tip.shape`). */
+export declare const BRUSH_PATCH_PROPERTIES: Readonly<Record<string, JsonSchema>>;
+/** The facets a patch can remove (`unset`), back to the engine's defaults. */
+export declare const UNSETTABLE_BRUSH_FACETS: readonly ["description", "tags", "medium", "variety", "marks", "dynamics", "behaviour", "light", "motion", "colour"];
+export type UnsettableBrushFacet = (typeof UNSETTABLE_BRUSH_FACETS)[number];
+/** The `unset` argument of tools that take a patch. */
+export declare const BRUSH_UNSET_PROPERTY: JsonSchema;
+/** `base` with `patch` laid over it: objects merge, everything else (lists included) is replaced. Marks of another kind replace the marks. */
+export declare function mergeBrushPatch<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>, path?: string): T;
+/** Leaf paths whose values differ between two brushes (dot paths; lists compare whole). */
+export declare function changedBrushPaths(a: unknown, b: unknown, path?: string): string[];

package/dist/brushes/patch.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Facet patches: a partial brush laid over another (`mergeBrushPatch`), the schema of one for
+ * tools (`BRUSH_PATCH_PROPERTIES`), and the leaf paths two brushes differ in (`changedBrushPaths`).
+ * The library tools and the paint editor's `set_brush` / `paint_stroke` share them, so a patch
+ * means the same everywhere.
+ */
+import type { JsonSchema } from '../tools/schema.js';
+import type { Brush } from './types.js';
+/** A brush's facets, any of them, as a patch takes them (the tip's `shape` may be left out). */
+export type BrushPatch = {
+    [K in Exclude<keyof Brush, 'id'>]?: K extends 'tip' ? Partial<Brush['tip']> : Brush[K];
+};
+/** The schema of every facet except `id` and `name`, as tool arguments (a patch may leave out `tip.shape`). */
+export declare const BRUSH_PATCH_PROPERTIES: Readonly<Record<string, JsonSchema>>;
+/** The facets a patch can remove (`unset`), back to the engine's defaults. */
+export declare const UNSETTABLE_BRUSH_FACETS: readonly ["description", "tags", "medium", "variety", "marks", "dynamics", "behaviour", "light", "motion", "colour"];
+export type UnsettableBrushFacet = (typeof UNSETTABLE_BRUSH_FACETS)[number];
+/** The `unset` argument of tools that take a patch. */
+export declare const BRUSH_UNSET_PROPERTY: JsonSchema;
+/** `base` with `patch` laid over it: objects merge, everything else (lists included) is replaced. Marks of another kind replace the marks. */
+export declare function mergeBrushPatch<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>, path?: string): T;
+/** Leaf paths whose values differ between two brushes (dot paths; lists compare whole). */
+export declare function changedBrushPaths(a: unknown, b: unknown, path?: string): 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/brushes/ui.d.cts

@@ -0,0 +1,105 @@
+/**
+ * The brush editor as data, for the React and Svelte `BrushEditor` and `BrushLibraryBrowser`:
+ * `brushEditorSections` lists a brush's facets as ordered sections of controls (Medium, Shape,
+ * Marks, Feel, Behaviour, Light, Motion, Colour), each control a facet path with its value,
+ * range and label, leaving out what the host profile can't render. `setBrushEditorValue` applies
+ * one control's change; `brushLibraryGroups` groups a library by medium and variety, tools apart.
+ *
+ * Sliders reuse the paint editor's tables (`BRUSH_SLIDERS`, `brushEngineControls`), mapped from
+ * engine paths to facet paths through `BRUSH_FIELDS`, so the panels and the editor agree.
+ */
+import type { BrushLibraryEntry } from './library.cjs';
+import { type BrushHostProfile } from './profiles.cjs';
+import { type Brush } from './types.cjs';
+export type BrushEditorSectionId = 'medium' | 'shape' | 'marks' | 'feel' | 'behaviour' | 'light' | 'motion' | 'colour';
+interface ControlBase {
+    /** Facet path the control sets (`tip.size`, `behaviour.exchange.pickup`…). */
+    path: string;
+    label: string;
+    /** Accessible name (stable across hosts, for tests and assistive tech). */
+    ariaLabel: string;
+    /** Set when the host paints without this setting (its profile ignores it). */
+    note?: string;
+}
+export type BrushEditorControl = (ControlBase & {
+    kind: 'slider';
+    min: number;
+    max: number;
+    step: number;
+    value: number;
+}) | (ControlBase & {
+    kind: 'choice';
+    options: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+    value: string;
+}) | (ControlBase & {
+    kind: 'toggle';
+    value: boolean;
+}) | (ControlBase & {
+    kind: 'text';
+    value: string;
+    placeholder?: string;
+})
+/** A solid colour (#rrggbb), or `null` when there is none (or the default is a gradient or effect). */
+ | (ControlBase & {
+    kind: 'colour';
+    value: string | null;
+}) | (ControlBase & {
+    kind: 'palette';
+    value: string[];
+    max: number;
+})
+/** Stamp refs (`editor:star`…): `options` are the editor's stamps; hosts may offer more refs. */
+ | (ControlBase & {
+    kind: 'stamps';
+    value: string[];
+    max: number;
+    options: ReadonlyArray<{
+        value: string;
+        label: string;
+    }>;
+});
+export interface BrushEditorSection {
+    id: BrushEditorSectionId;
+    title: string;
+    controls: BrushEditorControl[];
+}
+/**
+ * Sections of controls for a brush, in order, as the host `profile` (default the paint editor)
+ * can render them: sections and controls it refuses are left out, ones it paints without carry
+ * a note. Values are the brush's own, else the defaults of the engine it resolves to.
+ */
+export declare function brushEditorSections(brush: Brush, profile?: BrushHostProfile): BrushEditorSection[];
+/**
+ * The brush with one control's value set (`undefined` removes it), normalised. Changing the kind,
+ * the marks or the tip shape starts that facet afresh. Returns the brush and what was clamped or
+ * dropped; an invalid change returns the brush unchanged with the reason.
+ */
+export declare function setBrushEditorValue(brush: Brush, path: string, value: unknown): {
+    brush: Brush;
+    problems: string[];
+};
+export interface BrushLibraryGroup {
+    /** `tools`, or a medium (`paint`, `ink`, `dry`, `spray`), or `other`. */
+    id: string;
+    title: string;
+    /** Brushes by variety (`''`: no variety), in library order. */
+    varieties: Array<{
+        variety: string;
+        title: string;
+        entries: BrushLibraryEntry[];
+    }>;
+}
+/**
+ * A library grouped for a browser: marks by medium, then variety; tools as their own group.
+ * `text` keeps brushes whose id, name, variety or tags start with each word; `profile` keeps only
+ * what that host renders.
+ */
+export declare function brushLibraryGroups(entries: readonly BrushLibraryEntry[], filter?: {
+    text?: string;
+    profile?: BrushHostProfile;
+    source?: 'builtin' | 'user';
+}): BrushLibraryGroup[];
+export {};