@pixerate/editor 0.266.2 → 0.268.0

package/dist/brushes/sources.d.cts

@@ -0,0 +1,114 @@
+/**
+ * Brush sources: the images a brush is made from, as Procreate's Shape and Grain sources. A
+ * source is a grey mask (255 paints, or is a grain peak; 0 is empty) kept as a greyscale PNG
+ * `data:` URL, so a library file or a saved painting carries its bytes alongside the brushes
+ * that name it.
+ *
+ * - A stamp tip lays a source with the ref `source:<id>` in `tip.stamps`, the same way it lays a
+ *   sticker: shaped dabs, sprays and particle dots all take it.
+ * - `tip.grain.source` takes `source:<id>` as a grain texture (or one of the built-in grain
+ *   patterns).
+ *
+ * `makeBrushSource` reads an uploaded image (PNG, any size up to `MAX_BRUSH_SOURCE_INPUT_PIXELS`),
+ * picks the channel that holds the marks and scales it to fit `MAX_BRUSH_SOURCE_SIZE`.
+ */
+import type { Brush } from './types.cjs';
+/** The ref prefix of a brush source: `source:<id>`. The sticker provider id `source` is reserved for it. */
+export declare const BRUSH_SOURCE_PROVIDER = "source";
+/** Longest side a source is kept at (px); larger images are scaled down when added. */
+export declare const MAX_BRUSH_SOURCE_SIZE = 512;
+/** Largest image `makeBrushSource` decodes (pixels). */
+export declare const MAX_BRUSH_SOURCE_INPUT_PIXELS: number;
+/** Most sources one library keeps. */
+export declare const MAX_BRUSH_SOURCES = 500;
+/**
+ * Which part of an image holds the marks: `alpha` (art on a transparent background), `darkness`
+ * (dark marks on white paper, a scan), `lightness` (white marks on black, as Procreate's shape
+ * sources) or `auto`: alpha when the image has any transparency, else darkness.
+ */
+export type BrushSourceChannel = 'auto' | 'alpha' | 'darkness' | 'lightness';
+export declare const BRUSH_SOURCE_CHANNELS: readonly BrushSourceChannel[];
+/** A stored source. */
+export interface BrushSource {
+    /** Lowercase letters, digits and dashes, up to 64 characters. */
+    id: string;
+    /** Display name, up to 80 characters. */
+    name: string;
+    /** Size of the mask in px (each 1..`MAX_BRUSH_SOURCE_SIZE`). */
+    width: number;
+    height: number;
+    /** The mask: a greyscale PNG `data:` URL, 255 paints. */
+    image: string;
+    /** The licence or terms it came with (a brush pack's notes), kept with the source. */
+    licence?: string;
+    /** Where it came from: a file or brush pack name. */
+    origin?: string;
+}
+/** What `makeBrushSource` reads. */
+export interface BrushSourceInput {
+    /** Default: from the name. */
+    id?: string;
+    name: string;
+    /** A PNG as a `data:image/png;base64,…` URL, or its bytes. */
+    image: string | Uint8Array;
+    /** Default `auto`. */
+    channel?: BrushSourceChannel;
+    /** Swap painted and empty (default false). */
+    invert?: boolean;
+    licence?: string;
+    origin?: string;
+}
+/** A source without its image, for lists. */
+export type BrushSourceSummary = Omit<BrushSource, 'image'> & {
+    ref: string;
+};
+/** A refusal; the message says what to do instead. */
+export declare class BrushSourceError extends Error {
+    constructor(message: string);
+}
+/** `source:<id>`. */
+export declare function brushSourceRef(id: string): string;
+/** Whether a stamp or grain ref names a brush source. */
+export declare function isBrushSourceRef(ref: unknown): ref is string;
+/** The source id of a `source:<id>` ref, or `null` for any other ref. */
+export declare function brushSourceIdOf(ref: string): string | null;
+/** The ids of the sources a brush lays or textures with (its stamp tip and its grain). */
+export declare function brushSourceIds(brush: Pick<Brush, 'tip'>): string[];
+/** The list form of a source. */
+export declare function summarizeBrushSource(s: BrushSource): BrushSourceSummary;
+/** An id from a name: lowercase words joined by dashes. */
+export declare function brushSourceIdFromName(name: string): string;
+/**
+ * A source from a grey mask (255 paints), scaled to fit `MAX_BRUSH_SOURCE_SIZE`. Importers use it
+ * for tips they have decoded themselves. Throws when the mask is empty or the wrong size.
+ */
+export declare function brushSourceFromMask(meta: {
+    id: string;
+    name: string;
+    licence?: string;
+    origin?: string;
+}, width: number, height: number, mask: Uint8Array | Uint8ClampedArray): BrushSource;
+/**
+ * A source from an uploaded image (see the module comment): its marks read from `channel`,
+ * inverted when asked, scaled to fit. Throws (a `BrushSourceError`) when the image is not a PNG,
+ * too large, or empty in that channel; `problems` hears what was changed (scaling, the channel
+ * `auto` picked).
+ */
+export declare function makeBrushSource(input: BrushSourceInput, problems?: string[]): BrushSource;
+/**
+ * A stored source read back (from a library file or a saved painting), or `null` with the reason
+ * in `problems`. The image is checked for its form, not decoded (`decodeBrushSource` does that
+ * when it is first painted with).
+ */
+export declare function readBrushSource(raw: unknown, at: string, problems: string[]): BrushSource | null;
+/** A decoded source: one byte per pixel, 255 paints. */
+export interface DecodedBrushSource {
+    width: number;
+    height: number;
+    mask: Uint8ClampedArray;
+}
+/**
+ * The source's mask, decoded once per image (cached by its data, so a painting's copy and the
+ * library's share it). Throws when the image is not a valid PNG.
+ */
+export declare function decodeBrushSource(source: Pick<BrushSource, 'image'>): DecodedBrushSource;

package/dist/brushes/sources.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Brush sources: the images a brush is made from, as Procreate's Shape and Grain sources. A
+ * source is a grey mask (255 paints, or is a grain peak; 0 is empty) kept as a greyscale PNG
+ * `data:` URL, so a library file or a saved painting carries its bytes alongside the brushes
+ * that name it.
+ *
+ * - A stamp tip lays a source with the ref `source:<id>` in `tip.stamps`, the same way it lays a
+ *   sticker: shaped dabs, sprays and particle dots all take it.
+ * - `tip.grain.source` takes `source:<id>` as a grain texture (or one of the built-in grain
+ *   patterns).
+ *
+ * `makeBrushSource` reads an uploaded image (PNG, any size up to `MAX_BRUSH_SOURCE_INPUT_PIXELS`),
+ * picks the channel that holds the marks and scales it to fit `MAX_BRUSH_SOURCE_SIZE`.
+ */
+import type { Brush } from './types.js';
+/** The ref prefix of a brush source: `source:<id>`. The sticker provider id `source` is reserved for it. */
+export declare const BRUSH_SOURCE_PROVIDER = "source";
+/** Longest side a source is kept at (px); larger images are scaled down when added. */
+export declare const MAX_BRUSH_SOURCE_SIZE = 512;
+/** Largest image `makeBrushSource` decodes (pixels). */
+export declare const MAX_BRUSH_SOURCE_INPUT_PIXELS: number;
+/** Most sources one library keeps. */
+export declare const MAX_BRUSH_SOURCES = 500;
+/**
+ * Which part of an image holds the marks: `alpha` (art on a transparent background), `darkness`
+ * (dark marks on white paper, a scan), `lightness` (white marks on black, as Procreate's shape
+ * sources) or `auto`: alpha when the image has any transparency, else darkness.
+ */
+export type BrushSourceChannel = 'auto' | 'alpha' | 'darkness' | 'lightness';
+export declare const BRUSH_SOURCE_CHANNELS: readonly BrushSourceChannel[];
+/** A stored source. */
+export interface BrushSource {
+    /** Lowercase letters, digits and dashes, up to 64 characters. */
+    id: string;
+    /** Display name, up to 80 characters. */
+    name: string;
+    /** Size of the mask in px (each 1..`MAX_BRUSH_SOURCE_SIZE`). */
+    width: number;
+    height: number;
+    /** The mask: a greyscale PNG `data:` URL, 255 paints. */
+    image: string;
+    /** The licence or terms it came with (a brush pack's notes), kept with the source. */
+    licence?: string;
+    /** Where it came from: a file or brush pack name. */
+    origin?: string;
+}
+/** What `makeBrushSource` reads. */
+export interface BrushSourceInput {
+    /** Default: from the name. */
+    id?: string;
+    name: string;
+    /** A PNG as a `data:image/png;base64,…` URL, or its bytes. */
+    image: string | Uint8Array;
+    /** Default `auto`. */
+    channel?: BrushSourceChannel;
+    /** Swap painted and empty (default false). */
+    invert?: boolean;
+    licence?: string;
+    origin?: string;
+}
+/** A source without its image, for lists. */
+export type BrushSourceSummary = Omit<BrushSource, 'image'> & {
+    ref: string;
+};
+/** A refusal; the message says what to do instead. */
+export declare class BrushSourceError extends Error {
+    constructor(message: string);
+}
+/** `source:<id>`. */
+export declare function brushSourceRef(id: string): string;
+/** Whether a stamp or grain ref names a brush source. */
+export declare function isBrushSourceRef(ref: unknown): ref is string;
+/** The source id of a `source:<id>` ref, or `null` for any other ref. */
+export declare function brushSourceIdOf(ref: string): string | null;
+/** The ids of the sources a brush lays or textures with (its stamp tip and its grain). */
+export declare function brushSourceIds(brush: Pick<Brush, 'tip'>): string[];
+/** The list form of a source. */
+export declare function summarizeBrushSource(s: BrushSource): BrushSourceSummary;
+/** An id from a name: lowercase words joined by dashes. */
+export declare function brushSourceIdFromName(name: string): string;
+/**
+ * A source from a grey mask (255 paints), scaled to fit `MAX_BRUSH_SOURCE_SIZE`. Importers use it
+ * for tips they have decoded themselves. Throws when the mask is empty or the wrong size.
+ */
+export declare function brushSourceFromMask(meta: {
+    id: string;
+    name: string;
+    licence?: string;
+    origin?: string;
+}, width: number, height: number, mask: Uint8Array | Uint8ClampedArray): BrushSource;
+/**
+ * A source from an uploaded image (see the module comment): its marks read from `channel`,
+ * inverted when asked, scaled to fit. Throws (a `BrushSourceError`) when the image is not a PNG,
+ * too large, or empty in that channel; `problems` hears what was changed (scaling, the channel
+ * `auto` picked).
+ */
+export declare function makeBrushSource(input: BrushSourceInput, problems?: string[]): BrushSource;
+/**
+ * A stored source read back (from a library file or a saved painting), or `null` with the reason
+ * in `problems`. The image is checked for its form, not decoded (`decodeBrushSource` does that
+ * when it is first painted with).
+ */
+export declare function readBrushSource(raw: unknown, at: string, problems: string[]): BrushSource | null;
+/** A decoded source: one byte per pixel, 255 paints. */
+export interface DecodedBrushSource {
+    width: number;
+    height: number;
+    mask: Uint8ClampedArray;
+}
+/**
+ * The source's mask, decoded once per image (cached by its data, so a painting's copy and the
+ * library's share it). Throws when the image is not a valid PNG.
+ */
+export declare function decodeBrushSource(source: Pick<BrushSource, 'image'>): DecodedBrushSource;

package/dist/brushes/types.d.cts

@@ -29,8 +29,8 @@ export type BrushTool = 'eraser' | 'blender' | 'smudge' | 'water' | 'dryer' | 'b
 export declare const BRUSH_TOOLS: readonly BrushTool[];
 /**
  * The tip's shape. `round`, `flat` and `chisel` are ellipses (their `roundness` and `angle` set
- * the ellipse; the name is for people); `bristle` is a tuft of bristles; `stamp` lays textured
- * stamps (with `marks` `objects` or `particles`).
+ * the ellipse; the name is for people); `bristle` is a tuft of bristles; `stamp` lays shaped
+ * dabs: an editor stamp, a sticker, or an image source (`source:<id>`, see `brushes/sources.ts`).
  */
 export type BrushTipShape = 'round' | 'flat' | 'chisel' | 'bristle' | 'stamp';
 export declare const BRUSH_TIP_SHAPES: readonly BrushTipShape[];
@@ -41,10 +41,36 @@ export declare const BRUSH_MARKS_KINDS: readonly BrushMarksKind[];
 export type BrushSurface = 'dry' | 'wet' | 'thick';
 export declare const BRUSH_SURFACES: readonly BrushSurface[];
 /**
- * A sticker a `stamp` tip lays: a sticker ref `provider:id` (`editor:star`, or a host library's
- * sticker). Objects marks take any sticker; particle marks only the editor's own stamps.
+ * What a `stamp` tip lays: a sticker ref `provider:id` (`editor:star`, or a host library's
+ * sticker) or an image source `source:<id>` from the brush library. Objects marks take only
+ * stickers (each mark stays a sticker).
  */
 export type BrushStamp = StickerRef;
+/**
+ * How tip grain sits: `moving` rolls with the tip along the stroke (it turns with the tip, and
+ * every stroke shows it the same way); `texturised` stays put on the canvas, like a texture under
+ * the paint, so overlapping strokes show the same grain.
+ */
+export type BrushGrainMode = 'moving' | 'texturised';
+export declare const BRUSH_GRAIN_MODES: readonly BrushGrainMode[];
+/** Mirror each dab at random across these axes of the tip. */
+export type BrushFlip = 'none' | 'x' | 'y' | 'xy';
+export declare const BRUSH_FLIPS: readonly BrushFlip[];
+/** Texture inside the tip (Procreate's grain source), separate from the paper grain. */
+export interface BrushTipGrain {
+    /** A built-in grain pattern (`rough`, `canvas`, `sanded`…) or an image source `source:<id>` (light parts are peaks). */
+    source: string;
+    /** Default `texturised`. */
+    mode?: BrushGrainMode;
+    /** Grain size: 1 is the pattern's or image's own size, 2 twice as coarse; 0.05..20 (default 1). */
+    scale?: number;
+    /** How much the grain takes out of the mark: 0 none .. 1 only the peaks paint (default 0.6). */
+    depth?: number;
+    /** Height contrast around the middle, 0..3 (default 1). */
+    contrast?: number;
+    /** Swap peaks and valleys (default false). */
+    invert?: boolean;
+}
 /** The tuft of a `bristle` tip (each 0..1 unless noted). */
 export interface BrushBristles {
     /** Bristles in the tuft, 3..128 (default 32). */
@@ -81,8 +107,10 @@ export interface BrushTip {
     blend?: BlendMode;
     /** `bristle` tips: the tuft. */
     bristle?: BrushBristles;
-    /** `stamp` tips: sticker refs (objects: any sticker, one picked at random per mark; particles: up to 4 editor stamps, in `marks.stampOrder`). */
+    /** `stamp` tips: sticker or source refs (objects: any sticker, one picked at random per mark; particles: up to 4, in `marks.stampOrder`; continuous dabs: the first). */
     stamps?: BrushStamp[];
+    /** Texture inside each dab (continuous and scatter marks). */
+    grain?: BrushTipGrain;
 }
 /** Dabs laid along the path (the default). */
 export interface BrushContinuousMarks {
@@ -185,6 +213,10 @@ export interface BrushDynamics {
     opacityJitter?: number;
     /** Random offset across the stroke in diameters, 0..4 (default 0). */
     scatter?: number;
+    /** Dabs laid at each spacing step, 1..16, each with its own jitter (default 1). */
+    count?: number;
+    /** Mirror each dab at random across these axes (default `none`): variety for image tips. */
+    flip?: BrushFlip;
 }
 /** A Mixer Brush's paint reservoir: the brush is loaded with colour and mixes what it picks up into it. */
 export interface BrushReservoir {

package/dist/brushes/types.d.ts

@@ -29,8 +29,8 @@ export type BrushTool = 'eraser' | 'blender' | 'smudge' | 'water' | 'dryer' | 'b
 export declare const BRUSH_TOOLS: readonly BrushTool[];
 /**
  * The tip's shape. `round`, `flat` and `chisel` are ellipses (their `roundness` and `angle` set
- * the ellipse; the name is for people); `bristle` is a tuft of bristles; `stamp` lays textured
- * stamps (with `marks` `objects` or `particles`).
+ * the ellipse; the name is for people); `bristle` is a tuft of bristles; `stamp` lays shaped
+ * dabs: an editor stamp, a sticker, or an image source (`source:<id>`, see `brushes/sources.ts`).
  */
 export type BrushTipShape = 'round' | 'flat' | 'chisel' | 'bristle' | 'stamp';
 export declare const BRUSH_TIP_SHAPES: readonly BrushTipShape[];
@@ -41,10 +41,36 @@ export declare const BRUSH_MARKS_KINDS: readonly BrushMarksKind[];
 export type BrushSurface = 'dry' | 'wet' | 'thick';
 export declare const BRUSH_SURFACES: readonly BrushSurface[];
 /**
- * A sticker a `stamp` tip lays: a sticker ref `provider:id` (`editor:star`, or a host library's
- * sticker). Objects marks take any sticker; particle marks only the editor's own stamps.
+ * What a `stamp` tip lays: a sticker ref `provider:id` (`editor:star`, or a host library's
+ * sticker) or an image source `source:<id>` from the brush library. Objects marks take only
+ * stickers (each mark stays a sticker).
  */
 export type BrushStamp = StickerRef;
+/**
+ * How tip grain sits: `moving` rolls with the tip along the stroke (it turns with the tip, and
+ * every stroke shows it the same way); `texturised` stays put on the canvas, like a texture under
+ * the paint, so overlapping strokes show the same grain.
+ */
+export type BrushGrainMode = 'moving' | 'texturised';
+export declare const BRUSH_GRAIN_MODES: readonly BrushGrainMode[];
+/** Mirror each dab at random across these axes of the tip. */
+export type BrushFlip = 'none' | 'x' | 'y' | 'xy';
+export declare const BRUSH_FLIPS: readonly BrushFlip[];
+/** Texture inside the tip (Procreate's grain source), separate from the paper grain. */
+export interface BrushTipGrain {
+    /** A built-in grain pattern (`rough`, `canvas`, `sanded`…) or an image source `source:<id>` (light parts are peaks). */
+    source: string;
+    /** Default `texturised`. */
+    mode?: BrushGrainMode;
+    /** Grain size: 1 is the pattern's or image's own size, 2 twice as coarse; 0.05..20 (default 1). */
+    scale?: number;
+    /** How much the grain takes out of the mark: 0 none .. 1 only the peaks paint (default 0.6). */
+    depth?: number;
+    /** Height contrast around the middle, 0..3 (default 1). */
+    contrast?: number;
+    /** Swap peaks and valleys (default false). */
+    invert?: boolean;
+}
 /** The tuft of a `bristle` tip (each 0..1 unless noted). */
 export interface BrushBristles {
     /** Bristles in the tuft, 3..128 (default 32). */
@@ -81,8 +107,10 @@ export interface BrushTip {
     blend?: BlendMode;
     /** `bristle` tips: the tuft. */
     bristle?: BrushBristles;
-    /** `stamp` tips: sticker refs (objects: any sticker, one picked at random per mark; particles: up to 4 editor stamps, in `marks.stampOrder`). */
+    /** `stamp` tips: sticker or source refs (objects: any sticker, one picked at random per mark; particles: up to 4, in `marks.stampOrder`; continuous dabs: the first). */
     stamps?: BrushStamp[];
+    /** Texture inside each dab (continuous and scatter marks). */
+    grain?: BrushTipGrain;
 }
 /** Dabs laid along the path (the default). */
 export interface BrushContinuousMarks {
@@ -185,6 +213,10 @@ export interface BrushDynamics {
     opacityJitter?: number;
     /** Random offset across the stroke in diameters, 0..4 (default 0). */
     scatter?: number;
+    /** Dabs laid at each spacing step, 1..16, each with its own jitter (default 1). */
+    count?: number;
+    /** Mirror each dab at random across these axes (default `none`): variety for image tips. */
+    flip?: BrushFlip;
 }
 /** A Mixer Brush's paint reservoir: the brush is loaded with colour and mixes what it picks up into it. */
 export interface BrushReservoir {

package/dist/brushes/ui.d.cts

@@ -8,10 +8,11 @@
  * 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 BrushLibrary, type BrushLibraryEntry, type SaveBrushResult } from './library.cjs';
+import { type AddBrushSourceResult, type BrushLibrary, type BrushLibraryEntry, type SaveBrushResult } from './library.cjs';
 import { type BrushHostProfile, type BrushIssue } from './profiles.cjs';
+import { type BrushSource, type BrushSourceChannel } from './sources.cjs';
 import { type Brush } from './types.cjs';
-export type BrushEditorSectionId = 'medium' | 'shape' | 'marks' | 'feel' | 'behaviour' | 'light' | 'motion' | 'colour';
+export type BrushEditorSectionId = 'medium' | 'shape' | 'grain' | 'marks' | 'feel' | 'behaviour' | 'light' | 'motion' | 'colour';
 interface ControlBase {
     /** Facet path the control sets (`tip.size`, `behaviour.exchange.pickup`…). */
     path: string;
@@ -62,7 +63,10 @@ export type BrushEditorControl = (ControlBase & {
     }>;
     max: number;
 })
-/** Stamp refs (`editor:star`…): `options` are the editor's stamps; hosts may offer more refs. */
+/**
+ * Stamp refs (`editor:star`, `source:<id>`…): `options` are the editor's stamps and the image
+ * sources the host passed (`brushEditorSections`' `sources`); hosts may offer more refs.
+ */
  | (ControlBase & {
     kind: 'stamps';
     value: string[];
@@ -72,6 +76,11 @@ export type BrushEditorControl = (ControlBase & {
         label: string;
     }>;
 });
+/** What the host knows beyond the brush: the image sources it can paint with. */
+export interface BrushEditorContext {
+    /** The library's image sources (`listSources`), offered as stamps and grain. */
+    sources?: ReadonlyArray<Pick<BrushSource, 'id' | 'name'>>;
+}
 export interface BrushEditorSection {
     id: BrushEditorSectionId;
     title: string;
@@ -84,7 +93,7 @@ export interface BrushEditorSection {
  * edit keeps them as they are; `brushEditorScope` names them. Values are the brush's own, else
  * the defaults of the engine it resolves to.
  */
-export declare function brushEditorSections(brush: Brush, profile?: BrushHostProfile): BrushEditorSection[];
+export declare function brushEditorSections(brush: Brush, profile?: BrushHostProfile, context?: BrushEditorContext): BrushEditorSection[];
 /** What a brush has that the host can't use: one facet, in words. */
 export interface BrushEditorHiddenFacet {
     facet: string;
@@ -166,4 +175,31 @@ export declare function brushLibraryGroups(entries: readonly BrushLibraryEntry[]
     profile?: BrushHostProfile;
     source?: 'builtin' | 'user';
 }): BrushLibraryGroup[];
+/**
+ * A PNG `data:` URL of an image file a person picked, for `BrushLibrary.addSource`: a PNG is kept
+ * as it is; any other image (JPEG, WebP…) is drawn through the browser's `createImageBitmap` and
+ * `OffscreenCanvas`. Rejects, naming PNG, where there is no browser to draw it.
+ */
+export declare function imageFileToPngDataUrl(file: Blob): Promise<string>;
+/**
+ * Adds an image file to the library as a source (named after the file unless `name` is given),
+ * as the brush editor's "Add image" does. Returns the stored source, its `source:<id>` ref and what
+ * reading it changed.
+ */
+export declare function addBrushSourceFromFile(library: Pick<BrushLibrary, 'addSource'>, file: Blob & {
+    name?: string;
+}, options?: {
+    name?: string;
+    channel?: BrushSourceChannel;
+}): Promise<AddBrushSourceResult & {
+    ref: string;
+}>;
+/**
+ * The brush with an image source as its tip (`as: 'tip'`: a stamp tip laying it) or as its grain
+ * (`as: 'grain'`), normalised, as `setBrushEditorValue` returns it.
+ */
+export declare function withBrushSource(brush: Brush, ref: string, as: 'tip' | 'grain'): {
+    brush: Brush;
+    problems: string[];
+};
 export {};

package/dist/brushes/ui.d.ts

@@ -8,10 +8,11 @@
  * 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 BrushLibrary, type BrushLibraryEntry, type SaveBrushResult } from './library.js';
+import { type AddBrushSourceResult, type BrushLibrary, type BrushLibraryEntry, type SaveBrushResult } from './library.js';
 import { type BrushHostProfile, type BrushIssue } from './profiles.js';
+import { type BrushSource, type BrushSourceChannel } from './sources.js';
 import { type Brush } from './types.js';
-export type BrushEditorSectionId = 'medium' | 'shape' | 'marks' | 'feel' | 'behaviour' | 'light' | 'motion' | 'colour';
+export type BrushEditorSectionId = 'medium' | 'shape' | 'grain' | 'marks' | 'feel' | 'behaviour' | 'light' | 'motion' | 'colour';
 interface ControlBase {
     /** Facet path the control sets (`tip.size`, `behaviour.exchange.pickup`…). */
     path: string;
@@ -62,7 +63,10 @@ export type BrushEditorControl = (ControlBase & {
     }>;
     max: number;
 })
-/** Stamp refs (`editor:star`…): `options` are the editor's stamps; hosts may offer more refs. */
+/**
+ * Stamp refs (`editor:star`, `source:<id>`…): `options` are the editor's stamps and the image
+ * sources the host passed (`brushEditorSections`' `sources`); hosts may offer more refs.
+ */
  | (ControlBase & {
     kind: 'stamps';
     value: string[];
@@ -72,6 +76,11 @@ export type BrushEditorControl = (ControlBase & {
         label: string;
     }>;
 });
+/** What the host knows beyond the brush: the image sources it can paint with. */
+export interface BrushEditorContext {
+    /** The library's image sources (`listSources`), offered as stamps and grain. */
+    sources?: ReadonlyArray<Pick<BrushSource, 'id' | 'name'>>;
+}
 export interface BrushEditorSection {
     id: BrushEditorSectionId;
     title: string;
@@ -84,7 +93,7 @@ export interface BrushEditorSection {
  * edit keeps them as they are; `brushEditorScope` names them. Values are the brush's own, else
  * the defaults of the engine it resolves to.
  */
-export declare function brushEditorSections(brush: Brush, profile?: BrushHostProfile): BrushEditorSection[];
+export declare function brushEditorSections(brush: Brush, profile?: BrushHostProfile, context?: BrushEditorContext): BrushEditorSection[];
 /** What a brush has that the host can't use: one facet, in words. */
 export interface BrushEditorHiddenFacet {
     facet: string;
@@ -166,4 +175,31 @@ export declare function brushLibraryGroups(entries: readonly BrushLibraryEntry[]
     profile?: BrushHostProfile;
     source?: 'builtin' | 'user';
 }): BrushLibraryGroup[];
+/**
+ * A PNG `data:` URL of an image file a person picked, for `BrushLibrary.addSource`: a PNG is kept
+ * as it is; any other image (JPEG, WebP…) is drawn through the browser's `createImageBitmap` and
+ * `OffscreenCanvas`. Rejects, naming PNG, where there is no browser to draw it.
+ */
+export declare function imageFileToPngDataUrl(file: Blob): Promise<string>;
+/**
+ * Adds an image file to the library as a source (named after the file unless `name` is given),
+ * as the brush editor's "Add image" does. Returns the stored source, its `source:<id>` ref and what
+ * reading it changed.
+ */
+export declare function addBrushSourceFromFile(library: Pick<BrushLibrary, 'addSource'>, file: Blob & {
+    name?: string;
+}, options?: {
+    name?: string;
+    channel?: BrushSourceChannel;
+}): Promise<AddBrushSourceResult & {
+    ref: string;
+}>;
+/**
+ * The brush with an image source as its tip (`as: 'tip'`: a stamp tip laying it) or as its grain
+ * (`as: 'grain'`), normalised, as `setBrushEditorValue` returns it.
+ */
+export declare function withBrushSource(brush: Brush, ref: string, as: 'tip' | 'grain'): {
+    brush: Brush;
+    problems: string[];
+};
 export {};

package/dist/{brushstrokeRender-KD453OBX.js → brushstrokeRender-A727TTNQ.js}

@@ -1,9 +1,9 @@
 import {
   brushPreviewColours
-} from "./chunk-4ODRXQRW.js";
+} from "./chunk-LETF75CA.js";
 import {
   pathDataToPolyline
-} from "./chunk-DXYHQ2VN.js";
+} from "./chunk-BAZMCFVL.js";
 import {
   BRUSH_PRESETS,
   BUILTIN_BRUSHES,
@@ -14,8 +14,8 @@ import {
   normalizeBrushSpec,
   resolveBrush,
   resolveCategory
-} from "./chunk-CIJBSUM5.js";
-import "./chunk-ACFSFUQH.js";
+} from "./chunk-KZI3YWKW.js";
+import "./chunk-JL6YH5WD.js";
 import {
   formatNumber,
   getShapeSvg,
@@ -30,14 +30,14 @@ import {
   BrushstrokeCache,
   brushstrokeDataUrl,
   isBrushstrokeBrush
-} from "./chunk-TXFWZ5ZJ.js";
+} from "./chunk-W6JDUXP3.js";
 import {
   parsePaintSource
-} from "./chunk-GCVFEPJG.js";
+} from "./chunk-ACTHSQOI.js";
 import "./chunk-4D6KP5BV.js";
 import "./chunk-ODBT55Q7.js";
-import "./chunk-OTTT5N3K.js";
 import "./chunk-IRSTHLQQ.js";
+import "./chunk-OTTT5N3K.js";
 import "./chunk-HVVR5PZW.js";
 import "./chunk-QGHEDC7B.js";
 import {