@pixerate/editor 0.267.0 → 0.268.0

package/dist/brushes/index.js

@@ -8,7 +8,7 @@ import {
   createBrushLibraryToolProvider,
   createBrushLibraryTools,
   mergeBrushPatch
-} from "../chunk-JGWVZPT6.js";
+} from "../chunk-3XDSNIGF.js";
 import "../chunk-VE6UKYQ2.js";
 import {
   BRUSH_PREVIEW_DARK_PAPER,
@@ -17,59 +17,81 @@ import {
   brushPreviewColours,
   brushPreviewStrength,
   brushPreviewsOnDark
-} from "../chunk-EYSHTYLG.js";
+} from "../chunk-LETF75CA.js";
 import {
   BRUSH_FACET_SCHEMAS,
   BRUSH_FIELDS,
+  BRUSH_FLIPS,
+  BRUSH_GRAIN_MODES,
+  BRUSH_GRAIN_SOURCE_PATTERN,
   BRUSH_HOST_PROFILES,
+  BRUSH_ID,
   BRUSH_JSON_SCHEMA,
   BRUSH_KINDS,
   BRUSH_MARKS_KINDS,
   BRUSH_MEDIA,
   BRUSH_PRESETS,
   BRUSH_ROTATIONS,
+  BRUSH_SOURCE_CHANNELS,
+  BRUSH_SOURCE_PROVIDER,
   BRUSH_SURFACES,
   BRUSH_TIP_SHAPES,
   BRUSH_TOOLS,
   BRUSH_WORD,
   BUILTIN_BRUSHES,
   BrushLibraryError,
+  BrushSourceError,
   CANVAS_PROFILE,
   DOT_ROTATIONS,
   DOT_TEXTURE_ORDERS,
   IMAGE_PROFILE,
   IMPASTO_TOOLS,
   MAX_BRUSH_PALETTE,
+  MAX_BRUSH_SOURCES,
+  MAX_BRUSH_SOURCE_INPUT_PIXELS,
+  MAX_BRUSH_SOURCE_SIZE,
   MAX_DOT_TEXTURES,
   MAX_STICKER_STAMPS,
   PAINT_PROFILE,
   PARTICLE_KINDS,
   PARTICLE_RENDERS,
   RIBBON_PAIRS,
+  TIP_GRAIN_PATTERNS,
   VECTOR_PROFILE,
   WET_BRUSH_TOOLS,
   WET_MEDIA,
   brushColourKind,
+  brushSourceFromMask,
+  brushSourceIdFromName,
+  brushSourceIdOf,
+  brushSourceIds,
+  brushSourceRef,
   brushToJSON,
   checkBrush,
   checkBrushEdit,
   createBrushLibrary,
+  decodeBrushSource,
   degrade,
   getPath,
   isBrushLibrary,
+  isBrushSourceRef,
   listPresets,
+  makeBrushSource,
   migrateBrushV1,
   normalizeBrushSpec,
   normalizePaintBrush,
   parseBrushLibrary2 as parseBrushLibrary,
+  parseBrushLibrarySources,
+  readBrushSource,
   resolveBrush,
   resolveCategory,
   resolveEngine,
   resolveWetMedium,
   setPath,
   snapshotBrushLibrary,
+  summarizeBrushSource,
   withKeptIssues
-} from "../chunk-AGNUD5BI.js";
+} from "../chunk-KZI3YWKW.js";
 import {
   STAMP_KINDS
 } from "../chunk-JL6YH5WD.js";
@@ -80,12 +102,17 @@ import "../chunk-SZTI6EER.js";
 import "../chunk-V2ZCJRDM.js";
 import {
   MAX_BRUSH_SIZE
-} from "../chunk-GCVFEPJG.js";
+} from "../chunk-ACTHSQOI.js";
 import "../chunk-4D6KP5BV.js";
 import {
   BLEND_MODES
 } from "../chunk-IRSTHLQQ.js";
+import {
+  bytesToBase64,
+  isPng
+} from "../chunk-OTTT5N3K.js";
 import "../chunk-HVVR5PZW.js";
+import "../chunk-QGHEDC7B.js";
 import {
   isDualColor
 } from "../chunk-VR6OGHU5.js";
@@ -107,6 +134,9 @@ var RENDER_LABELS = { dot: "Dots", line: "Lines", sequence: "Beads", ribbon: "Ri
 var APPLICATOR_LABELS = { brush: "Brush", tube: "Paint tube", knife: "Palette knife", roller: "Roller", gloop: "Gloop pen" };
 var WET_MEDIUM_LABELS = { watercolor: "Watercolour", gouache: "Gouache", oil: "Oil" };
 var STAMP_OPTIONS = STAMP_KINDS.map((k) => ({ value: `editor:${k}`, label: title(k) }));
+var GRAIN_MODE_LABELS = { texturised: "Texturised (stays put)", moving: "Moving (rolls with the tip)" };
+var FLIP_LABELS = { none: "None", x: "Across", y: "Along", xy: "Both" };
+var DAB_ENGINES = /* @__PURE__ */ new Set(["dab", "eraser", "mixer", "blender", "smudge"]);
 var ARIA = {
   "dynamics.rotation": "Brush rotation",
   "tip.blend": "Brush blend",
@@ -119,10 +149,12 @@ var ARIA = {
   "marks.stampRotation": "Dot rotation",
   "behaviour.wet.medium": "Wet medium",
   "behaviour.thick.applicator": "Impasto tool",
-  "light.pressure": "Light follows pressure"
+  "light.pressure": "Light follows pressure",
+  "tip.grain.source": "Tip grain",
+  "dynamics.angleJitter": "Brush rotation jitter"
 };
 var aria = (path, label) => ARIA[path] ?? `Brush ${label.toLowerCase()}`;
-function brushEditorSections(brush, profile = PAINT_PROFILE) {
+function brushEditorSections(brush, profile = PAINT_PROFILE, context = {}) {
   const resolved = resolveBrush(brush);
   const engine = resolveEngine(brush);
   const fieldOf = (facet) => BRUSH_FIELDS.find((f) => f.facet === facet && f.engines.includes(engine));
@@ -160,6 +192,7 @@ function brushEditorSections(brush, profile = PAINT_PROFILE) {
   };
   const isTool = brush.kind === "tool";
   const shape = brush.tip.shape;
+  const sourceOptions = (context.sources ?? []).map((x) => ({ value: brushSourceRef(x.id), label: x.name }));
   const marks = brush.marks?.kind ?? "continuous";
   const exchangeFull = full(brush.behaviour?.exchange?.reservoir ? profile.reservoir : profile.exchange);
   add("medium", "Medium", [
@@ -175,8 +208,20 @@ function brushEditorSections(brush, profile = PAINT_PROFILE) {
     ...tipSliders.map((c) => slider(c)),
     engine === "dab" && choice("tip.blend", "Blend", BLEND_MODES.map((m) => ({ value: m.id, label: m.label })), "normal"),
     ...shape === "bristle" && engineOk && engineControls ? engineControls.sliders.filter((c) => c.path.startsWith("bristle.")).map((c) => slider(c)) : [],
-    shape === "stamp" && engineOk && withNote({ kind: "stamps", path: "tip.stamps", label: "Stamps", ariaLabel: "Brush stamps", value: [...value("tip.stamps") ?? []], max: marks === "particles" ? MAX_DOT_TEXTURES : MAX_STICKER_STAMPS, options: STAMP_OPTIONS })
+    shape === "stamp" && engineOk && withNote({ kind: "stamps", path: "tip.stamps", label: "Stamps", ariaLabel: "Brush stamps", value: [...value("tip.stamps") ?? []], max: marks === "particles" ? MAX_DOT_TEXTURES : MAX_STICKER_STAMPS, options: marks === "objects" ? STAMP_OPTIONS : [...STAMP_OPTIONS, ...sourceOptions] })
   ]);
+  const dabs = DAB_ENGINES.has(engine) && engineOk && shape !== "bristle" && marks !== "particles" && marks !== "objects";
+  const grain = brush.tip.grain;
+  if (dabs && full(profile.tipGrain ?? "none")) {
+    add("grain", "Tip grain", [
+      choice("tip.grain.source", "Texture", [{ value: "", label: "None" }, ...options(TIP_GRAIN_PATTERNS), ...sourceOptions], ""),
+      !!grain && choice("tip.grain.mode", "Grain moves", options(BRUSH_GRAIN_MODES, GRAIN_MODE_LABELS), "texturised"),
+      !!grain && withNote({ kind: "slider", path: "tip.grain.scale", label: "Grain scale", ariaLabel: "Brush grain scale", min: 0.1, max: 8, step: 0.05, value: grain.scale ?? 1 }),
+      !!grain && withNote({ kind: "slider", path: "tip.grain.depth", label: "Grain depth", ariaLabel: "Brush grain depth", min: 0, max: 1, step: 0.01, value: grain.depth ?? 0.6 }),
+      !!grain && withNote({ kind: "slider", path: "tip.grain.contrast", label: "Grain contrast", ariaLabel: "Brush grain contrast", min: 0, max: 3, step: 0.05, value: grain.contrast ?? 1 }),
+      !!grain && toggle("tip.grain.invert", "Invert grain")
+    ]);
+  }
   if (!isTool && profile.marks.length > 1 && engineOk) {
     const particles = marks === "particles" && engineControls ? engineControls.sliders.filter((c) => c.path.startsWith("particle.") && c.path !== "particle.waveSpeed") : [];
     const objects = marks === "objects" && engineControls ? engineControls.sliders.filter((c) => c.path.startsWith("sticker.")) : [];
@@ -193,11 +238,18 @@ function brushEditorSections(brush, profile = PAINT_PROFILE) {
     ]);
   }
   const feel = BRUSH_SLIDERS.filter((c) => ["tip.smoothing", "pressureSmoothing", "dynamics.minSize", "dynamics.tiltSize", "dynamics.velocitySize"].includes(c.path)).filter((c) => !(c.path === "dynamics.tiltSize" && !full(profile.tilt)) && !(c.path === "dynamics.velocitySize" && !full(profile.velocity)));
+  const stampDabs = dabs && shape === "stamp";
+  const jitter = (path, label, max = 1, step = 0.01) => withNote({ kind: "slider", path, label, ariaLabel: aria(path, label), min: 0, max, step, value: Number(value(path) ?? 0) });
   add("feel", "Feel", [
     ...feel.map((c) => slider(c)),
     toggle("dynamics.pressureSize", "Pressure \u2192 size"),
     toggle("dynamics.pressureOpacity", "Pressure \u2192 opacity"),
-    choice("dynamics.rotation", "Rotation", options(BRUSH_ROTATIONS, ROTATION_LABELS))
+    choice("dynamics.rotation", "Rotation", options(BRUSH_ROTATIONS, ROTATION_LABELS)),
+    stampDabs && full(profile.dabCount ?? "none") && withNote({ kind: "slider", path: "dynamics.count", label: "Count", ariaLabel: "Brush dab count", min: 1, max: 16, step: 1, value: brush.dynamics?.count ?? 1 }),
+    stampDabs && jitter("dynamics.scatter", "Scatter", 4),
+    stampDabs && jitter("dynamics.angleJitter", "Rotation jitter"),
+    stampDabs && jitter("dynamics.sizeJitter", "Size jitter"),
+    stampDabs && choice("dynamics.flip", "Flip", options(BRUSH_FLIPS, FLIP_LABELS), "none")
   ]);
   const surfaces = profile.surfaces;
   const engineSliders = (engineOk ? engineControls?.sliders ?? [] : []).filter((c) => !/^(bristle|particle|sticker)\./.test(c.path) && c.path !== "light.amount" && c.path !== "impasto.rim" && c.path !== "impasto.clarity");
@@ -259,6 +311,10 @@ function hiddenLabel(issue, b) {
       return "paint pick-up";
     case "behaviour.grain":
       return "paper grain";
+    case "tip.grain":
+      return "tip grain";
+    case "dynamics.count":
+      return "several dabs per step";
     case "light":
       return "light";
     case "motion":
@@ -330,6 +386,8 @@ function setBrushEditorValue(brush, path, value) {
     next.marks = value === "continuous" ? void 0 : { kind: value };
     if (value !== "continuous" && next.tip.shape === "bristle") next.tip = { ...next.tip, shape: "round", bristle: void 0 };
     if (value === "objects") next.tip = { ...next.tip, shape: "stamp" };
+  } else if (path === "tip.grain.source" && (value === void 0 || value === "")) {
+    delete next.tip.grain;
   } else if (path === "tip.shape" && value !== "stamp") {
     next.tip = { ...next.tip, shape: value, stamps: void 0 };
     if (value !== "bristle") delete next.tip.bristle;
@@ -369,6 +427,28 @@ function brushLibraryGroups(entries, filter = {}) {
   const order = ["dry", "ink", "paint", "spray", "other", "tools"];
   return [...groups.values()].sort((a, b) => order.indexOf(a.id) - order.indexOf(b.id));
 }
+async function imageFileToPngDataUrl(file) {
+  const bytes = new Uint8Array(await file.arrayBuffer());
+  if (isPng(bytes)) return `data:image/png;base64,${bytesToBase64(bytes)}`;
+  const g = globalThis;
+  if (!g.createImageBitmap || !g.OffscreenCanvas) throw new BrushSourceError("Only PNG images can be read here; convert the image to PNG.");
+  const bitmap = await g.createImageBitmap(file);
+  const canvas = new g.OffscreenCanvas(bitmap.width, bitmap.height);
+  canvas.getContext("2d").drawImage(bitmap, 0, 0);
+  const png = new Uint8Array(await (await canvas.convertToBlob({ type: "image/png" })).arrayBuffer());
+  return `data:image/png;base64,${bytesToBase64(png)}`;
+}
+async function addBrushSourceFromFile(library, file, options2 = {}) {
+  const name = (options2.name ?? file.name?.replace(/\.[a-z0-9]+$/i, "") ?? "Image").trim() || "Image";
+  const result = await library.addSource({ name, image: await imageFileToPngDataUrl(file), origin: file.name, ...options2.channel ? { channel: options2.channel } : {} });
+  return { ...result, ref: brushSourceRef(result.source.id) };
+}
+function withBrushSource(brush, ref, as) {
+  if (as === "grain") return setBrushEditorValue(brush, "tip.grain.source", ref);
+  const stamp = brush.tip.shape === "stamp" ? { brush, problems: [] } : setBrushEditorValue(brush, "tip.shape", "stamp");
+  const r = setBrushEditorValue(stamp.brush, "tip.stamps", [ref]);
+  return { brush: r.brush, problems: [...stamp.problems, ...r.problems] };
+}
 
 // src/brushes/contract.ts
 var BRUSH_CONTRACT_FORMAT_VERSION = 1;
@@ -391,7 +471,9 @@ var BRUSH_PROFILE_JSON_SCHEMA = {
     motion: { ...SUPPORT, description: "Motion after painting." },
     colours: { type: "array", items: { type: "string", enum: ["solid", "dual", "gradient", "effect"] }, description: "Colour kinds a default colour may be." },
     velocity: { ...SUPPORT, description: "Velocity dynamics." },
-    tilt: { ...SUPPORT, description: "Tilt dynamics." }
+    tilt: { ...SUPPORT, description: "Tilt dynamics." },
+    tipGrain: { ...SUPPORT, description: "Texture inside the tip (tip.grain); missing: none." },
+    dabCount: { ...SUPPORT, description: "Several dabs per spacing step (dynamics.count); missing: none." }
   },
   required: ["id", "name", "kinds", "tools", "tipShapes", "marks", "surfaces", "exchange", "reservoir", "grain", "light", "motion", "colours", "velocity", "tilt"],
   additionalProperties: false
@@ -402,7 +484,27 @@ var BRUSH_LIBRARY_FILE_JSON_SCHEMA = {
   properties: {
     format: { type: "string", const: "pixerate-brushes", description: 'Always "pixerate-brushes".' },
     version: { type: "integer", const: 2, description: "Always 2." },
-    brushes: { type: "array", items: { $ref: "brush.schema.json" }, description: "The brushes, each a facet brush (brush.schema.json)." }
+    brushes: { type: "array", items: { $ref: "brush.schema.json" }, description: "The brushes, each a facet brush (brush.schema.json)." },
+    sources: {
+      type: "array",
+      maxItems: MAX_BRUSH_SOURCES,
+      description: "The image sources the brushes name (source:<id> in tip.stamps or tip.grain.source), bytes included.",
+      items: {
+        type: "object",
+        description: "An image source: a grey mask, 255 paints (or is a grain peak).",
+        properties: {
+          id: { type: "string", pattern: BRUSH_ID.source, description: "Source id." },
+          name: { type: "string", maxLength: 80, description: "Display name." },
+          width: { type: "integer", minimum: 1, maximum: MAX_BRUSH_SOURCE_SIZE, description: "Width in px." },
+          height: { type: "integer", minimum: 1, maximum: MAX_BRUSH_SOURCE_SIZE, description: "Height in px." },
+          image: { type: "string", pattern: "^data:image/png;base64,", description: "The mask as a greyscale PNG data: URL." },
+          licence: { type: "string", maxLength: 2e3, description: "The licence or terms it came with." },
+          origin: { type: "string", maxLength: 200, description: "Where it came from (a file or pack name)." }
+        },
+        required: ["id", "name", "width", "height", "image"],
+        additionalProperties: false
+      }
+    }
   },
   required: ["format", "version", "brushes"],
   additionalProperties: false
@@ -480,6 +582,9 @@ function brushContracts() {
 export {
   BRUSH_CONTRACT_FORMAT_VERSION,
   BRUSH_FACET_SCHEMAS,
+  BRUSH_FLIPS,
+  BRUSH_GRAIN_MODES,
+  BRUSH_GRAIN_SOURCE_PATTERN,
   BRUSH_HOST_PROFILES,
   BRUSH_JSON_SCHEMA,
   BRUSH_KINDS,
@@ -492,19 +597,27 @@ export {
   BRUSH_PREVIEW_FALLBACKS,
   BRUSH_PREVIEW_MIN_CONTRAST,
   BRUSH_PROFILE_JSON_SCHEMA,
+  BRUSH_SOURCE_CHANNELS,
+  BRUSH_SOURCE_PROVIDER,
   BRUSH_SURFACES,
   BRUSH_TIP_SHAPES,
   BRUSH_TOOLS,
   BRUSH_UNSET_PROPERTY,
   BRUSH_WORD,
   BrushLibraryError,
+  BrushSourceError,
   CANVAS_PROFILE,
   IMAGE_PROFILE,
   MAX_BRUSH_PALETTE,
+  MAX_BRUSH_SOURCES,
+  MAX_BRUSH_SOURCE_INPUT_PIXELS,
+  MAX_BRUSH_SOURCE_SIZE,
   PAINT_PROFILE,
+  TIP_GRAIN_PATTERNS,
   UNSETTABLE_BRUSH_FACETS,
   VECTOR_PROFILE,
   WET_BRUSH_TOOLS,
+  addBrushSourceFromFile,
   brushColourHex,
   brushColourKind,
   brushContracts,
@@ -515,20 +628,31 @@ export {
   brushPreviewColours,
   brushPreviewStrength,
   brushPreviewsOnDark,
+  brushSourceFromMask,
+  brushSourceIdFromName,
+  brushSourceIdOf,
+  brushSourceIds,
+  brushSourceRef,
   changedBrushPaths,
   checkBrush,
   checkBrushEdit,
   createBrushLibrary,
   createBrushLibraryToolProvider,
   createBrushLibraryTools,
+  decodeBrushSource,
   degrade,
+  imageFileToPngDataUrl,
   isBrushLibrary,
+  isBrushSourceRef,
   listPresets,
+  makeBrushSource,
   mergeBrushPatch,
   migrateBrushV1,
   newBrushFor,
   normalizeBrushSpec,
   parseBrushLibrary,
+  parseBrushLibrarySources,
+  readBrushSource,
   resolveBrush,
   resolveCategory,
   resolveEngine,
@@ -536,5 +660,7 @@ export {
   saveBrushEdit,
   setBrushEditorValue,
   snapshotBrushLibrary,
+  summarizeBrushSource,
+  withBrushSource,
   withKeptIssues
 };

package/dist/brushes/library.d.cts

@@ -9,14 +9,17 @@
  */
 import type { StorageAdapter } from '../persistence/storage.cjs';
 import { type BrushHostProfile } from './profiles.cjs';
+import { type BrushSource, type BrushSourceInput } from './sources.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[];
+    /** The image sources the brushes lay or texture with (`source:<id>`), bytes included. */
+    sources?: BrushSource[];
 }
-export type BrushLibraryErrorCode = 'unknown_brush' | 'builtin' | 'exists' | 'invalid';
+export type BrushLibraryErrorCode = 'unknown_brush' | 'unknown_source' | 'builtin' | 'exists' | 'invalid';
 /** A refusal; the message says what to do instead. */
 export declare class BrushLibraryError extends Error {
     readonly code: BrushLibraryErrorCode;
@@ -54,6 +57,16 @@ export interface ImportBrushesResult {
     replaced: string[];
     skipped: string[];
     problems: string[];
+    /** Image sources added or replaced (only when there were any). */
+    sources?: string[];
+}
+export interface AddBrushSourceResult {
+    /** The source as stored. */
+    source: BrushSource;
+    /** What reading the image changed (the channel picked, scaling). */
+    problems: string[];
+    /** It replaced a source of the same id. */
+    replaced: boolean;
 }
 export interface BrushLibraryOptions {
     /** Where the user's brushes are kept (default: memory only, gone on reload). */
@@ -88,11 +101,24 @@ export interface BrushLibrary {
     importFile(raw: unknown, options?: {
         overwrite?: boolean;
     }): Promise<ImportBrushesResult>;
+    /** The image sources brushes lay (`tip.stamps` `source:<id>`) or texture with (`tip.grain.source`), in the order added. */
+    listSources(): Promise<BrushSource[]>;
+    getSource(id: string): Promise<BrushSource | null>;
+    /**
+     * Stores an image source: an uploaded image (`BrushSourceInput`, read by `makeBrushSource`) or a
+     * source as stored. Without an id it gets one from its name; a taken id is refused unless
+     * `overwrite`.
+     */
+    addSource(input: BrushSourceInput | BrushSource, options?: {
+        overwrite?: boolean;
+    }): Promise<AddBrushSourceResult>;
     /** Called after every change. Returns an unsubscribe function. */
     subscribe(listener: () => void): () => void;
 }
 /** Whether `library` is a whole `BrushLibrary` (it can save), not only a list to read: hosts offer brush editing on one. */
 export declare function isBrushLibrary(library: unknown): library is BrushLibrary;
+/** The image sources of a library file (`sources`), each checked; bad ones are skipped and reported. */
+export declare function parseBrushLibrarySources(raw: unknown, problems?: string[]): BrushSource[];
 /**
  * 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.

package/dist/brushes/library.d.ts

@@ -9,14 +9,17 @@
  */
 import type { StorageAdapter } from '../persistence/storage.js';
 import { type BrushHostProfile } from './profiles.js';
+import { type BrushSource, type BrushSourceInput } from './sources.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[];
+    /** The image sources the brushes lay or texture with (`source:<id>`), bytes included. */
+    sources?: BrushSource[];
 }
-export type BrushLibraryErrorCode = 'unknown_brush' | 'builtin' | 'exists' | 'invalid';
+export type BrushLibraryErrorCode = 'unknown_brush' | 'unknown_source' | 'builtin' | 'exists' | 'invalid';
 /** A refusal; the message says what to do instead. */
 export declare class BrushLibraryError extends Error {
     readonly code: BrushLibraryErrorCode;
@@ -54,6 +57,16 @@ export interface ImportBrushesResult {
     replaced: string[];
     skipped: string[];
     problems: string[];
+    /** Image sources added or replaced (only when there were any). */
+    sources?: string[];
+}
+export interface AddBrushSourceResult {
+    /** The source as stored. */
+    source: BrushSource;
+    /** What reading the image changed (the channel picked, scaling). */
+    problems: string[];
+    /** It replaced a source of the same id. */
+    replaced: boolean;
 }
 export interface BrushLibraryOptions {
     /** Where the user's brushes are kept (default: memory only, gone on reload). */
@@ -88,11 +101,24 @@ export interface BrushLibrary {
     importFile(raw: unknown, options?: {
         overwrite?: boolean;
     }): Promise<ImportBrushesResult>;
+    /** The image sources brushes lay (`tip.stamps` `source:<id>`) or texture with (`tip.grain.source`), in the order added. */
+    listSources(): Promise<BrushSource[]>;
+    getSource(id: string): Promise<BrushSource | null>;
+    /**
+     * Stores an image source: an uploaded image (`BrushSourceInput`, read by `makeBrushSource`) or a
+     * source as stored. Without an id it gets one from its name; a taken id is refused unless
+     * `overwrite`.
+     */
+    addSource(input: BrushSourceInput | BrushSource, options?: {
+        overwrite?: boolean;
+    }): Promise<AddBrushSourceResult>;
     /** Called after every change. Returns an unsubscribe function. */
     subscribe(listener: () => void): () => void;
 }
 /** Whether `library` is a whole `BrushLibrary` (it can save), not only a list to read: hosts offer brush editing on one. */
 export declare function isBrushLibrary(library: unknown): library is BrushLibrary;
+/** The image sources of a library file (`sources`), each checked; bad ones are skipped and reported. */
+export declare function parseBrushLibrarySources(raw: unknown, problems?: string[]): BrushSource[];
 /**
  * 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.

package/dist/brushes/profiles.d.cts

@@ -35,6 +35,10 @@ export interface BrushHostProfile {
     velocity: BrushSupport;
     /** Tilt dynamics (needs pen tilt). */
     tilt: BrushSupport;
+    /** Texture inside the tip (`tip.grain`); missing: `none`. */
+    tipGrain?: BrushSupport;
+    /** Several dabs per spacing step (`dynamics.count` above 1); missing: `none`. */
+    dabCount?: BrushSupport;
 }
 export interface BrushIssue {
     /** The facet path the issue is about, e.g. `tip.shape`, `light`, `behaviour.exchange.reservoir`. */

package/dist/brushes/profiles.d.ts

@@ -35,6 +35,10 @@ export interface BrushHostProfile {
     velocity: BrushSupport;
     /** Tilt dynamics (needs pen tilt). */
     tilt: BrushSupport;
+    /** Texture inside the tip (`tip.grain`); missing: `none`. */
+    tipGrain?: BrushSupport;
+    /** Several dabs per spacing step (`dynamics.count` above 1); missing: `none`. */
+    dabCount?: BrushSupport;
 }
 export interface BrushIssue {
     /** The facet path the issue is about, e.g. `tip.shape`, `light`, `behaviour.exchange.reservoir`. */

package/dist/brushes/schema.d.cts

@@ -10,11 +10,15 @@ export declare const MAX_BRUSH_PALETTE = 16;
 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;
+/** Tip grain sources: the built-in patterns (not the flat `smooth`) or an image source `source:<id>`. */
+export declare const TIP_GRAIN_PATTERNS: ("canvas" | "linen" | "cold-pressed" | "hot-pressed" | "rough" | "vellum" | "laid" | "ingres" | "sanded" | "gesso")[];
+export declare const BRUSH_GRAIN_SOURCE_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 tipGrain: JsonSchema;
     readonly marks: {
         readonly continuous: JsonSchema;
         readonly scatter: JsonSchema;

package/dist/brushes/schema.d.ts

@@ -10,11 +10,15 @@ export declare const MAX_BRUSH_PALETTE = 16;
 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;
+/** Tip grain sources: the built-in patterns (not the flat `smooth`) or an image source `source:<id>`. */
+export declare const TIP_GRAIN_PATTERNS: ("canvas" | "linen" | "cold-pressed" | "hot-pressed" | "rough" | "vellum" | "laid" | "ingres" | "sanded" | "gesso")[];
+export declare const BRUSH_GRAIN_SOURCE_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 tipGrain: JsonSchema;
     readonly marks: {
         readonly continuous: JsonSchema;
         readonly scatter: JsonSchema;

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;