@pixerate/editor 0.236.0 → 0.238.0

package/dist/paint-editor/index.js

@@ -7,7 +7,7 @@ import {
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-JVNGCS26.js";
+} from "../chunk-3E36VDMJ.js";
 import "../chunk-3CI7FRMK.js";
 import "../chunk-ZNA3IQZF.js";
 import {
@@ -55,7 +55,7 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-IVSWRVB4.js";
-import "../chunk-CU6ANS5L.js";
+import "../chunk-7YGBSFC6.js";
 import {
   BRUSH_ID,
   BRUSH_ROTATIONS,
@@ -120,12 +120,13 @@ import {
   sampleEffectAt,
   sampleEffectField,
   stampCoverage,
+  stickerAt,
   stickerRect,
   stickerSurface,
   tiltToOrientation,
   toStrokePoint,
   usesPaintExchange
-} from "../chunk-TQOL6CF7.js";
+} from "../chunk-PJYG6FCF.js";
 import "../chunk-M6DNZNVY.js";
 import "../chunk-WEIK3UYB.js";
 import "../chunk-PWBZH3FK.js";
@@ -240,16 +241,17 @@ import {
   defineEditorDocument
 } from "../chunk-XBQX76CT.js";
 import "../chunk-HF5QZS7Z.js";
-import "../chunk-M2TPMYJE.js";
+import "../chunk-V6DT2CDH.js";
 import "../chunk-2WPNAGHI.js";
 import {
   HARMONY_KINDS,
   colorHarmony,
   hueToWheel,
   wheelToHue
-} from "../chunk-7272D3K2.js";
-import "../chunk-YBAPT7NL.js";
-import "../chunk-MHLU6GRJ.js";
+} from "../chunk-BP6KSGVD.js";
+import "../chunk-6ADHGQ73.js";
+import "../chunk-JEGJP4OW.js";
+import "../chunk-F67XMVDI.js";
 import "../chunk-6ONMQ6WF.js";
 
 // src/paint-editor/document.ts
@@ -3404,6 +3406,7 @@ var PaintEditorError = class extends Error {
   }
 };
 var HEX2 = /^#[0-9a-f]{6}$/i;
+var MAX_ADD_STICKERS = 500;
 function parseColor(value, what = "color") {
   if (typeof value !== "string" || !HEX2.test(value.trim())) throw new PaintEditorError(`${what} is ${JSON.stringify(value)}; use #rrggbb, e.g. "#2a4b8d".`);
   return value.trim().toLowerCase();
@@ -3447,6 +3450,9 @@ var PaintEditorController = class _PaintEditorController {
   mixerLoad = EMPTY_MIXER_LOAD;
   view = { ...DEFAULT_VIEW, pan: { ...DEFAULT_VIEW.pan } };
   hand;
+  selectedSticker = null;
+  /** A sticker drag in progress (`previewSticker`): the document before it, so the drop undoes in one step, and the one it showed last. */
+  stickerPreview = null;
   encodeImage;
   listeners = /* @__PURE__ */ new Set();
   version = 0;
@@ -3543,6 +3549,7 @@ var PaintEditorController = class _PaintEditorController {
       mixerLoad: this.mixerLoad,
       view: this.view,
       hand: this.hand,
+      selectedSticker: this.selectedSticker,
       canUndo: this.undoStack.length > 0 && !this.session,
       canRedo: this.redoStack.length > 0 && !this.session,
       undoLabel: last?.label ?? null,
@@ -4802,7 +4809,11 @@ var PaintEditorController = class _PaintEditorController {
     const snapper = init.snapToPerspective && perspective.enabled && perspective.snap ? new PerspectiveSnapper(perspective) : null;
     const useStencils = init.stencils !== false;
     const stencilSnapper = useStencils && this.guides.stencils.some((x) => x.enabled && x.mode === "guide") ? new StencilSnapper(this.guides.stencils) : null;
-    const selection = init.maskStencils ? this.stencilSelection(init.maskStencils) : useStencils ? this.stencilSelection() : null;
+    if (brush.engine === "sticker" && !init.maskStencils && useStencils && this.stencilSelection()) {
+      const masks = this.guides.stencils.filter((x) => x.enabled && x.mode === "mask").map((x) => x.id);
+      throw new PaintEditorError(`Stickers can't be clipped by mask stencils (${masks.join(", ")}): they are objects drawn whole. Hide them (update_stencil enabled false) to spray stickers, or erase stickers you don't want (remove_stickers).`);
+    }
+    const selection = brush.engine === "sticker" ? null : init.maskStencils ? this.stencilSelection(init.maskStencils) : useStencils ? this.stencilSelection() : null;
     const inputFilter = snapper || stencilSnapper ? (p) => stencilSnapper ? stencilSnapper.snap(snapper ? snapper.snap(p) : p) : snapper.snap(p) : void 0;
     const rgba = rgbaOf(color);
     const seed = init.seed ?? mix32(this.seedCounter++ * 2654435761 >>> 0) & 2147483647;
@@ -5897,28 +5908,115 @@ var PaintEditorController = class _PaintEditorController {
     this.requireLayer(id);
     return (this.doc.stickers?.[id] ?? []).map((s) => ({ ...s }));
   }
-  /** Replaces a layer's stickers and redraws its pixels from them (one undo step). */
-  commitStickers(label, layer, stickers) {
+  /**
+   * Replaces a layer's stickers and redraws its pixels from them (one undo step). With `dirty`,
+   * only the tiles under those rects are redrawn.
+   */
+  commitStickers(label, layer, stickers, dirty) {
     if (isLayerLocked(layer, "pixels")) throw new PaintEditorError(`Layer "${layer.name}" has its pixels locked; unlock it first.`);
-    const surface = stickerSurface(stickers);
+    const before = this.previewBase() ?? this.doc;
+    this.stickerPreview = null;
+    const surface = this.redrawStickers(layer, stickers, dirty);
     const doc = { ...this.doc, layers: mapLayer(this.doc.layers, layer.id, () => ({ ...layer, surface, offset: { x: 0, y: 0 } })), stickers: { ...this.doc.stickers ?? {}, [layer.id]: stickers } };
-    this.commit(label, this.withPaintEvent(doc, { kind: "stickers", layerId: layer.id, data: { stickers: stickers.map((s) => ({ ...s })) } }));
+    this.commit(label, this.withPaintEvent(doc, { kind: "stickers", layerId: layer.id, data: { stickers: stickers.map((s) => ({ ...s })) } }), before);
+  }
+  redrawStickers(layer, stickers, dirty) {
+    const partial = dirty && !layer.offset.x && !layer.offset.y;
+    return partial ? stickerSurface(stickers, layer.surface, dirty) : stickerSurface(stickers);
+  }
+  /** The document from before the sticker preview on screen, or `null` when none is (anything else changed the document since). */
+  previewBase() {
+    return this.stickerPreview?.shown === this.doc ? this.stickerPreview.base : null;
+  }
+  readStickerUpdate(update) {
+    try {
+      return normalizeStickerUpdate(update);
+    } catch (e) {
+      throw new PaintEditorError(e.message);
+    }
+  }
+  /** The top-most sticker under a point (document pixels) on a layer (default the active one), or `null`. */
+  stickerAt(layerId, x, y) {
+    if (!Number.isFinite(x) || !Number.isFinite(y)) throw new PaintEditorError("x and y must be numbers of document pixels.");
+    const id = layerId ?? this.doc.activeLayerId;
+    if (!id) return null;
+    this.requireLayer(id);
+    const hit = stickerAt(this.doc.stickers?.[id] ?? [], x, y);
+    return hit ? { ...hit } : null;
+  }
+  /** Picks a sticker for the panel and canvas (`null` for none). Editor state, not an undo step. */
+  selectSticker(id) {
+    if (id === this.selectedSticker) return;
+    this.selectedSticker = id;
+    this.emit([]);
+  }
+  /**
+   * Shows a sticker change without committing it (a drag in progress): only the tiles under its
+   * old and new place are redrawn. `updateSticker` then commits it as one undo step from before
+   * the first preview; `cancelStickerPreview` puts it back.
+   */
+  previewSticker(layerId, id, update) {
+    const { layer, stickers } = this.stickerLayer(layerId);
+    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 list = stickers.map((s, j) => j === i ? next : s);
+    const dirty = [stickerRect(stickers[i]), stickerRect(next)];
+    const base = this.previewBase() ?? this.doc;
+    const surface = this.redrawStickers(layer, list, dirty);
+    this.doc = { ...this.doc, layers: mapLayer(this.doc.layers, layer.id, () => ({ ...layer, surface, offset: { x: 0, y: 0 } })), stickers: { ...this.doc.stickers ?? {}, [layer.id]: list } };
+    this.stickerPreview = { base, shown: this.doc };
+    this.emit(dirty);
+    return { ...next };
+  }
+  /** Drops a sticker preview, restoring the document from before it. */
+  cancelStickerPreview() {
+    const base = this.previewBase();
+    this.stickerPreview = null;
+    if (!base) return;
+    this.doc = base;
+    this.emit();
   }
   /** Moves, turns, resizes, recolours or restamps one sticker (one undo step). Returns it. */
   updateSticker(layerId, id, update) {
     const { layer, stickers } = this.stickerLayer(layerId);
     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.`);
-    let u;
-    try {
-      u = normalizeStickerUpdate(update);
-    } catch (e) {
-      throw new PaintEditorError(e.message);
-    }
+    const u = this.readStickerUpdate(update);
     const next = { ...stickers[i], ...u };
-    this.commitStickers("Edit sticker", layer, stickers.map((s, j) => j === i ? next : s));
+    this.commitStickers("Edit sticker", layer, stickers.map((s, j) => j === i ? next : s), [stickerRect(stickers[i]), stickerRect(next)]);
     return { ...next };
   }
+  /**
+   * Places stickers exactly (one undo step), on top of a sticker layer or onto an empty layer,
+   * which becomes one. Missing fields: size 48 px, rotation 0, the paint colour, opacity 1, a seed
+   * from the new id. Returns the new stickers with their ids.
+   */
+  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 > 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) {
+      if (this.wet.wetLayerIds().includes(layer.id) || contentBounds(layer.surface)) throw new PaintEditorError(`Layer "${layer.name}" already has paint; add stickers to an empty layer (add_layer) or a sticker layer so they stay editable.`);
+    }
+    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}.`);
+      let u;
+      try {
+        u = this.readStickerUpdate(raw);
+      } catch (e) {
+        throw new PaintEditorError(`Sticker ${i}: ${e.message}`);
+      }
+      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 };
+    });
+    this.commitStickers("Add stickers", layer, [...existing ?? [], ...added], existing?.length ? added.map(stickerRect) : void 0);
+    return added.map((s) => ({ ...s }));
+  }
   /** Brings stickers to the top (`front`) or bottom of their layer (one undo step). */
   arrangeStickers(layerId, ids, to) {
     const { layer, stickers } = this.stickerLayer(layerId);
@@ -5926,7 +6024,7 @@ var PaintEditorController = class _PaintEditorController {
     const picked = stickers.filter((s) => ids.includes(s.id));
     const rest = stickers.filter((s) => !ids.includes(s.id));
     const next = to === "front" ? [...rest, ...picked] : [...picked, ...rest];
-    this.commitStickers("Arrange stickers", layer, next);
+    this.commitStickers("Arrange stickers", layer, next, picked.map(stickerRect));
     return next.map((s) => s.id);
   }
   /** Deletes stickers (`ids`, or all of them on the layer) (one undo step). Returns the ids removed. */
@@ -5936,7 +6034,7 @@ var PaintEditorController = class _PaintEditorController {
       for (const id of ids) if (!stickers.some((s) => s.id === id)) throw new PaintEditorError(`Layer "${layer.name}" has no sticker "${id}". Call list_stickers for the ids.`);
     }
     const removed = ids ? [...ids] : stickers.map((s) => s.id);
-    this.commitStickers("Remove stickers", layer, stickers.filter((s) => !removed.includes(s.id)));
+    this.commitStickers("Remove stickers", layer, stickers.filter((s) => !removed.includes(s.id)), ids ? stickers.filter((s) => removed.includes(s.id)).map(stickerRect) : void 0);
     return removed;
   }
   /** Sets a layer's stickers (replays). */
@@ -6512,6 +6610,61 @@ function createPaintStickerTools(c) {
       coordinates: { out: ["stickers[]"] },
       handler: ({ layerId }) => ({ layerId: layerId ?? c.document.activeLayerId, stickers: c.listStickers(layerId) })
     },
+    {
+      name: "sticker_at",
+      title: "Find the sticker at a point",
+      description: "Returns the top-most sticker under a point (document pixels) by its stamp\u2019s shape, or sticker null when none is there, so you can pick one sticker among many similar ones before update_sticker, arrange_stickers or remove_stickers. Changes nothing.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          layerId: LAYER_ID,
+          x: { type: "number", description: "Point x in document pixels." },
+          y: { type: "number", description: "Point y in document pixels." }
+        },
+        required: ["x", "y"],
+        additionalProperties: false
+      },
+      annotations: { title: "Find the sticker at a point", ...READ },
+      coordinates: { in: [""], out: ["sticker"] },
+      handler: ({ layerId, x, y }) => ({ layerId: layerId ?? c.document.activeLayerId, sticker: c.stickerAt(layerId, x, y) })
+    },
+    {
+      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.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          layerId: LAYER_ID,
+          stickers: {
+            type: "array",
+            minItems: 1,
+            maxItems: 500,
+            description: "The stickers to place, drawn in this order (later ones on top).",
+            items: {
+              type: "object",
+              properties: {
+                stamp: { type: "string", enum: [...STAMP_KINDS], description: "The 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)." },
+                rotation: { type: "number", minimum: -3600, maximum: 3600, description: "Degrees clockwise (default 0)." },
+                color: { type: "string", pattern: "^#[0-9a-fA-F]{6}$", description: "Colour #rrggbb (default the paint colour)." },
+                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"],
+              additionalProperties: false
+            }
+          }
+        },
+        required: ["stickers"],
+        additionalProperties: false
+      },
+      annotations: { title: "Place stickers", ...WRITE },
+      coordinates: { in: ["stickers[]"], out: ["stickers[]"] },
+      handler: ({ layerId, stickers }) => ({ layerId: layerId ?? c.document.activeLayerId, stickers: c.addStickers(layerId, stickers) })
+    },
     {
       name: "update_sticker",
       title: "Change a sticker",
@@ -7508,11 +7661,11 @@ var STICKER_BRUSH = {
   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)." },
-    density: { type: "number", minimum: 0, maximum: 1, description: "Stickers per distance travelled." },
+    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." },
     scatter: { type: "number", minimum: 0, maximum: 2, description: "How far from the path stickers land, in tip diameters." },
-    colorJitter: { type: "number", minimum: 0, maximum: 1, description: "Random colour change around the paint colour." }
+    colorJitter: { type: "number", minimum: 0, maximum: 1, description: "Random colour change around the paint colour: at 1, up to \xB140\xB0 of hue and \xB10.15 OKLab lightness, kept in gamut. Default 0.2." }
   },
   additionalProperties: false
 };
@@ -8331,6 +8484,7 @@ function hostTool({ coordinates, ...tool }, { origin, onChange }) {
 var PAINT_TOOLS = [
   { id: "brush", label: "Brush", key: "b" },
   { id: "eyedropper", label: "Eyedropper", key: "i" },
+  { id: "sticker", label: "Stickers", key: "s" },
   { id: "pan", label: "Pan", key: "h" },
   { id: "rotate", label: "Rotate view", key: "r" }
 ];
@@ -8383,6 +8537,7 @@ var PaintGesture = class {
       this.pick(e);
       return false;
     }
+    if (tool === "sticker") return this.stickerDown(e);
     try {
       const p = this.pen(e);
       const session = this.controller.beginStroke({ start: p });
@@ -8394,6 +8549,29 @@ var PaintGesture = class {
       return false;
     }
   }
+  /**
+   * The Stickers tool: pressing a sticker picks it and dragging moves it (one undo step at the
+   * drop); pressing anywhere else places the active brush's first stamp there, at its tip size and
+   * the paint colour, and picks it.
+   */
+  stickerDown(e) {
+    const p = this.doc(e);
+    try {
+      const hit = this.controller.stickerAt(void 0, p.x, p.y);
+      if (hit) {
+        this.controller.selectSticker(hit.id);
+        this.mode = { kind: "sticker", pointerId: e.pointerId, id: hit.id, dx: hit.x - p.x, dy: hit.y - p.y, at: null };
+        return true;
+      }
+      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 }]);
+      this.controller.selectSticker(added.id);
+    } catch (err) {
+      this.error = err instanceof Error ? err.message : String(err);
+    }
+    return false;
+  }
   pick(e) {
     const p = this.doc(e);
     const { width, height } = this.controller.document.canvas;
@@ -8416,6 +8594,16 @@ var PaintGesture = class {
       this.controller.setView({ rotation: r });
       return;
     }
+    if (m.kind === "sticker") {
+      const p = this.doc(e);
+      m.at = { x: round2(p.x + m.dx), y: round2(p.y + m.dy) };
+      try {
+        this.controller.previewSticker(void 0, m.id, m.at);
+      } catch (err) {
+        this.error = err instanceof Error ? err.message : String(err);
+      }
+      return;
+    }
     const session = this.controller.activeStroke;
     if (!session) return;
     const events = typeof e.getCoalescedEvents === "function" ? e.getCoalescedEvents() : [];
@@ -8430,11 +8618,20 @@ var PaintGesture = class {
     this.mode = null;
     this.predicted = [];
     if (m.kind === "stroke") this.controller.activeStroke?.end();
+    if (m.kind === "sticker" && m.at) {
+      try {
+        this.controller.updateSticker(void 0, m.id, m.at);
+      } catch (err) {
+        this.controller.cancelStickerPreview();
+        this.error = err instanceof Error ? err.message : String(err);
+      }
+    }
   }
   cancel() {
     this.penDown = false;
     this.predicted = [];
     if (this.mode?.kind === "stroke") this.controller.activeStroke?.cancel();
+    if (this.mode?.kind === "sticker") this.controller.cancelStickerPreview();
     this.mode = null;
   }
   get active() {
@@ -8455,6 +8652,7 @@ var PaintGesture = class {
     this.controller.setView({ zoom, pan: { x: px - (px - s.view.pan.x) * k, y: py - (py - s.view.pan.y) * k } });
   }
 };
+var round2 = (v) => Math.round(v * 100) / 100;
 function handlePaintShortcut(controller, gesture, e) {
   const mod = e.ctrlKey || e.metaKey;
   const key = e.key.toLowerCase();
@@ -8532,6 +8730,15 @@ function guideOverlay(controller) {
   const s = controller.getState();
   const size = s.document.canvas;
   const out = [];
+  const layerId = s.document.activeLayerId;
+  const picked = layerId && s.selectedSticker ? s.document.stickers?.[layerId]?.find((x) => x.id === s.selectedSticker) : void 0;
+  if (picked) {
+    const r = picked.size / 2 + 2;
+    const a = picked.rotation * Math.PI / 180;
+    const corner = (u, v) => ({ x: picked.x + (u * Math.cos(a) - v * Math.sin(a)) * r, y: picked.y + (u * Math.sin(a) + v * Math.cos(a)) * r });
+    const box = [corner(-1, -1), corner(1, -1), corner(1, 1), corner(-1, 1)];
+    for (let i = 0; i < 4; i++) out.push({ from: box[i], to: box[(i + 1) % 4], kind: "sticker" });
+  }
   for (const st of s.guides.stencils) {
     if (!st.enabled) continue;
     const line = stencilOutline(st);
@@ -9392,6 +9599,7 @@ export {
   startWetClock,
   stencilMask,
   stencilOutline,
+  stickerAt,
   stickerRect,
   stickerSurface,
   strokeBounds,

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

@@ -1,7 +1,7 @@
 /**
  * Agent tools for stickers: stamps sprayed with a sticker brush (`paint_stroke`, list_brushes
  * category sticker) stay objects on their layer, which these tools list, move, turn, resize,
- * recolour, reorder and delete. Each change is one undo step and redraws the layer.
+ * recolour, reorder and delete, find by point (`sticker_at`), and places new ones exactly (`add_stickers`). Each change is one undo step and redraws the layer.
  */
 import type { PaintAgentTool } from './hosted.cjs';
 import type { PaintEditorController } from './controller.cjs';

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

@@ -1,7 +1,7 @@
 /**
  * Agent tools for stickers: stamps sprayed with a sticker brush (`paint_stroke`, list_brushes
  * category sticker) stay objects on their layer, which these tools list, move, turn, resize,
- * recolour, reorder and delete. Each change is one undo step and redraws the layer.
+ * recolour, reorder and delete, find by point (`sticker_at`), and places new ones exactly (`add_stickers`). Each change is one undo step and redraws the layer.
  */
 import type { PaintAgentTool } from './hosted.js';
 import type { PaintEditorController } from './controller.js';

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

@@ -37,7 +37,7 @@ export interface Sticker {
 export interface StickerSettings {
     /** The stamps to spray (picked at random per sticker). */
     stamps: StampKind[];
-    /** Stickers per tip diameter of travel. */
+    /** How closely stickers follow each other: about `density × 4` per tip diameter of travel (0.25 ≈ one per diameter). */
     density: number;
     /** Random size change. */
     sizeJitter: number;
@@ -98,5 +98,12 @@ export declare class StickerSpray {
 export declare function renderStickers(stickers: readonly Sticker[], target: PaintTileTarget): 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'>>;
-/** A sticker layer's pixels: its stickers drawn bottom first over a transparent layer. */
-export declare function stickerSurface(stickers: readonly Sticker[]): TiledSurface;
+/**
+ * A sticker layer's pixels: its stickers drawn bottom first over a transparent layer. With `base`
+ * (the layer's current pixels, at offset 0) and `dirty` rects, only the tiles those rects touch are
+ * 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;

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

@@ -37,7 +37,7 @@ export interface Sticker {
 export interface StickerSettings {
     /** The stamps to spray (picked at random per sticker). */
     stamps: StampKind[];
-    /** Stickers per tip diameter of travel. */
+    /** How closely stickers follow each other: about `density × 4` per tip diameter of travel (0.25 ≈ one per diameter). */
     density: number;
     /** Random size change. */
     sizeJitter: number;
@@ -98,5 +98,12 @@ export declare class StickerSpray {
 export declare function renderStickers(stickers: readonly Sticker[], target: PaintTileTarget): 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'>>;
-/** A sticker layer's pixels: its stickers drawn bottom first over a transparent layer. */
-export declare function stickerSurface(stickers: readonly Sticker[]): TiledSurface;
+/**
+ * A sticker layer's pixels: its stickers drawn bottom first over a transparent layer. With `base`
+ * (the layer's current pixels, at offset 0) and `dirty` rects, only the tiles those rects touch are
+ * 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;

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

@@ -34,7 +34,7 @@ export interface PaintPointerEvent extends PointerSample {
     getCoalescedEvents?(): PaintPointerEvent[];
     getPredictedEvents?(): PaintPointerEvent[];
 }
-export type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate';
+export type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate' | 'sticker';
 export declare const PAINT_TOOLS: ReadonlyArray<{
     id: PaintTool;
     label: string;
@@ -63,6 +63,12 @@ export declare class PaintGesture {
     private pen;
     /** Pointer down; returns true when the gesture took the pointer (capture it). */
     down(e: PaintPointerEvent): boolean;
+    /**
+     * The Stickers tool: pressing a sticker picks it and dragging moves it (one undo step at the
+     * drop); pressing anywhere else places the active brush's first stamp there, at its tip size and
+     * the paint colour, and picks it.
+     */
+    private stickerDown;
     private pick;
     move(e: PaintPointerEvent): void;
     up(e: PaintPointerEvent): void;
@@ -101,11 +107,12 @@ export declare class PaintCanvasPresenter {
     /** Draws what changed into `ctx` (a canvas the size of the document); returns the tiles drawn. */
     render(ctx: Paint2DContext): number;
 }
-/** Lines to draw over the canvas for the guides, in document pixels, with a style key. */
+export type GuideOverlayKind = 'symmetry' | 'perspective' | 'snap' | 'stencil' | 'sticker';
+/** Lines to draw over the canvas for the guides and the picked sticker, in document pixels, with a style key. */
 export declare function guideOverlay(controller: PaintEditorController): Array<{
     from: Point2;
     to: Point2;
-    kind: 'symmetry' | 'perspective' | 'snap' | 'stencil';
+    kind: GuideOverlayKind;
 }>;
 /** One slider of a panel: a path into the brush (or paper) settings. */
 export interface SliderControl {

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

@@ -34,7 +34,7 @@ export interface PaintPointerEvent extends PointerSample {
     getCoalescedEvents?(): PaintPointerEvent[];
     getPredictedEvents?(): PaintPointerEvent[];
 }
-export type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate';
+export type PaintTool = 'brush' | 'eyedropper' | 'pan' | 'rotate' | 'sticker';
 export declare const PAINT_TOOLS: ReadonlyArray<{
     id: PaintTool;
     label: string;
@@ -63,6 +63,12 @@ export declare class PaintGesture {
     private pen;
     /** Pointer down; returns true when the gesture took the pointer (capture it). */
     down(e: PaintPointerEvent): boolean;
+    /**
+     * The Stickers tool: pressing a sticker picks it and dragging moves it (one undo step at the
+     * drop); pressing anywhere else places the active brush's first stamp there, at its tip size and
+     * the paint colour, and picks it.
+     */
+    private stickerDown;
     private pick;
     move(e: PaintPointerEvent): void;
     up(e: PaintPointerEvent): void;
@@ -101,11 +107,12 @@ export declare class PaintCanvasPresenter {
     /** Draws what changed into `ctx` (a canvas the size of the document); returns the tiles drawn. */
     render(ctx: Paint2DContext): number;
 }
-/** Lines to draw over the canvas for the guides, in document pixels, with a style key. */
+export type GuideOverlayKind = 'symmetry' | 'perspective' | 'snap' | 'stencil' | 'sticker';
+/** Lines to draw over the canvas for the guides and the picked sticker, in document pixels, with a style key. */
 export declare function guideOverlay(controller: PaintEditorController): Array<{
     from: Point2;
     to: Point2;
-    kind: 'symmetry' | 'perspective' | 'snap' | 'stencil';
+    kind: GuideOverlayKind;
 }>;
 /** One slider of a panel: a path into the brush (or paper) settings. */
 export interface SliderControl {

package/dist/tokens/index.cjs

@@ -55,7 +55,7 @@
 
 
 
-var _chunkUXETV2NCcjs = require('../chunk-UXETV2NC.cjs');
+var _chunkGA4EU4P3cjs = require('../chunk-GA4EU4P3.cjs');
 require('../chunk-SJ2CPTQC.cjs');
 require('../chunk-2BSBFBOA.cjs');
 
@@ -63,7 +63,8 @@ require('../chunk-2BSBFBOA.cjs');
 
 
 var _chunkA6QWKBJPcjs = require('../chunk-A6QWKBJP.cjs');
-require('../chunk-5UEFBM2M.cjs');
+require('../chunk-RD7RX52G.cjs');
+require('../chunk-7AHBW2CQ.cjs');
 require('../chunk-IPJ3TEYR.cjs');
 
 
@@ -125,4 +126,4 @@ require('../chunk-IPJ3TEYR.cjs');
 
 
 
-exports.EMPTY_TOKEN_STATE = _chunkUXETV2NCcjs.EMPTY_TOKEN_STATE; exports.TOKEN_SCOPES_BY_TYPE = _chunkUXETV2NCcjs.TOKEN_SCOPES_BY_TYPE; exports.TOKEN_TYPES = _chunkUXETV2NCcjs.TOKEN_TYPES; exports.TokenError = _chunkUXETV2NCcjs.TokenError; exports.TokenStore = _chunkUXETV2NCcjs.TokenStore; exports.W3C_TOKENS_EXTENSION = _chunkUXETV2NCcjs.W3C_TOKENS_EXTENSION; exports.addTokenMode = _chunkUXETV2NCcjs.addTokenMode; exports.checkTokenAlias = _chunkUXETV2NCcjs.checkTokenAlias; exports.coerceTokenLiteral = _chunkUXETV2NCcjs.coerceTokenLiteral; exports.createTokenCollection = _chunkUXETV2NCcjs.createTokenCollection; exports.createTokenStore = _chunkUXETV2NCcjs.createTokenStore; exports.createTokenStyleSource = _chunkUXETV2NCcjs.createTokenStyleSource; exports.createTokenVariable = _chunkUXETV2NCcjs.createTokenVariable; exports.createTokensEditorDocument = _chunkUXETV2NCcjs.createTokensEditorDocument; exports.createTokensStyleToolProvider = _chunkUXETV2NCcjs.createTokensStyleToolProvider; exports.cssString = _chunkUXETV2NCcjs.cssString; exports.defaultTokenId = _chunkUXETV2NCcjs.defaultTokenId; exports.defaultTokenValue = _chunkUXETV2NCcjs.defaultTokenValue; exports.deleteTokenCollection = _chunkUXETV2NCcjs.deleteTokenCollection; exports.deleteTokenVariables = _chunkUXETV2NCcjs.deleteTokenVariables; exports.exportTokensCss = _chunkUXETV2NCcjs.exportTokensCss; exports.exportW3CTokens = _chunkUXETV2NCcjs.exportW3CTokens; exports.exportW3CTokensJson = _chunkUXETV2NCcjs.exportW3CTokensJson; exports.findTokenCollection = _chunkUXETV2NCcjs.findTokenCollection; exports.findTokenMode = _chunkUXETV2NCcjs.findTokenMode; exports.findTokenVariable = _chunkUXETV2NCcjs.findTokenVariable; exports.formatTokenCssValue = _chunkUXETV2NCcjs.formatTokenCssValue; exports.formatTokenValue = _chunkUXETV2NCcjs.formatTokenValue; exports.getCollectionVariables = _chunkUXETV2NCcjs.getCollectionVariables; exports.getCurrentMode = _chunkUXETV2NCcjs.getCurrentMode; exports.getDefaultMode = _chunkUXETV2NCcjs.getDefaultMode; exports.getTokenCollection = _chunkUXETV2NCcjs.getTokenCollection; exports.getTokenCssName = _chunkUXETV2NCcjs.getTokenCssName; exports.getTokenCssVariables = _chunkUXETV2NCcjs.getTokenCssVariables; exports.getTokenVariable = _chunkUXETV2NCcjs.getTokenVariable; exports.hexToRgba = _chunkA6QWKBJPcjs.hexToRgba; exports.importW3CTokens = _chunkUXETV2NCcjs.importW3CTokens; exports.isTokenAlias = _chunkUXETV2NCcjs.isTokenAlias; exports.isTokenInScope = _chunkUXETV2NCcjs.isTokenInScope; exports.isTokenScopeKnown = _chunkUXETV2NCcjs.isTokenScopeKnown; exports.literalTokenType = _chunkUXETV2NCcjs.literalTokenType; exports.moveTokenMode = _chunkUXETV2NCcjs.moveTokenMode; exports.normalizeTokenColor = _chunkA6QWKBJPcjs.normalizeTokenColor; exports.normalizeTokenName = _chunkUXETV2NCcjs.normalizeTokenName; exports.normalizeTokenScopes = _chunkUXETV2NCcjs.normalizeTokenScopes; exports.parseTokenState = _chunkUXETV2NCcjs.parseTokenState; exports.prepareTokenValue = _chunkUXETV2NCcjs.prepareTokenValue; exports.removeTokenMode = _chunkUXETV2NCcjs.removeTokenMode; exports.renameTokenCollection = _chunkUXETV2NCcjs.renameTokenCollection; exports.renameTokenMode = _chunkUXETV2NCcjs.renameTokenMode; exports.renameTokenVariable = _chunkUXETV2NCcjs.renameTokenVariable; exports.resolveToken = _chunkUXETV2NCcjs.resolveToken; exports.resolveTokenInMode = _chunkUXETV2NCcjs.resolveTokenInMode; exports.resolveTokenValue = _chunkUXETV2NCcjs.resolveTokenValue; exports.rgbaToHex = _chunkA6QWKBJPcjs.rgbaToHex; exports.setTokenValue = _chunkUXETV2NCcjs.setTokenValue; exports.tokenSlug = _chunkUXETV2NCcjs.tokenSlug; exports.tokensStyleDomain = _chunkUXETV2NCcjs.tokensStyleDomain; exports.updateTokenVariable = _chunkUXETV2NCcjs.updateTokenVariable;
+exports.EMPTY_TOKEN_STATE = _chunkGA4EU4P3cjs.EMPTY_TOKEN_STATE; exports.TOKEN_SCOPES_BY_TYPE = _chunkGA4EU4P3cjs.TOKEN_SCOPES_BY_TYPE; exports.TOKEN_TYPES = _chunkGA4EU4P3cjs.TOKEN_TYPES; exports.TokenError = _chunkGA4EU4P3cjs.TokenError; exports.TokenStore = _chunkGA4EU4P3cjs.TokenStore; exports.W3C_TOKENS_EXTENSION = _chunkGA4EU4P3cjs.W3C_TOKENS_EXTENSION; exports.addTokenMode = _chunkGA4EU4P3cjs.addTokenMode; exports.checkTokenAlias = _chunkGA4EU4P3cjs.checkTokenAlias; exports.coerceTokenLiteral = _chunkGA4EU4P3cjs.coerceTokenLiteral; exports.createTokenCollection = _chunkGA4EU4P3cjs.createTokenCollection; exports.createTokenStore = _chunkGA4EU4P3cjs.createTokenStore; exports.createTokenStyleSource = _chunkGA4EU4P3cjs.createTokenStyleSource; exports.createTokenVariable = _chunkGA4EU4P3cjs.createTokenVariable; exports.createTokensEditorDocument = _chunkGA4EU4P3cjs.createTokensEditorDocument; exports.createTokensStyleToolProvider = _chunkGA4EU4P3cjs.createTokensStyleToolProvider; exports.cssString = _chunkGA4EU4P3cjs.cssString; exports.defaultTokenId = _chunkGA4EU4P3cjs.defaultTokenId; exports.defaultTokenValue = _chunkGA4EU4P3cjs.defaultTokenValue; exports.deleteTokenCollection = _chunkGA4EU4P3cjs.deleteTokenCollection; exports.deleteTokenVariables = _chunkGA4EU4P3cjs.deleteTokenVariables; exports.exportTokensCss = _chunkGA4EU4P3cjs.exportTokensCss; exports.exportW3CTokens = _chunkGA4EU4P3cjs.exportW3CTokens; exports.exportW3CTokensJson = _chunkGA4EU4P3cjs.exportW3CTokensJson; exports.findTokenCollection = _chunkGA4EU4P3cjs.findTokenCollection; exports.findTokenMode = _chunkGA4EU4P3cjs.findTokenMode; exports.findTokenVariable = _chunkGA4EU4P3cjs.findTokenVariable; exports.formatTokenCssValue = _chunkGA4EU4P3cjs.formatTokenCssValue; exports.formatTokenValue = _chunkGA4EU4P3cjs.formatTokenValue; exports.getCollectionVariables = _chunkGA4EU4P3cjs.getCollectionVariables; exports.getCurrentMode = _chunkGA4EU4P3cjs.getCurrentMode; exports.getDefaultMode = _chunkGA4EU4P3cjs.getDefaultMode; exports.getTokenCollection = _chunkGA4EU4P3cjs.getTokenCollection; exports.getTokenCssName = _chunkGA4EU4P3cjs.getTokenCssName; exports.getTokenCssVariables = _chunkGA4EU4P3cjs.getTokenCssVariables; exports.getTokenVariable = _chunkGA4EU4P3cjs.getTokenVariable; exports.hexToRgba = _chunkA6QWKBJPcjs.hexToRgba; exports.importW3CTokens = _chunkGA4EU4P3cjs.importW3CTokens; exports.isTokenAlias = _chunkGA4EU4P3cjs.isTokenAlias; exports.isTokenInScope = _chunkGA4EU4P3cjs.isTokenInScope; exports.isTokenScopeKnown = _chunkGA4EU4P3cjs.isTokenScopeKnown; exports.literalTokenType = _chunkGA4EU4P3cjs.literalTokenType; exports.moveTokenMode = _chunkGA4EU4P3cjs.moveTokenMode; exports.normalizeTokenColor = _chunkA6QWKBJPcjs.normalizeTokenColor; exports.normalizeTokenName = _chunkGA4EU4P3cjs.normalizeTokenName; exports.normalizeTokenScopes = _chunkGA4EU4P3cjs.normalizeTokenScopes; exports.parseTokenState = _chunkGA4EU4P3cjs.parseTokenState; exports.prepareTokenValue = _chunkGA4EU4P3cjs.prepareTokenValue; exports.removeTokenMode = _chunkGA4EU4P3cjs.removeTokenMode; exports.renameTokenCollection = _chunkGA4EU4P3cjs.renameTokenCollection; exports.renameTokenMode = _chunkGA4EU4P3cjs.renameTokenMode; exports.renameTokenVariable = _chunkGA4EU4P3cjs.renameTokenVariable; exports.resolveToken = _chunkGA4EU4P3cjs.resolveToken; exports.resolveTokenInMode = _chunkGA4EU4P3cjs.resolveTokenInMode; exports.resolveTokenValue = _chunkGA4EU4P3cjs.resolveTokenValue; exports.rgbaToHex = _chunkA6QWKBJPcjs.rgbaToHex; exports.setTokenValue = _chunkGA4EU4P3cjs.setTokenValue; exports.tokenSlug = _chunkGA4EU4P3cjs.tokenSlug; exports.tokensStyleDomain = _chunkGA4EU4P3cjs.tokensStyleDomain; exports.updateTokenVariable = _chunkGA4EU4P3cjs.updateTokenVariable;

package/dist/tokens/index.js

@@ -55,7 +55,7 @@ import {
   tokenSlug,
   tokensStyleDomain,
   updateTokenVariable
-} from "../chunk-ILP77UD6.js";
+} from "../chunk-YGQVCQTG.js";
 import "../chunk-XBQX76CT.js";
 import "../chunk-HF5QZS7Z.js";
 import {
@@ -63,7 +63,8 @@ import {
   normalizeTokenColor,
   rgbaToHex
 } from "../chunk-2WPNAGHI.js";
-import "../chunk-MHLU6GRJ.js";
+import "../chunk-JEGJP4OW.js";
+import "../chunk-F67XMVDI.js";
 import "../chunk-6ONMQ6WF.js";
 export {
   EMPTY_TOKEN_STATE,