@pixerate/editor 0.246.0 → 0.249.0

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

@@ -6,8 +6,12 @@
  *   rules. `string`: strands of masses on springs, dragged behind the pen like hair or wet string;
  *   `spring`: each particle tied to the pen by a spring, overshooting and wobbling; `orbit`:
  *   particles circling the pen (spirograph curls); `flow`: particles thrown off the pen and carried
- *   by a swirling flow field until they fade. Each is drawn as `dot`s, a continuous `line`, or a
- *   `sequence` of beads spaced along its path.
+ *   by a swirling flow field until they fade; `elastic`: strands whose masses keep a rest length,
+ *   stretching when the pen is fast and snapping back; `fuzzy`: strings that wind, each strand
+ *   waving out of step with the others. Each is drawn as `dot`s (round, or stamped with up to four
+ *   textures), a continuous `line`, a `sequence` of beads spaced along its path, or a `ribbon`:
+ *   the area between neighbouring particles' paths filled, with their paths as its edges. Any kind
+ *   can wave: each particle's drawn place moves sideways on a sine along the pen's path.
  * - **Bristle brushes** (`engine: 'bristle'`): a tuft of bristles, each its own thin line. Pressure
  *   splays the tuft, tilt flattens it, and bristles lag behind the tip by their stiffness, so they
  *   bend into curves at turns; each bristle carries its own paint and runs dry at its own pace, so
@@ -19,11 +23,12 @@
  */
 import { CoverageMap } from '../paint/brush.cjs';
 import { type PaintGradientSource } from '../paint/gradient-paint.cjs';
-import type { RasterRect } from '../raster/surface.cjs';
+import { type RasterRect } from '../raster/surface.cjs';
 import type { PaintBrush } from './brushes.cjs';
 import { type EffectPaintPixels } from './effect-paint.cjs';
 import { PenDabWalker, PenSmoother, type PenDab, type PenPoint, type StrokeCopy } from './engine.cjs';
 import { type PaperGrain } from './paper.cjs';
+import { type StampKind } from './stickers.cjs';
 export interface ProceduralStrokeOptions {
     grain: PaperGrain | null;
     paperDepth: number;
@@ -71,13 +76,36 @@ declare abstract class MarkStroke implements CoverageStroke {
     protected abstract advance(copy: number, d: PenDab, rects: RasterRect[]): void;
     /** Stamps one round mark of radius `r` at (x, y) with flow `alpha` towards `opacity`. */
     protected mark(x: number, y: number, r: number, alpha: number, opacity: number, pressure: number, rects: RasterRect[]): void;
+    /**
+     * Stamps a textured mark: `kind` from the sticker stamps over a square of half-size `r`, turned
+     * `rotation` radians clockwise, with flow `alpha` towards `opacity`. Small marks are supersampled.
+     */
+    protected stamp(x: number, y: number, r: number, kind: StampKind, rotation: number, seed: number, alpha: number, opacity: number, pressure: number, rects: RasterRect[]): void;
+    /** A scratch buffer of `n` values (reused; valid until the next mark). */
+    protected scratch(n: number): Float32Array;
+    /**
+     * Lays coverage `vals` over `rect` towards `opacity`: paper grain, then effect paint or the
+     * colour of a mark at (x, y) (gradient paint), into the stroke's coverage.
+     */
+    protected lay(rect: RasterRect, vals: Float32Array, opacity: number, pressure: number, x: number, y: number, rects: RasterRect[]): void;
     /** Marks along a segment, spaced by a fraction of the radius. */
     protected segment(x0: number, y0: number, x1: number, y1: number, r: number, alpha: number, opacity: number, pressure: number, rects: RasterRect[]): void;
 }
-export type ParticleKind = 'string' | 'spring' | 'orbit' | 'flow';
+export type ParticleKind = 'string' | 'spring' | 'orbit' | 'flow' | 'elastic' | 'fuzzy';
 export declare const PARTICLE_KINDS: readonly ParticleKind[];
-export type ParticleRender = 'dot' | 'line' | 'sequence';
+export type ParticleRender = 'dot' | 'line' | 'sequence' | 'ribbon';
 export declare const PARTICLE_RENDERS: readonly ParticleRender[];
+/** Ribbon: which particles' paths are joined (`adjacent`: each to its neighbour; `first-last`: one band between the outermost two). */
+export type RibbonPairs = 'adjacent' | 'first-last';
+export declare const RIBBON_PAIRS: readonly RibbonPairs[];
+/** Textured dots: the stamps in turn, or one picked at random (seeded) per dot. */
+export type DotTextureOrder = 'sequence' | 'random';
+export declare const DOT_TEXTURE_ORDERS: readonly DotTextureOrder[];
+/** Textured dots: turned with the particle's motion, at random, or at the tip angle. */
+export type DotRotation = 'follow' | 'random' | 'fixed';
+export declare const DOT_ROTATIONS: readonly DotRotation[];
+/** Textured dots: at most this many stamps. */
+export declare const MAX_DOT_TEXTURES = 4;
 /** Particle engine settings (each 0..1 unless noted). */
 export interface ParticleSettings {
     kind: ParticleKind;
@@ -100,17 +128,66 @@ export interface ParticleSettings {
     life: number;
     /** Sequence: spacing of the beads along each path. */
     interval: number;
+    /** Ribbon: opacity of the fill between the paths, relative to their edges. */
+    ribbonFill: number;
+    /** Ribbon: which paths are joined. */
+    ribbonPairs: RibbonPairs;
+    /** Wave: how far each particle's drawn place swings sideways, as a fraction of the tip size (0: no wave). */
+    waveAmplitude: number;
+    /** Wave: wavelength in px of pen travel, 4..2000. */
+    waveLength: number;
+    /** Wave: how fast the waves run (0: they stand still on the path; 1: about four a second while the pen moves). */
+    waveSpeed: number;
+    /** Wave: how far out of step the particles' waves are (0: all in step; 1: random phases). */
+    wavePhaseJitter: number;
+    /** Dots and beads: up to four sticker stamps drawn instead of round marks (empty: round). */
+    dotTextures: StampKind[];
+    dotTextureOrder: DotTextureOrder;
+    dotRotation: DotRotation;
 }
 export declare const DEFAULT_PARTICLE: Readonly<ParticleSettings>;
 export declare function normalizeParticle(raw?: Partial<ParticleSettings>, base?: ParticleSettings): ParticleSettings;
+/**
+ * Adds the area polygon `pts` (x, y pairs, even-odd) covers in each pixel of `rect`, times `weight`, to `out`,
+ * exactly across each of `RIBBON_SUB` sub-rows per row. Points on an edge two polygons share
+ * count for exactly one of them, so polygons that tile a region add up to it with no seams.
+ */
+export declare function addPolygonArea(pts: readonly number[], rect: RasterRect, out: Float32Array, weight?: number): void;
 /** A particle-brush stroke. */
 export declare class ParticleStroke extends MarkStroke {
     private readonly sets;
+    /** Ribbon pairs per copy: particles in their order around the pen (non-flow kinds). */
+    private readonly orders;
     private readonly s;
     private spawn;
+    /** Textured dots drawn so far, per copy (sequence order, random picks). */
+    private readonly dots;
+    /** Ribbon fill: the area each pixel has had so far this stroke (telescoped into the coverage). */
+    private readonly filled;
+    private pts;
     constructor(brush: PaintBrush, options: ProceduralStrokeOptions);
+    /** Strand kinds: a chain of masses behind each particle. */
+    private get strands();
+    private newParticle;
     private init;
+    /** The sideways wave of particle `p` at pen dab `d` (px along the normal to the pen's direction). */
+    private wave;
     protected advance(copy: number, d: PenDab, rects: RasterRect[]): void;
+    /** A dot (or bead): round, or a textured stamp turned by the particle's motion (mx, my), at random or to the tip angle. */
+    private dot;
+    /**
+     * Ribbon fill for one step: the band between each pair of joined particles, from where they
+     * were drawn last step to where they are drawn now. Bands of one step, and of consecutive steps,
+     * share edges exactly, so the fill has no seams; it is telescoped into the coverage
+     * (`telescope`), so it does not build up at the joins.
+     */
+    private ribbon;
+    /**
+     * Turns the area newly filled over `rect` into coverage to lay towards the fill's ceiling: the
+     * share of what was left unfilled, so after any number of bands (in any grouping) a pixel's
+     * coverage is the ceiling times the area filled there. False when nothing was added.
+     */
+    private telescope;
 }
 /** Bristle engine settings (each 0..1 unless noted). */
 export interface BristleSettings {

package/dist/paint-editor/procedural.d.ts

@@ -6,8 +6,12 @@
  *   rules. `string`: strands of masses on springs, dragged behind the pen like hair or wet string;
  *   `spring`: each particle tied to the pen by a spring, overshooting and wobbling; `orbit`:
  *   particles circling the pen (spirograph curls); `flow`: particles thrown off the pen and carried
- *   by a swirling flow field until they fade. Each is drawn as `dot`s, a continuous `line`, or a
- *   `sequence` of beads spaced along its path.
+ *   by a swirling flow field until they fade; `elastic`: strands whose masses keep a rest length,
+ *   stretching when the pen is fast and snapping back; `fuzzy`: strings that wind, each strand
+ *   waving out of step with the others. Each is drawn as `dot`s (round, or stamped with up to four
+ *   textures), a continuous `line`, a `sequence` of beads spaced along its path, or a `ribbon`:
+ *   the area between neighbouring particles' paths filled, with their paths as its edges. Any kind
+ *   can wave: each particle's drawn place moves sideways on a sine along the pen's path.
  * - **Bristle brushes** (`engine: 'bristle'`): a tuft of bristles, each its own thin line. Pressure
  *   splays the tuft, tilt flattens it, and bristles lag behind the tip by their stiffness, so they
  *   bend into curves at turns; each bristle carries its own paint and runs dry at its own pace, so
@@ -19,11 +23,12 @@
  */
 import { CoverageMap } from '../paint/brush.js';
 import { type PaintGradientSource } from '../paint/gradient-paint.js';
-import type { RasterRect } from '../raster/surface.js';
+import { type RasterRect } from '../raster/surface.js';
 import type { PaintBrush } from './brushes.js';
 import { type EffectPaintPixels } from './effect-paint.js';
 import { PenDabWalker, PenSmoother, type PenDab, type PenPoint, type StrokeCopy } from './engine.js';
 import { type PaperGrain } from './paper.js';
+import { type StampKind } from './stickers.js';
 export interface ProceduralStrokeOptions {
     grain: PaperGrain | null;
     paperDepth: number;
@@ -71,13 +76,36 @@ declare abstract class MarkStroke implements CoverageStroke {
     protected abstract advance(copy: number, d: PenDab, rects: RasterRect[]): void;
     /** Stamps one round mark of radius `r` at (x, y) with flow `alpha` towards `opacity`. */
     protected mark(x: number, y: number, r: number, alpha: number, opacity: number, pressure: number, rects: RasterRect[]): void;
+    /**
+     * Stamps a textured mark: `kind` from the sticker stamps over a square of half-size `r`, turned
+     * `rotation` radians clockwise, with flow `alpha` towards `opacity`. Small marks are supersampled.
+     */
+    protected stamp(x: number, y: number, r: number, kind: StampKind, rotation: number, seed: number, alpha: number, opacity: number, pressure: number, rects: RasterRect[]): void;
+    /** A scratch buffer of `n` values (reused; valid until the next mark). */
+    protected scratch(n: number): Float32Array;
+    /**
+     * Lays coverage `vals` over `rect` towards `opacity`: paper grain, then effect paint or the
+     * colour of a mark at (x, y) (gradient paint), into the stroke's coverage.
+     */
+    protected lay(rect: RasterRect, vals: Float32Array, opacity: number, pressure: number, x: number, y: number, rects: RasterRect[]): void;
     /** Marks along a segment, spaced by a fraction of the radius. */
     protected segment(x0: number, y0: number, x1: number, y1: number, r: number, alpha: number, opacity: number, pressure: number, rects: RasterRect[]): void;
 }
-export type ParticleKind = 'string' | 'spring' | 'orbit' | 'flow';
+export type ParticleKind = 'string' | 'spring' | 'orbit' | 'flow' | 'elastic' | 'fuzzy';
 export declare const PARTICLE_KINDS: readonly ParticleKind[];
-export type ParticleRender = 'dot' | 'line' | 'sequence';
+export type ParticleRender = 'dot' | 'line' | 'sequence' | 'ribbon';
 export declare const PARTICLE_RENDERS: readonly ParticleRender[];
+/** Ribbon: which particles' paths are joined (`adjacent`: each to its neighbour; `first-last`: one band between the outermost two). */
+export type RibbonPairs = 'adjacent' | 'first-last';
+export declare const RIBBON_PAIRS: readonly RibbonPairs[];
+/** Textured dots: the stamps in turn, or one picked at random (seeded) per dot. */
+export type DotTextureOrder = 'sequence' | 'random';
+export declare const DOT_TEXTURE_ORDERS: readonly DotTextureOrder[];
+/** Textured dots: turned with the particle's motion, at random, or at the tip angle. */
+export type DotRotation = 'follow' | 'random' | 'fixed';
+export declare const DOT_ROTATIONS: readonly DotRotation[];
+/** Textured dots: at most this many stamps. */
+export declare const MAX_DOT_TEXTURES = 4;
 /** Particle engine settings (each 0..1 unless noted). */
 export interface ParticleSettings {
     kind: ParticleKind;
@@ -100,17 +128,66 @@ export interface ParticleSettings {
     life: number;
     /** Sequence: spacing of the beads along each path. */
     interval: number;
+    /** Ribbon: opacity of the fill between the paths, relative to their edges. */
+    ribbonFill: number;
+    /** Ribbon: which paths are joined. */
+    ribbonPairs: RibbonPairs;
+    /** Wave: how far each particle's drawn place swings sideways, as a fraction of the tip size (0: no wave). */
+    waveAmplitude: number;
+    /** Wave: wavelength in px of pen travel, 4..2000. */
+    waveLength: number;
+    /** Wave: how fast the waves run (0: they stand still on the path; 1: about four a second while the pen moves). */
+    waveSpeed: number;
+    /** Wave: how far out of step the particles' waves are (0: all in step; 1: random phases). */
+    wavePhaseJitter: number;
+    /** Dots and beads: up to four sticker stamps drawn instead of round marks (empty: round). */
+    dotTextures: StampKind[];
+    dotTextureOrder: DotTextureOrder;
+    dotRotation: DotRotation;
 }
 export declare const DEFAULT_PARTICLE: Readonly<ParticleSettings>;
 export declare function normalizeParticle(raw?: Partial<ParticleSettings>, base?: ParticleSettings): ParticleSettings;
+/**
+ * Adds the area polygon `pts` (x, y pairs, even-odd) covers in each pixel of `rect`, times `weight`, to `out`,
+ * exactly across each of `RIBBON_SUB` sub-rows per row. Points on an edge two polygons share
+ * count for exactly one of them, so polygons that tile a region add up to it with no seams.
+ */
+export declare function addPolygonArea(pts: readonly number[], rect: RasterRect, out: Float32Array, weight?: number): void;
 /** A particle-brush stroke. */
 export declare class ParticleStroke extends MarkStroke {
     private readonly sets;
+    /** Ribbon pairs per copy: particles in their order around the pen (non-flow kinds). */
+    private readonly orders;
     private readonly s;
     private spawn;
+    /** Textured dots drawn so far, per copy (sequence order, random picks). */
+    private readonly dots;
+    /** Ribbon fill: the area each pixel has had so far this stroke (telescoped into the coverage). */
+    private readonly filled;
+    private pts;
     constructor(brush: PaintBrush, options: ProceduralStrokeOptions);
+    /** Strand kinds: a chain of masses behind each particle. */
+    private get strands();
+    private newParticle;
     private init;
+    /** The sideways wave of particle `p` at pen dab `d` (px along the normal to the pen's direction). */
+    private wave;
     protected advance(copy: number, d: PenDab, rects: RasterRect[]): void;
+    /** A dot (or bead): round, or a textured stamp turned by the particle's motion (mx, my), at random or to the tip angle. */
+    private dot;
+    /**
+     * Ribbon fill for one step: the band between each pair of joined particles, from where they
+     * were drawn last step to where they are drawn now. Bands of one step, and of consecutive steps,
+     * share edges exactly, so the fill has no seams; it is telescoped into the coverage
+     * (`telescope`), so it does not build up at the joins.
+     */
+    private ribbon;
+    /**
+     * Turns the area newly filled over `rect` into coverage to lay towards the fill's ceiling: the
+     * share of what was left unfilled, so after any number of bands (in any grouping) a pixel's
+     * coverage is the ceiling times the area filled there. False when nothing was added.
+     */
+    private telescope;
 }
 /** Bristle engine settings (each 0..1 unless noted). */
 export interface BristleSettings {

package/dist/paint-editor/sticker-art.d.cts

@@ -0,0 +1,55 @@
+/**
+ * Art for stickers from a sticker provider (anything but the editor's own procedural stamps): the
+ * spray brush draws while a stroke is in progress, so it can't wait for a provider. Each sticker
+ * is loaded once, rasterised to RGBA and kept here; drawing reads it synchronously.
+ *
+ * PNG art (`data:` URLs) is decoded here, in any environment. SVG and `https:` images need a
+ * rasteriser: the browser's (`createImageBitmap` and `OffscreenCanvas`) by default, or the
+ * host's (`PaintEditorOptions.rasterizeSticker`).
+ */
+import type { StickerAsset, StickerProvider, StickerRef } from '../stickers/types.cjs';
+/** Rasterised sticker art (straight RGBA) and whether to recolour it. */
+export interface StickerArt {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+    /** Flat art: drawn in the sticker's colour, keeping its alpha. */
+    tintable: boolean;
+}
+/** The art for a ref, when it has loaded. */
+export type StickerArtLookup = (ref: StickerRef) => StickerArt | undefined;
+/** Turns a sticker asset into RGBA at about `size` px on its longest side. */
+export type StickerRasterizer = (asset: StickerAsset, size: number) => Promise<{
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}>;
+/** Longest side sticker art is kept at (px); larger stickers are drawn from it, smoothly scaled. */
+export declare const STICKER_ART_SIZE = 256;
+/**
+ * Decodes PNG data URLs anywhere; draws SVG and other images with the browser's
+ * `createImageBitmap` and `OffscreenCanvas` when present, and otherwise refuses, naming the option
+ * that adds a rasteriser.
+ */
+export declare const defaultStickerRasterizer: StickerRasterizer;
+/** Loaded sticker art by ref, with the state of each load. */
+export declare class StickerArtCache {
+    private readonly entries;
+    /** The art for `ref` when it has loaded (editor stamps never need any). */
+    get: StickerArtLookup;
+    /** `ready`, `loading`, `failed` (with the reason) or `none` (never asked for). Editor stamps are always `ready`. */
+    status(ref: StickerRef): {
+        status: 'ready' | 'loading' | 'failed' | 'none';
+        error?: string;
+    };
+    /**
+     * Loads and rasterises `ref` from `provider` once (later calls share the load). Unknown refs
+     * reject with the closest known ones; failures are kept so they are reported, and retried on
+     * the next call.
+     */
+    ensure(provider: StickerProvider, ref: StickerRef, rasterize: StickerRasterizer): Promise<StickerArt | null>;
+    /** Forgets every load (a new provider). */
+    clear(): void;
+}
+/** Bilinear RGBA sample of `art` at (x, y) in its pixels (straight alpha, colour weighted by alpha). */
+export declare function sampleArt(art: StickerArt, x: number, y: number, out: number[]): number[];

package/dist/paint-editor/sticker-art.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Art for stickers from a sticker provider (anything but the editor's own procedural stamps): the
+ * spray brush draws while a stroke is in progress, so it can't wait for a provider. Each sticker
+ * is loaded once, rasterised to RGBA and kept here; drawing reads it synchronously.
+ *
+ * PNG art (`data:` URLs) is decoded here, in any environment. SVG and `https:` images need a
+ * rasteriser: the browser's (`createImageBitmap` and `OffscreenCanvas`) by default, or the
+ * host's (`PaintEditorOptions.rasterizeSticker`).
+ */
+import type { StickerAsset, StickerProvider, StickerRef } from '../stickers/types.js';
+/** Rasterised sticker art (straight RGBA) and whether to recolour it. */
+export interface StickerArt {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+    /** Flat art: drawn in the sticker's colour, keeping its alpha. */
+    tintable: boolean;
+}
+/** The art for a ref, when it has loaded. */
+export type StickerArtLookup = (ref: StickerRef) => StickerArt | undefined;
+/** Turns a sticker asset into RGBA at about `size` px on its longest side. */
+export type StickerRasterizer = (asset: StickerAsset, size: number) => Promise<{
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+}>;
+/** Longest side sticker art is kept at (px); larger stickers are drawn from it, smoothly scaled. */
+export declare const STICKER_ART_SIZE = 256;
+/**
+ * Decodes PNG data URLs anywhere; draws SVG and other images with the browser's
+ * `createImageBitmap` and `OffscreenCanvas` when present, and otherwise refuses, naming the option
+ * that adds a rasteriser.
+ */
+export declare const defaultStickerRasterizer: StickerRasterizer;
+/** Loaded sticker art by ref, with the state of each load. */
+export declare class StickerArtCache {
+    private readonly entries;
+    /** The art for `ref` when it has loaded (editor stamps never need any). */
+    get: StickerArtLookup;
+    /** `ready`, `loading`, `failed` (with the reason) or `none` (never asked for). Editor stamps are always `ready`. */
+    status(ref: StickerRef): {
+        status: 'ready' | 'loading' | 'failed' | 'none';
+        error?: string;
+    };
+    /**
+     * Loads and rasterises `ref` from `provider` once (later calls share the load). Unknown refs
+     * reject with the closest known ones; failures are kept so they are reported, and retried on
+     * the next call.
+     */
+    ensure(provider: StickerProvider, ref: StickerRef, rasterize: StickerRasterizer): Promise<StickerArt | null>;
+    /** Forgets every load (a new provider). */
+    clear(): void;
+}
+/** Bilinear RGBA sample of `art` at (x, y) in its pixels (straight alpha, colour weighted by alpha). */
+export declare function sampleArt(art: StickerArt, x: number, y: number, out: number[]): number[];

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

@@ -14,13 +14,18 @@ import { TileMedium, type PaintTileTarget } from '../paint/exchange.cjs';
 import { type PaintGradientSource } from '../paint/gradient-paint.cjs';
 import type { PaintBrush } from './brushes.cjs';
 import { type PenPoint, type StrokeCopy } from './engine.cjs';
+import { type StampKind } from '../stickers/stamps.cjs';
+import type { StickerRef } from '../stickers/types.cjs';
+import { type StickerArtLookup } from './sticker-art.cjs';
+export { STAMP_KINDS, stampCoverage, type StampKind } from '../stickers/stamps.cjs';
 import { type EffectPaintPixels } from './effect-paint.cjs';
-export type StampKind = 'dot' | 'star' | 'heart' | 'leaf' | 'flower' | 'confetti' | 'splat' | 'sparkle' | 'ring';
-export declare const STAMP_KINDS: readonly StampKind[];
 /** One sticker (document pixels). */
 export interface Sticker {
     id: string;
-    stamp: StampKind;
+    /** What it shows: a sticker ref (`provider:id`), e.g. `editor:star` or a host library's sticker. */
+    ref: StickerRef;
+    /** The editor stamp, when `ref` is one (`editor:star` → `star`); kept for documents and code that read it. */
+    stamp?: StampKind;
     x: number;
     y: number;
     /** Diameter in pixels. */
@@ -36,8 +41,11 @@ export interface Sticker {
 }
 /** Sticker spray settings (each 0..1 unless noted). */
 export interface StickerSettings {
-    /** The stamps to spray (picked at random per sticker). */
-    stamps: StampKind[];
+    /**
+     * The stickers to spray (one picked at random per sticker): refs `provider:id`. A bare editor
+     * stamp (`"star"`) is read as `editor:star`.
+     */
+    stamps: StickerRef[];
     /** How closely stickers follow each other: about `density × 4` per tip diameter of travel (0.25 ≈ one per diameter). */
     density: number;
     /** Random size change. */
@@ -49,20 +57,21 @@ export interface StickerSettings {
     /** Random colour change (hue and lightness). */
     colorJitter: number;
 }
+/** At most this many stickers in a sticker brush. */
+export declare const MAX_STICKER_STAMPS = 16;
 export declare const DEFAULT_STICKER: Readonly<StickerSettings>;
 export declare function normalizeStickerSettings(raw?: Partial<StickerSettings>, base?: StickerSettings): StickerSettings;
-/**
- * Coverage of a stamp at a point (u, v) of its unit square (−1..1, y down), 0..1, before shading.
- * `t` is the sticker's seed for shapes with random parts (splat, confetti).
- */
-export declare function stampCoverage(kind: StampKind, u: number, v: number, t: number): number;
 /** The pixel rectangle a sticker covers. */
 export declare function stickerRect(s: Sticker): RasterRect;
+/** The editor stamp a sticker shows, or `null` for a provider's sticker. */
+export declare function stickerStamp(s: Pick<Sticker, 'ref' | 'stamp'>): StampKind | null;
 /**
- * Draws one sticker through a `TileMedium` (straight source-over): the stamp's coverage, lit a
- * little from the top left and given a fine seeded texture, in its colour and opacity.
+ * Draws one sticker through a `TileMedium` (straight source-over). An editor stamp: its coverage,
+ * lit a little from the top left and given a fine seeded texture, in its colour and opacity. A
+ * provider's sticker: its loaded art (`art`), fitted into the sticker's size and turned, in its
+ * own colours or, when tintable, in the sticker's colour; nothing until the art has loaded.
  */
-export declare function drawSticker(medium: TileMedium, s: Sticker): RasterRect;
+export declare function drawSticker(medium: TileMedium, s: Sticker, art?: StickerArtLookup): RasterRect;
 export interface StickerSprayInit {
     brush: PaintBrush;
     target: PaintTileTarget;
@@ -79,12 +88,16 @@ export interface StickerSprayInit {
      * stays recolourable); none lands where the effect is transparent.
      */
     effect?: EffectPaintPixels | null;
+    /** Loaded art for provider stickers; stickers without art yet are skipped (see `skipped`). */
+    art?: StickerArtLookup;
 }
 /** A sticker-spray stroke: drops stickers along the path and draws them as it goes. */
 export declare class StickerSpray {
     readonly init: StickerSprayInit;
     dabCount: number;
     readonly stickers: Sticker[];
+    /** Refs the spray picked but could not draw because their art had not loaded. */
+    readonly skipped: Set<string>;
     private readonly smoother;
     private readonly walkers;
     private readonly copies;
@@ -101,7 +114,7 @@ export declare class StickerSpray {
     private colorAt;
 }
 /** A sticker list rendered over a transparent layer, through a tile target. */
-export declare function renderStickers(stickers: readonly Sticker[], target: PaintTileTarget): void;
+export declare function renderStickers(stickers: readonly Sticker[], target: PaintTileTarget, art?: StickerArtLookup): void;
 /** Checks and rounds a sticker change; throws a sentence naming the bad field. */
 export declare function normalizeStickerUpdate(u: Partial<Omit<Sticker, 'id'>>): Partial<Omit<Sticker, 'id'>>;
 /**
@@ -110,6 +123,6 @@ export declare function normalizeStickerUpdate(u: Partial<Omit<Sticker, 'id'>>):
  * drawn again, from the stickers that reach them; the rest are kept. The pixels are the same as a
  * full redraw, since a tile depends only on the stickers over it.
  */
-export declare function stickerSurface(stickers: readonly Sticker[], base?: TiledSurface, dirty?: readonly RasterRect[]): TiledSurface;
-/** The top-most sticker under a point (document pixels), by its stamp's shape, or `null`. */
-export declare function stickerAt(stickers: readonly Sticker[], x: number, y: number): Sticker | null;
+export declare function stickerSurface(stickers: readonly Sticker[], base?: TiledSurface, dirty?: readonly RasterRect[], art?: StickerArtLookup): TiledSurface;
+/** The top-most sticker under a point (document pixels), by its stamp's shape (or its art's alpha), or `null`. */
+export declare function stickerAt(stickers: readonly Sticker[], x: number, y: number, art?: StickerArtLookup): Sticker | null;

package/dist/paint-editor/stickers.d.ts

@@ -14,13 +14,18 @@ import { TileMedium, type PaintTileTarget } from '../paint/exchange.js';
 import { type PaintGradientSource } from '../paint/gradient-paint.js';
 import type { PaintBrush } from './brushes.js';
 import { type PenPoint, type StrokeCopy } from './engine.js';
+import { type StampKind } from '../stickers/stamps.js';
+import type { StickerRef } from '../stickers/types.js';
+import { type StickerArtLookup } from './sticker-art.js';
+export { STAMP_KINDS, stampCoverage, type StampKind } from '../stickers/stamps.js';
 import { type EffectPaintPixels } from './effect-paint.js';
-export type StampKind = 'dot' | 'star' | 'heart' | 'leaf' | 'flower' | 'confetti' | 'splat' | 'sparkle' | 'ring';
-export declare const STAMP_KINDS: readonly StampKind[];
 /** One sticker (document pixels). */
 export interface Sticker {
     id: string;
-    stamp: StampKind;
+    /** What it shows: a sticker ref (`provider:id`), e.g. `editor:star` or a host library's sticker. */
+    ref: StickerRef;
+    /** The editor stamp, when `ref` is one (`editor:star` → `star`); kept for documents and code that read it. */
+    stamp?: StampKind;
     x: number;
     y: number;
     /** Diameter in pixels. */
@@ -36,8 +41,11 @@ export interface Sticker {
 }
 /** Sticker spray settings (each 0..1 unless noted). */
 export interface StickerSettings {
-    /** The stamps to spray (picked at random per sticker). */
-    stamps: StampKind[];
+    /**
+     * The stickers to spray (one picked at random per sticker): refs `provider:id`. A bare editor
+     * stamp (`"star"`) is read as `editor:star`.
+     */
+    stamps: StickerRef[];
     /** How closely stickers follow each other: about `density × 4` per tip diameter of travel (0.25 ≈ one per diameter). */
     density: number;
     /** Random size change. */
@@ -49,20 +57,21 @@ export interface StickerSettings {
     /** Random colour change (hue and lightness). */
     colorJitter: number;
 }
+/** At most this many stickers in a sticker brush. */
+export declare const MAX_STICKER_STAMPS = 16;
 export declare const DEFAULT_STICKER: Readonly<StickerSettings>;
 export declare function normalizeStickerSettings(raw?: Partial<StickerSettings>, base?: StickerSettings): StickerSettings;
-/**
- * Coverage of a stamp at a point (u, v) of its unit square (−1..1, y down), 0..1, before shading.
- * `t` is the sticker's seed for shapes with random parts (splat, confetti).
- */
-export declare function stampCoverage(kind: StampKind, u: number, v: number, t: number): number;
 /** The pixel rectangle a sticker covers. */
 export declare function stickerRect(s: Sticker): RasterRect;
+/** The editor stamp a sticker shows, or `null` for a provider's sticker. */
+export declare function stickerStamp(s: Pick<Sticker, 'ref' | 'stamp'>): StampKind | null;
 /**
- * Draws one sticker through a `TileMedium` (straight source-over): the stamp's coverage, lit a
- * little from the top left and given a fine seeded texture, in its colour and opacity.
+ * Draws one sticker through a `TileMedium` (straight source-over). An editor stamp: its coverage,
+ * lit a little from the top left and given a fine seeded texture, in its colour and opacity. A
+ * provider's sticker: its loaded art (`art`), fitted into the sticker's size and turned, in its
+ * own colours or, when tintable, in the sticker's colour; nothing until the art has loaded.
  */
-export declare function drawSticker(medium: TileMedium, s: Sticker): RasterRect;
+export declare function drawSticker(medium: TileMedium, s: Sticker, art?: StickerArtLookup): RasterRect;
 export interface StickerSprayInit {
     brush: PaintBrush;
     target: PaintTileTarget;
@@ -79,12 +88,16 @@ export interface StickerSprayInit {
      * stays recolourable); none lands where the effect is transparent.
      */
     effect?: EffectPaintPixels | null;
+    /** Loaded art for provider stickers; stickers without art yet are skipped (see `skipped`). */
+    art?: StickerArtLookup;
 }
 /** A sticker-spray stroke: drops stickers along the path and draws them as it goes. */
 export declare class StickerSpray {
     readonly init: StickerSprayInit;
     dabCount: number;
     readonly stickers: Sticker[];
+    /** Refs the spray picked but could not draw because their art had not loaded. */
+    readonly skipped: Set<string>;
     private readonly smoother;
     private readonly walkers;
     private readonly copies;
@@ -101,7 +114,7 @@ export declare class StickerSpray {
     private colorAt;
 }
 /** A sticker list rendered over a transparent layer, through a tile target. */
-export declare function renderStickers(stickers: readonly Sticker[], target: PaintTileTarget): void;
+export declare function renderStickers(stickers: readonly Sticker[], target: PaintTileTarget, art?: StickerArtLookup): void;
 /** Checks and rounds a sticker change; throws a sentence naming the bad field. */
 export declare function normalizeStickerUpdate(u: Partial<Omit<Sticker, 'id'>>): Partial<Omit<Sticker, 'id'>>;
 /**
@@ -110,6 +123,6 @@ export declare function normalizeStickerUpdate(u: Partial<Omit<Sticker, 'id'>>):
  * drawn again, from the stickers that reach them; the rest are kept. The pixels are the same as a
  * full redraw, since a tile depends only on the stickers over it.
  */
-export declare function stickerSurface(stickers: readonly Sticker[], base?: TiledSurface, dirty?: readonly RasterRect[]): TiledSurface;
-/** The top-most sticker under a point (document pixels), by its stamp's shape, or `null`. */
-export declare function stickerAt(stickers: readonly Sticker[], x: number, y: number): Sticker | null;
+export declare function stickerSurface(stickers: readonly Sticker[], base?: TiledSurface, dirty?: readonly RasterRect[], art?: StickerArtLookup): TiledSurface;
+/** The top-most sticker under a point (document pixels), by its stamp's shape (or its art's alpha), or `null`. */
+export declare function stickerAt(stickers: readonly Sticker[], x: number, y: number, art?: StickerArtLookup): Sticker | null;

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

@@ -20,6 +20,7 @@ import type { Affine } from './strokes.cjs';
 import type { WetStrokeDriver } from './wet.cjs';
 import { type ThickChannels } from './thick.cjs';
 import { type Sticker } from './stickers.cjs';
+import type { StickerArtLookup } from './sticker-art.cjs';
 export interface StrokeSessionHost {
     /** Shows the layer's live surface (no history); `rects` are where it changed. */
     update(layerId: string, surface: TiledSurface, rects: RasterRect[]): void;
@@ -74,6 +75,7 @@ export interface StrokeSessionInit {
     /** Sticker brushes: the next sticker number on the layer. */
     sticker?: {
         nextId: number;
+        art?: StickerArtLookup;
     };
     /** Gradient paint (resolved: concrete colours), or `null` for the one colour. Recorded with the stroke. */
     paint?: PaintGradientSource | null;
@@ -104,6 +106,8 @@ export interface PaintStrokeResult {
     mixerLoad?: MixerLoad;
     /** Wet brushes: the paint is wet (it keeps moving until it dries; see dry_paint / advance_wet_paint). */
     wet?: boolean;
+    /** Sticker brushes: refs the spray picked but skipped because their art had not loaded yet. */
+    skippedStickers?: string[];
 }
 export declare class PaintStrokeSession {
     private readonly host;

package/dist/paint-editor/stroke.d.ts

@@ -20,6 +20,7 @@ import type { Affine } from './strokes.js';
 import type { WetStrokeDriver } from './wet.js';
 import { type ThickChannels } from './thick.js';
 import { type Sticker } from './stickers.js';
+import type { StickerArtLookup } from './sticker-art.js';
 export interface StrokeSessionHost {
     /** Shows the layer's live surface (no history); `rects` are where it changed. */
     update(layerId: string, surface: TiledSurface, rects: RasterRect[]): void;
@@ -74,6 +75,7 @@ export interface StrokeSessionInit {
     /** Sticker brushes: the next sticker number on the layer. */
     sticker?: {
         nextId: number;
+        art?: StickerArtLookup;
     };
     /** Gradient paint (resolved: concrete colours), or `null` for the one colour. Recorded with the stroke. */
     paint?: PaintGradientSource | null;
@@ -104,6 +106,8 @@ export interface PaintStrokeResult {
     mixerLoad?: MixerLoad;
     /** Wet brushes: the paint is wet (it keeps moving until it dries; see dry_paint / advance_wet_paint). */
     wet?: boolean;
+    /** Sticker brushes: refs the spray picked but skipped because their art had not loaded yet. */
+    skippedStickers?: string[];
 }
 export declare class PaintStrokeSession {
     private readonly host;

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

@@ -6,7 +6,7 @@
  */
 import type { AgentToolProvider } from '../tools/registry.cjs';
 import { type PaintOrigin } from './hosted.cjs';
-import type { PaintEditorController } from './controller.cjs';
+import { type PaintEditorController } from './controller.cjs';
 import type { PaintDirector } from './presence.cjs';
 import type { PresenceActorInfo } from '../animation/presence.cjs';
 export interface PaintEditorToolProviderOptions {