@pixerate/editor 0.262.1 → 0.263.0

package/dist/paint-editor/index.js

@@ -1,7 +1,7 @@
 import {
   StickerBrowser,
   editorStickers
-} from "../chunk-F7CPSRLN.js";
+} from "../chunk-DOZ6F2K2.js";
 import {
   BRUSH_PATCH_PROPERTIES,
   BRUSH_SLIDERS,
@@ -11,11 +11,11 @@ import {
   mergeBrushPatch,
   multiColorSliders,
   patchBrushValue
-} from "../chunk-X2EXYY4J.js";
+} from "../chunk-CNLO6E2K.js";
 import {
   createStickerTools,
   describeStickerRef
-} from "../chunk-J5UQHWVL.js";
+} from "../chunk-6JL2D5SG.js";
 import {
   toVideoFfmpeg
 } from "../chunk-MWUZCEFT.js";
@@ -30,7 +30,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-D4TE5JNW.js";
+} from "../chunk-QW7LKWKE.js";
 import "../chunk-WJ4WQJCC.js";
 import {
   LAYER_EFFECT_KINDS,
@@ -88,7 +88,7 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-IVSWRVB4.js";
-import "../chunk-6NZL24W4.js";
+import "../chunk-34HIZXFX.js";
 import {
   BRUSH_ID,
   BRUSH_PRESETS,
@@ -143,15 +143,16 @@ import {
   parseBrushLibrary,
   resolveBrush,
   usesPaintExchange
-} from "../chunk-5IW65VQ6.js";
+} from "../chunk-P5343XZO.js";
 import {
   STAMP_KINDS,
   StickersSlot,
   editorStampOf,
   normalizeStickerRef,
   stampCoverage,
-  stickerIdFor
-} from "../chunk-APX63ILU.js";
+  stickerIdFor,
+  stickerVariantFor
+} from "../chunk-ACFSFUQH.js";
 import "../chunk-M6DNZNVY.js";
 import {
   bezierPathToSvg,
@@ -2538,49 +2539,77 @@ var defaultStickerRasterizer = async (asset, size) => {
   const img = ctx.getImageData(0, 0, w, h);
   return { width: w, height: h, data: img.data };
 };
-var StickerArtCache = class {
+var StickerArtCache = class _StickerArtCache {
   entries = /* @__PURE__ */ new Map();
-  /** The art for `ref` when it has loaded (editor stamps never need any). */
-  get = (ref2) => {
-    const e = this.entries.get(ref2);
+  /** Descriptions by ref (their variants pick the art), shared by the loads that need them. */
+  descriptions = /* @__PURE__ */ new Map();
+  variants = /* @__PURE__ */ new Map();
+  static key(ref2, variant = "light") {
+    return variant === "dark" ? `${ref2}#dark` : ref2;
+  }
+  /** The art for `ref` in `variant` (default `light`) when it has loaded (editor stamps never need any). */
+  get = (ref2, variant) => {
+    const e = this.entries.get(_StickerArtCache.key(ref2, variant));
     return e?.status === "ready" ? e.art : void 0;
   };
+  /** The variant to draw `ref` in on a dark or light background: `dark` once the sticker is known to have it. */
+  variantFor(ref2, dark) {
+    return dark && this.variants.get(ref2)?.includes("dark") ? "dark" : "light";
+  }
   /** `ready`, `loading`, `failed` (with the reason) or `none` (never asked for). Editor stamps are always `ready`. */
-  status(ref2) {
+  status(ref2, variant) {
     if (editorStampOf(ref2)) return { status: "ready" };
-    const e = this.entries.get(ref2);
-    if (!e) return { status: "none" };
+    const e = this.entries.get(_StickerArtCache.key(ref2, variant));
+    if (!e) return this.descriptions.has(ref2) && !this.variants.has(ref2) ? { status: "loading" } : { status: "none" };
     return e.status === "failed" ? { status: "failed", error: e.error } : { status: e.status };
   }
   /**
-   * 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.
+   * Loads and rasterises `ref` from `provider` once per variant (later calls share the load): the
+   * dark variant when `dark` and the sticker has one, else the light. Unknown refs reject with the
+   * closest known ones; failures are kept so they are reported, and retried on the next call.
    */
-  ensure(provider, ref2, rasterize) {
-    if (editorStampOf(ref2)) return Promise.resolve(null);
-    const e = this.entries.get(ref2);
+  async ensure(provider, ref2, rasterize, dark = false) {
+    if (editorStampOf(ref2)) return null;
+    let described = this.descriptions.get(ref2);
+    if (!described) {
+      described = describeStickerRef(provider, ref2);
+      this.descriptions.set(ref2, described);
+    }
+    let d;
+    try {
+      d = await described;
+    } catch (err) {
+      this.descriptions.delete(ref2);
+      this.entries.set(_StickerArtCache.key(ref2), { status: "failed", error: err instanceof Error ? err.message : String(err) });
+      throw err;
+    }
+    this.variants.set(ref2, d.variants ?? ["light"]);
+    return this.load(provider, ref2, d, stickerVariantFor(d, dark), rasterize);
+  }
+  load(provider, ref2, d, variant, rasterize) {
+    const key = _StickerArtCache.key(ref2, variant);
+    const e = this.entries.get(key);
     if (e?.status === "ready") return Promise.resolve(e.art);
     if (e?.status === "loading") return e.promise;
     const promise = (async () => {
-      const d = await describeStickerRef(provider, ref2);
       const id = stickerIdFor(provider, ref2);
       const max = provider.capabilities.maxSize ?? STICKER_ART_SIZE;
       const size = Math.min(STICKER_ART_SIZE, max);
-      const asset = await provider.load(id, d.formats.includes("png") ? { format: "png", size } : { format: d.formats[0] ?? "svg", size });
+      const v = variant === "dark" ? { variant } : {};
+      const asset = await provider.load(id, d.formats.includes("png") ? { format: "png", size, ...v } : { format: d.formats[0] ?? "svg", size, ...v });
       const px = await rasterize(asset, size);
       if (!(px.width > 0 && px.height > 0) || px.data.length !== px.width * px.height * 4) throw new StickerError("load_failed", `The art for "${ref2}" came back empty or the wrong size.`);
       return { ...px, tintable: d.tintable };
     })();
-    this.entries.set(ref2, { status: "loading", promise });
+    this.entries.set(key, { status: "loading", promise });
     return promise.then(
       (art) => {
-        this.entries.set(ref2, { status: "ready", art });
+        this.entries.set(key, { status: "ready", art });
         return art;
       },
       (err) => {
         const message = err instanceof Error ? err.message : String(err);
-        this.entries.set(ref2, { status: "failed", error: message });
+        this.entries.set(key, { status: "failed", error: message });
         throw err;
       }
     );
@@ -2588,6 +2617,8 @@ var StickerArtCache = class {
   /** Forgets every load (a new provider). */
   clear() {
     this.entries.clear();
+    this.descriptions.clear();
+    this.variants.clear();
   }
 };
 function sampleArt(art, x, y, out) {
@@ -2645,7 +2676,7 @@ function stickerStamp(s) {
 function drawSticker(medium, s, art) {
   const kind = stickerStamp(s);
   if (!kind) {
-    const a2 = art?.(s.ref);
+    const a2 = art?.(s.ref, s.variant);
     return a2 ? drawArtSticker(medium, s, a2) : stickerRect(s);
   }
   const rect = stickerRect(s);
@@ -2792,7 +2823,8 @@ var StickerSpray = class {
     }
     const ref2 = st.stamps[Math.floor(rand01(seed, i, 57) * st.stamps.length)] ?? "editor:dot";
     const stamp = stickerStamp({ ref: ref2 });
-    if (!stamp && !this.init.art?.(ref2)) {
+    const variant = stamp ? "light" : this.init.variant?.(ref2) ?? "light";
+    if (!stamp && !this.init.art?.(ref2, variant)) {
       this.skipped.add(ref2);
       this.next++;
       return;
@@ -2807,7 +2839,8 @@ var StickerSpray = class {
       rotation: Math.round((-d.angle * 180 / Math.PI + (rand01(seed, i, 59) * 2 - 1) * 180 * st.rotationJitter) * 10) / 10,
       color: st.colorJitter > 0 ? jitterColor(base.color, st.colorJitter, seed, i) : base.color,
       opacity: Math.round(Math.min(1, d.opacity * this.init.brush.tip.opacity * base.alpha) * 1e3) / 1e3,
-      seed: Math.floor(rand01(seed, i, 65) * 1e9)
+      seed: Math.floor(rand01(seed, i, 65) * 1e9),
+      ...variant === "dark" ? { variant } : {}
     };
     this.stickers.push(sticker);
     rects.push(drawSticker(this.medium, sticker, this.init.art));
@@ -2914,7 +2947,7 @@ function stickerAt(stickers, x, y, art) {
       if (stampCoverage(kind, u, v, s.seed) > 0.25) return s;
       continue;
     }
-    const pic = art?.(s.ref);
+    const pic = art?.(s.ref, s.variant);
     if (!pic) return s;
     const scale = Math.max(pic.width, pic.height) / 2;
     if (sampleArt(pic, u * scale + pic.width / 2, v * scale + pic.height / 2, [0, 0, 0, 0])[3] > 0.25) return s;
@@ -2965,7 +2998,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, art: init.sticker.art });
+      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, variant: init.sticker.variant });
     } 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 });
@@ -7465,6 +7498,8 @@ var PaintEditorController = class _PaintEditorController {
     this.colorScheme = next;
     const hex2 = this.brushColour ? brushColourHex(this.brushColour, next) : null;
     if (hex2) this.color = hex2;
+    const refs = brushStickerRefs(this.brush);
+    if (refs.some((r) => !editorStampOf(r))) void this.prepareStickers(refs).catch(() => this.emit([]));
     this.emit([]);
   }
   /** Locks the paint colour: choosing a brush with a default colour keeps it. Editor state, not an undo step. */
@@ -7748,7 +7783,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), art: this.stickerArt.get } : void 0,
+      sticker: brush.engine === "sticker" ? { nextId: this.nextStickerNumber(doc), art: this.stickerArt.get, variant: (ref2) => this.stickerArt.variantFor(ref2, this.colorScheme === "dark") } : void 0,
       stampArt: this.stickerArt.get,
       paint: effect ? null : this.strokeGradient(init, brush, color),
       effect
@@ -8598,8 +8633,8 @@ var PaintEditorController = class _PaintEditorController {
           try {
             const ref2 = normalizeStickerRef(x.ref ?? x.stamp);
             const stamp = editorStampOf(ref2);
-            const { stamp: _old, ...rest } = x;
-            return [{ ...rest, ref: ref2, ...stamp ? { stamp } : {} }];
+            const { stamp: _old, variant, ...rest } = x;
+            return [{ ...rest, ref: ref2, ...stamp ? { stamp } : {}, ...variant === "dark" && !stamp ? { variant } : {} }];
           } catch {
             return [];
           }
@@ -9056,22 +9091,32 @@ var PaintEditorController = class _PaintEditorController {
   }
   /**
    * 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
+   * can draw them: their dark variants when the colour scheme is dark and they have one. 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)));
+      await Promise.all(list.map((r) => this.stickerArt.ensure(this.stickers.provider, r, this.rasterizeSticker, this.colorScheme === "dark")));
     } 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`. */
+  /** Whether a sticker's art is ready to draw in the variant the colour scheme picks: `ready` (always for editor stamps), `loading`, `failed` (with why) or `none`. */
   stickerArtStatus(ref2) {
-    return this.stickerArt.status(this.readStickerRef(ref2));
+    const r = this.readStickerRef(ref2);
+    return this.stickerArt.status(r, this.stickerArt.variantFor(r, this.colorScheme === "dark"));
+  }
+  /**
+   * A sticker whose ref is new (placed or restamped) in the variant the colour scheme picks: `dark`
+   * on a dark scheme when its sticker has one (known once its art was asked for).
+   */
+  withStickerVariant(s) {
+    const { variant: _old, ...rest } = s;
+    const v = editorStampOf(s.ref) ? "light" : this.stickerArt.variantFor(s.ref, this.colorScheme === "dark");
+    return v === "dark" ? { ...rest, variant: v } : rest;
   }
   readStickerRef(ref2) {
     try {
@@ -9082,10 +9127,17 @@ var PaintEditorController = class _PaintEditorController {
   }
   /** 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))];
+    const missing = stickers.filter((s) => !stickerStamp(s) && !this.stickerArt.get(s.ref, s.variant));
     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.`);
+      const dark = this.colorScheme === "dark";
+      const loads = /* @__PURE__ */ new Map();
+      for (const s of missing) {
+        loads.set(`${s.ref}#${s.variant ?? "light"}`, [s.ref, s.variant === "dark"]);
+        if (dark) loads.set(`${s.ref}#dark`, [s.ref, true]);
+      }
+      for (const [r, d] of loads.values()) void this.stickerArt.ensure(this.stickers.provider, r, this.rasterizeSticker, d).then(() => this.emit([]), () => this.emit([]));
+      const refs = [...new Set(missing.map((s) => s.ref))];
+      throw new PaintEditorError(`The art for ${refs.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. */
@@ -9148,7 +9200,8 @@ var PaintEditorController = class _PaintEditorController {
     if (isLayerLocked(layer, "pixels")) throw new PaintEditorError(`Layer "${layer.name}" has its pixels locked; unlock it first.`);
     const i = stickers.findIndex((s) => s.id === id);
     if (i < 0) throw new PaintEditorError(`Layer "${layer.name}" has no sticker "${id}". Call list_stickers for the ids.`);
-    const next = { ...stickers[i], ...this.readStickerUpdate(update) };
+    const u = this.readStickerUpdate(update);
+    const next = u.ref !== void 0 ? this.withStickerVariant({ ...stickers[i], ...u }) : { ...stickers[i], ...u };
     const list = stickers.map((s, j) => j === i ? next : s);
     const dirty = [stickerRect(stickers[i]), stickerRect(next)];
     const base = this.previewBase() ?? this.doc;
@@ -9172,7 +9225,7 @@ var PaintEditorController = class _PaintEditorController {
     const i = stickers.findIndex((s) => s.id === id);
     if (i < 0) throw new PaintEditorError(`Layer "${layer.name}" has no sticker "${id}". Call list_stickers for the ids.`);
     const u = this.readStickerUpdate(update);
-    const next = { ...stickers[i], ...u };
+    const next = u.ref !== void 0 ? this.withStickerVariant({ ...stickers[i], ...u }) : { ...stickers[i], ...u };
     this.commitStickers("Edit sticker", layer, stickers.map((s, j) => j === i ? next : s), [stickerRect(stickers[i]), stickerRect(next)]);
     return { ...next };
   }
@@ -9201,7 +9254,7 @@ var PaintEditorController = class _PaintEditorController {
       }
       if (raw.seed !== void 0 && !Number.isInteger(raw.seed)) throw new PaintEditorError(`Sticker ${i}: seed must be a whole number.`);
       const id = n++;
-      return { id: `st${id}`, size: 48, rotation: 0, color: this.color, opacity: 1, seed: raw.seed ?? mix32(id * 2654435761 >>> 0) & 2147483647, ...u };
+      return this.withStickerVariant({ id: `st${id}`, size: 48, rotation: 0, color: this.color, opacity: 1, seed: raw.seed ?? mix32(id * 2654435761 >>> 0) & 2147483647, ...u });
     });
     this.commitStickers("Add stickers", layer, [...existing ?? [], ...added], existing?.length ? added.map(stickerRect) : void 0);
     return added.map((s) => ({ ...s }));

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

@@ -6,8 +6,11 @@
  * 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`).
+ *
+ * A sticker with a dark variant is kept in each variant asked for: `ensure(…, dark)` loads the dark
+ * art when the sticker has it, and sprayed stickers record the variant they were drawn in.
  */
-import type { StickerAsset, StickerProvider, StickerRef } from '../stickers/types.cjs';
+import type { StickerAsset, StickerProvider, StickerRef, StickerVariant } from '../stickers/types.cjs';
 /** Rasterised sticker art (straight RGBA) and whether to recolour it. */
 export interface StickerArt {
     width: number;
@@ -16,8 +19,8 @@ export interface StickerArt {
     /** 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;
+/** The art for a ref in a variant (default `light`), when it has loaded. */
+export type StickerArtLookup = (ref: StickerRef, variant?: StickerVariant) => 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;
@@ -32,22 +35,29 @@ export declare const STICKER_ART_SIZE = 256;
  * that adds a rasteriser.
  */
 export declare const defaultStickerRasterizer: StickerRasterizer;
-/** Loaded sticker art by ref, with the state of each load. */
+/** Loaded sticker art by ref and variant, 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). */
+    /** Descriptions by ref (their variants pick the art), shared by the loads that need them. */
+    private readonly descriptions;
+    private readonly variants;
+    private static key;
+    /** The art for `ref` in `variant` (default `light`) when it has loaded (editor stamps never need any). */
     get: StickerArtLookup;
+    /** The variant to draw `ref` in on a dark or light background: `dark` once the sticker is known to have it. */
+    variantFor(ref: StickerRef, dark: boolean): StickerVariant;
     /** `ready`, `loading`, `failed` (with the reason) or `none` (never asked for). Editor stamps are always `ready`. */
-    status(ref: StickerRef): {
+    status(ref: StickerRef, variant?: StickerVariant): {
         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.
+     * Loads and rasterises `ref` from `provider` once per variant (later calls share the load): the
+     * dark variant when `dark` and the sticker has one, else the light. 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>;
+    ensure(provider: StickerProvider, ref: StickerRef, rasterize: StickerRasterizer, dark?: boolean): Promise<StickerArt | null>;
+    private load;
     /** Forgets every load (a new provider). */
     clear(): void;
 }

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

@@ -6,8 +6,11 @@
  * 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`).
+ *
+ * A sticker with a dark variant is kept in each variant asked for: `ensure(…, dark)` loads the dark
+ * art when the sticker has it, and sprayed stickers record the variant they were drawn in.
  */
-import type { StickerAsset, StickerProvider, StickerRef } from '../stickers/types.js';
+import type { StickerAsset, StickerProvider, StickerRef, StickerVariant } from '../stickers/types.js';
 /** Rasterised sticker art (straight RGBA) and whether to recolour it. */
 export interface StickerArt {
     width: number;
@@ -16,8 +19,8 @@ export interface StickerArt {
     /** 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;
+/** The art for a ref in a variant (default `light`), when it has loaded. */
+export type StickerArtLookup = (ref: StickerRef, variant?: StickerVariant) => 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;
@@ -32,22 +35,29 @@ export declare const STICKER_ART_SIZE = 256;
  * that adds a rasteriser.
  */
 export declare const defaultStickerRasterizer: StickerRasterizer;
-/** Loaded sticker art by ref, with the state of each load. */
+/** Loaded sticker art by ref and variant, 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). */
+    /** Descriptions by ref (their variants pick the art), shared by the loads that need them. */
+    private readonly descriptions;
+    private readonly variants;
+    private static key;
+    /** The art for `ref` in `variant` (default `light`) when it has loaded (editor stamps never need any). */
     get: StickerArtLookup;
+    /** The variant to draw `ref` in on a dark or light background: `dark` once the sticker is known to have it. */
+    variantFor(ref: StickerRef, dark: boolean): StickerVariant;
     /** `ready`, `loading`, `failed` (with the reason) or `none` (never asked for). Editor stamps are always `ready`. */
-    status(ref: StickerRef): {
+    status(ref: StickerRef, variant?: StickerVariant): {
         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.
+     * Loads and rasterises `ref` from `provider` once per variant (later calls share the load): the
+     * dark variant when `dark` and the sticker has one, else the light. 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>;
+    ensure(provider: StickerProvider, ref: StickerRef, rasterize: StickerRasterizer, dark?: boolean): Promise<StickerArt | null>;
+    private load;
     /** Forgets every load (a new provider). */
     clear(): void;
 }

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

@@ -15,7 +15,7 @@ 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 { StickerRef, StickerVariant } from '../stickers/types.cjs';
 import { type StickerArtLookup } from './sticker-art.cjs';
 export { STAMP_KINDS, stampCoverage, type StampKind } from '../stickers/stamps.cjs';
 export { DEFAULT_STICKER, MAX_STICKER_STAMPS, normalizeStickerSettings, type StickerSettings } from './mark-settings.cjs';
@@ -39,6 +39,11 @@ export interface Sticker {
     opacity: number;
     /** Texture seed. */
     seed: number;
+    /**
+     * `dark` when it is drawn in its sticker's dark variant (sprayed or placed while the editor's
+     * colour scheme was dark and the sticker has one); absent for the light art.
+     */
+    variant?: StickerVariant;
 }
 /** The pixel rectangle a sticker covers. */
 export declare function stickerRect(s: Sticker): RasterRect;
@@ -69,6 +74,8 @@ export interface StickerSprayInit {
     effect?: EffectPaintPixels | null;
     /** Loaded art for provider stickers; stickers without art yet are skipped (see `skipped`). */
     art?: StickerArtLookup;
+    /** The variant to spray a provider sticker in (default `light`); recorded on each sticker. */
+    variant?: (ref: StickerRef) => StickerVariant;
 }
 /** A sticker-spray stroke: drops stickers along the path and draws them as it goes. */
 export declare class StickerSpray {

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

@@ -15,7 +15,7 @@ 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 { StickerRef, StickerVariant } from '../stickers/types.js';
 import { type StickerArtLookup } from './sticker-art.js';
 export { STAMP_KINDS, stampCoverage, type StampKind } from '../stickers/stamps.js';
 export { DEFAULT_STICKER, MAX_STICKER_STAMPS, normalizeStickerSettings, type StickerSettings } from './mark-settings.js';
@@ -39,6 +39,11 @@ export interface Sticker {
     opacity: number;
     /** Texture seed. */
     seed: number;
+    /**
+     * `dark` when it is drawn in its sticker's dark variant (sprayed or placed while the editor's
+     * colour scheme was dark and the sticker has one); absent for the light art.
+     */
+    variant?: StickerVariant;
 }
 /** The pixel rectangle a sticker covers. */
 export declare function stickerRect(s: Sticker): RasterRect;
@@ -69,6 +74,8 @@ export interface StickerSprayInit {
     effect?: EffectPaintPixels | null;
     /** Loaded art for provider stickers; stickers without art yet are skipped (see `skipped`). */
     art?: StickerArtLookup;
+    /** The variant to spray a provider sticker in (default `light`); recorded on each sticker. */
+    variant?: (ref: StickerRef) => StickerVariant;
 }
 /** A sticker-spray stroke: drops stickers along the path and draws them as it goes. */
 export declare class StickerSpray {

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

@@ -21,6 +21,7 @@ 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';
+import type { StickerRef, StickerVariant } from '../stickers/types.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;
@@ -78,6 +79,7 @@ export interface StrokeSessionInit {
     sticker?: {
         nextId: number;
         art?: StickerArtLookup;
+        variant?: (ref: StickerRef) => StickerVariant;
     };
     /** Loaded sticker art for stamp tips and textured particle dots of stickers from the sticker library. */
     stampArt?: StickerArtLookup;

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

@@ -21,6 +21,7 @@ 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';
+import type { StickerRef, StickerVariant } from '../stickers/types.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;
@@ -78,6 +79,7 @@ export interface StrokeSessionInit {
     sticker?: {
         nextId: number;
         art?: StickerArtLookup;
+        variant?: (ref: StickerRef) => StickerVariant;
     };
     /** Loaded sticker art for stamp tips and textured particle dots of stickers from the sticker library. */
     stampArt?: StickerArtLookup;

package/dist/stickers/browser.d.cts

@@ -1,9 +1,10 @@
 /**
  * `StickerBrowser`: the state behind a sticker picker, shared by the React and Svelte pickers. It
- * searches or lists the provider a page at a time (search words, category), keeps the pages it
- * has loaded and its categories, and tells listeners when anything changes. UI-agnostic.
+ * searches or lists the provider a page at a time (search words, category, collection), keeps the
+ * pages it has loaded, its categories and collections, and tells listeners when anything changes.
+ * UI-agnostic.
  */
-import type { StickerProvider, StickerRef, StickerSummary } from './types.cjs';
+import type { StickerCollection, StickerProvider, StickerRef, StickerSummary } from './types.cjs';
 export interface StickerBrowserItem extends StickerSummary {
     ref: StickerRef;
 }
@@ -11,6 +12,8 @@ export interface StickerBrowserState {
     query: string;
     /** `''` for every category. */
     category: string;
+    /** `''` for every collection. */
+    collection: string;
     items: StickerBrowserItem[];
     total: number;
     /** More pages to load (`more()`). */
@@ -22,6 +25,8 @@ export interface StickerBrowserState {
         name: string;
         count: number;
     }>;
+    /** The provider's collections (empty when it has none). */
+    collections: StickerCollection[];
     /** The provider's name. */
     provider: string;
 }
@@ -42,6 +47,8 @@ export declare class StickerBrowser {
     setQuery(query: string): Promise<void>;
     /** Shows one category (`''` for all) from the first page. */
     setCategory(category: string): Promise<void>;
+    /** Shows one collection (`''` for all) from the first page. */
+    setCollection(collection: string): Promise<void>;
     /** Loads the next page onto the list. */
     more(): Promise<void>;
     private page;

package/dist/stickers/browser.d.ts

@@ -1,9 +1,10 @@
 /**
  * `StickerBrowser`: the state behind a sticker picker, shared by the React and Svelte pickers. It
- * searches or lists the provider a page at a time (search words, category), keeps the pages it
- * has loaded and its categories, and tells listeners when anything changes. UI-agnostic.
+ * searches or lists the provider a page at a time (search words, category, collection), keeps the
+ * pages it has loaded, its categories and collections, and tells listeners when anything changes.
+ * UI-agnostic.
  */
-import type { StickerProvider, StickerRef, StickerSummary } from './types.js';
+import type { StickerCollection, StickerProvider, StickerRef, StickerSummary } from './types.js';
 export interface StickerBrowserItem extends StickerSummary {
     ref: StickerRef;
 }
@@ -11,6 +12,8 @@ export interface StickerBrowserState {
     query: string;
     /** `''` for every category. */
     category: string;
+    /** `''` for every collection. */
+    collection: string;
     items: StickerBrowserItem[];
     total: number;
     /** More pages to load (`more()`). */
@@ -22,6 +25,8 @@ export interface StickerBrowserState {
         name: string;
         count: number;
     }>;
+    /** The provider's collections (empty when it has none). */
+    collections: StickerCollection[];
     /** The provider's name. */
     provider: string;
 }
@@ -42,6 +47,8 @@ export declare class StickerBrowser {
     setQuery(query: string): Promise<void>;
     /** Shows one category (`''` for all) from the first page. */
     setCategory(category: string): Promise<void>;
+    /** Shows one collection (`''` for all) from the first page. */
+    setCollection(collection: string): Promise<void>;
     /** Loads the next page onto the list. */
     more(): Promise<void>;
     private page;

package/dist/stickers/combine.d.cts

@@ -3,6 +3,8 @@ import type { StickerProvider } from './types.cjs';
  * One provider over several, in order. Its ids are refs (`provider:id`, `namespaced`), so the
  * same id from two libraries stays two stickers. Pages run through the providers in turn; the
  * cursor is `<provider index>|<that provider's cursor>`. Capabilities are what any of them offers.
+ * Collections are namespaced the same way (`provider:collection`), so a picker can tell a
+ * provider's collections apart from another provider's.
  */
 export declare function combineStickerProviders(providers: readonly StickerProvider[], options?: {
     id?: string;

package/dist/stickers/combine.d.ts

@@ -3,6 +3,8 @@ import type { StickerProvider } from './types.js';
  * One provider over several, in order. Its ids are refs (`provider:id`, `namespaced`), so the
  * same id from two libraries stays two stickers. Pages run through the providers in turn; the
  * cursor is `<provider index>|<that provider's cursor>`. Capabilities are what any of them offers.
+ * Collections are namespaced the same way (`provider:collection`), so a picker can tell a
+ * provider's collections apart from another provider's.
  */
 export declare function combineStickerProviders(providers: readonly StickerProvider[], options?: {
     id?: string;