@pixerate/editor 0.266.2 → 0.268.0

package/dist/paint/index.js

@@ -1,7 +1,51 @@
+import {
+  DEFAULT_RETOUCH,
+  IDENTITY_CLONE_TRANSFORM,
+  RETOUCH_SAMPLES,
+  RegionPixelSource,
+  RetouchDabStroke,
+  SPOT_HEAL_TYPES,
+  TONE_RANGES,
+  TilePixelSource,
+  TransformedPixelSource,
+  applyRetouchToTile,
+  applyToneToDeepTile,
+  boxBlurPixels,
+  cloneSamplePoint,
+  createPigmentTools,
+  dodgeBurn,
+  dodgeBurnCurve,
+  healPixels,
+  isIdentityCloneTransform,
+  luma,
+  normalizeRetouch,
+  perDabStrength,
+  pointerPressure,
+  pointerStrokeSample,
+  pointerStrokeSamples,
+  readSourceRegion,
+  retouchFilter,
+  rgbaViewOfGrey,
+  saturationOf,
+  smudgeEffect,
+  sponge,
+  spongeEffect,
+  spotHealPixels,
+  spotHealWindow,
+  toneOf
+} from "../chunk-HVO6XCI4.js";
+import {
+  bestOffset,
+  contentAwareFill,
+  dilateMask,
+  maskBounds,
+  membraneFill,
+  seamlessClone,
+  solveMembrane
+} from "../chunk-VWEWY4FY.js";
 import {
   BODY_SCATTER,
   DEFAULT_FLOW,
-  DEFAULT_RETOUCH,
   DEFAULT_WET_PAPER,
   DEFAULT_WET_PARAMS,
   DRY_EPS,
@@ -16,7 +60,6 @@ import {
   FLAT,
   FREE_INTERVAL,
   HIDE,
-  IDENTITY_CLONE_TRANSFORM,
   MASS_CHANNELS,
   MAX_BATCH,
   MAX_TILT_ACCEL,
@@ -42,19 +85,12 @@ import {
   P_SW,
   P_UX,
   P_UY,
-  RETOUCH_SAMPLES,
-  RegionPixelSource,
-  RetouchDabStroke,
   SET_PLANES,
   SLOT_BYTES,
   SLOT_PLANES,
   SLOT_SIDE,
-  SPOT_HEAL_TYPES,
   SRGB_TO_LINEAR,
   STRIP,
-  TONE_RANGES,
-  TilePixelSource,
-  TransformedPixelSource,
   U_MAX,
   W9,
   WET_FLOW_KINDS,
@@ -68,17 +104,10 @@ import {
   WetWorkerPool,
   WetWorld,
   WetWorldError,
-  applyRetouchToTile,
-  applyToneToDeepTile,
-  boxBlurPixels,
   canShareMemory,
-  cloneSamplePoint,
-  createPigmentTools,
   createWetGpuEngine,
   dexp,
   dlog,
-  dodgeBurn,
-  dodgeBurnCurve,
   dpow,
   dsincos,
   edgeBits,
@@ -87,71 +116,38 @@ import {
   filmReflectance,
   findWebGpu,
   flowField,
-  healPixels,
-  isIdentityCloneTransform,
   latticeViscosity,
   linearToSrgb8,
   loadWetKernel,
-  luma,
   moveWetSnapshot,
   normalizeFlow,
-  normalizeRetouch,
   normalizeTilt,
   normalizeWetParams,
   packWetParams,
-  perDabStrength,
   pigmentColor,
   pigmentOf,
   pixelPigment,
-  pointerPressure,
-  pointerStrokeSample,
-  pointerStrokeSamples,
-  readSourceRegion,
-  retouchFilter,
-  rgbaViewOfGrey,
-  saturationOf,
   shadeLightTile,
   shadeTile,
-  smudgeEffect,
-  sponge,
-  spongeEffect,
-  spotHealPixels,
-  spotHealWindow,
   srgbByteToLinear,
   stepSlotTs,
-  toneOf,
   wetGpuSupport,
   wetSimdSupported,
   wetSupport
-} from "../chunk-XC6DPRYI.js";
-import {
-  bestOffset,
-  contentAwareFill,
-  dilateMask,
-  maskBounds,
-  membraneFill,
-  seamlessClone,
-  solveMembrane
-} from "../chunk-VWEWY4FY.js";
+} from "../chunk-GSTSZPSR.js";
 import {
   BrushstrokeCache,
-  GRAIN_PATTERNS,
-  GRAIN_TILE,
-  PaperGrain,
   brushstrokeDataUrl,
   brushstrokeKey,
   brushstrokeSamples,
   brushstrokeStrokeOptions,
   brushstrokeToCanvas,
-  grainCatch,
-  grainHeights,
   isBrushstrokeBrush,
   paintPathStroke,
   pathStrokeCoverage,
   pathStrokeDabs,
-  renderBrushstroke,
-  strokeGrainCatch
-} from "../chunk-TXFWZ5ZJ.js";
+  renderBrushstroke
+} from "../chunk-W6JDUXP3.js";
 import {
   CoverageMap,
   DEFAULT_BLENDER,
@@ -162,6 +158,8 @@ import {
   DEFAULT_SMUDGE,
   DabWalker,
   EMPTY_MIXER_LOAD,
+  GRAIN_PATTERNS,
+  GRAIN_TILE,
   MAX_BRUSH_SIZE,
   MIXER_DRAIN,
   MIXER_PICKUP_RATE,
@@ -182,6 +180,7 @@ import {
   PaintExchange,
   PaintGradientSampler,
   PaintSourceError,
+  PaperGrain,
   SmudgeTip,
   StrokeCoverage,
   TIP_GRADIENT_STEPS,
@@ -198,6 +197,8 @@ import {
   dabRect,
   exchangeRates,
   gradientDabColor,
+  grainCatch,
+  grainHeights,
   hexToPaintRgb,
   isGradientPaint,
   loadMixer,
@@ -220,12 +221,13 @@ import {
   scalePaintGradient,
   smoothPoints,
   solidPaint,
+  strokeGrainCatch,
   tipFalloff,
   tipReach,
   tipShape,
   updatePaintGradientStop,
   walkDabs
-} from "../chunk-GCVFEPJG.js";
+} from "../chunk-ACTHSQOI.js";
 import {
   TileableNoise,
   hash2,
@@ -239,7 +241,6 @@ import {
   BRUSHSTROKE_MIN_SCALE,
   brushstrokeScaleBucket
 } from "../chunk-ODBT55Q7.js";
-import "../chunk-OTTT5N3K.js";
 import {
   PIGMENT_BANDS,
   PIGMENT_LAMBDA_MIN,
@@ -253,6 +254,7 @@ import {
   rgbToReflectance,
   setPigmentColor
 } from "../chunk-IRSTHLQQ.js";
+import "../chunk-OTTT5N3K.js";
 import "../chunk-HVVR5PZW.js";
 import "../chunk-QGHEDC7B.js";
 export {

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

@@ -2,17 +2,27 @@
  * The shared brush library's agent tools for a paint editor (`createPaintBrushLibraryToolProvider`),
  * with `preview_brush` painted by this editor.
  */
+import type { BrushLibrary } from '../brushes/library.cjs';
+import type { StickerArtLookup } from './sticker-art.cjs';
 import { type BrushLibraryToolProviderOptions, type BrushPreviewRenderer } from '../brushes/tools.cjs';
 import type { AgentToolProvider } from '../tools/registry.cjs';
 import type { PaintEditorController } from './controller.cjs';
 import { type PaperSettings } from './paper.cjs';
 export type PaintBrushLibraryToolProviderOptions = Omit<BrushLibraryToolProviderOptions, 'renderPreview'>;
+/** Where a preview renderer finds a brush's image sources (and sticker art). */
+export interface PaintBrushPreviewOptions {
+    /** Image sources are read from this library before each preview that needs them. */
+    library?: Pick<BrushLibrary, 'getSource'>;
+    /** Art for sticker stamp tips (and anything else not in the library), read on every call. */
+    stampArt?: () => StickerArtLookup | undefined;
+}
 /**
  * A brush preview renderer (`BrushPreviewRenderer`, as `preview_brush` and `BrushLibraryEditor`
  * take) that paints the test stroke with the paint engine on `paper` (read on every call; default
- * the default paper). Any brush the paint editor renders, so also the image editor's.
+ * the default paper). Any brush the paint editor renders, so also the image editor's. With
+ * `options.library`, image tips and image grain are drawn from its sources.
  */
-export declare function paintBrushPreviewRenderer(paper?: () => PaperSettings): BrushPreviewRenderer;
+export declare function paintBrushPreviewRenderer(paper?: () => PaperSettings, options?: PaintBrushPreviewOptions): BrushPreviewRenderer;
 /**
  * The brush library tools for a paint editor (`@pixerate/editor/brushes`' provider on the
  * editor's `brushLibrary`, `PAINT_PROFILE`), with `preview_brush` painting the test stroke on the

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

@@ -2,17 +2,27 @@
  * The shared brush library's agent tools for a paint editor (`createPaintBrushLibraryToolProvider`),
  * with `preview_brush` painted by this editor.
  */
+import type { BrushLibrary } from '../brushes/library.js';
+import type { StickerArtLookup } from './sticker-art.js';
 import { type BrushLibraryToolProviderOptions, type BrushPreviewRenderer } from '../brushes/tools.js';
 import type { AgentToolProvider } from '../tools/registry.js';
 import type { PaintEditorController } from './controller.js';
 import { type PaperSettings } from './paper.js';
 export type PaintBrushLibraryToolProviderOptions = Omit<BrushLibraryToolProviderOptions, 'renderPreview'>;
+/** Where a preview renderer finds a brush's image sources (and sticker art). */
+export interface PaintBrushPreviewOptions {
+    /** Image sources are read from this library before each preview that needs them. */
+    library?: Pick<BrushLibrary, 'getSource'>;
+    /** Art for sticker stamp tips (and anything else not in the library), read on every call. */
+    stampArt?: () => StickerArtLookup | undefined;
+}
 /**
  * A brush preview renderer (`BrushPreviewRenderer`, as `preview_brush` and `BrushLibraryEditor`
  * take) that paints the test stroke with the paint engine on `paper` (read on every call; default
- * the default paper). Any brush the paint editor renders, so also the image editor's.
+ * the default paper). Any brush the paint editor renders, so also the image editor's. With
+ * `options.library`, image tips and image grain are drawn from its sources.
  */
-export declare function paintBrushPreviewRenderer(paper?: () => PaperSettings): BrushPreviewRenderer;
+export declare function paintBrushPreviewRenderer(paper?: () => PaperSettings, options?: PaintBrushPreviewOptions): BrushPreviewRenderer;
 /**
  * The brush library tools for a paint editor (`@pixerate/editor/brushes`' provider on the
  * editor's `brushLibrary`, `PAINT_PROFILE`), with `preview_brush` painting the test stroke on the

package/dist/paint-editor/brush-model.d.cts

@@ -156,7 +156,31 @@ export interface BrushDynamics {
     opacityJitter: number;
     /** Random offset across the stroke in diameters, 0..4 (default 0). */
     scatter: number;
+    /** Dabs laid at each spacing step, 1..16, each with its own jitter (missing: 1). */
+    count?: number;
+    /** Mirror each dab at random across these axes (missing: `none`). */
+    flip?: DabFlip;
 }
+/** Random mirroring of dabs. */
+export type DabFlip = 'none' | 'x' | 'y' | 'xy';
+export declare const DAB_FLIPS: readonly DabFlip[];
+export type TipGrainMode = 'moving' | 'texturised';
+export declare const TIP_GRAIN_MODES: readonly TipGrainMode[];
+/** Texture inside the tip (dab engines): each dab's coverage is multiplied by it. */
+export interface TipGrainSettings {
+    /** A grain pattern (`rough`, `canvas`…) or an image source `source:<id>`. */
+    source: string;
+    /** `texturised` (default): fixed to the canvas; `moving`: rolls along with the tip. */
+    mode: TipGrainMode;
+    /** 0.05..20: 1 the source's own size (default 1). */
+    scale: number;
+    /** 0..1: how much it takes out of the dab (default 0.6). */
+    depth: number;
+    /** 0..3 around the middle (default 1). */
+    contrast: number;
+    invert: boolean;
+}
+export declare const DEFAULT_TIP_GRAIN: Readonly<Omit<TipGrainSettings, 'source'>>;
 export declare const DEFAULT_DYNAMICS: Readonly<BrushDynamics>;
 export interface PaintBrush {
     /** Library id (lowercase letters, digits and dashes). */
@@ -202,6 +226,8 @@ export interface PaintBrush {
     stamp: string | null;
     /** Dab engine: spray marks. Each dab lays a seeded scatter of droplets across the tip; `null` (default): one mark per dab. */
     spray: SpraySettings | null;
+    /** Dab engines: texture inside the tip (missing: none). Recorded with the stroke, source ref included, so replays match. */
+    tipGrain?: TipGrainSettings;
     /**
      * The brush's own gradient paint (`@pixerate/editor/paint` `PaintGradientSource`), used instead
      * of the editor's paint; `null` (default): the editor's paint. Stops may be `paint` / `secondary`
@@ -228,8 +254,10 @@ export interface SpraySettings {
     size: number;
 }
 export declare const DEFAULT_SPRAY: Readonly<SpraySettings>;
-export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light' | 'spray'>> & {
+export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light' | 'spray' | 'tipGrain'>> & {
     spray?: Partial<SpraySettings> | null;
+    /** Tip grain (`null` removes it). */
+    tipGrain?: Partial<TipGrainSettings> | null;
     light?: Partial<LightSettings>;
     /** A gradient (or `null` for the editor's paint); a plain colour source clears it. */
     paint?: PaintSource | null;

package/dist/paint-editor/brush-model.d.ts

@@ -156,7 +156,31 @@ export interface BrushDynamics {
     opacityJitter: number;
     /** Random offset across the stroke in diameters, 0..4 (default 0). */
     scatter: number;
+    /** Dabs laid at each spacing step, 1..16, each with its own jitter (missing: 1). */
+    count?: number;
+    /** Mirror each dab at random across these axes (missing: `none`). */
+    flip?: DabFlip;
 }
+/** Random mirroring of dabs. */
+export type DabFlip = 'none' | 'x' | 'y' | 'xy';
+export declare const DAB_FLIPS: readonly DabFlip[];
+export type TipGrainMode = 'moving' | 'texturised';
+export declare const TIP_GRAIN_MODES: readonly TipGrainMode[];
+/** Texture inside the tip (dab engines): each dab's coverage is multiplied by it. */
+export interface TipGrainSettings {
+    /** A grain pattern (`rough`, `canvas`…) or an image source `source:<id>`. */
+    source: string;
+    /** `texturised` (default): fixed to the canvas; `moving`: rolls along with the tip. */
+    mode: TipGrainMode;
+    /** 0.05..20: 1 the source's own size (default 1). */
+    scale: number;
+    /** 0..1: how much it takes out of the dab (default 0.6). */
+    depth: number;
+    /** 0..3 around the middle (default 1). */
+    contrast: number;
+    invert: boolean;
+}
+export declare const DEFAULT_TIP_GRAIN: Readonly<Omit<TipGrainSettings, 'source'>>;
 export declare const DEFAULT_DYNAMICS: Readonly<BrushDynamics>;
 export interface PaintBrush {
     /** Library id (lowercase letters, digits and dashes). */
@@ -202,6 +226,8 @@ export interface PaintBrush {
     stamp: string | null;
     /** Dab engine: spray marks. Each dab lays a seeded scatter of droplets across the tip; `null` (default): one mark per dab. */
     spray: SpraySettings | null;
+    /** Dab engines: texture inside the tip (missing: none). Recorded with the stroke, source ref included, so replays match. */
+    tipGrain?: TipGrainSettings;
     /**
      * The brush's own gradient paint (`@pixerate/editor/paint` `PaintGradientSource`), used instead
      * of the editor's paint; `null` (default): the editor's paint. Stops may be `paint` / `secondary`
@@ -228,8 +254,10 @@ export interface SpraySettings {
     size: number;
 }
 export declare const DEFAULT_SPRAY: Readonly<SpraySettings>;
-export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light' | 'spray'>> & {
+export type PaintBrushInput = Partial<Omit<PaintBrush, 'tip' | 'dynamics' | 'mixer' | 'behavior' | 'blender' | 'smudge' | 'wet' | 'impasto' | 'particle' | 'bristle' | 'sticker' | 'paint' | 'light' | 'spray' | 'tipGrain'>> & {
     spray?: Partial<SpraySettings> | null;
+    /** Tip grain (`null` removes it). */
+    tipGrain?: Partial<TipGrainSettings> | null;
     light?: Partial<LightSettings>;
     /** A gradient (or `null` for the editor's paint); a plain colour source clears it. */
     paint?: PaintSource | null;

package/dist/paint-editor/brush-source-art.d.cts

@@ -0,0 +1,32 @@
+/**
+ * Brush sources the paint engine can draw with: the brush library's and the open painting's, by
+ * id. Strokes read them synchronously, as they read sticker art (`StickerArtLookup`): a stamp tip
+ * `source:<id>` and an image tip grain both take the source's mask as alpha. Each mask is decoded
+ * the first time it is drawn.
+ */
+import { type BrushSource } from '../brushes/sources.cjs';
+import type { StickerArtLookup } from './sticker-art.cjs';
+export declare class BrushSourceArtCache {
+    private readonly sources;
+    private readonly art;
+    /** Adds or replaces sources (a replaced image is decoded again). */
+    set(sources: Iterable<BrushSource>): void;
+    /** The source of an id, if known. */
+    source(id: string): BrushSource | undefined;
+    /** Every known source. */
+    all(): BrushSource[];
+    /** The art of a `source:<id>` ref (alpha = the mask), or `undefined` when the source is unknown or its image can't be read. */
+    get: StickerArtLookup;
+    /** A lookup that reads sources from here and every other ref from `stickers`. */
+    with(stickers: StickerArtLookup): StickerArtLookup;
+}
+/** The ids of the sources an engine brush draws with: its stamp tip, its tip grain and its particle stamps. */
+export declare function engineBrushSourceIds(brush: {
+    stamp: string | null;
+    tipGrain?: {
+        source: string;
+    };
+    particle?: {
+        dotTextures: readonly string[];
+    };
+}): string[];

package/dist/paint-editor/brush-source-art.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Brush sources the paint engine can draw with: the brush library's and the open painting's, by
+ * id. Strokes read them synchronously, as they read sticker art (`StickerArtLookup`): a stamp tip
+ * `source:<id>` and an image tip grain both take the source's mask as alpha. Each mask is decoded
+ * the first time it is drawn.
+ */
+import { type BrushSource } from '../brushes/sources.js';
+import type { StickerArtLookup } from './sticker-art.js';
+export declare class BrushSourceArtCache {
+    private readonly sources;
+    private readonly art;
+    /** Adds or replaces sources (a replaced image is decoded again). */
+    set(sources: Iterable<BrushSource>): void;
+    /** The source of an id, if known. */
+    source(id: string): BrushSource | undefined;
+    /** Every known source. */
+    all(): BrushSource[];
+    /** The art of a `source:<id>` ref (alpha = the mask), or `undefined` when the source is unknown or its image can't be read. */
+    get: StickerArtLookup;
+    /** A lookup that reads sources from here and every other ref from `stickers`. */
+    with(stickers: StickerArtLookup): StickerArtLookup;
+}
+/** The ids of the sources an engine brush draws with: its stamp tip, its tip grain and its particle stamps. */
+export declare function engineBrushSourceIds(brush: {
+    stamp: string | null;
+    tipGrain?: {
+        source: string;
+    };
+    particle?: {
+        dotTextures: readonly string[];
+    };
+}): string[];

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

@@ -39,7 +39,8 @@ import { type PaintGuides, type PerspectiveGuide, type ReferenceImage, type Symm
 import { MixingPad, type MixingPadTool, type PadMixOptions } from './mixing-pad.cjs';
 import { type Stencil, type StencilInput } from './stencils.cjs';
 import { type Sticker } from './stickers.cjs';
-import { type StickerRasterizer } from './sticker-art.cjs';
+import { type StickerArtLookup, type StickerRasterizer } from './sticker-art.cjs';
+import { BrushSourceArtCache } from './brush-source-art.cjs';
 import { StickersSlot } from '../stickers/helpers.cjs';
 import type { StickerProvider, StickerRef } from '../stickers/types.cjs';
 import { type LightSpill } from './light.cjs';
@@ -445,6 +446,10 @@ export declare class PaintEditorController {
     /** The sticker library slot (see `setStickersProvider`). */
     readonly stickers: StickersSlot;
     private readonly stickerArt;
+    /** Image sources strokes draw with: the brush library's and the open painting's (saved with it). */
+    readonly brushSources: BrushSourceArtCache;
+    /** Art for stamp tips and tip grain: image sources from `brushSources`, stickers from the sticker library. */
+    readonly stampArt: StickerArtLookup;
     private readonly rasterizeSticker;
     private readonly effectsRenderer;
     private paperEffectNodeCache;
@@ -478,10 +483,12 @@ export declare class PaintEditorController {
     withOrigin<T>(origin: string, fn: () => T): T;
     /**
      * Runs `fn` as one undo step named `label`: every change it makes (strokes, fills, new layers) is
-     * undone together. Wet paint can't be grouped. Nested groups join the outer one. If `fn` throws,
-     * its changes are put back and nothing is recorded.
+     * undone together. When `fn` returns a promise, the group holds until it settles; until then other
+     * changes (the user's strokes, undo) are refused, except those `fn` makes through `within`, so
+     * nothing else lands in (or is lost with) the group's step. Nested groups join the outer one. If
+     * `fn` throws or rejects, its changes are put back and nothing is recorded.
      */
-    group<T>(label: string, fn: () => T): T;
+    group<T>(label: string, fn: (within: <U>(step: () => U) => U) => T): T;
     /**
      * What `fn` would paint, without changing anything: it runs on a new empty layer (above the
      * active layer, another one, or at the bottom), and the layer's pixels and the picture with them

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

@@ -39,7 +39,8 @@ import { type PaintGuides, type PerspectiveGuide, type ReferenceImage, type Symm
 import { MixingPad, type MixingPadTool, type PadMixOptions } from './mixing-pad.js';
 import { type Stencil, type StencilInput } from './stencils.js';
 import { type Sticker } from './stickers.js';
-import { type StickerRasterizer } from './sticker-art.js';
+import { type StickerArtLookup, type StickerRasterizer } from './sticker-art.js';
+import { BrushSourceArtCache } from './brush-source-art.js';
 import { StickersSlot } from '../stickers/helpers.js';
 import type { StickerProvider, StickerRef } from '../stickers/types.js';
 import { type LightSpill } from './light.js';
@@ -445,6 +446,10 @@ export declare class PaintEditorController {
     /** The sticker library slot (see `setStickersProvider`). */
     readonly stickers: StickersSlot;
     private readonly stickerArt;
+    /** Image sources strokes draw with: the brush library's and the open painting's (saved with it). */
+    readonly brushSources: BrushSourceArtCache;
+    /** Art for stamp tips and tip grain: image sources from `brushSources`, stickers from the sticker library. */
+    readonly stampArt: StickerArtLookup;
     private readonly rasterizeSticker;
     private readonly effectsRenderer;
     private paperEffectNodeCache;
@@ -478,10 +483,12 @@ export declare class PaintEditorController {
     withOrigin<T>(origin: string, fn: () => T): T;
     /**
      * Runs `fn` as one undo step named `label`: every change it makes (strokes, fills, new layers) is
-     * undone together. Wet paint can't be grouped. Nested groups join the outer one. If `fn` throws,
-     * its changes are put back and nothing is recorded.
+     * undone together. When `fn` returns a promise, the group holds until it settles; until then other
+     * changes (the user's strokes, undo) are refused, except those `fn` makes through `within`, so
+     * nothing else lands in (or is lost with) the group's step. Nested groups join the outer one. If
+     * `fn` throws or rejects, its changes are put back and nothing is recorded.
      */
-    group<T>(label: string, fn: () => T): T;
+    group<T>(label: string, fn: (within: <U>(step: () => U) => U) => T): T;
     /**
      * What `fn` would paint, without changing anything: it runs on a new empty layer (above the
      * active layer, another one, or at the bottom), and the layer's pixels and the picture with them

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

@@ -76,6 +76,8 @@ export declare class PaintDabStroke {
     private lastFed;
     /** The stamp tip's shape (dab brushes), or `null` for the round computed tip. */
     private readonly stamp;
+    /** The tip's own grain, or `null`. */
+    private readonly tipGrain;
     constructor(brush: PaintBrush, options: PaintDabStrokeOptions);
     /** What copy 0's brush carries after the dabs so far (mixer and wet-capable dab brushes). */
     get load(): MixerLoad | null;

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

@@ -76,6 +76,8 @@ export declare class PaintDabStroke {
     private lastFed;
     /** The stamp tip's shape (dab brushes), or `null` for the round computed tip. */
     private readonly stamp;
+    /** The tip's own grain, or `null`. */
+    private readonly tipGrain;
     constructor(brush: PaintBrush, options: PaintDabStrokeOptions);
     /** What copy 0's brush carries after the dabs so far (mixer and wet-capable dab brushes). */
     get load(): MixerLoad | null;

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

@@ -88,6 +88,8 @@ export interface PenDab extends Dab {
     lean: number;
     /** Pen speed (px/ms), or `null` when the samples carry no time. */
     speed: number | null;
+    /** Mirrored across the tip's x axis (bit 1) and y axis (bit 2), from `dynamics.flip`; 0 or missing: not mirrored. */
+    flip?: number;
 }
 /**
  * Walks pen samples into dabs, incrementally (any chunking gives the same dabs). Dab angles are in
@@ -115,6 +117,8 @@ export declare class PenDabWalker {
     private dab;
     push(p: PenPoint, out: PenDab[]): void;
     finish(out: PenDab[]): void;
+    /** The dabs of one spacing step: `dynamics.count` of them, each with its own index and so its own jitter. */
+    private lay;
 }
 export interface DryStrokeOptions {
     /** The paper's dry height field, or `null` for no grain. */
@@ -127,7 +131,10 @@ export interface DryStrokeOptions {
     copies?: readonly StrokeCopy[];
     /** Effect paint: each pixel takes its colour (and alpha) from these canvas-sized pixels. */
     effect?: EffectPaintPixels | null;
-    /** Loaded sticker art, for a stamp tip of a sticker from the sticker library (`brush.stamp`); without it such a tip paints round. */
+    /**
+     * Loaded art for a stamp tip of a sticker or an image source (`brush.stamp`) and for an image
+     * tip grain (`brush.tipGrain.source`); without it such a tip paints round, and the grain is left out.
+     */
     stampArt?: StickerArtLookup;
 }
 /**
@@ -149,13 +156,15 @@ export declare class DryStroke {
     private lastFed;
     /** The stamp tip's shape, or `null` for the round computed tip. */
     private readonly stamp;
+    /** The tip's own grain, or `null`. */
+    private readonly tipGrain;
     constructor(brush: PaintBrush, options: DryStrokeOptions);
     /** Feeds raw pen samples; returns the document rectangles the new dabs touched. */
     push(points: readonly PenPoint[]): RasterRect[];
     /** Ends the stroke: the smoothed path catches up with the last raw sample; a single tap paints one dab. */
     finish(): RasterRect[];
     private paint;
-    /** Lays one mark (a dab, or a spray droplet of dab `d`): the round tip or the stamp, the paper grain, effect paint. */
+    /** Lays one mark (a dab, or a spray droplet of dab `d`): the round tip or the stamp, the tip grain, the paper grain, effect paint. */
     private mark;
 }
 /** The shared engine's tip for the Mixer Brush engine (it smooths and walks by itself, so smoothing is applied before). */

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

@@ -88,6 +88,8 @@ export interface PenDab extends Dab {
     lean: number;
     /** Pen speed (px/ms), or `null` when the samples carry no time. */
     speed: number | null;
+    /** Mirrored across the tip's x axis (bit 1) and y axis (bit 2), from `dynamics.flip`; 0 or missing: not mirrored. */
+    flip?: number;
 }
 /**
  * Walks pen samples into dabs, incrementally (any chunking gives the same dabs). Dab angles are in
@@ -115,6 +117,8 @@ export declare class PenDabWalker {
     private dab;
     push(p: PenPoint, out: PenDab[]): void;
     finish(out: PenDab[]): void;
+    /** The dabs of one spacing step: `dynamics.count` of them, each with its own index and so its own jitter. */
+    private lay;
 }
 export interface DryStrokeOptions {
     /** The paper's dry height field, or `null` for no grain. */
@@ -127,7 +131,10 @@ export interface DryStrokeOptions {
     copies?: readonly StrokeCopy[];
     /** Effect paint: each pixel takes its colour (and alpha) from these canvas-sized pixels. */
     effect?: EffectPaintPixels | null;
-    /** Loaded sticker art, for a stamp tip of a sticker from the sticker library (`brush.stamp`); without it such a tip paints round. */
+    /**
+     * Loaded art for a stamp tip of a sticker or an image source (`brush.stamp`) and for an image
+     * tip grain (`brush.tipGrain.source`); without it such a tip paints round, and the grain is left out.
+     */
     stampArt?: StickerArtLookup;
 }
 /**
@@ -149,13 +156,15 @@ export declare class DryStroke {
     private lastFed;
     /** The stamp tip's shape, or `null` for the round computed tip. */
     private readonly stamp;
+    /** The tip's own grain, or `null`. */
+    private readonly tipGrain;
     constructor(brush: PaintBrush, options: DryStrokeOptions);
     /** Feeds raw pen samples; returns the document rectangles the new dabs touched. */
     push(points: readonly PenPoint[]): RasterRect[];
     /** Ends the stroke: the smoothed path catches up with the last raw sample; a single tap paints one dab. */
     finish(): RasterRect[];
     private paint;
-    /** Lays one mark (a dab, or a spray droplet of dab `d`): the round tip or the stamp, the paper grain, effect paint. */
+    /** Lays one mark (a dab, or a spray droplet of dab `d`): the round tip or the stamp, the tip grain, the paper grain, effect paint. */
     private mark;
 }
 /** The shared engine's tip for the Mixer Brush engine (it smooths and walks by itself, so smoothing is applied before). */