@lvl99dotcom/paintcanvas 0.5.0 → 0.6.0

package/dist/lib/brushes/configRanges/index.d.ts

@@ -23,6 +23,13 @@ export declare const PARAM_LIMITS: Record<VaryingParam, {
     min: number;
     max: number;
 }>;
+/**
+ * The config key of a setting's variation.
+ *
+ * @example
+ * configKey("width"); // "widthConfig"
+ */
+export declare const configKey: (param: VaryingParam) => `${VaryingParam}Config`;
 /**
  * Read a setting as the configuration window shows it. When it varies, its range comes from the first source turned
  * on: scale settings (width, height, opacity) go from `value × min factor` to the value; rotation goes from the angle
@@ -50,3 +57,13 @@ export declare const writeRange: (config: BrushConfig, param: VaryingParam, rang
  * when it is the first, a starting range (half to full size, the angle itself, or no scatter).
  */
 export declare const toggleSource: (config: BrushConfig, param: VaryingParam, source: VariationSource, on: boolean) => Partial<BrushConfig>;
+/**
+ * Make a setting vary with one source only (or none, with `undefined`), as config changes. Switching from another
+ * source keeps the setting's range; the first source takes a starting range (see `toggleSource`). The setting's profile
+ * graph is kept.
+ *
+ * @example
+ * selectSource({ id: "a", widthConfig: { usePressure: true, minPressure: 0.5 } }, "width", "tilt");
+ * // { widthConfig: { usePressure: false, useTilt: true, minTilt: 0.5, maxTilt: 1, useRandomise: false, … } }
+ */
+export declare const selectSource: (config: BrushConfig, param: VaryingParam, source: VariationSource | undefined) => Partial<BrushConfig>;

package/dist/lib/brushes/configRanges/index.js

@@ -65,6 +65,12 @@ var SOURCE_DEFAULTS = {
 	tilt: [0, 1],
 	randomise: [1, 1]
 };
+/**
+* The config key of a setting's variation.
+*
+* @example
+* configKey("width"); // "widthConfig"
+*/
 var configKey = (param) => `${param}Config`;
 var clamp = (value, min, max) => Math.max(min, Math.min(max, value));
 /** A setting's value as stored (alpha as 0–1) */
@@ -203,4 +209,28 @@ var toggleSource = (config, param, source, on) => {
 	});
 	return { [key]: variation };
 };
-export { PARAM_LIMITS, VARIATION_SOURCES, readRange, toggleSource, writeRange };
+/**
+* Make a setting vary with one source only (or none, with `undefined`), as config changes. Switching from another
+* source keeps the setting's range; the first source takes a starting range (see `toggleSource`). The setting's profile
+* graph is kept.
+*
+* @example
+* selectSource({ id: "a", widthConfig: { usePressure: true, minPressure: 0.5 } }, "width", "tilt");
+* // { widthConfig: { usePressure: false, useTilt: true, minTilt: 0.5, maxTilt: 1, useRandomise: false, … } }
+*/
+var selectSource = (config, param, source) => {
+	const key = configKey(param);
+	const previous = VARIATION_SOURCES.find((each) => readRange(config, param).sources[each]);
+	if (source && !previous) return toggleSource(config, param, source, true);
+	const variation = { ...config[key] };
+	for (const each of VARIATION_SOURCES) variation[SOURCE_KEYS[each][0]] = each === source;
+	if (source && previous && source !== previous) {
+		const [, fromMin, fromMax] = SOURCE_KEYS[previous];
+		const [, toMin, toMax] = SOURCE_KEYS[source];
+		const [minDefault, maxDefault] = SOURCE_DEFAULTS[previous];
+		variation[toMin] = variation[fromMin] ?? minDefault;
+		variation[toMax] = variation[fromMax] ?? maxDefault;
+	}
+	return { [key]: variation };
+};
+export { PARAM_LIMITS, VARIATION_SOURCES, configKey, readRange, selectSource, toggleSource, writeRange };

package/dist/lib/brushes/params/index.d.ts

@@ -49,7 +49,8 @@ export declare const tiltAmount: (tiltX?: number, tiltY?: number) => number;
 export declare const tiltDirection: (tiltX?: number, tiltY?: number) => number;
 /**
  * Combine a parameter's randomise, pressure and tilt factors into one factor (they multiply). Returns 1 when nothing is enabled.
- * Pressure and tilt only apply to pens; for other devices they count as full (`maxPressure`/`maxTilt`).
+ * Pressure and tilt only apply to pens; for other devices they count as full (`maxPressure`/`maxTilt`). Each input goes
+ * through the parameter's profile graph (see `applyProfile`) before it sets the factor between its min and max.
  *
  * @example
  * variationFactor({ useRandomise: true, minRandomise: 0.5, maxRandomise: 1 }, { isPen: false }, () => 0); // 0.5

package/dist/lib/brushes/params/index.js

@@ -1,3 +1,4 @@
+import { applyProfile } from "../../profiles/index.js";
 // src/lib/brushes/params/index.ts
 /**
 * Linear interpolation between two values.
@@ -27,22 +28,24 @@ var tiltAmount = (tiltX = 0, tiltY = 0) => clamp01(Math.hypot(tiltX, tiltY) / 90
 var tiltDirection = (tiltX = 0, tiltY = 0) => Math.atan2(tiltY, tiltX) * 180 / Math.PI;
 /**
 * Combine a parameter's randomise, pressure and tilt factors into one factor (they multiply). Returns 1 when nothing is enabled.
-* Pressure and tilt only apply to pens; for other devices they count as full (`maxPressure`/`maxTilt`).
+* Pressure and tilt only apply to pens; for other devices they count as full (`maxPressure`/`maxTilt`). Each input goes
+* through the parameter's profile graph (see `applyProfile`) before it sets the factor between its min and max.
 *
 * @example
 * variationFactor({ useRandomise: true, minRandomise: 0.5, maxRandomise: 1 }, { isPen: false }, () => 0); // 0.5
 */
 var variationFactor = (config, input, random = Math.random) => {
 	if (!config) return 1;
+	const { profile } = config;
 	let factor = 1;
-	if (config.useRandomise) factor *= lerp(config.minRandomise ?? 1, config.maxRandomise ?? 1, random());
+	if (config.useRandomise) factor *= lerp(config.minRandomise ?? 1, config.maxRandomise ?? 1, applyProfile(profile, random()));
 	if (config.usePressure) {
 		const pressure = input.isPen ? clamp01(input.pressure ?? 1) : 1;
-		factor *= lerp(config.minPressure ?? 0, config.maxPressure ?? 1, pressure);
+		factor *= lerp(config.minPressure ?? 0, config.maxPressure ?? 1, applyProfile(profile, pressure));
 	}
 	if (config.useTilt) {
 		const tilt = input.isPen ? tiltAmount(input.tiltX, input.tiltY) : 1;
-		factor *= lerp(config.minTilt ?? 0, config.maxTilt ?? 1, tilt);
+		factor *= lerp(config.minTilt ?? 0, config.maxTilt ?? 1, applyProfile(profile, tilt));
 	}
 	return factor;
 };

package/dist/lib/brushes/types/index.d.ts

@@ -1,3 +1,4 @@
+import type { ProfilePoint } from "../../profiles";
 export interface AssetAuthorDetails {
     /** Author's name */
     name: string;
@@ -94,6 +95,13 @@ export interface BrushParamConfig {
      * @default 1
      */
     maxTilt?: number;
+    /**
+     * The profile graph the input (pressure, tilt or the random number) goes through before setting the factor between
+     * its min and max, e.g. so a light touch goes most of the way (see `applyProfile`). A straight line by default.
+     */
+    profile?: ProfilePoint[];
+    /** The ID of the profile graph `profile` came from (a preset's or one of the user's), to show its name */
+    profileId?: string;
 }
 export interface BrushConfig {
     /** Unique ID */

package/dist/lib/classes/Layer/index.d.ts

@@ -29,6 +29,16 @@ export type CanvasFactory = (width: number, height: number) => OffscreenCanvas;
  * Create an `OffscreenCanvas` of the given size.
  */
 export declare const createOffscreenCanvas: CanvasFactory;
+/**
+ * Create an `OffscreenCanvas` whose pixels are kept in regular memory rather than on the GPU (its 2D context is made
+ * with `willReadFrequently`). Reading its pixels, encoding it and copying it are then plain memory copies, which on
+ * phones avoids long stalls waiting for the GPU (up to 15 seconds were seen on an iPhone), at the cost of drawing on
+ * the CPU. PaintCanvas makes its canvases this way by default.
+ *
+ * @example
+ * const canvas = createMemoryCanvas(2000, 2000);
+ */
+export declare const createMemoryCanvas: CanvasFactory;
 /**
  * Clamp an opacity value to 0–1.
  *

package/dist/lib/classes/Layer/index.js

@@ -16,6 +16,20 @@ var MAX_LAYER_NAME_LENGTH = 64;
 */
 var createOffscreenCanvas = (width, height) => new OffscreenCanvas(width, height);
 /**
+* Create an `OffscreenCanvas` whose pixels are kept in regular memory rather than on the GPU (its 2D context is made
+* with `willReadFrequently`). Reading its pixels, encoding it and copying it are then plain memory copies, which on
+* phones avoids long stalls waiting for the GPU (up to 15 seconds were seen on an iPhone), at the cost of drawing on
+* the CPU. PaintCanvas makes its canvases this way by default.
+*
+* @example
+* const canvas = createMemoryCanvas(2000, 2000);
+*/
+var createMemoryCanvas = (width, height) => {
+	const canvas = new OffscreenCanvas(width, height);
+	canvas.getContext("2d", { willReadFrequently: true });
+	return canvas;
+};
+/**
 * Clamp an opacity value to 0–1.
 *
 * @example
@@ -108,4 +122,4 @@ var Layer = class {
 		};
 	}
 };
-export { BlendMode, MAX_LAYER_NAME_LENGTH, clampOpacity, createOffscreenCanvas, Layer as default };
+export { BlendMode, MAX_LAYER_NAME_LENGTH, clampOpacity, createMemoryCanvas, createOffscreenCanvas, Layer as default };

package/dist/lib/classes/LayerAutosave/index.d.ts

@@ -34,7 +34,7 @@ export interface AutosaveOptions {
     locks?: LockManager | null;
     /** Tells when the page is hidden or shown again (the page's document by default) */
     document?: Pick<Document, "visibilityState" | "addEventListener" | "removeEventListener"> | null;
-    /** Turns a layer's canvas into a PNG (replaceable for tests) */
+    /** Turns a layer's canvas into a PNG (in a background worker by default; replaceable for tests) */
     encode?: (canvas: OffscreenCanvas) => Promise<Blob>;
     /** Turns a saved PNG into an image to draw (replaceable for tests) */
     decode?: (image: Blob) => Promise<CanvasImageSource>;
@@ -44,8 +44,8 @@ export interface AutosaveOptions {
 /**
  * Keeps a canvas's layers in a store, so the drawing survives reloading the page: restores the saved drawing when it
  * starts, then saves soon after the layers change (once drawing pauses), and straight away when the page is hidden.
- * Only layers whose pixels changed are encoded and saved again; a quick fingerprint of each layer's pixels tells
- * which.
+ * Only layers whose pixels changed are encoded and saved again: the layers' change counts tell which (see
+ * `LayerStack.pixelVersion`), without reading their pixels, which is slow on phones.
  *
  * Only one window draws on a drawing at a time: the first to start has it, and others wait in the `elsewhere` state
  * (the UI blocks drawing there). When the page is shown again it tries again, and `takeOver` takes the drawing from
@@ -74,14 +74,10 @@ export default class LayerAutosave extends EventTarget {
     private readonly delayMs;
     /** The layers being watched for changes */
     private watched?;
-    /** Fingerprints of each layer's pixels as last saved, by layer ID */
-    private prints;
+    /** Each layer as last saved, by layer ID: the layer itself and its change count (see `LayerStack.pixelVersion`) */
+    private saved;
     /** Size in bytes of each layer's image as last saved or restored, by layer ID */
     private sizes;
-    /** Layers whose pixels changed since the last save */
-    private changed;
-    /** Whether any layer may have changed since the last save (not only those in `changed`) */
-    private checkAll;
     private timer?;
     /** The save being written, if any */
     private saving?;
@@ -133,11 +129,13 @@ export default class LayerAutosave extends EventTarget {
      */
     private restore;
     /**
-     * Remember each layer's pixels as saved (just restored).
+     * Remember each layer as saved (just restored).
      */
     private remember;
+    /** A layer and its change count, to tell later whether it changed */
+    private record;
     /**
-     * Save the drawing, encoding only the layers whose pixels changed since they were last saved.
+     * Save the drawing, encoding only the layers whose pixels changed since they were last saved (or that are new).
      */
     private write;
     /**
@@ -145,10 +143,6 @@ export default class LayerAutosave extends EventTarget {
      * changed.
      */
     private rememberSizes;
-    /**
-     * A fingerprint of a layer's pixels.
-     */
-    private fingerprint;
     /**
      * Save once the layers have stopped changing for a moment and drawing pauses.
      */

package/dist/lib/classes/LayerAutosave/index.js

@@ -1,4 +1,4 @@
-import { pixelFingerprint } from "../../image/index.js";
+import PngEncoder from "../PngEncoder/index.js";
 import "../../storage/index.js";
 // src/lib/classes/LayerAutosave/index.ts
 /** How long to wait after the layers change before saving, so quick changes are saved together (milliseconds) */
@@ -18,12 +18,14 @@ var AutosaveState = {
 	/** Not saving any more (see `stop`) */
 	Stopped: "stopped"
 };
+/** Encodes layers as PNGs in a background worker, shared by every autosave on the page (made on first use) */
+var sharedEncoder;
 /**
-* Encode a canvas as a PNG.
+* Encode a canvas as a PNG, in a background worker where one can be used, so saving doesn't freeze the page.
 */
 var encodePng = (canvas) => {
-	canvas.getContext("2d");
-	return canvas.convertToBlob({ type: "image/png" });
+	sharedEncoder ??= new PngEncoder();
+	return sharedEncoder.encode(canvas);
 };
 /**
 * Whether a saved drawing has the expected shape and an image for each layer.
@@ -32,8 +34,8 @@ var isComplete = (drawing, images) => drawing.version === 1 && drawing.layers.le
 /**
 * Keeps a canvas's layers in a store, so the drawing survives reloading the page: restores the saved drawing when it
 * starts, then saves soon after the layers change (once drawing pauses), and straight away when the page is hidden.
-* Only layers whose pixels changed are encoded and saved again; a quick fingerprint of each layer's pixels tells
-* which.
+* Only layers whose pixels changed are encoded and saved again: the layers' change counts tell which (see
+* `LayerStack.pixelVersion`), without reading their pixels, which is slow on phones.
 *
 * Only one window draws on a drawing at a time: the first to start has it, and others wait in the `elsewhere` state
 * (the UI blocks drawing there). When the page is shown again it tries again, and `takeOver` takes the drawing from
@@ -62,14 +64,10 @@ var LayerAutosave = class extends EventTarget {
 	delayMs;
 	/** The layers being watched for changes */
 	watched;
-	/** Fingerprints of each layer's pixels as last saved, by layer ID */
-	prints = /* @__PURE__ */ new Map();
+	/** Each layer as last saved, by layer ID: the layer itself and its change count (see `LayerStack.pixelVersion`) */
+	saved = /* @__PURE__ */ new Map();
 	/** Size in bytes of each layer's image as last saved or restored, by layer ID */
 	sizes = /* @__PURE__ */ new Map();
-	/** Layers whose pixels changed since the last save */
-	changed = /* @__PURE__ */ new Set();
-	/** Whether any layer may have changed since the last save (not only those in `changed`) */
-	checkAll = false;
 	timer;
 	/** The save being written, if any */
 	saving;
@@ -77,12 +75,7 @@ var LayerAutosave = class extends EventTarget {
 	again = false;
 	/** Lets go of the drawing's lock, while held */
 	release;
-	onLayersChange = () => {
-		const id = this.watched?.changedLayerId;
-		if (id) this.changed.add(id);
-		else this.checkAll = true;
-		this.schedule();
-	};
+	onLayersChange = () => this.schedule();
 	onCanvasChange = () => {
 		if (this.canvas.layers === this.watched) return;
 		this.watch();
@@ -202,7 +195,7 @@ var LayerAutosave = class extends EventTarget {
 			return;
 		}
 		if (this.currentState !== AutosaveState.Starting) return;
-		this.prints = /* @__PURE__ */ new Map();
+		this.saved = /* @__PURE__ */ new Map();
 		this.watch();
 		if (restored) this.remember();
 		this.setState(AutosaveState.Ready);
@@ -222,29 +215,32 @@ var LayerAutosave = class extends EventTarget {
 		return true;
 	}
 	/**
-	* Remember each layer's pixels as saved (just restored).
+	* Remember each layer as saved (just restored).
 	*/
 	remember() {
-		for (const layer of this.canvas.layers.layers) this.prints.set(layer.id, this.fingerprint(layer.id));
-		this.changed.clear();
-		this.checkAll = false;
+		const stack = this.canvas.layers;
+		for (const layer of stack.layers) this.saved.set(layer.id, this.record(layer));
+	}
+	/** A layer and its change count, to tell later whether it changed */
+	record(layer) {
+		return {
+			layer,
+			version: this.canvas.layers.pixelVersion(layer.id)
+		};
 	}
 	/**
-	* Save the drawing, encoding only the layers whose pixels changed since they were last saved.
+	* Save the drawing, encoding only the layers whose pixels changed since they were last saved (or that are new).
 	*/
 	async write() {
 		const stack = this.canvas.layers;
-		const { checkAll, changed } = this;
-		this.checkAll = false;
-		this.changed = /* @__PURE__ */ new Set();
-		const prints = /* @__PURE__ */ new Map();
+		const encoded = /* @__PURE__ */ new Map();
 		try {
 			const encoding = [];
 			for (const layer of stack.layers) {
-				if (!!this.prints.has(layer.id) && !checkAll && !changed.has(layer.id)) continue;
-				const print = this.fingerprint(layer.id);
-				if (print === this.prints.get(layer.id)) continue;
-				prints.set(layer.id, print);
+				const record = this.record(layer);
+				const saved = this.saved.get(layer.id);
+				if (saved?.layer === layer && saved.version === record.version) continue;
+				encoded.set(layer.id, record);
 				encoding.push(this.encode(layer.canvas).then((image) => [layer.id, image]));
 			}
 			const drawing = {
@@ -258,13 +254,11 @@ var LayerAutosave = class extends EventTarget {
 			if (this.currentState !== AutosaveState.Ready) return;
 			await this.store.save(drawing, images);
 			const kept = new Set(drawing.layers.map((layer) => layer.id));
-			for (const id of this.prints.keys()) if (!kept.has(id)) this.prints.delete(id);
-			for (const [id, print] of prints) this.prints.set(id, print);
+			for (const id of this.saved.keys()) if (!kept.has(id)) this.saved.delete(id);
+			for (const [id, record] of encoded) this.saved.set(id, record);
 			this.error = void 0;
 			this.rememberSizes(kept, images);
 		} catch (error) {
-			for (const id of [...changed, ...prints.keys()]) this.changed.add(id);
-			this.checkAll ||= checkAll;
 			this.fail(error);
 		}
 	}
@@ -279,13 +273,6 @@ var LayerAutosave = class extends EventTarget {
 		if (this.storedBytes !== before) this.dispatchEvent(new Event("change"));
 	}
 	/**
-	* A fingerprint of a layer's pixels.
-	*/
-	fingerprint(id) {
-		const layer = this.canvas.layers.get(id);
-		return pixelFingerprint(layer.context.getImageData(0, 0, layer.width, layer.height).data);
-	}
-	/**
 	* Save once the layers have stopped changing for a moment and drawing pauses.
 	*/
 	schedule() {

package/dist/lib/classes/LayerStack/index.d.ts

@@ -29,6 +29,8 @@ export default class LayerStack extends EventTarget {
     /** The layer the change being announced is about, when only its pixels changed (see `changedLayerId`) */
     private onlyChanged?;
     private readonly createCanvas;
+    /** How many times each layer's image data has been changed through the stack (see `pixelVersion`) */
+    private readonly versions;
     /** Most layers the stack can have */
     readonly maxLayers: number;
     constructor(width: number, height: number, createCanvas?: CanvasFactory, maxLayers?: number);
@@ -71,6 +73,17 @@ export default class LayerStack extends EventTarget {
      * `markChanged`, e.g. a brush stroke); undefined when anything may have changed.
      */
     get changedLayerId(): string | undefined;
+    /**
+     * How many times a layer's image data has been changed through the stack (`markChanged`, `changeImage`, `clear`,
+     * merging into it, and undoing or redoing those), to tell whether it changed since some point without reading its
+     * pixels (which is slow on phones). A new layer starts at 0.
+     *
+     * @example
+     * const before = stack.pixelVersion(id);
+     * stack.markChanged(id);
+     * stack.pixelVersion(id) > before; // true
+     */
+    pixelVersion(id: string): number;
     /**
      * Tell listeners a layer's image data changed (e.g. after a brush stroke), so thumbnails and the map redraw.
      */
@@ -150,6 +163,8 @@ export default class LayerStack extends EventTarget {
      * An undoable change of image data: undo and redo both swap the stored pixels with the layer's, then select the layer.
      */
     private imageEntry;
+    /** Count a change to a layer's image data */
+    private touch;
     /**
      * Create a layer with the stack's size and canvas factory.
      */

package/dist/lib/classes/LayerStack/index.js

@@ -31,6 +31,8 @@ var LayerStack = class extends EventTarget {
 	/** The layer the change being announced is about, when only its pixels changed (see `changedLayerId`) */
 	onlyChanged;
 	createCanvas;
+	/** How many times each layer's image data has been changed through the stack (see `pixelVersion`) */
+	versions = /* @__PURE__ */ new WeakMap();
 	/** Most layers the stack can have */
 	maxLayers;
 	constructor(width, height, createCanvas = createOffscreenCanvas, maxLayers = 5) {
@@ -130,10 +132,23 @@ var LayerStack = class extends EventTarget {
 		return this.onlyChanged;
 	}
 	/**
+	* How many times a layer's image data has been changed through the stack (`markChanged`, `changeImage`, `clear`,
+	* merging into it, and undoing or redoing those), to tell whether it changed since some point without reading its
+	* pixels (which is slow on phones). A new layer starts at 0.
+	*
+	* @example
+	* const before = stack.pixelVersion(id);
+	* stack.markChanged(id);
+	* stack.pixelVersion(id) > before; // true
+	*/
+	pixelVersion(id) {
+		return this.versions.get(this.get(id)) ?? 0;
+	}
+	/**
 	* Tell listeners a layer's image data changed (e.g. after a brush stroke), so thumbnails and the map redraw.
 	*/
 	markChanged(id) {
-		this.get(id);
+		this.touch(this.get(id));
 		this.onlyChanged = id;
 		try {
 			this.notify();
@@ -150,6 +165,7 @@ var LayerStack = class extends EventTarget {
 		const area = contentBounds(data, this.width, this.height);
 		if (area) this.recordImage(id, area);
 		layer.clear();
+		this.touch(layer);
 		this.notify();
 	}
 	/**
@@ -174,7 +190,9 @@ var LayerStack = class extends EventTarget {
 	*/
 	changeImage(id, area, change) {
 		this.recordImage(id, area);
-		change(this.get(id).context);
+		const layer = this.get(id);
+		change(layer.context);
+		this.touch(layer);
 		this.notify();
 	}
 	/**
@@ -209,6 +227,7 @@ var LayerStack = class extends EventTarget {
 				ctx.globalCompositeOperation = layer.blendMode;
 				ctx.drawImage(layer.canvas, x, y, width, height, x, y, width, height);
 				ctx.restore();
+				this.touch(below);
 			}
 			this.items = this.items.filter((l) => l !== layer);
 			this.activeId = below.id;
@@ -332,6 +351,7 @@ var LayerStack = class extends EventTarget {
 			ctx.clearRect(area.x, area.y, area.width, area.height);
 			ctx.drawImage(stored, area.x, area.y);
 			stored = current;
+			this.touch(layer);
 			this.select(id);
 		};
 		return {
@@ -339,6 +359,10 @@ var LayerStack = class extends EventTarget {
 			redo: swap
 		};
 	}
+	/** Count a change to a layer's image data */
+	touch(layer) {
+		this.versions.set(layer, this.pixelVersion(layer.id) + 1);
+	}
 	/**
 	* Create a layer with the stack's size and canvas factory.
 	*/

package/dist/lib/classes/PaintCanvas/index.d.ts

@@ -20,6 +20,7 @@ import CustomPresets, { type PresetStoreLike } from "../CustomPresets";
 import InputSettings from "../InputSettings";
 import UiSettings from "../UiSettings";
 import Palette from "../Palette";
+import ProfileGraphs from "../ProfileGraphs";
 import ShortcutSettings from "../ShortcutSettings";
 import ExternalSheets from "../ExternalSheets";
 import { type CanvasMessage, type PatchMessage, type StrokeMessage } from "../../messages";
@@ -114,7 +115,11 @@ export interface PaintCanvasOptions {
     maxCanvasSize?: number;
     /** Most layers the user can have (default `DEFAULT_MAX_LAYERS`) */
     maxLayers?: number;
-    /** Creates layer canvases (replaceable for tests) */
+    /**
+     * Creates the canvases the engine draws in: layers, stroke buffers, masks and copies. `createMemoryCanvas` by default,
+     * keeping pixels in regular memory so saving and copying don't stall phones; pass `createOffscreenCanvas` to keep them
+     * on the GPU instead (replaceable for tests).
+     */
     createCanvas?: CanvasFactory;
     /** Where custom brush presets are kept (defaults to keeping them in memory only) */
     presetStore?: PresetStoreLike;
@@ -171,6 +176,8 @@ export default class PaintCanvas extends EventTarget {
     readonly ui: UiSettings;
     /** The user's saved colours, shown as swatches */
     readonly palette: Palette;
+    /** The user's own profile graphs (and the presets), for shaping how brush settings vary */
+    readonly profiles: ProfileGraphs;
     /** The user's keyboard shortcuts: each configurable action's key combination */
     readonly shortcuts: ShortcutSettings;
     /** The user's pointer position over the canvas, in canvas pixels (undefined when off the canvas) */
@@ -439,6 +446,20 @@ export default class PaintCanvas extends EventTarget {
      * nothing during a stroke or while a transform is pending. Returns the area copied, if any.
      */
     copy(): Rect | undefined;
+    /**
+     * Copy the masked image data of all the shown layers, mixed as they're shown (each layer's opacity and blend mode,
+     * without the white background), to the clipboard. Hidden layers are left out. Like `copy`, it needs a mask with image
+     * data inside it, and does nothing during a stroke or while a transform is pending. Returns the area copied, if any.
+     *
+     * @example
+     * app.selection.selectAll();
+     * app.copyMerged(); // { x: 10, y: 20, width: 30, height: 5 }: the part of the canvas with paint on any shown layer
+     */
+    copyMerged(): Rect | undefined;
+    /**
+     * Copy the masked part of a canvas-sized image to the clipboard (see `copy`), returning the area copied, if any.
+     */
+    private copyMasked;
     /**
      * How many times image data has been copied or cut, to tell whether it was copied here since something else may have
      * been copied in another app (see `KeyboardShortcuts`).
@@ -484,9 +505,11 @@ export default class PaintCanvas extends EventTarget {
      * data when its alpha lock is on. None if that is empty.
      */
     private fillArea;
+    /** Whether image data can be copied now: not during a stroke or while a transform is pending */
+    private get canCopy();
     /**
-     * The bounds of the selected layer's image data inside the mask, if there is a mask with image data inside it. None
-     * during a stroke or while a transform is pending.
+     * The bounds of a canvas-sized image's data (the selected layer's by default) inside the mask, if there is a mask
+     * with image data inside it. None during a stroke or while a transform is pending.
      */
     private maskedArea;
     /**