@pixerate/editor 0.248.0 → 0.249.0

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

@@ -51,3 +51,6 @@ export type { WetBackendInfo } from '../paint/wet/world.cjs';
 export * from '../paint/gradient-paint.cjs';
 export * from './playback.cjs';
 export * from './editorDocument.cjs';
+export { StickerBrowser, type StickerBrowserItem, type StickerBrowserState } from '../stickers/browser.cjs';
+export type { StickerProvider, StickerRef, StickerSummary } from '../stickers/types.cjs';
+export * from './sticker-art.cjs';

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

@@ -51,3 +51,6 @@ export type { WetBackendInfo } from '../paint/wet/world.js';
 export * from '../paint/gradient-paint.js';
 export * from './playback.js';
 export * from './editorDocument.js';
+export { StickerBrowser, type StickerBrowserItem, type StickerBrowserState } from '../stickers/browser.js';
+export type { StickerProvider, StickerRef, StickerSummary } from '../stickers/types.js';
+export * from './sticker-art.js';

package/dist/paint-editor/index.js

@@ -1,3 +1,7 @@
+import {
+  StickerBrowser,
+  editorStickers
+} from "../chunk-EJLRBS5Q.js";
 import {
   toVideoFfmpeg
 } from "../chunk-L3JFOTBQ.js";
@@ -8,7 +12,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-ZFSLEOSQ.js";
+} from "../chunk-UBRJOIR5.js";
 import "../chunk-3CI7FRMK.js";
 import "../chunk-ZNA3IQZF.js";
 import {
@@ -26,7 +30,7 @@ import {
   mergeLayerEffect,
   newEffectId,
   validateLayerEffects
-} from "../chunk-UOOK7HTX.js";
+} from "../chunk-3PPJRMIG.js";
 import "../chunk-OHKOFKBY.js";
 import "../chunk-ZIF4UJJ6.js";
 import {
@@ -53,7 +57,7 @@ import {
   pigmentOf,
   pointerPressure,
   wetSupport
-} from "../chunk-P3NIPIKS.js";
+} from "../chunk-WQCNC4DK.js";
 import "../chunk-HVQVHUTV.js";
 import {
   writeZip
@@ -64,7 +68,7 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-IVSWRVB4.js";
-import "../chunk-Q2HA52V4.js";
+import "../chunk-PZP2SZIZ.js";
 import {
   BRUSH_ID,
   BRUSH_ROTATIONS,
@@ -89,6 +93,7 @@ import {
   IDENTITY_COPY,
   IMPASTO_TOOLS,
   MAX_DOT_TEXTURES,
+  MAX_STICKER_STAMPS,
   MULTI_COLOR_MODES,
   PAINT_BRUSH_CATEGORIES,
   PAINT_BRUSH_ENGINES,
@@ -100,7 +105,8 @@ import {
   PenDabWalker,
   PenSmoother,
   RIBBON_PAIRS,
-  STAMP_KINDS,
+  STICKER_ART_SIZE,
+  StickerArtCache,
   StickerSpray,
   WET_MEDIA,
   WET_TOOLS,
@@ -108,6 +114,7 @@ import {
   brushTakesPaint,
   brushToJSON,
   clonePaper,
+  defaultStickerRasterizer,
   drawSticker,
   effectDabField,
   effectPaintKey,
@@ -138,16 +145,25 @@ import {
   readPaintEffectPaint,
   renderPaper,
   renderStickers,
+  sampleArt,
   sampleEffectAt,
   sampleEffectField,
-  stampCoverage,
   stickerAt,
   stickerRect,
+  stickerStamp,
   stickerSurface,
   tiltToOrientation,
   toStrokePoint,
   usesPaintExchange
-} from "../chunk-VNBUDVD4.js";
+} from "../chunk-J7T5QZ45.js";
+import {
+  STAMP_KINDS,
+  StickersSlot,
+  createStickerTools,
+  editorStampOf,
+  normalizeStickerRef,
+  stampCoverage
+} from "../chunk-5RH3VXAK.js";
 import "../chunk-M6DNZNVY.js";
 import "../chunk-WEIK3UYB.js";
 import "../chunk-PWBZH3FK.js";
@@ -188,7 +204,6 @@ import {
   PaperGrain,
   SmudgeTip,
   TileMedium,
-  TileableNoise,
   addPaintGradientStop,
   applyStrokeToTile,
   blenderDab,
@@ -198,46 +213,51 @@ import {
   exchangeRates,
   grainCatch,
   grainHeights,
-  hash2,
   hexToPaintRgb,
   isGradientPaint,
   loadMixer,
-  mix32,
   mixerRates,
   normalizeHexColor,
   paintGradientMappingFor,
   paintSourceColor,
   paintSourceCss,
   parsePaintSource,
-  rand01,
-  randSigned,
   rasterizeDab,
   readPaintSource,
   removePaintGradientStop,
   resolvePaintGradient,
   reversePaintGradient,
   scalePaintGradient,
-  seedFromString,
   solidPaint,
   updatePaintGradientStop
-} from "../chunk-2PBZBRP5.js";
+} from "../chunk-D5KGAO4Z.js";
+import {
+  TileableNoise,
+  hash2,
+  mix32,
+  rand01,
+  randSigned,
+  seedFromString
+} from "../chunk-4D6KP5BV.js";
 import "../chunk-ODBT55Q7.js";
 import {
   BLEND_MODES,
   PAINTERLY_BLEND_MODES,
+  isBlendMode,
+  isPainterlyBlendMode,
+  mixPigment8,
+  mixPigments,
+  standardBlendMode
+} from "../chunk-IRSTHLQQ.js";
+import {
   base64ToBytes,
   bytesToBase64,
   decodePng,
   encodePng,
-  isBlendMode,
-  isPainterlyBlendMode,
   isPng,
-  mixPigment8,
-  mixPigments,
   parseDataUrl,
-  pngDataUrl,
-  standardBlendMode
-} from "../chunk-42TWUPNJ.js";
+  pngDataUrl
+} from "../chunk-OTTT5N3K.js";
 import {
   TILE,
   TiledSurface,
@@ -1305,7 +1325,7 @@ var PaintStrokeSession = class _PaintStrokeSession {
     };
     if (this.wetDriver) {
     } else if (init.sticker) {
-      this.stickerSpray = new StickerSpray({ brush, target: this.tileTarget(), color: init.colorHex, seed: init.seed, copies: this.copies, nextId: init.sticker.nextId, paint: init.paint ?? null, effect });
+      this.stickerSpray = new StickerSpray({ brush, target: this.tileTarget(), color: init.colorHex, seed: init.seed, copies: this.copies, nextId: init.sticker.nextId, paint: init.paint ?? null, effect, art: init.sticker.art });
     } else if (init.thick) {
       const rgb = (c) => [c[0] / 255, c[1] / 255, c[2] / 255];
       this.thickDriver = new ThickStrokeDriver({ brush, target: this.tileTarget(), channels: init.thick.channels, color: rgb(init.color), load: init.mixerLoad, seed: init.seed, copies: this.copies, paint: init.paint ?? null, effect });
@@ -1515,6 +1535,7 @@ var PaintStrokeSession = class _PaintStrokeSession {
     const surface = changed ? new TiledSurface(ch, tiles, this.base.defaultValue) : null;
     const dabs = this.dry ? this.dry.dabCount : this.thickDriver ? this.thickDriver.dabCount : this.stickerSpray ? this.stickerSpray.dabCount : this.wet.dabCount;
     this.result = { layerId: this.layerId, bounds: changed ? this.bounds : null, dabs, strokeId: null };
+    if (this.stickerSpray?.skipped.size) this.result.skippedStickers = [...this.stickerSpray.skipped];
     const carried = this.wet?.load ?? this.thickDriver?.load;
     if (carried) this.result.mixerLoad = this.init.brush.behavior.dirty ? carried : cleanMixer(carried);
     this.host.commit(this, surface, false);
@@ -4161,10 +4182,16 @@ var PaintEditorController = class _PaintEditorController {
   wetOp = null;
   /** The effects provider slot (see `setEffectsProvider`). */
   effects = new EffectsSlot();
+  /** The sticker library slot (see `setStickersProvider`). */
+  stickers = new StickersSlot(editorStickers());
+  stickerArt = new StickerArtCache();
+  rasterizeSticker;
   effectsRenderer = new PaintEffectsRenderer();
   paperEffectNodeCache = null;
   constructor(options = {}) {
     this.historyLimit = Math.max(1, options.historyLimit ?? 200);
+    this.rasterizeSticker = options.rasterizeSticker ?? defaultStickerRasterizer;
+    if (options.stickers) this.stickers.set(options.stickers);
     this.doc = createPaintDocument({ width: options.width, height: options.height, dpi: options.dpi, paper: this.resolvePaper(options.paper) });
     this.userBrushes = (options.brushes ?? []).map((b) => normalizePaintBrush({ ...b, builtin: false }));
     const start = this.findBrush(options.brushId ?? DEFAULT_BRUSH_ID) ?? this.findBrush(DEFAULT_BRUSH_ID);
@@ -5323,6 +5350,7 @@ var PaintEditorController = class _PaintEditorController {
     else delete next.builtin;
     this.brush = next;
     this.emit([]);
+    if (next.engine === "sticker" && next.sticker.stamps.some((r) => !editorStampOf(r))) void this.prepareStickers(next.sticker.stamps).catch(() => this.emit([]));
     return this.brush;
   }
   /** Saves the active brush (or `brush`) into the user library under `id` / `name`. */
@@ -5648,7 +5676,7 @@ var PaintEditorController = class _PaintEditorController {
       thick: brush.engine === "impasto" ? { channels: doc.thick?.[layer.id] ?? emptyThickChannels() } : void 0,
       // Light paint: a twin of the stroke paints the light channel (laying, dimming, moving light).
       light: !wet && brush.engine !== "sticker" && (brush.light.amount > 0 || doc.light?.[layer.id]) ? { surface: doc.light?.[layer.id] ?? emptyLight() } : null,
-      sticker: brush.engine === "sticker" ? { nextId: this.nextStickerNumber(doc) } : void 0,
+      sticker: brush.engine === "sticker" ? { nextId: this.nextStickerNumber(doc), art: this.stickerArt.get } : void 0,
       paint: effect ? null : this.strokeGradient(init, brush, color),
       effect
     });
@@ -6445,9 +6473,19 @@ var PaintEditorController = class _PaintEditorController {
       const stickers = {};
       for (const [id, list] of Object.entries(ext.stickers)) {
         if (!findLayer(state.layers, id) || !Array.isArray(list)) continue;
-        const ok = list.filter((x) => x && typeof x.id === "string" && STAMP_KINDS.includes(x.stamp) && Number.isFinite(x.x) && Number.isFinite(x.y) && x.size > 0);
+        const ok = list.flatMap((x) => {
+          if (!x || typeof x.id !== "string" || !Number.isFinite(x.x) || !Number.isFinite(x.y) || !(x.size > 0)) return [];
+          try {
+            const ref2 = normalizeStickerRef(x.ref ?? x.stamp);
+            const stamp = editorStampOf(ref2);
+            const { stamp: _old, ...rest } = x;
+            return [{ ...rest, ref: ref2, ...stamp ? { stamp } : {} }];
+          } catch {
+            return [];
+          }
+        });
         if (ok.length !== list.length) problems.push(`Some stickers of layer "${id}" could not be read; they were dropped.`);
-        stickers[id] = ok.map((x) => ({ ...x }));
+        stickers[id] = ok;
       }
       if (Object.keys(stickers).length) state = { ...state, stickers };
     }
@@ -6551,6 +6589,8 @@ var PaintEditorController = class _PaintEditorController {
     delete this.extensions.paperEffect;
     this.viewCompositor.clear();
     this.emit();
+    const refs = Object.values(this.doc.stickers ?? {}).flatMap((list) => list.map((x) => x.ref));
+    if (refs.some((r) => !editorStampOf(r))) void this.prepareStickers(refs).catch(() => this.emit([]));
     return loaded.problems;
   }
   /** Opens a saved document (clears the history). Returns what could not be read. */
@@ -6878,6 +6918,56 @@ var PaintEditorController = class _PaintEditorController {
     if (!stickers) throw new PaintEditorError(`Layer "${l.name}" has no stickers; spray some with a sticker brush (list_brushes category sticker).`);
     return { layer: l, stickers };
   }
+  // --- The sticker library ---------------------------------------------------------
+  /** The sticker library: the editor's own stamps unless a host set its own. */
+  get stickersProvider() {
+    return this.stickers.provider;
+  }
+  /**
+   * Sets the sticker library (`null` goes back to the editor's own stamps, `editorStickers()`);
+   * to offer both, pass `combineStickerProviders([editorStickers(), yours])`. Loaded art is
+   * forgotten. Not an edit: no undo step.
+   */
+  setStickersProvider(provider) {
+    if ((provider ?? this.stickers.fallback) === this.stickers.provider) return;
+    this.stickers.set(provider);
+    this.stickerArt.clear();
+    this.emit([]);
+  }
+  /**
+   * Loads the art of `refs` (provider stickers; editor stamps need none) so sprays and placements
+   * can draw them. Rejects with a `PaintEditorError` naming an unknown ref and the closest known
+   * ones, or a sticker whose art failed. Emits when art arrives, so views redraw.
+   */
+  async prepareStickers(refs) {
+    const list = [...new Set(refs.map((r) => this.readStickerRef(r)))].filter((r) => !editorStampOf(r));
+    try {
+      await Promise.all(list.map((r) => this.stickerArt.ensure(this.stickers.provider, r, this.rasterizeSticker)));
+    } catch (e) {
+      throw new PaintEditorError(e instanceof Error ? e.message : String(e));
+    } finally {
+      if (list.length) this.emit([]);
+    }
+  }
+  /** Whether a sticker's art is ready to draw: `ready` (always for editor stamps), `loading`, `failed` (with why) or `none`. */
+  stickerArtStatus(ref2) {
+    return this.stickerArt.status(this.readStickerRef(ref2));
+  }
+  readStickerRef(ref2) {
+    try {
+      return normalizeStickerRef(ref2);
+    } catch (e) {
+      throw new PaintEditorError(e.message);
+    }
+  }
+  /** Refuses to redraw stickers whose art has not loaded (they would vanish), naming them and what to call. */
+  requireStickerArt(stickers) {
+    const missing = [...new Set(stickers.filter((s) => !stickerStamp(s) && !this.stickerArt.get(s.ref)).map((s) => s.ref))];
+    if (missing.length) {
+      for (const r of missing) void this.stickerArt.ensure(this.stickers.provider, r, this.rasterizeSticker).then(() => this.emit([]), () => this.emit([]));
+      throw new PaintEditorError(`The art for ${missing.map((r) => `"${r}"`).join(", ")} has not loaded yet; it is loading now (prepareStickers), so try again when it has.`);
+    }
+  }
   /** A layer's stickers, bottom first. */
   listStickers(layerId) {
     const id = layerId ?? this.doc.activeLayerId;
@@ -6891,6 +6981,7 @@ var PaintEditorController = class _PaintEditorController {
    */
   commitStickers(label, layer, stickers, dirty) {
     if (isLayerLocked(layer, "pixels")) throw new PaintEditorError(`Layer "${layer.name}" has its pixels locked; unlock it first.`);
+    this.requireStickerArt(stickers);
     const before = this.previewBase() ?? this.doc;
     this.stickerPreview = null;
     const surface = this.redrawStickers(layer, stickers, dirty);
@@ -6899,7 +6990,7 @@ var PaintEditorController = class _PaintEditorController {
   }
   redrawStickers(layer, stickers, dirty) {
     const partial = dirty && !layer.offset.x && !layer.offset.y;
-    return partial ? stickerSurface(stickers, layer.surface, dirty) : stickerSurface(stickers);
+    return partial ? stickerSurface(stickers, layer.surface, dirty, this.stickerArt.get) : stickerSurface(stickers, void 0, void 0, this.stickerArt.get);
   }
   /** The document from before the sticker preview on screen, or `null` when none is (anything else changed the document since). */
   previewBase() {
@@ -6918,7 +7009,7 @@ var PaintEditorController = class _PaintEditorController {
     const id = layerId ?? this.doc.activeLayerId;
     if (!id) return null;
     this.requireLayer(id);
-    const hit = stickerAt(this.doc.stickers?.[id] ?? [], x, y);
+    const hit = stickerAt(this.doc.stickers?.[id] ?? [], x, y, this.stickerArt.get);
     return hit ? { ...hit } : null;
   }
   /** Picks a sticker for the panel and canvas (`null` for none). Editor state, not an undo step. */
@@ -6972,7 +7063,7 @@ var PaintEditorController = class _PaintEditorController {
    */
   addStickers(layerId, input) {
     const layer = this.wetLayer(layerId, "add stickers to");
-    if (!input.length) throw new PaintEditorError("Pass at least one sticker (stamp, x, y).");
+    if (!input.length) throw new PaintEditorError("Pass at least one sticker (ref, x, y).");
     if (input.length > MAX_ADD_STICKERS) throw new PaintEditorError(`At most ${MAX_ADD_STICKERS} stickers per call; split them over several calls.`);
     const existing = this.doc.stickers?.[layer.id];
     if (!existing?.length) {
@@ -6980,7 +7071,8 @@ var PaintEditorController = class _PaintEditorController {
     }
     let n = this.nextStickerNumber();
     const added = input.map((raw, i) => {
-      for (const k of ["stamp", "x", "y"]) if (raw[k] === void 0) throw new PaintEditorError(`Sticker ${i} needs ${k}.`);
+      if (raw.ref === void 0 && raw.stamp === void 0) throw new PaintEditorError(`Sticker ${i} needs ref (a sticker ref from find_stickers, e.g. "editor:star").`);
+      for (const k of ["x", "y"]) if (raw[k] === void 0) throw new PaintEditorError(`Sticker ${i} needs ${k}.`);
       let u;
       try {
         u = this.readStickerUpdate(raw);
@@ -8045,7 +8137,7 @@ function createPaintStickerTools(c) {
     {
       name: "list_stickers",
       title: "List stickers",
-      description: "Lists a layer\u2019s stickers bottom first: id, stamp, x, y (centre, document pixels), size (diameter px), rotation (degrees clockwise), color, opacity. Empty for a layer without stickers. Changes nothing.",
+      description: "Lists a layer\u2019s stickers bottom first: id, ref (provider:id; stamp too for the editor\u2019s own), x, y (centre, document pixels), size (diameter px), rotation (degrees clockwise), color, opacity. Empty for a layer without stickers. Changes nothing.",
       inputSchema: { type: "object", properties: { layerId: LAYER_ID }, additionalProperties: false },
       annotations: { title: "List stickers", ...READ },
       coordinates: { out: ["stickers[]"] },
@@ -8072,7 +8164,7 @@ function createPaintStickerTools(c) {
     {
       name: "add_stickers",
       title: "Place stickers",
-      description: "Places stickers exactly where you say, on top of a sticker layer or onto an empty layer (which becomes a sticker layer). Use it for deliberate placement; spray with paint_stroke and a sticker brush for a random scatter. One undo step. Returns the new stickers with their ids, for update_sticker, arrange_stickers and remove_stickers.",
+      description: "Places stickers exactly where you say, on top of a sticker layer or onto an empty layer (which becomes a sticker layer): any sticker from the sticker library by ref (find_stickers), its art loaded first; tintable ones take color. Use it for deliberate placement; spray with paint_stroke and a sticker brush for a random scatter. An unknown ref is refused with the closest ones. One undo step. Returns the new stickers with their ids, for update_sticker, arrange_stickers and remove_stickers.",
       inputSchema: {
         type: "object",
         properties: {
@@ -8085,7 +8177,8 @@ function createPaintStickerTools(c) {
             items: {
               type: "object",
               properties: {
-                stamp: { type: "string", enum: [...STAMP_KINDS], description: "The stamp." },
+                ref: { type: "string", minLength: 1, description: "The sticker: a ref provider:id from find_stickers (e.g. editor:star). Give ref or stamp." },
+                stamp: { type: "string", enum: [...STAMP_KINDS], description: "Older form: an editor stamp (same as ref editor:<stamp>)." },
                 x: { type: "number", description: "Centre x in document pixels." },
                 y: { type: "number", description: "Centre y in document pixels." },
                 size: { type: "number", minimum: 2, maximum: 2048, description: "Diameter in pixels (default 48)." },
@@ -8094,7 +8187,7 @@ function createPaintStickerTools(c) {
                 opacity: { type: "number", minimum: 0, maximum: 1, description: "Opacity 0..1 (default 1)." },
                 seed: { type: "integer", minimum: 0, description: "Texture seed (default from the new id); splat and confetti shapes vary with it." }
               },
-              required: ["stamp", "x", "y"],
+              required: ["x", "y"],
               additionalProperties: false
             }
           }
@@ -8104,7 +8197,14 @@ function createPaintStickerTools(c) {
       },
       annotations: { title: "Place stickers", ...WRITE },
       coordinates: { in: ["stickers[]"], out: ["stickers[]"] },
-      handler: ({ layerId, stickers }) => ({ layerId: layerId ?? c.document.activeLayerId, stickers: c.addStickers(layerId, stickers) })
+      handler: async ({ layerId, stickers }) => {
+        const list = stickers;
+        list.forEach((x, i) => {
+          if (x.ref === void 0 && x.stamp === void 0) throw new Error(`Sticker ${i} needs ref (a sticker ref from find_stickers, e.g. "editor:star").`);
+        });
+        await c.prepareStickers(list.map((x) => x.ref ?? `editor:${x.stamp}`));
+        return { layerId: layerId ?? c.document.activeLayerId, stickers: c.addStickers(layerId, list) };
+      }
     },
     {
       name: "update_sticker",
@@ -8115,7 +8215,8 @@ function createPaintStickerTools(c) {
         properties: {
           layerId: LAYER_ID,
           id: { type: "string", description: "Sticker id from list_stickers." },
-          stamp: { type: "string", enum: [...STAMP_KINDS], description: "Another stamp." },
+          ref: { type: "string", minLength: 1, description: "Another sticker: a ref provider:id from find_stickers." },
+          stamp: { type: "string", enum: [...STAMP_KINDS], description: "Older form: another editor stamp (same as ref editor:<stamp>)." },
           x: { type: "number", description: "Centre x in document pixels." },
           y: { type: "number", description: "Centre y in document pixels." },
           size: { type: "number", minimum: 2, maximum: 2048, description: "Diameter in pixels." },
@@ -8128,7 +8229,11 @@ function createPaintStickerTools(c) {
       },
       annotations: { title: "Change a sticker", ...WRITE },
       coordinates: { in: [""], out: [""] },
-      handler: ({ layerId, id, ...update }) => c.updateSticker(layerId, id, update)
+      handler: async ({ layerId, id, ...update }) => {
+        const refs = c.listStickers(layerId).map((s) => s.ref);
+        await c.prepareStickers(update.ref ? [...refs, update.ref] : refs);
+        return c.updateSticker(layerId, id, update);
+      }
     },
     {
       name: "arrange_stickers",
@@ -8145,7 +8250,10 @@ function createPaintStickerTools(c) {
         additionalProperties: false
       },
       annotations: { title: "Bring stickers forward or back", ...WRITE },
-      handler: ({ layerId, ids, to }) => ({ order: c.arrangeStickers(layerId, ids, to) })
+      handler: async ({ layerId, ids, to }) => {
+        await c.prepareStickers(c.listStickers(layerId).map((s) => s.ref));
+        return { order: c.arrangeStickers(layerId, ids, to) };
+      }
     },
     {
       name: "remove_stickers",
@@ -8153,7 +8261,10 @@ function createPaintStickerTools(c) {
       description: "Deletes stickers by id, or every sticker on the layer when ids is missing. One undo step. Returns the ids removed.",
       inputSchema: { type: "object", properties: { layerId: LAYER_ID, ids: { type: "array", items: { type: "string", description: "Sticker id." }, description: "Sticker ids (default all)." } }, additionalProperties: false },
       annotations: { title: "Delete stickers", ...DESTRUCTIVE },
-      handler: ({ layerId, ids }) => ({ removed: c.removeStickers(layerId, ids) })
+      handler: async ({ layerId, ids }) => {
+        await c.prepareStickers(c.listStickers(layerId).map((s) => s.ref));
+        return { removed: c.removeStickers(layerId, ids) };
+      }
     }
   ];
 }
@@ -9167,7 +9278,13 @@ var STICKER_BRUSH = {
   type: "object",
   description: "Sticker engine settings: stamps sprayed along the stroke as editable stickers. Missing fields keep their current values.",
   properties: {
-    stamps: { type: "array", minItems: 1, maxItems: 9, items: { type: "string", enum: [...STAMP_KINDS], description: "A stamp." }, description: "The stamps to spray (one picked at random per sticker)." },
+    stamps: {
+      type: "array",
+      minItems: 1,
+      maxItems: MAX_STICKER_STAMPS,
+      items: { type: "string", minLength: 1, description: "A sticker ref provider:id from find_stickers (e.g. editor:star); a bare editor stamp (star) means editor:star." },
+      description: `The stickers to spray, one picked at random per sticker: refs from find_stickers (the editor's own: ${STAMP_KINDS.map((k) => `editor:${k}`).join(", ")}). Each is checked against the sticker library and an unknown ref is refused with the closest ones. A provider's sticker is drawn from its art (tinted to the paint colour when tintable), loaded before the stroke.`
+    },
     density: { type: "number", minimum: 0, maximum: 1, description: "How closely stickers follow each other: about density \xD7 4 stickers per tip diameter of travel (0.25 \u2248 one per diameter, 1 \u2248 four). Default 0.4." },
     sizeJitter: { type: "number", minimum: 0, maximum: 1, description: "Random size change." },
     rotationJitter: { type: "number", minimum: 0, maximum: 1, description: "Random turn as a fraction of \xB1180\xB0." },
@@ -9594,7 +9711,11 @@ function createPaintEditorToolProvider(controller, options = {}) {
     description: "Chooses the active brush (id) and / or changes its settings; strokes without a brush use it. Editor state, not an undo step. Changes stay on the active brush until save_brush stores them. Returns the active brush.",
     inputSchema: { type: "object", properties: { id: { type: "string", description: "Brush id from list_brushes to start from." }, ...BRUSH_FIELDS }, additionalProperties: false },
     annotations: { title: "Set the brush", ...SET4 },
-    handler: (a) => brushToJSON(c.setBrush(a))
+    handler: async (a) => {
+      const stamps = a.sticker?.stamps;
+      if (stamps) await c.prepareStickers(stamps);
+      return brushToJSON(c.setBrush(a));
+    }
   });
   add({
     name: "save_brush",
@@ -9770,6 +9891,9 @@ function createPaintEditorToolProvider(controller, options = {}) {
     coordinates: { in: ["points[]"], out: ["bounds"] },
     handler: async (a) => {
       await c.wetIdle();
+      const base = a.brushId ? c.getBrush(a.brushId) : c.getState().brush;
+      const over = a.brush;
+      if ((over?.engine ?? base?.engine) === "sticker") await c.prepareStickers(over?.sticker?.stamps ?? base?.sticker.stamps ?? []);
       const stroke = { points: a.points, layerId: a.layerId, brushId: a.brushId, brush: a.brush, color: a.color, paint: a.paint, seed: a.seed, snapToPerspective: a.snapToPerspective };
       const r = await act({ kind: "stroke", stroke }, () => c.paintStroke(stroke));
       return r.mixerLoad ? { ...r, mixerLoad: loadResult(r.mixerLoad) } : r;
@@ -10078,6 +10202,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   tools.push(...createPaintReplayTools(c));
   tools.push(...createPaintStickerTools(c));
   tools.push(...createPigmentTools());
+  tools.push(...createStickerTools({ provider: () => c.stickersProvider }));
   tools.push(
     ...createLayerEffectTools(
       {
@@ -10251,7 +10376,7 @@ var PaintGesture = class {
       }
       const brush = this.controller.getState().brush;
       const size = Math.min(2048, Math.max(2, Math.round(brush.tip.size)));
-      const [added] = this.controller.addStickers(void 0, [{ stamp: brush.sticker.stamps[0] ?? "star", x: round2(p.x), y: round2(p.y), size }]);
+      const [added] = this.controller.addStickers(void 0, [{ ref: brush.sticker.stamps[0] ?? "editor:star", x: round2(p.x), y: round2(p.y), size }]);
       this.controller.selectSticker(added.id);
     } catch (err) {
       this.error = err instanceof Error ? err.message : String(err);
@@ -10787,6 +10912,15 @@ var RIBBON_PAIR_LABELS = { adjacent: "Neighbours", "first-last": "Outermost" };
 var DOT_TEXTURE_ORDER_LABELS = { sequence: "In turn", random: "Random" };
 var DOT_ROTATION_LABELS = { follow: "Follow motion", random: "Random", fixed: "Tip angle" };
 var STAMP_LABELS = { dot: "Dot", star: "Star", heart: "Heart", leaf: "Leaf", flower: "Flower", confetti: "Confetti", splat: "Splat", sparkle: "Sparkle", ring: "Ring" };
+function toggleStickerRef(refs, ref2) {
+  if (refs.includes(ref2)) return refs.length > 1 ? refs.filter((r) => r !== ref2) : [...refs];
+  return refs.length < MAX_STICKER_STAMPS ? [...refs, ref2] : [...refs];
+}
+function stickerRefLabel(ref2) {
+  const stamp = ref2.startsWith("editor:") ? ref2.slice(7) : null;
+  if (stamp && STAMP_LABELS[stamp]) return STAMP_LABELS[stamp];
+  return ref2.slice(ref2.indexOf(":") + 1);
+}
 function toggleStamp(stamps, stamp) {
   const next = stamps.includes(stamp) ? stamps.filter((s) => s !== stamp) : [...stamps, stamp];
   return next.length ? next : [stamp];
@@ -11141,6 +11275,7 @@ export {
   MAX_DOT_TEXTURES,
   MAX_IMAGE_SIDE,
   MAX_LIVE_EFFECT_SOURCES,
+  MAX_STICKER_STAMPS,
   MAX_ZOOM,
   MIN_CANVAS_SIDE,
   MIN_ZOOM,
@@ -11205,10 +11340,13 @@ export {
   STAMP_LABELS,
   STENCIL_KINDS,
   STENCIL_SHAPES,
+  STICKER_ART_SIZE,
   STICKER_SLIDERS,
   STROKE_SLIDERS,
   SYMMETRY_MODES,
   StencilSnapper,
+  StickerArtCache,
+  StickerBrowser,
   StickerSpray,
   TRACING_NODE_ID,
   ThickStrokeDriver,
@@ -11256,6 +11394,7 @@ export {
   decodeImageBlob,
   defaultGuides,
   defaultImageEncoder,
+  defaultStickerRasterizer,
   deserializePaintDocument,
   deserializePaintDocumentAsync,
   documentExtensions,
@@ -11374,6 +11513,7 @@ export {
   rgbToHexColor,
   rgbToHsl,
   rgbToHsv,
+  sampleArt,
   sampleEffectAt,
   sampleEffectField,
   samplePressure,
@@ -11391,6 +11531,8 @@ export {
   stencilOutline,
   stickerAt,
   stickerRect,
+  stickerRefLabel,
+  stickerStamp,
   stickerSurface,
   strokeBounds,
   strokeDuration,
@@ -11408,6 +11550,7 @@ export {
   toStrokePoint,
   toggleDotTexture,
   toggleStamp,
+  toggleStickerRef,
   translateStencil,
   updatePaintGradientStop,
   usesPaintExchange,

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[];