@pixerate/editor 0.250.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/migrate.d.cts

@@ -0,0 +1,17 @@
+/**
+ * Version 1 brushes (`PaintBrush`, the flat engine form) to facet brushes. Files, documents and
+ * recorded strokes written before the facet model still load: each v1 brush becomes the sparse
+ * facet brush that resolves back to it.
+ *
+ * What the engine reads survives exactly. Settings of engine blocks the brush's engine never
+ * reads (a dab brush's mixer settings) are dropped, and the category is derived again
+ * (`resolveCategory`), so a v1 brush filed under a category its settings do not match moves.
+ */
+import { type PaintBrushInput } from '../paint-editor/brushes.cjs';
+import type { Brush } from './types.cjs';
+/**
+ * The facet brush a v1 brush (any `PaintBrush`, or the JSON of one) amounts to: its engine's
+ * settings, stored only where they differ from that engine's defaults.
+ * `resolveBrush(migrateBrushV1(b))` paints exactly as `b` does.
+ */
+export declare function migrateBrushV1(raw: PaintBrushInput): Brush;

package/dist/brushes/migrate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Version 1 brushes (`PaintBrush`, the flat engine form) to facet brushes. Files, documents and
+ * recorded strokes written before the facet model still load: each v1 brush becomes the sparse
+ * facet brush that resolves back to it.
+ *
+ * What the engine reads survives exactly. Settings of engine blocks the brush's engine never
+ * reads (a dab brush's mixer settings) are dropped, and the category is derived again
+ * (`resolveCategory`), so a v1 brush filed under a category its settings do not match moves.
+ */
+import { type PaintBrushInput } from '../paint-editor/brushes.js';
+import type { Brush } from './types.js';
+/**
+ * The facet brush a v1 brush (any `PaintBrush`, or the JSON of one) amounts to: its engine's
+ * settings, stored only where they differ from that engine's defaults.
+ * `resolveBrush(migrateBrushV1(b))` paints exactly as `b` does.
+ */
+export declare function migrateBrushV1(raw: PaintBrushInput): Brush;

package/dist/brushes/normalize.d.cts

@@ -0,0 +1,15 @@
+/**
+ * `normalizeBrushSpec`: a brush with every given field checked against `BRUSH_JSON_SCHEMA`. It
+ * stays sparse (missing fields are not filled in): numbers are clamped into range, integers
+ * rounded, unknown fields, bad values and facets the brush does not use are dropped, and each
+ * change is reported in `problems` so a caller (or an agent) sees what was fixed. Only an id,
+ * name or kind it cannot make sense of throws.
+ */
+import { type Brush, type BrushTool } from './types.cjs';
+/** The tools that work on the wet layer. */
+export declare const WET_BRUSH_TOOLS: readonly BrushTool[];
+/**
+ * A brush with every given field in range (see the module comment). Throws when the id, name or
+ * kind cannot be used; every other fix is reported in `problems`.
+ */
+export declare function normalizeBrushSpec(raw: unknown, problems?: string[]): Brush;

package/dist/brushes/normalize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `normalizeBrushSpec`: a brush with every given field checked against `BRUSH_JSON_SCHEMA`. It
+ * stays sparse (missing fields are not filled in): numbers are clamped into range, integers
+ * rounded, unknown fields, bad values and facets the brush does not use are dropped, and each
+ * change is reported in `problems` so a caller (or an agent) sees what was fixed. Only an id,
+ * name or kind it cannot make sense of throws.
+ */
+import { type Brush, type BrushTool } from './types.js';
+/** The tools that work on the wet layer. */
+export declare const WET_BRUSH_TOOLS: readonly BrushTool[];
+/**
+ * A brush with every given field in range (see the module comment). Throws when the id, name or
+ * kind cannot be used; every other fix is reported in `problems`.
+ */
+export declare function normalizeBrushSpec(raw: unknown, problems?: string[]): Brush;

package/dist/brushes/presets.d.cts

@@ -0,0 +1,12 @@
+/**
+ * The built-in brushes as facet specs. Each resolves (`resolveBrush`) to exactly the paint
+ * editor's built-in brush of the same id (`BUILTIN_BRUSHES`, which `tests/brushes.test.ts`
+ * checks), so the engine paints them as it always has. Medium and variety are new: they file
+ * each brush under what it is for browsing and filtering. Only what differs from the engine's
+ * defaults is written down.
+ *
+ * Our own settings; none come from another product.
+ */
+import type { Brush } from './types.cjs';
+/** The built-in brush library, in the paint editor's order. */
+export declare const BRUSH_PRESETS: readonly Brush[];

package/dist/brushes/presets.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The built-in brushes as facet specs. Each resolves (`resolveBrush`) to exactly the paint
+ * editor's built-in brush of the same id (`BUILTIN_BRUSHES`, which `tests/brushes.test.ts`
+ * checks), so the engine paints them as it always has. Medium and variety are new: they file
+ * each brush under what it is for browsing and filtering. Only what differs from the engine's
+ * defaults is written down.
+ *
+ * Our own settings; none come from another product.
+ */
+import type { Brush } from './types.js';
+/** The built-in brush library, in the paint editor's order. */
+export declare const BRUSH_PRESETS: readonly Brush[];

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/resolve.d.cts

@@ -0,0 +1,56 @@
+/**
+ * From a facet `Brush` to the flat form the paint engine reads (`ResolvedBrush`, today's
+ * `PaintBrush`). The engine is derived from the tip, the marks and the behaviour
+ * (`resolveEngine`); the category the libraries group by is derived too (`resolveCategory`).
+ *
+ * `BRUSH_FIELDS` maps each facet field to the engine field it sets, for the engines that read it.
+ * `migrateBrushV1` reads the same map the other way, so the two directions cannot drift apart.
+ */
+import { type PaintBrushCategory, type PaintBrushEngine, type WetMediumKind, type WetTool } from '../paint-editor/brushes.cjs';
+import type { Brush, BrushTool, ResolvedBrush } from './types.cjs';
+/** One facet field and the engine field it sets. */
+export interface BrushField {
+    /** Dot path in the facet brush. */
+    facet: string;
+    /** Dot path in the resolved brush. */
+    engine: string;
+    /** The engines that read it. */
+    engines: readonly PaintBrushEngine[];
+    /** When the two forms differ: facet value → engine value, and back. */
+    map?: {
+        toEngine(v: unknown): unknown;
+        toFacet(v: unknown): unknown;
+    };
+    /** Read only on these tip shapes. */
+    shapes?: readonly string[];
+}
+/** Every facet field and where it lands in the resolved brush. */
+export declare const BRUSH_FIELDS: readonly BrushField[];
+/** The wet tool each wet-layer tool brush is. */
+export declare const WET_TOOL_OF: Readonly<Partial<Record<BrushTool, WetTool>>>;
+export declare function getPath(o: unknown, path: string): unknown;
+export declare function setPath(o: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * The engine that renders a brush: tools by what they do; marks by how they are laid
+ * (particles, objects), the tip (bristle), the surface (thick, wet) and the paint exchange (a
+ * reservoir makes a Mixer Brush); everything else paints dabs.
+ */
+export declare function resolveEngine(brush: Pick<Brush, 'kind' | 'tool' | 'tip' | 'marks' | 'behaviour'>): PaintBrushEngine;
+/** The wet medium a wet brush paints: `behaviour.wet.medium`, else its variety when that is a wet medium. */
+export declare function resolveWetMedium(brush: Pick<Brush, 'variety' | 'behaviour'>): WetMediumKind | undefined;
+/**
+ * The library category a brush is grouped under: tools by what they do; light brushes; then by
+ * engine (particles are procedural, objects stickers, bristle, thick impasto, wet oil or
+ * watercolour, the Mixer Brush); dab brushes by variety, then medium.
+ */
+export declare function resolveCategory(brush: Brush, engine?: PaintBrushEngine): PaintBrushCategory;
+export interface ResolveBrushOptions {
+    /** Mark the result built-in (a library's presets). */
+    builtin?: boolean;
+}
+/**
+ * The flat engine form of a brush. Missing fields take the engine's defaults, and every value is
+ * clamped into range, so any brush resolves (check it with `normalizeBrushSpec` first to hear
+ * what was out of range).
+ */
+export declare function resolveBrush(brush: Brush, options?: ResolveBrushOptions): ResolvedBrush;

package/dist/brushes/resolve.d.ts

@@ -0,0 +1,56 @@
+/**
+ * From a facet `Brush` to the flat form the paint engine reads (`ResolvedBrush`, today's
+ * `PaintBrush`). The engine is derived from the tip, the marks and the behaviour
+ * (`resolveEngine`); the category the libraries group by is derived too (`resolveCategory`).
+ *
+ * `BRUSH_FIELDS` maps each facet field to the engine field it sets, for the engines that read it.
+ * `migrateBrushV1` reads the same map the other way, so the two directions cannot drift apart.
+ */
+import { type PaintBrushCategory, type PaintBrushEngine, type WetMediumKind, type WetTool } from '../paint-editor/brushes.js';
+import type { Brush, BrushTool, ResolvedBrush } from './types.js';
+/** One facet field and the engine field it sets. */
+export interface BrushField {
+    /** Dot path in the facet brush. */
+    facet: string;
+    /** Dot path in the resolved brush. */
+    engine: string;
+    /** The engines that read it. */
+    engines: readonly PaintBrushEngine[];
+    /** When the two forms differ: facet value → engine value, and back. */
+    map?: {
+        toEngine(v: unknown): unknown;
+        toFacet(v: unknown): unknown;
+    };
+    /** Read only on these tip shapes. */
+    shapes?: readonly string[];
+}
+/** Every facet field and where it lands in the resolved brush. */
+export declare const BRUSH_FIELDS: readonly BrushField[];
+/** The wet tool each wet-layer tool brush is. */
+export declare const WET_TOOL_OF: Readonly<Partial<Record<BrushTool, WetTool>>>;
+export declare function getPath(o: unknown, path: string): unknown;
+export declare function setPath(o: Record<string, unknown>, path: string, value: unknown): void;
+/**
+ * The engine that renders a brush: tools by what they do; marks by how they are laid
+ * (particles, objects), the tip (bristle), the surface (thick, wet) and the paint exchange (a
+ * reservoir makes a Mixer Brush); everything else paints dabs.
+ */
+export declare function resolveEngine(brush: Pick<Brush, 'kind' | 'tool' | 'tip' | 'marks' | 'behaviour'>): PaintBrushEngine;
+/** The wet medium a wet brush paints: `behaviour.wet.medium`, else its variety when that is a wet medium. */
+export declare function resolveWetMedium(brush: Pick<Brush, 'variety' | 'behaviour'>): WetMediumKind | undefined;
+/**
+ * The library category a brush is grouped under: tools by what they do; light brushes; then by
+ * engine (particles are procedural, objects stickers, bristle, thick impasto, wet oil or
+ * watercolour, the Mixer Brush); dab brushes by variety, then medium.
+ */
+export declare function resolveCategory(brush: Brush, engine?: PaintBrushEngine): PaintBrushCategory;
+export interface ResolveBrushOptions {
+    /** Mark the result built-in (a library's presets). */
+    builtin?: boolean;
+}
+/**
+ * The flat engine form of a brush. Missing fields take the engine's defaults, and every value is
+ * clamped into range, so any brush resolves (check it with `normalizeBrushSpec` first to hear
+ * what was out of range).
+ */
+export declare function resolveBrush(brush: Brush, options?: ResolveBrushOptions): ResolvedBrush;

package/dist/brushes/schema.d.cts

@@ -0,0 +1,29 @@
+/**
+ * JSON Schema of a `Brush`: strict (`additionalProperties: false` at every level), every field
+ * described with its units and default. `normalizeBrushSpec` clamps and checks against the same
+ * ranges, so the schema, the normaliser and the engine agree.
+ */
+import type { JsonSchema } from '../tools/schema.cjs';
+/** Most colours in a brush's palette. */
+export declare const MAX_BRUSH_PALETTE = 16;
+/** Variety and tag ids: lowercase letters, digits and dashes. */
+export declare const BRUSH_WORD: RegExp;
+/** A sticker ref `provider:id`, or a bare editor stamp (read as `editor:<stamp>`). */
+export declare const BRUSH_STAMP_PATTERN: string;
+/** JSON Schema of a `Brush`. */
+export declare const BRUSH_JSON_SCHEMA: JsonSchema;
+/** The facet schemas, for tools that take one facet. */
+export declare const BRUSH_FACET_SCHEMAS: {
+    readonly tip: JsonSchema;
+    readonly marks: {
+        readonly continuous: JsonSchema;
+        readonly particles: JsonSchema;
+        readonly objects: JsonSchema;
+    };
+    readonly dynamics: JsonSchema;
+    readonly behaviour: JsonSchema;
+    readonly light: JsonSchema;
+    readonly motion: JsonSchema;
+    readonly colour: JsonSchema;
+    readonly paint: JsonSchema;
+};

package/dist/brushes/schema.d.ts

@@ -0,0 +1,29 @@
+/**
+ * JSON Schema of a `Brush`: strict (`additionalProperties: false` at every level), every field
+ * described with its units and default. `normalizeBrushSpec` clamps and checks against the same
+ * ranges, so the schema, the normaliser and the engine agree.
+ */
+import type { JsonSchema } from '../tools/schema.js';
+/** Most colours in a brush's palette. */
+export declare const MAX_BRUSH_PALETTE = 16;
+/** Variety and tag ids: lowercase letters, digits and dashes. */
+export declare const BRUSH_WORD: RegExp;
+/** A sticker ref `provider:id`, or a bare editor stamp (read as `editor:<stamp>`). */
+export declare const BRUSH_STAMP_PATTERN: string;
+/** JSON Schema of a `Brush`. */
+export declare const BRUSH_JSON_SCHEMA: JsonSchema;
+/** The facet schemas, for tools that take one facet. */
+export declare const BRUSH_FACET_SCHEMAS: {
+    readonly tip: JsonSchema;
+    readonly marks: {
+        readonly continuous: JsonSchema;
+        readonly particles: JsonSchema;
+        readonly objects: JsonSchema;
+    };
+    readonly dynamics: JsonSchema;
+    readonly behaviour: JsonSchema;
+    readonly light: JsonSchema;
+    readonly motion: JsonSchema;
+    readonly colour: JsonSchema;
+    readonly paint: JsonSchema;
+};