@pixerate/editor 0.246.0 → 0.248.0

package/dist/paint-editor/index.js

@@ -2,21 +2,30 @@ import {
   toVideoFfmpeg
 } from "../chunk-L3JFOTBQ.js";
 import {
+  createLayerEffectTools,
   deserializeLayers,
   exportPsd,
   resolveExternalAssets,
   serializeLayers,
   serializeLayersExternal
-} from "../chunk-4PMCMWQS.js";
+} from "../chunk-ZFSLEOSQ.js";
 import "../chunk-3CI7FRMK.js";
 import "../chunk-ZNA3IQZF.js";
 import {
+  LAYER_EFFECT_KINDS,
+  LayerEffectError,
   RasterCompositor,
+  defaultLayerEffect,
   findLayer,
   flattenLayers,
   insertLayer,
+  isLayerEffectKind,
   isLayerLocked,
-  mapLayer
+  layerEffectLabel,
+  mapLayer,
+  mergeLayerEffect,
+  newEffectId,
+  validateLayerEffects
 } from "../chunk-UOOK7HTX.js";
 import "../chunk-OHKOFKBY.js";
 import "../chunk-ZIF4UJJ6.js";
@@ -55,7 +64,7 @@ import {
   realPresenceClock,
   tweenPresenceCursor
 } from "../chunk-IVSWRVB4.js";
-import "../chunk-N6WUB3Y5.js";
+import "../chunk-Q2HA52V4.js";
 import {
   BRUSH_ID,
   BRUSH_ROTATIONS,
@@ -72,11 +81,14 @@ import {
   DEFAULT_PARTICLE,
   DEFAULT_STICKER,
   DEFAULT_WET_BRUSH,
+  DOT_ROTATIONS,
+  DOT_TEXTURE_ORDERS,
   DryStroke,
   EFFECT_MAP_REPEATS,
   EFFECT_STRIP_HEIGHT,
   IDENTITY_COPY,
   IMPASTO_TOOLS,
+  MAX_DOT_TEXTURES,
   MULTI_COLOR_MODES,
   PAINT_BRUSH_CATEGORIES,
   PAINT_BRUSH_ENGINES,
@@ -87,10 +99,12 @@ import {
   ParticleStroke,
   PenDabWalker,
   PenSmoother,
+  RIBBON_PAIRS,
   STAMP_KINDS,
   StickerSpray,
   WET_MEDIA,
   WET_TOOLS,
+  addPolygonArea,
   brushTakesPaint,
   brushToJSON,
   clonePaper,
@@ -133,7 +147,7 @@ import {
   tiltToOrientation,
   toStrokePoint,
   usesPaintExchange
-} from "../chunk-VDAWA546.js";
+} from "../chunk-VNBUDVD4.js";
 import "../chunk-M6DNZNVY.js";
 import "../chunk-WEIK3UYB.js";
 import "../chunk-PWBZH3FK.js";
@@ -3500,7 +3514,9 @@ function liveStrokeBounds(stroke) {
       if (q.y > y1) y1 = q.y;
     }
   }
-  const pad = stroke.brush.tip.size * (stroke.brush.engine === "particle" ? 2 : 1) + 2;
+  const particle = stroke.brush.engine === "particle" ? stroke.brush.particle : null;
+  const wave = particle ? Math.max(particle.waveAmplitude ?? 0, particle.kind === "fuzzy" ? 0.12 : 0) : 0;
+  const pad = stroke.brush.tip.size * (particle ? 2 + wave : 1) + 2;
   return { x: Math.floor(x0 - pad), y: Math.floor(y0 - pad), width: Math.ceil(x1 - x0 + 2 * pad), height: Math.ceil(y1 - y0 + 2 * pad) };
 }
 
@@ -4032,6 +4048,14 @@ function effectLayersToJSON(map, keep) {
 }
 
 // src/paint-editor/controller.ts
+function effectGuard(fn) {
+  try {
+    return fn();
+  } catch (e) {
+    if (e instanceof LayerEffectError) throw new PaintEditorError(e.message);
+    throw e;
+  }
+}
 var PaintEditorError = class extends Error {
   constructor(message) {
     super(message);
@@ -4557,6 +4581,7 @@ var PaintEditorController = class _PaintEditorController {
       active: l.id === this.doc.activeLayerId,
       bounds,
       ...this.doc.liveStrokes?.[l.id] ? { liveStrokes: this.doc.liveStrokes[l.id].length } : {},
+      ...l.effects?.items.length ? { effects: l.effects.items.length } : {},
       parentId,
       depth
     };
@@ -4630,6 +4655,94 @@ var PaintEditorController = class _PaintEditorController {
     this.commit("Layer properties", { ...this.doc, layers: mapLayer(this.doc.layers, id, () => next) });
     return this.describeLayer(next);
   }
+  // --- Layer effects (layer styles) ---------------------------------------------
+  /** A layer's live effects (an empty, enabled list when it has none). */
+  getLayerEffects(id) {
+    return this.requireLayer(id).effects ?? { enabled: true, items: [] };
+  }
+  /**
+   * Adds a live effect of `kind` (outer and inner glow, drop and inner shadow, stroke, bevel &
+   * emboss, satin, colour / gradient / pattern overlay) with Photoshop's defaults and `settings`
+   * applied, at `index` in the layer's list (default the end). The effect is drawn from the
+   * layer's pixels when it is composited, so it follows later painting. One undo step.
+   */
+  addLayerEffect(id, kind, settings = {}, index) {
+    if (!isLayerEffectKind(kind)) throw new PaintEditorError(`Unknown effect kind "${String(kind)}". Kinds: ${LAYER_EFFECT_KINDS.join(", ")}.`);
+    const current = this.effectsLayer(id, "add effects").effects ?? { enabled: true, items: [] };
+    const ids = new Set(current.items.map((e) => e.id));
+    let effectId = newEffectId();
+    while (ids.has(effectId)) effectId = newEffectId();
+    const { id: _id, kind: _kind, ...rest } = settings;
+    const effect = effectGuard(() => mergeLayerEffect(defaultLayerEffect(kind, effectId), rest));
+    const items = [...current.items];
+    const at = index === void 0 ? items.length : Math.max(0, Math.min(items.length, Math.floor(index)));
+    items.splice(at, 0, effect);
+    this.writeLayerEffects(id, { ...current, items }, `Add ${layerEffectLabel(kind)}`, true);
+    return { effect, effects: this.getLayerEffects(id) };
+  }
+  /**
+   * Changes one effect: only the given settings (nested objects replace whole; `null` removes an
+   * optional contour or texture). One undo step, or with `commitToHistory` false folded into the
+   * last change of this effect (a slider drag). Returns the layer's effects.
+   */
+  updateLayerEffect(id, effectId, changes, commitToHistory = true) {
+    const current = this.effectsLayer(id, "change its effects").effects;
+    const i = this.requireEffect(id, effectId);
+    const items = [...current.items];
+    items[i] = effectGuard(() => mergeLayerEffect(items[i], changes));
+    this.writeLayerEffects(id, { ...current, items }, `Change ${layerEffectLabel(items[i].kind)}`, commitToHistory);
+    return this.getLayerEffects(id);
+  }
+  /** Removes one effect (one undo step). Returns the layer's remaining effects. */
+  removeLayerEffect(id, effectId) {
+    const current = this.effectsLayer(id, "change its effects").effects;
+    const i = this.requireEffect(id, effectId);
+    this.writeLayerEffects(id, { ...current, items: current.items.filter((e) => e.id !== effectId) }, `Remove ${layerEffectLabel(current.items[i].kind)}`, true);
+    return this.getLayerEffects(id);
+  }
+  /** Turns all of a layer's effects on or off and, when given, sets Scale Effects (0.01..10). One undo step. */
+  setLayerEffectsEnabled(id, enabled, scale, commitToHistory = true) {
+    const current = this.effectsLayer(id, "change its effects").effects ?? { enabled: true, items: [] };
+    if (scale !== void 0 && !(Number.isFinite(scale) && scale >= 0.01 && scale <= 10)) throw new PaintEditorError(`scale must be from 0.01 to 10 (1 = 100 %), got ${scale}.`);
+    const next = { ...current, enabled };
+    if (scale !== void 0) {
+      if (scale === 1) delete next.scale;
+      else next.scale = scale;
+    }
+    this.writeLayerEffects(id, next, "Layer effects", commitToHistory);
+    return this.getLayerEffects(id);
+  }
+  /** Replaces a layer's effects, validated (`null` removes them). One undo step. Returns the effects. */
+  setLayerEffects(id, effects, commitToHistory = true) {
+    this.effectsLayer(id, "change its effects");
+    if (effects) effectGuard(() => validateLayerEffects(effects));
+    this.writeLayerEffects(id, effects, "Layer effects", commitToHistory);
+    return this.getLayerEffects(id);
+  }
+  /** Document patterns for pattern effects besides the built-in ones: none (paint documents bring none). */
+  getDocumentPatterns() {
+    return [];
+  }
+  effectsLayer(id, action) {
+    this.requireIdle("changing layer effects");
+    const l = this.requireLayer(id);
+    if (isLayerLocked(l, "all")) throw new PaintEditorError(`Layer "${l.name}" is fully locked, so it can't ${action}; unlock it first (locks {all: false}).`);
+    return l;
+  }
+  requireEffect(id, effectId) {
+    const l = this.requireLayer(id);
+    const items = l.effects?.items ?? [];
+    const i = items.findIndex((e) => e.id === effectId);
+    if (i === -1) throw new PaintEditorError(`Layer "${l.name}" has no effect "${effectId}". Effects: ${items.map((e) => `${e.id} (${e.kind})`).join(", ") || "none"}; call list_layer_effects.`);
+    return i;
+  }
+  /** Writes a layer's effects (dropped when empty, enabled and unscaled), as an undo step or folded into the last one. */
+  writeLayerEffects(id, effects, label, commitToHistory) {
+    const next = { ...this.requireLayer(id) };
+    if (effects && (effects.items.length || effects.psd || effects.scale !== void 0 || !effects.enabled)) next.effects = effects;
+    else delete next.effects;
+    this.commitOrAmend(label, { ...this.doc, layers: mapLayer(this.doc.layers, id, () => next) }, commitToHistory);
+  }
   removeLayer(id) {
     this.requireIdle("removing a layer");
     const l = this.requireLayer(id);
@@ -9001,17 +9114,39 @@ var PARTICLE_BRUSH = {
   type: "object",
   description: "Particle engine settings (procedural brushes). Missing fields keep their current values.",
   properties: {
-    kind: { type: "string", enum: [...PARTICLE_KINDS], description: "string: strands of masses on springs dragged behind the pen (hair, fur, wet string); spring: particles on springs to the pen, overshooting and wobbling; orbit: particles circling the pen (curls); flow: particles thrown off the pen into a swirling flow until they fade." },
-    render: { type: "string", enum: [...PARTICLE_RENDERS], description: "dot: a mark at each step; line: each particle draws a continuous line; sequence: beads spaced along each path." },
+    kind: {
+      type: "string",
+      enum: [...PARTICLE_KINDS],
+      description: "string: strands of masses on springs dragged behind the pen (hair, fur, wet string); spring: particles on springs to the pen, overshooting and wobbling; orbit: particles circling the pen (curls); flow: particles thrown off the pen into a swirling flow until they fade; elastic: strands whose links keep a rest length, stretching when the pen is fast and snapping back; fuzzy: winding strings, each strand waving out of step with the others (always waves by at least 0.12 of the tip size)."
+    },
+    render: {
+      type: "string",
+      enum: [...PARTICLE_RENDERS],
+      description: "dot: a mark at each step (round, or dotTextures); line: each particle draws a continuous line; sequence: beads spaced along each path (round, or dotTextures); ribbon: the band between neighbouring particles' paths filled (ribbonFill), with the paths drawn as its edges at the mark size (flame, silk, smoke)."
+    },
     count: { type: "integer", minimum: 1, maximum: 64, description: "Particles (flow: how many are thrown per tip of travel)." },
-    size: { type: "number", minimum: 0, maximum: 1, description: "Mark size as a fraction of the tip size." },
-    spread: { type: "number", minimum: 0, maximum: 1, description: "How far apart the particles start, as a fraction of the tip size." },
-    stiffness: { type: "number", minimum: 0, maximum: 1, description: "Spring and string stiffness: stiff follows closely, soft swings wide." },
+    size: { type: "number", minimum: 0, maximum: 1, description: "Mark size as a fraction of the tip size (ribbon: the width of its edges)." },
+    spread: { type: "number", minimum: 0, maximum: 1, description: "How far apart the particles start, as a fraction of the tip size (ribbon: how wide it is)." },
+    stiffness: { type: "number", minimum: 0, maximum: 1, description: "Spring, string and elastic stiffness: stiff follows closely (elastic: snaps back faster), soft swings wide." },
     damping: { type: "number", minimum: 0, maximum: 1, description: "How quickly motion dies down." },
     speed: { type: "number", minimum: 0, maximum: 1, description: "Orbit and flow speed." },
     gravity: { type: "number", minimum: -1, maximum: 1, description: "Pull downwards (negative: upwards)." },
     life: { type: "number", minimum: 0, maximum: 1, description: "Flow particles: how long they live." },
-    interval: { type: "number", minimum: 0, maximum: 1, description: "Sequence: spacing of the beads." }
+    interval: { type: "number", minimum: 0, maximum: 1, description: "Sequence: spacing of the beads." },
+    ribbonFill: { type: "number", minimum: 0, maximum: 1, description: "Ribbon: opacity of the fill between the paths, relative to their edges (default 0.5; 0 draws only the edges)." },
+    ribbonPairs: { type: "string", enum: [...RIBBON_PAIRS], description: "Ribbon: adjacent (default) joins each particle to its neighbour around the pen; first-last makes one band between the outermost two." },
+    waveAmplitude: { type: "number", minimum: 0, maximum: 1, description: "Wave: how far each particle's drawn place swings sideways to the stroke, as a fraction of the tip size (default 0: no wave). Works with every kind and render." },
+    waveLength: { type: "number", minimum: 4, maximum: 2e3, description: "Wave: wavelength in px of pen travel (default 60)." },
+    waveSpeed: { type: "number", minimum: 0, maximum: 1, description: "Wave: how fast the waves run, by stroke time (0 default: they stand still on the path; 1: about four a second, so slow strokes wave more). Strokes without times run at a nominal 0.5 px/ms." },
+    wavePhaseJitter: { type: "number", minimum: 0, maximum: 1, description: "Wave: how far out of step the particles' waves are (default 0: all in step, a wavy band; 1: random phases, tangled strands)." },
+    dotTextures: {
+      type: "array",
+      maxItems: MAX_DOT_TEXTURES,
+      items: { type: "string", enum: [...STAMP_KINDS], description: "A stamp." },
+      description: `Dot and sequence renders: up to ${MAX_DOT_TEXTURES} sticker stamps (list_stickers) drawn instead of round marks; repeats are allowed (they weight the order). Empty (default): round marks.`
+    },
+    dotTextureOrder: { type: "string", enum: [...DOT_TEXTURE_ORDERS], description: "Textured dots: sequence (default) uses the stamps in turn; random picks one per dot (seeded, so replays are exact)." },
+    dotRotation: { type: "string", enum: [...DOT_ROTATIONS], description: "Textured dots: follow turns each with its particle's motion; random (default) turns each at random; fixed uses the tip angle." }
   },
   additionalProperties: false
 };
@@ -9431,7 +9566,7 @@ function createPaintEditorToolProvider(controller, options = {}) {
   add({
     name: "list_brushes",
     title: "List brushes",
-    description: "Lists the brush library: built-in dry media (pencils, pastels, charcoal, airbrush, marker, ink, erasers), paint brushes (dirty round, multi-colour flat, palette dabber), blending tools (blender, smudge, pigment smudge, Mixer Brush), light paint (category light: glow gel, neon marker, light airbrush, spark trail, glow wash, highlighter; light is the amount they lay) and saved user brushes, with id, name, category, engine, size, grain response, rotation mode, whether it can pick up paint (wetCapable), its pick-up ratio, dirty and multi-colour mode, plus the active brush id.",
+    description: "Lists the brush library: built-in dry media (pencils, pastels, charcoal, airbrush, marker, ink, erasers), paint brushes (dirty round, multi-colour flat, palette dabber), blending tools (blender, smudge, pigment smudge, Mixer Brush), light paint (category light: glow gel, neon marker, light airbrush, spark trail, light ribbon, flame ribbon, neon strand, smoke ribbon, bokeh dots, twinkle sparks, glow wash, highlighter; light is the amount they lay) and saved user brushes, with id, name, category, engine, size, grain response, rotation mode, whether it can pick up paint (wetCapable), its pick-up ratio, dirty and multi-colour mode, plus the active brush id.",
     inputSchema: EMPTY3,
     annotations: { title: "List brushes", ...READ6 },
     handler: () => {
@@ -9943,6 +10078,19 @@ function createPaintEditorToolProvider(controller, options = {}) {
   tools.push(...createPaintReplayTools(c));
   tools.push(...createPaintStickerTools(c));
   tools.push(...createPigmentTools());
+  tools.push(
+    ...createLayerEffectTools(
+      {
+        requireLayer: (id) => void c.getLayerEffects(id),
+        getLayerEffects: (id) => c.getLayerEffects(id),
+        addLayerEffect: (id, kind, settings, index) => c.addLayerEffect(id, kind, settings, index),
+        updateLayerEffect: (id, effectId, changes) => c.updateLayerEffect(id, effectId, changes),
+        removeLayerEffect: (id, effectId) => c.removeLayerEffect(id, effectId),
+        setLayerEffectsEnabled: (id, enabled, scale) => c.setLayerEffectsEnabled(id, enabled, scale)
+      },
+      { layers: "a pixel, stroke, sticker or group layer", error: (m) => new PaintEditorError(m) }
+    )
+  );
   const exclude = new Set(options.exclude ?? []);
   const description = "Natural-media painting: paper and grain, dry and wet brushes, the brush library, strokes as data, pigment mixing, stencils, guides, layers and export.";
   return withPaintPlayback({
@@ -10413,7 +10561,12 @@ function engineControls(brush) {
           { path: "particle.speed", label: "Speed", min: 0, max: 1, step: 0.01 },
           { path: "particle.gravity", label: "Gravity", min: -1, max: 1, step: 0.01 },
           { path: "particle.life", label: "Life", min: 0, max: 1, step: 0.01 },
-          { path: "particle.interval", label: "Bead spacing", min: 0, max: 1, step: 0.01 }
+          { path: "particle.interval", label: "Bead spacing", min: 0, max: 1, step: 0.01 },
+          { path: "particle.ribbonFill", label: "Ribbon fill", min: 0, max: 1, step: 0.01 },
+          { path: "particle.waveAmplitude", label: "Wave", min: 0, max: 1, step: 0.01 },
+          { path: "particle.waveLength", label: "Wavelength", min: 4, max: 400, step: 1 },
+          { path: "particle.waveSpeed", label: "Wave speed", min: 0, max: 1, step: 0.01 },
+          { path: "particle.wavePhaseJitter", label: "Wave scatter", min: 0, max: 1, step: 0.01 }
         ],
         mixingPath: null,
         dirty: false,
@@ -10628,13 +10781,20 @@ var LIGHT_SLIDERS = [
   { path: "elevation", label: "Light height", min: 5, max: 90, step: 1 },
   { path: "relief", label: "Relief", min: 0, max: 1, step: 0.01 }
 ];
-var PARTICLE_KIND_LABELS = { string: "Strings", spring: "Springs", orbit: "Orbits", flow: "Flow" };
-var PARTICLE_RENDER_LABELS = { dot: "Dots", line: "Lines", sequence: "Beads" };
+var PARTICLE_KIND_LABELS = { string: "Strings", spring: "Springs", orbit: "Orbits", flow: "Flow", elastic: "Elastic", fuzzy: "Fuzzy" };
+var PARTICLE_RENDER_LABELS = { dot: "Dots", line: "Lines", sequence: "Beads", ribbon: "Ribbon" };
+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 toggleStamp(stamps, stamp) {
   const next = stamps.includes(stamp) ? stamps.filter((s) => s !== stamp) : [...stamps, stamp];
   return next.length ? next : [stamp];
 }
+function toggleDotTexture(textures, stamp) {
+  if (textures.includes(stamp)) return textures.filter((s) => s !== stamp);
+  return textures.length < MAX_DOT_TEXTURES ? [...textures, stamp] : [...textures];
+}
 var STROKE_SLIDERS = [
   { path: "tip.size", label: "Size", min: 1, max: 400, step: 1 },
   { path: "tip.opacity", label: "Opacity", min: 0, max: 1, step: 0.01 },
@@ -10957,6 +11117,10 @@ export {
   DEFAULT_VIEW,
   DEFAULT_WET_BRUSH,
   DEFAULT_WET_PARAMS,
+  DOT_ROTATIONS,
+  DOT_ROTATION_LABELS,
+  DOT_TEXTURE_ORDERS,
+  DOT_TEXTURE_ORDER_LABELS,
   DryStroke,
   EFFECT_MAP_REPEATS,
   EFFECT_STRIP_HEIGHT,
@@ -10974,6 +11138,7 @@ export {
   MAX_BRUSH_SIZE,
   MAX_CANVAS_SIDE,
   MAX_COORDINATE,
+  MAX_DOT_TEXTURES,
   MAX_IMAGE_SIDE,
   MAX_LIVE_EFFECT_SOURCES,
   MAX_ZOOM,
@@ -11033,6 +11198,8 @@ export {
   PenDabWalker,
   PenSmoother,
   PerspectiveSnapper,
+  RIBBON_PAIRS,
+  RIBBON_PAIR_LABELS,
   SNAP_DECIDE_DISTANCE,
   STAMP_KINDS,
   STAMP_LABELS,
@@ -11061,6 +11228,7 @@ export {
   WET_TOOL_LABELS,
   WetStrokeDriver,
   addPaintGradientStop,
+  addPolygonArea,
   affineCopy,
   applyAffine,
   backlightOf,
@@ -11238,6 +11406,7 @@ export {
   timeLapseVideo,
   timeLapseZip,
   toStrokePoint,
+  toggleDotTexture,
   toggleStamp,
   translateStencil,
   updatePaintGradientStop,

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

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

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

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

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

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

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

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