@pixerate/editor 0.252.0 → 0.254.0

package/dist/effects/types.d.ts

@@ -11,9 +11,10 @@ import type { FlairSvgAnimation } from '../animation-editor/flair.js';
 import type { EffectAuthoringSession, EffectAuthoringSource } from './authoring.js';
 /**
  * How an effect is drawn: a pixel shader, an animated vector picture, motion applied to someone
- * else's vector art, or a camera move, which moves a scene's camera and draws no pixels.
+ * else's vector art, a camera move, which moves a scene's camera and draws no pixels, or a
+ * timing effect, which retimes video footage and draws no pixels of its own.
  */
-export type EffectKind = 'shader' | 'vector' | 'motion' | 'camera';
+export type EffectKind = 'shader' | 'vector' | 'motion' | 'camera' | 'timing';
 /**
  * What an effect is for. An effect may have several uses.
  *
@@ -26,8 +27,10 @@ export type EffectKind = 'shader' | 'vector' | 'motion' | 'camera';
  * - `interactive`: reacts to pointer, scroll or audio input at run time.
  * - `camera`: moves a scene's camera (`cameraView`). Only `camera` effects have it, and they have
  *   no other use, so editors that draw pixels never offer them.
+ * - `timing`: retimes video footage (`timingSample`): slow motion, a reverse, a freeze, a long
+ *   exposure. Only `timing` effects have it, and they have no other use.
  */
-export type EffectUse = 'filter' | 'transition' | 'generator' | 'overlay' | 'title' | 'motion' | 'interactive' | 'camera';
+export type EffectUse = 'filter' | 'transition' | 'generator' | 'overlay' | 'title' | 'motion' | 'interactive' | 'camera' | 'timing';
 export declare const EFFECT_KINDS: readonly EffectKind[];
 export declare const EFFECT_USES: readonly EffectUse[];
 /**
@@ -66,7 +69,10 @@ export interface EffectSummary {
     transparent: boolean;
     /** True when the effect loops; its `duration` is then one cycle. */
     loop: boolean;
-    /** Length of one play (ms). Absent for effects that do not change over time. */
+    /**
+     * Length of one play (ms). Absent for effects that do not change over time, and for `timing`
+     * effects, whose length depends on their footage (`timingLength`).
+     */
     duration?: number;
     /**
      * The control (a number from 0 to 1) setting how opaque the effect's own background is: at 0
@@ -300,6 +306,59 @@ export interface CameraMoveSample {
     /** Ms of the cut, when the move has one. */
     cut?: number;
 }
+/** The frame rate footage is taken to have when a timing request does not say. */
+export declare const TIMING_DEFAULT_FPS = 30;
+/** Most footage frames one retimed frame blends (`TimingSample.frames`). */
+export declare const TIMING_MAX_FRAMES = 128;
+/** Highest footage frame rate a timing request may give. */
+export declare const TIMING_MAX_FPS = 240;
+/**
+ * How a retimed frame's footage frames combine (straight-alpha RGBA in, straight alpha out;
+ * `blendTimingFrames` is the reference):
+ *
+ * - `average`: the weighted mean in premultiplied alpha, so transparent edges do not darken.
+ *   Colour is Σ(c·a·w) / Σ(a·w) and alpha Σ(a·w) / Σw, with `a` the frame's alpha (0–1).
+ * - `lighten`: each channel's brightest. Every frame is first scaled by `weight / maxWeight`
+ *   (`k`): colour by `a·k`, alpha by `k`. The result keeps the largest scaled colour and the
+ *   largest scaled alpha, and its colour is not divided back up by its alpha, so a faded trail
+ *   stays dimmer.
+ *
+ * A single frame is shown as it is either way.
+ */
+export type TimingBlend = 'average' | 'lighten';
+export declare const TIMING_BLENDS: readonly TimingBlend[];
+/** Where a retimed frame is: what `timingSample` takes. */
+export interface TimingSampleRequest {
+    /** Ms into the retimed clip (any finite number; frames are held within the footage). */
+    time: number;
+    /** Length of the footage (ms); > 0. */
+    footage: number;
+    /** Footage frames per second, > 0 and at most `TIMING_MAX_FPS`. Default `TIMING_DEFAULT_FPS`. */
+    fps?: number;
+}
+/** One footage frame of a retimed frame. */
+export interface TimingFrame {
+    /** Footage time (ms): the start of a frame, `index * 1000 / fps`. */
+    time: number;
+    /** Share of the blend, > 0; a sample's weights add up to 1. */
+    weight: number;
+}
+/**
+ * The footage frames one retimed frame is made of, and how to blend them. The host decodes the
+ * frames from its own footage and blends them (`blendTimingFrames` does it for `EffectPixels`).
+ *
+ * - Each `time` is a footage frame's start, `index * 1000 / fps` with a whole `index` from 0 to
+ *   the footage's last frame (`ceil(footage * fps / 1000) - 1`): a time before the footage is held
+ *   on its first frame and one after it on its last.
+ * - Times are distinct (frames that land on the same footage frame are merged, their weights
+ *   added), sorted earliest first, and at most `TIMING_MAX_FRAMES` (spaced evenly when an effect
+ *   wants more).
+ * - Weights are > 0 and add up to 1.
+ */
+export interface TimingSample {
+    frames: readonly TimingFrame[];
+    blend: TimingBlend;
+}
 /** A box in a sequence's stage units (pixels of `EffectSequence.stage`). */
 export interface EffectRect {
     x: number;
@@ -516,6 +575,8 @@ export interface EffectProviderCapabilities {
     supportsAuthoring?: boolean;
     /** Lists `camera` effects and implements `cameraView` (and maybe `sampleCameraMove`). */
     supportsCamera?: boolean;
+    /** Lists `timing` effects and implements `timingLength` and `timingSample`. */
+    supportsTiming?: boolean;
     /** Implements `listTemplates`, `describeTemplate` and `instantiateTemplate`. */
     supportsTemplates?: boolean;
 }
@@ -539,7 +600,8 @@ export interface EffectProvider {
     describe(id: string): MaybePromise<EffectDescription>;
     /**
      * A pixel renderer. A `vector` effect may refuse with `EffectUnsupportedError` where it cannot
-     * lay out SVG (a Worker); a `camera` effect draws no pixels and may refuse with one saying so.
+     * lay out SVG (a Worker); `camera` and `timing` effects draw no pixels of their own and may
+     * refuse with one saying so.
      */
     createRenderer(id: string, options: EffectRendererOptions): MaybePromise<EffectRenderer>;
     /**
@@ -573,6 +635,23 @@ export interface EffectProvider {
      * `sampleEffectCameraMove` falls back to `cameraView` per frame. Errors as for `cameraView`.
      */
     sampleCameraMove?(id: string, request: CameraMoveSampleRequest): MaybePromise<CameraMoveSample>;
+    /**
+     * Ms a timing effect's retimed clip lasts for footage `footageMs` long (a speed change stretches
+     * or squeezes it, a freeze adds its hold, a boomerang goes there and back); > 0. Present when
+     * `capabilities.supportsTiming`. Synchronous and pure. Unknown ids throw `UnknownEffectError`,
+     * invalid values `EffectControlError`, and an effect that is not a timing effect (or a footage
+     * length that is not a number of ms > 0) `EffectUnsupportedError`, each with a sentence naming
+     * what is valid.
+     */
+    timingLength?(id: string, footageMs: number, values?: EffectValues): number;
+    /**
+     * The footage frames retimed frame `request.time` shows and how to blend them (see
+     * `TimingSample` for exactly what it holds). Present when `capabilities.supportsTiming`.
+     * Synchronous and pure: a frame can be drawn on its own, in any order, and the same id,
+     * request and values always give the same sample. Errors as for `timingLength`; a time that is
+     * not finite or an `fps` outside 0–`TIMING_MAX_FPS` also throw `EffectUnsupportedError`.
+     */
+    timingSample?(id: string, request: TimingSampleRequest, values?: EffectValues): TimingSample;
     /** Sequence templates, best match first. Present when `capabilities.supportsTemplates`. */
     listTemplates?(options?: EffectTemplateSearchOptions): MaybePromise<readonly EffectTemplateSummary[]>;
     /** A template with its slots. Unknown ids throw `UnknownTemplateError`. */

package/dist/image-editor/index.cjs

@@ -765,7 +765,7 @@ var _chunkPY4GWSE2cjs = require('../chunk-PY4GWSE2.cjs');
 
 
 
-var _chunkISIO63Q5cjs = require('../chunk-ISIO63Q5.cjs');
+var _chunkL2JTLW6Bcjs = require('../chunk-L2JTLW6B.cjs');
 require('../chunk-WOFXZ3XU.cjs');
 
 
@@ -4857,10 +4857,10 @@ var IMAGE_EFFECT_PLACES = {
 };
 function checkImageEffectPlace(d, place) {
   const allowed = IMAGE_EFFECT_PLACES[place];
-  const takesLayer = place === "filter" && _chunkISIO63Q5cjs.layerImageInput.call(void 0, d) !== null;
+  const takesLayer = place === "filter" && _chunkL2JTLW6Bcjs.layerImageInput.call(void 0, d) !== null;
   if (d.kind === "motion" || !takesLayer && !d.uses.some((u) => allowed.includes(u))) {
     const instead = place === "filter" && d.uses.some((u) => IMAGE_EFFECT_PLACES.layer.includes(u)) ? "; add it as an effect layer with add_effect_layer instead" : place === "layer" && d.uses.includes("filter") ? "; apply it to a layer as a smart filter with apply_effect instead" : "";
-    throw new (0, _chunkISIO63Q5cjs.EffectUnsupportedError)(
+    throw new (0, _chunkL2JTLW6Bcjs.EffectUnsupportedError)(
       `"${d.id}" (${d.name}) is a ${d.uses.join(" / ")} effect, and ${place === "filter" ? "a smart filter takes filter effects" : "an effect layer takes generator, overlay or title effects"}${instead}.`,
       d.id
     );
@@ -4884,9 +4884,9 @@ function effectPixelsToSurface(p, depth) {
   const d = new Uint16Array(f.length);
   const code = (v) => v > 0 ? v < 1 ? Math.round(v * 65535) : 65535 : 0;
   for (let i = 0; i < f.length; i += 4) {
-    d[i] = code(_chunkISIO63Q5cjs.linearToSrgb.call(void 0, f[i]));
-    d[i + 1] = code(_chunkISIO63Q5cjs.linearToSrgb.call(void 0, f[i + 1]));
-    d[i + 2] = code(_chunkISIO63Q5cjs.linearToSrgb.call(void 0, f[i + 2]));
+    d[i] = code(_chunkL2JTLW6Bcjs.linearToSrgb.call(void 0, f[i]));
+    d[i + 1] = code(_chunkL2JTLW6Bcjs.linearToSrgb.call(void 0, f[i + 1]));
+    d[i + 2] = code(_chunkL2JTLW6Bcjs.linearToSrgb.call(void 0, f[i + 2]));
     d[i + 3] = code(f[i + 3]);
   }
   return _chunk2VX55NFMcjs.surfaceFromDeepPixels.call(void 0, { width: p.width, height: p.height, data: d }, 4);
@@ -4903,7 +4903,7 @@ var ImageEffectsEngine = (_class9 = class {
   __init49() {this.generation = 0}
   
   constructor(options = {}) {;_class9.prototype.__init44.call(this);_class9.prototype.__init45.call(this);_class9.prototype.__init46.call(this);_class9.prototype.__init47.call(this);_class9.prototype.__init48.call(this);_class9.prototype.__init49.call(this);
-    this.slot = _nullishCoalesce(options.slot, () => ( new (0, _chunkISIO63Q5cjs.EffectsSlot)()));
+    this.slot = _nullishCoalesce(options.slot, () => ( new (0, _chunkL2JTLW6Bcjs.EffectsSlot)()));
     this.maxEntries = _nullishCoalesce(options.maxEntries, () => ( 24));
     this.pool = new (0, _chunkPY4GWSE2cjs.EffectRendererPool)({ maxRenderers: options.maxRenderers });
     this.detach = this.slot.subscribe(() => {
@@ -4951,7 +4951,7 @@ var ImageEffectsEngine = (_class9 = class {
   /** A filter effect over `source`: its result, or (for an overlay) the effect drawn over it. */
   async filter(provider, effect, values, source) {
     const d = await this.describe(provider, effect);
-    const input = _chunkISIO63Q5cjs.layerImageInput.call(void 0, d);
+    const input = _chunkL2JTLW6Bcjs.layerImageInput.call(void 0, d);
     const out = await this.render(provider, effect, source.width, source.height, 8, { time: 0, values, ...input ? { inputs: { [input]: source } } : {} });
     return input ? out.data : over(source.data, out.data);
   }
@@ -4963,7 +4963,7 @@ var ImageEffectsEngine = (_class9 = class {
     const provider = this.slot.require();
     const depth = _nullishCoalesce(size.depth, () => ( 8));
     const out = await this.render(provider, effect, size.width, size.height, depth, { time: _nullishCoalesce(size.time, () => ( 0)), values });
-    return out.width === size.width && out.height === size.height ? out : _chunkISIO63Q5cjs.createEffectPixels.call(void 0, size.width, size.height);
+    return out.width === size.width && out.height === size.height ? out : _chunkL2JTLW6Bcjs.createEffectPixels.call(void 0, size.width, size.height);
   }
   /** Why the result for `key` failed, if it did. */
   failure(key2) {
@@ -6225,7 +6225,7 @@ var ImageEditorController = (_class12 = class {
   __init84() {this.selectionWorker = null}
   __init85() {this.documentOpener = null}
   /** The effects provider slot (see `setEffectsProvider`). */
-  __init86() {this.effects = new (0, _chunkISIO63Q5cjs.EffectsSlot)()}
+  __init86() {this.effects = new (0, _chunkL2JTLW6Bcjs.EffectsSlot)()}
   /** Renders provider effects: effect smart filter results and effect layers. */
   __init87() {this.effectsEngine = new ImageEffectsEngine({ slot: this.effects })}
   __init88() {this.effectRefresh = "none"}
@@ -6561,7 +6561,7 @@ var ImageEditorController = (_class12 = class {
    */
   async applyEffectFilter(layerId, effect, options = {}) {
     const d = await this.describeEffect(effect, "filter");
-    const values = _chunkISIO63Q5cjs.resolveEffectValues.call(void 0, d, options.values);
+    const values = _chunkL2JTLW6Bcjs.resolveEffectValues.call(void 0, d, options.values);
     const found = _chunkDPYAO5U6cjs.findLayer.call(void 0, this.state.layers, layerId);
     if (!found) throw new (0, _chunkJFHBXNR2cjs.LayerOperationError)(`There is no layer "${layerId}"; call list_layers for the layer ids.`);
     let layers = this.state.layers;
@@ -6603,7 +6603,7 @@ var ImageEditorController = (_class12 = class {
         else if (k in d.controls.properties) base[k] = d.defaults[k];
         else throw new (0, _chunkJFHBXNR2cjs.LayerOperationError)(`"${k}" is not a control of "${d.id}"; its controls are ${Object.keys(d.controls.properties).join(", ")}.`);
       }
-      update.values = { ...base, ..._chunkISIO63Q5cjs.resolveEffectValues.call(void 0, { ...d, defaults: base }, given) };
+      update.values = { ...base, ..._chunkL2JTLW6Bcjs.resolveEffectValues.call(void 0, { ...d, defaults: base }, given) };
     }
     for (const k of ["enabled", "blend", "opacity", "preserveTransparency"]) if (changes[k] !== void 0) update[k] = changes[k];
     let res = _chunkJFHBXNR2cjs.updateSmartFilter.call(void 0, this.state.layers, layerId, filterId, update, this.canvasSize);
@@ -6630,7 +6630,7 @@ var ImageEditorController = (_class12 = class {
     const id = options.id && !ids.has(options.id) ? options.id : _chunkJFHBXNR2cjs.newLayerId.call(void 0, );
     const placed = _chunkJFHBXNR2cjs.placeLayer.call(void 0, this.state.layers, { type: "pixel", id, name: "", visible: true, opacity: 1, blend: "normal", surface: _chunk474IQG74cjs.emptySurface.call(void 0, 4), offset: { x: 0, y: 0 } }, this.newLayerPlacement(options));
     if (options.clipped) requireClipBase(placed, id);
-    const values = _chunkISIO63Q5cjs.resolveEffectValues.call(void 0, d, withBackgroundOpacity(d, options.values, hasLayersBelow(placed, id)));
+    const values = _chunkL2JTLW6Bcjs.resolveEffectValues.call(void 0, d, withBackgroundOpacity(d, options.values, hasLayersBelow(placed, id)));
     const { width, height } = this.naturalSize;
     const pixels = await this.effectsEngine.renderLayer(d.id, values, { width, height, depth: this.bitDepth, time });
     const layer = {
@@ -6675,7 +6675,7 @@ var ImageEditorController = (_class12 = class {
       else if (k in d.controls.properties) base[k] = d.defaults[k];
       else throw new (0, _chunkJFHBXNR2cjs.LayerOperationError)(`"${k}" is not a control of "${d.id}"; its controls are ${Object.keys(d.controls.properties).join(", ")}.`);
     }
-    const values = { ...base, ..._chunkISIO63Q5cjs.resolveEffectValues.call(void 0, { ...d, defaults: base }, given) };
+    const values = { ...base, ..._chunkL2JTLW6Bcjs.resolveEffectValues.call(void 0, { ...d, defaults: base }, given) };
     const time = changes.time === void 0 ? _nullishCoalesce(g.time, () => ( 0)) : checkEffectTime(changes.time);
     const animate = changes.animate === void 0 ? g.animate : changes.animate === null ? void 0 : checkEffectAnimation(changes.animate);
     const { width, height } = this.naturalSize;
@@ -21492,7 +21492,7 @@ function createImageEffectsToolProvider(controller, options = {}) {
     return { target, effect: _nullishCoalesce(effects.find((e) => e.id === instance), () => ( effects[effects.length - 1])), effects, ...extra };
   };
   const plainValues = (v) => v;
-  return withImagePlayback(_chunkISIO63Q5cjs.createEffectToolProvider.call(void 0, {
+  return withImagePlayback(_chunkL2JTLW6Bcjs.createEffectToolProvider.call(void 0, {
     id: _nullishCoalesce(options.id, () => ( "image-effects")),
     namespace: options.namespace,
     title: "Image effects",

package/dist/image-editor/index.js

@@ -765,7 +765,7 @@ import {
   layerImageInput,
   linearToSrgb,
   resolveEffectValues
-} from "../chunk-JA57JIT5.js";
+} from "../chunk-MV7CYFMJ.js";
 import "../chunk-V2ZCJRDM.js";
 import {
   BrushstrokeCache,

package/dist/paint-editor/brush-controls.d.cts

@@ -0,0 +1,57 @@
+/**
+ * The brush panel's slider tables and the controls each engine adds (`brushEngineControls`),
+ * as plain data: paths into the engine brush. No renderer is imported, so the brush editor
+ * descriptor (`@pixerate/editor/brushes` `brushEditorSections`) reuses them without bundling the
+ * paint engine.
+ */
+import type { PaintBrush, PaintBrushInput } from './brushes.cjs';
+/** One slider of a panel: a path into the brush (or paper) settings. */
+export interface SliderControl {
+    path: string;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+}
+export declare const BRUSH_SLIDERS: readonly SliderControl[];
+export interface BrushEngineControls {
+    /** Section heading. */
+    title: string;
+    sliders: readonly SliderControl[];
+    /** Where the RGB / pigment choice is stored, or `null` when the engine has none. */
+    mixingPath: 'behavior.mixing' | 'blender.mixing' | 'smudge.mixing' | null;
+    /** The dirty-brush toggle (`behavior.dirty`). */
+    dirty: boolean;
+    /** The multi-colour controls (`behavior.multicolor`; the panels show the brush gradient, `brush.paint`, instead). */
+    multicolor: boolean;
+    /** Load / Clean buttons and a swatch of what the brush carries. */
+    load: boolean;
+    /** The wet tool menu (`wet.tool`, `WET_TOOLS`) and medium menu (`wet.medium`, `WET_MEDIA`). */
+    wetTool?: boolean;
+    /** The impasto tool menu (`impasto.tool`, `IMPASTO_TOOLS`). */
+    impastoTool?: boolean;
+    /**
+     * The particle menus: kind and render (`particle.kind`, `particle.render`), ribbon pairs
+     * (`particle.ribbonPairs`), and the textured-dot stamps, order and rotation
+     * (`particle.dotTextures` up to `MAX_DOT_TEXTURES` of `STAMP_KINDS`, `dotTextureOrder`, `dotRotation`).
+     */
+    particleMenus?: boolean;
+    /** The sticker picker for the brush's stickers (`sticker.stamps`, refs from the sticker library; `toggleStickerRef`). */
+    stickerStamps?: boolean;
+    /** Light paint: the "light follows pressure" toggle (`light.pressure`); the Light slider is in `sliders`. */
+    light?: boolean;
+}
+/**
+ * The controls the active brush's engine adds to the brush panel (`null` for the eraser):
+ * blender strength and blend distance; smudge strength and length; the Mixer Brush's pick-up,
+ * mix and load; a dab brush's pick-up and mix ratios. Every engine but the eraser has an RGB /
+ * pigment choice; dab and mixer brushes also have the dirty and multi-colour controls. Pick-up
+ * and mix always go through `behavior`, which keeps a Mixer Brush's `mixer` block in sync.
+ */
+export declare function brushEngineControls(brush: Pick<PaintBrush, 'engine'> & {
+    wet?: PaintBrush['wet'];
+}): BrushEngineControls | null;
+/** The multi-colour sliders for a mode: softness, and dabs per colour in `dab` mode. */
+export declare function multiColorSliders(mode: string): readonly SliderControl[];
+/** A brush change setting `path` (e.g. `smudge.mixing`, `behavior.dirty`) to any value, keeping the rest of its block. */
+export declare function patchBrushValue(brush: PaintBrush, path: string, value: unknown): PaintBrushInput;

package/dist/paint-editor/brush-controls.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The brush panel's slider tables and the controls each engine adds (`brushEngineControls`),
+ * as plain data: paths into the engine brush. No renderer is imported, so the brush editor
+ * descriptor (`@pixerate/editor/brushes` `brushEditorSections`) reuses them without bundling the
+ * paint engine.
+ */
+import type { PaintBrush, PaintBrushInput } from './brushes.js';
+/** One slider of a panel: a path into the brush (or paper) settings. */
+export interface SliderControl {
+    path: string;
+    label: string;
+    min: number;
+    max: number;
+    step: number;
+}
+export declare const BRUSH_SLIDERS: readonly SliderControl[];
+export interface BrushEngineControls {
+    /** Section heading. */
+    title: string;
+    sliders: readonly SliderControl[];
+    /** Where the RGB / pigment choice is stored, or `null` when the engine has none. */
+    mixingPath: 'behavior.mixing' | 'blender.mixing' | 'smudge.mixing' | null;
+    /** The dirty-brush toggle (`behavior.dirty`). */
+    dirty: boolean;
+    /** The multi-colour controls (`behavior.multicolor`; the panels show the brush gradient, `brush.paint`, instead). */
+    multicolor: boolean;
+    /** Load / Clean buttons and a swatch of what the brush carries. */
+    load: boolean;
+    /** The wet tool menu (`wet.tool`, `WET_TOOLS`) and medium menu (`wet.medium`, `WET_MEDIA`). */
+    wetTool?: boolean;
+    /** The impasto tool menu (`impasto.tool`, `IMPASTO_TOOLS`). */
+    impastoTool?: boolean;
+    /**
+     * The particle menus: kind and render (`particle.kind`, `particle.render`), ribbon pairs
+     * (`particle.ribbonPairs`), and the textured-dot stamps, order and rotation
+     * (`particle.dotTextures` up to `MAX_DOT_TEXTURES` of `STAMP_KINDS`, `dotTextureOrder`, `dotRotation`).
+     */
+    particleMenus?: boolean;
+    /** The sticker picker for the brush's stickers (`sticker.stamps`, refs from the sticker library; `toggleStickerRef`). */
+    stickerStamps?: boolean;
+    /** Light paint: the "light follows pressure" toggle (`light.pressure`); the Light slider is in `sliders`. */
+    light?: boolean;
+}
+/**
+ * The controls the active brush's engine adds to the brush panel (`null` for the eraser):
+ * blender strength and blend distance; smudge strength and length; the Mixer Brush's pick-up,
+ * mix and load; a dab brush's pick-up and mix ratios. Every engine but the eraser has an RGB /
+ * pigment choice; dab and mixer brushes also have the dirty and multi-colour controls. Pick-up
+ * and mix always go through `behavior`, which keeps a Mixer Brush's `mixer` block in sync.
+ */
+export declare function brushEngineControls(brush: Pick<PaintBrush, 'engine'> & {
+    wet?: PaintBrush['wet'];
+}): BrushEngineControls | null;
+/** The multi-colour sliders for a mode: softness, and dabs per colour in `dab` mode. */
+export declare function multiColorSliders(mode: string): readonly SliderControl[];
+/** A brush change setting `path` (e.g. `smudge.mixing`, `behavior.dirty`) to any value, keeping the rest of its block. */
+export declare function patchBrushValue(brush: PaintBrush, path: string, value: unknown): PaintBrushInput;

package/dist/paint-editor/brush-library-tools.d.cts

@@ -0,0 +1,15 @@
+/**
+ * The shared brush library's agent tools for a paint editor (`createPaintBrushLibraryToolProvider`),
+ * with `preview_brush` painted by this editor.
+ */
+import { type BrushLibraryToolProviderOptions } from '../brushes/tools.cjs';
+import type { AgentToolProvider } from '../tools/registry.cjs';
+import type { PaintEditorController } from './controller.cjs';
+export type PaintBrushLibraryToolProviderOptions = Omit<BrushLibraryToolProviderOptions, 'renderPreview'>;
+/**
+ * The brush library tools for a paint editor (`@pixerate/editor/brushes`' provider on the
+ * editor's `brushLibrary`, `PAINT_PROFILE`), with `preview_brush` painting the test stroke on the
+ * editor's paper. Register it next to `createPaintEditorToolProvider`: it lists, saves, shares and
+ * previews the brushes `set_brush` picks.
+ */
+export declare function createPaintBrushLibraryToolProvider(controller: PaintEditorController, options?: PaintBrushLibraryToolProviderOptions): AgentToolProvider;

package/dist/paint-editor/brush-library-tools.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The shared brush library's agent tools for a paint editor (`createPaintBrushLibraryToolProvider`),
+ * with `preview_brush` painted by this editor.
+ */
+import { type BrushLibraryToolProviderOptions } from '../brushes/tools.js';
+import type { AgentToolProvider } from '../tools/registry.js';
+import type { PaintEditorController } from './controller.js';
+export type PaintBrushLibraryToolProviderOptions = Omit<BrushLibraryToolProviderOptions, 'renderPreview'>;
+/**
+ * The brush library tools for a paint editor (`@pixerate/editor/brushes`' provider on the
+ * editor's `brushLibrary`, `PAINT_PROFILE`), with `preview_brush` painting the test stroke on the
+ * editor's paper. Register it next to `createPaintEditorToolProvider`: it lists, saves, shares and
+ * previews the brushes `set_brush` picks.
+ */
+export declare function createPaintBrushLibraryToolProvider(controller: PaintEditorController, options?: PaintBrushLibraryToolProviderOptions): AgentToolProvider;

package/dist/paint-editor/brush-library.d.cts

@@ -0,0 +1,29 @@
+/**
+ * The paint editor's side of the shared brush library (`@pixerate/editor/brushes`): the
+ * controller's synchronous copy of the library (each brush as stored, as facets, and as the
+ * engine paints it), and facet brushes for engine brushes edited by their settings.
+ */
+import type { StorageAdapter } from '../persistence/storage.cjs';
+import type { Brush } from '../brushes/types.cjs';
+import { type PaintBrush } from './brushes.cjs';
+/** A library brush as the paint editor keeps it: its facets and the engine form it paints with. */
+export interface LibraryBrush {
+    spec: Brush;
+    brush: PaintBrush;
+    builtin: boolean;
+}
+export declare const copyJSON: <T>(v: T) => T;
+export declare function libraryBrush(spec: Brush, builtin: boolean, resolved?: PaintBrush): LibraryBrush;
+/** The built-in presets, paired with the engine brushes they resolve to (`BUILTIN_BRUSHES`, in the same order). */
+export declare function builtinLibraryBrushes(): readonly LibraryBrush[];
+/** Storage that starts with these brushes (a version 1 file) and keeps the rest in memory; none without brushes. */
+export declare function seededStorage(brushes: readonly PaintBrush[]): Pick<StorageAdapter, 'get' | 'set'> | undefined;
+/**
+ * The facet brush an engine brush edited by its settings amounts to (`migrateBrushV1`), keeping
+ * what the engine doesn't read from the brush it was edited from: description, tags, medium and
+ * variety, suggested colours, light spill and glow, and motion hints. Hints that would change how
+ * it paints are left out.
+ */
+export declare function brushSpecOf(next: PaintBrush, from: Brush): Brush;
+/** The engine settings `next` changes on `base`, as `normalizePaintBrush(changes, base)` takes them (lists whole). */
+export declare function engineChanges(base: PaintBrush, next: PaintBrush): Omit<Partial<PaintBrush>, 'id'>;

package/dist/paint-editor/brush-library.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The paint editor's side of the shared brush library (`@pixerate/editor/brushes`): the
+ * controller's synchronous copy of the library (each brush as stored, as facets, and as the
+ * engine paints it), and facet brushes for engine brushes edited by their settings.
+ */
+import type { StorageAdapter } from '../persistence/storage.js';
+import type { Brush } from '../brushes/types.js';
+import { type PaintBrush } from './brushes.js';
+/** A library brush as the paint editor keeps it: its facets and the engine form it paints with. */
+export interface LibraryBrush {
+    spec: Brush;
+    brush: PaintBrush;
+    builtin: boolean;
+}
+export declare const copyJSON: <T>(v: T) => T;
+export declare function libraryBrush(spec: Brush, builtin: boolean, resolved?: PaintBrush): LibraryBrush;
+/** The built-in presets, paired with the engine brushes they resolve to (`BUILTIN_BRUSHES`, in the same order). */
+export declare function builtinLibraryBrushes(): readonly LibraryBrush[];
+/** Storage that starts with these brushes (a version 1 file) and keeps the rest in memory; none without brushes. */
+export declare function seededStorage(brushes: readonly PaintBrush[]): Pick<StorageAdapter, 'get' | 'set'> | undefined;
+/**
+ * The facet brush an engine brush edited by its settings amounts to (`migrateBrushV1`), keeping
+ * what the engine doesn't read from the brush it was edited from: description, tags, medium and
+ * variety, suggested colours, light spill and glow, and motion hints. Hints that would change how
+ * it paints are left out.
+ */
+export declare function brushSpecOf(next: PaintBrush, from: Brush): Brush;
+/** The engine settings `next` changes on `base`, as `normalizePaintBrush(changes, base)` takes them (lists whole). */
+export declare function engineChanges(base: PaintBrush, next: PaintBrush): Omit<Partial<PaintBrush>, 'id'>;

package/dist/paint-editor/controller.d.cts

@@ -18,7 +18,10 @@ import { type LayerLocks } from '../raster/layers.cjs';
 import { type LayerEffect, type LayerEffectKind, type LayerEffects } from '../raster/effects/model.cjs';
 import type { EffectPattern } from '../raster/effects/patterns.cjs';
 import { TiledSurface, type RasterRect, type Tile } from '../raster/surface.cjs';
-import { type PaintBrushInput, type BrushLibraryFile, type PaintBrush } from './brushes.cjs';
+import { type PaintBrushInput, type PaintBrush } from './brushes.cjs';
+import { type BrushLibrary, type BrushLibraryFile } from '../brushes/library.cjs';
+import { type BrushPatch, type UnsettableBrushFacet } from '../brushes/patch.cjs';
+import type { Brush } from '../brushes/types.cjs';
 import { type PaintCanvas, type PaintDocumentState, type PaintLayer } from './document.cjs';
 import { type ImageEncoder, type ImageFormat } from './encode.cjs';
 import type { PenPoint } from './engine.cjs';
@@ -57,7 +60,12 @@ export interface PaintEditorOptions extends Partial<PaintCanvas> {
     paper?: Partial<PaperSettings> | string;
     /** Active brush id (default `pencil-6b`). */
     brushId?: string;
-    /** Saved user brushes to start the library with. */
+    /**
+     * The brush library: built-in presets plus saved brushes, on any storage. Pass one library to
+     * every editor so a brush saved in one shows in all of them (default: a library in memory).
+     */
+    brushLibrary?: BrushLibrary;
+    /** Saved user brushes to start the default library with (or to add to `brushLibrary`). */
     brushes?: readonly PaintBrush[];
     /** Paint colour #rrggbb (default #1f2937). */
     color?: string;
@@ -296,8 +304,17 @@ export declare class PaintEditorController {
     private undoStack;
     private redoStack;
     private readonly historyLimit;
+    /** The brush library this editor lists, saves into and paints from (shared with other editors when the host passes one). */
+    readonly brushLibrary: BrushLibrary;
     private brush;
-    private userBrushes;
+    /** The active brush as facets (what `getBrushSpec` and saving use). */
+    private brushSpec;
+    /** The library's brushes as last read, each as stored (facets) and as the engine paints it. */
+    private brushEntries;
+    /** The brush id asked for at construction, while the library had not listed it yet. */
+    private pendingBrushId;
+    private brushesLoaded;
+    private readonly unsubscribeLibrary;
     /** The library list in the state (the same array until the user brushes change, so thumbnails are not redrawn). */
     private library;
     private color;
@@ -673,39 +690,81 @@ export declare class PaintEditorController {
         source: PaintEffectSource;
         amount: number;
     }>;
+    private findEntry;
     private findBrush;
-    /** A library brush by id (`undefined` when unknown). */
-    getBrush(id: string): PaintBrush | undefined;
+    private requireEntry;
     private requireBrush;
+    /** Reads the library again (after a change anywhere it is shared). */
+    private refreshBrushes;
+    /** Resolves once the brush library has been read (user brushes kept in storage are listed from then on). */
+    whenBrushesLoaded(): Promise<void>;
+    /** A library brush by id, as the engine paints it (`undefined` when unknown). */
+    getBrush(id: string): PaintBrush | undefined;
+    /** A library brush by id as stored (its facets), or without an id the active brush as edited. */
+    getBrushSpec(id?: string): Brush | undefined;
     /**
-     * Chooses the active brush (`id`: a library brush) and / or changes its settings. Editor state,
-     * not an undo step. Returns the active brush.
+     * Chooses the active brush (`id`: a library brush) and / or changes its engine settings. Editor
+     * state, not an undo step. Returns the active brush. `setBrushFacets` changes it by facets.
      */
     setBrush(update?: {
         id?: string;
     } & Omit<PaintBrushInput, 'id'>): PaintBrush;
-    /** Saves the active brush (or `brush`) into the user library under `id` / `name`. */
+    /**
+     * Chooses the active brush (`id`: a library brush) and / or lays a facet patch over it (objects
+     * merge, lists and values replace, as the library's `update_brush` does). Editor state, not an
+     * undo step. `unset` removes whole facets first. Returns the active brush as the engine paints
+     * it, its facets, and what was clamped or dropped.
+     */
+    setBrushFacets(patch?: BrushPatch, id?: string, unset?: readonly UnsettableBrushFacet[]): {
+        brush: PaintBrush;
+        spec: Brush;
+        problems: string[];
+    };
+    /**
+     * Makes `spec` (a whole facet brush, as the brush editor edits it) the active brush, keeping the
+     * active brush's id. Editor state, not an undo step. Returns it as the engine paints it, its
+     * facets, and what was clamped or dropped.
+     */
+    setBrushSpec(spec: Brush): {
+        brush: PaintBrush;
+        spec: Brush;
+        problems: string[];
+    };
+    /**
+     * The engine settings a facet patch changes on a brush (`from`: a library brush id or a brush as
+     * painted; default the active brush), as `paintStroke`'s and `updateStroke`'s `brush` take them.
+     */
+    brushChanges(patch: BrushPatch, from?: string | PaintBrush): Omit<PaintBrushInput, 'id'>;
+    private readBrushPatch;
+    private useBrush;
+    /**
+     * Saves the active brush (or `brush`, engine settings on top of it) into the brush library under
+     * `id` / `name`, replacing a user brush with that id. Built-in ids are refused. Resolves with the
+     * saved brush.
+     */
     saveBrush(options: {
         id: string;
         name?: string;
         brush?: PaintBrushInput;
-    }): PaintBrush;
-    removeBrush(id: string): void;
-    /** The user's saved brushes. */
+    }): Promise<PaintBrush>;
+    /** Removes a user brush from the brush library (built-in brushes can't be removed). */
+    removeBrush(id: string): Promise<void>;
+    /** The user's saved brushes, as the engine paints them. */
     getUserBrushes(): PaintBrush[];
-    /** A brush library file of the given brushes (default: the user's brushes). */
-    exportBrushes(ids?: readonly string[]): BrushLibraryFile;
+    /** A brush library file (version 2) of the given brushes (default: the user's brushes). */
+    exportBrushes(ids?: readonly string[]): Promise<BrushLibraryFile>;
     /**
-     * Adds the brushes of a library file to the user library. A brush whose id is taken is skipped
-     * unless `replace` (built-in ids are always skipped). Returns the ids added and the problems.
+     * Adds the brushes of a library file (version 1 or 2) to the brush library. A brush whose id is
+     * taken is skipped unless `replace` (built-in ids are always skipped). Resolves with the ids
+     * added or replaced, the ids skipped and the problems.
      */
     importBrushes(file: unknown, options?: {
         replace?: boolean;
-    }): {
+    }): Promise<{
         added: string[];
         skipped: string[];
         problems: string[];
-    };
+    }>;
     /** A thumbnail of a brush: a test stroke on the current paper. */
     brushThumbnail(id: string, options?: {
         width?: number;