@lvl99dotcom/paintcanvas 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,965 @@
+import StrokeLog from "../StrokeLog/index.js";
+import BackgroundWork from "../BackgroundWork/index.js";
+import BrushSettings from "../BrushSettings/index.js";
+import LayerStack from "../LayerStack/index.js";
+import Viewport from "../Viewport/index.js";
+import StrokeEngine, { BEFORE_COMMIT_EVENT, STROKE_BEGIN_EVENT, STROKE_END_EVENT } from "../../brushes/StrokeEngine/index.js";
+import BrushTipCache from "../../brushes/BrushTipCache/index.js";
+import Selection from "../../selection/Selection/index.js";
+import Lasso from "../../selection/Lasso/index.js";
+import Transformer, { applyMask, contentBounds, copyArea, drawTransformed } from "../../transform/Transformer/index.js";
+import { boxBounds } from "../../transform/geometry/index.js";
+import Layer, { createOffscreenCanvas } from "../Layer/index.js";
+import LayerAutosave from "../LayerAutosave/index.js";
+import { brushPresets, eraserPresets } from "../../brushes/index.js";
+import { BUILT_IN_AUTHOR, UNKNOWN_AUTHOR, authorHandle } from "../../brushes/authors/index.js";
+import { BRUSH_PRESET_FILE_FORMAT } from "../../presets/schema.js";
+import CustomPresets from "../CustomPresets/index.js";
+import InputSettings from "../InputSettings/index.js";
+import ExternalSheets from "../ExternalSheets/index.js";
+import PatchSender from "../../messages/PatchSender/index.js";
+import { createPatchMessage, validateCanvasMessage } from "../../messages/index.js";
+import { REDO_EVENT, UNDO_EVENT } from "../History/index.js";
+import { CanvasMessageType } from "../../messages/schema.js";
+import { ImageEncoding, base64ToBytes, boundingBoxSize, bytesToBase64, decodeRgbaDeflate, encodeRgbaDeflate } from "../../image/index.js";
+import { drawLayers } from "../../rendering/compositing/index.js";
+import { DOCUMENT_FORMAT } from "../../document/schema.js";
+import { isValidDocument } from "../../document/index.js";
+import { averageColour, flattenArea, pixelRect, readPixels } from "../../rendering/sample/index.js";
+// src/lib/classes/PaintCanvas/index.ts
+/** Drawing and navigation tools */
+var Tool = /* @__PURE__ */ function(Tool) {
+	Tool["Brush"] = "brush";
+	Tool["Eraser"] = "eraser";
+	/** Move, scale and rotate */
+	Tool["Move"] = "move";
+	Tool["RectangleLasso"] = "rectangle-lasso";
+	Tool["CircleLasso"] = "circle-lasso";
+	Tool["PolygonLasso"] = "polygon-lasso";
+	Tool["FreeformLasso"] = "freeform-lasso";
+	Tool["Pan"] = "pan";
+	Tool["Zoom"] = "zoom";
+	/** Set the current colour from the canvas (eyedropper) */
+	Tool["ColourSample"] = "colour-sample";
+	return Tool;
+}({});
+/** Toggleable panels */
+var Panel = /* @__PURE__ */ function(Panel) {
+	Panel["Brush"] = "brush";
+	Panel["Eraser"] = "eraser";
+	Panel["Layers"] = "layers";
+	/** The implementer's own app menu */
+	Panel["Menu"] = "menu";
+	return Panel;
+}({});
+/** Panels opened by tools */
+var TOOL_PANELS = {
+	["brush"]: "brush",
+	["eraser"]: "eraser"
+};
+/** Canvas width and height when none is given */
+var DEFAULT_CANVAS_SIZE = 2e3;
+/** Largest canvas width or height allowed when the `maxCanvasSize` option isn't given */
+var MAX_CANVAS_SIZE = 2e3;
+/** Drawing colour to start with */
+var DEFAULT_COLOUR = "#000000";
+/** Owner of the custom presets when the `ownerId` option isn't given */
+var DEFAULT_OWNER_ID = "local";
+/** Author name of presets made with `newPreset` when the `presetAuthor` option isn't given */
+var DEFAULT_AUTHOR = UNKNOWN_AUTHOR;
+/** PaintCanvas's own names */
+var DEFAULT_NAMES = {
+	app: BUILT_IN_AUTHOR,
+	filePrefix: "paintcanvas",
+	presetFileFormat: BRUSH_PRESET_FILE_FORMAT,
+	unknownAuthor: UNKNOWN_AUTHOR
+};
+/** Pattern for colour input values */
+var COLOUR_PATTERN = /^#[0-9a-f]{6}$/i;
+/**
+* A canvas's pixels as a PNG data URL.
+*/
+var toPngDataUrl = async (canvas) => {
+	canvas.getContext("2d");
+	const blob = await canvas.convertToBlob({ type: "image/png" });
+	return `data:image/png;base64,${bytesToBase64(new Uint8Array(await blob.arrayBuffer()))}`;
+};
+/**
+* Decode a PNG data URL into an image.
+*/
+var fromPngDataUrl = (dataUrl) => createImageBitmap(new Blob([base64ToBytes(dataUrl.slice(dataUrl.indexOf(",") + 1))], { type: "image/png" }));
+/**
+* Decode a patch into pixels.
+*/
+var decodePatch = async (patch) => {
+	if (patch.encoding === ImageEncoding.Png) return createImageBitmap(new Blob([base64ToBytes(patch.data)], { type: "image/png" }));
+	const { width, height } = boundingBoxSize(patch.coords);
+	return new ImageData(await decodeRgbaDeflate(patch.data, patch.coords), width, height);
+};
+/**
+* The painting engine: canvas size, layers, brush and eraser settings, custom presets, the selected tool, colour,
+* selection, transforms, clipboard, undo/redo history, viewport and input settings. Where its data is kept and who it
+* is shared with are up to the implementer (see `onMessage` and `receive`).
+*
+* Dispatches a `change` event whenever its own state changes. Layers, brushes and selection dispatch their own `change`
+* events. Also dispatches `pointer` when the pointer moves over the canvas.
+*
+* @example
+* const canvas = new PaintCanvas({ width: 1000, height: 800 });
+* canvas.selectTool(Tool.Brush, { fromToolbar: true });
+* canvas.setColour("#ff0000");
+*/
+var PaintCanvas = class extends EventTarget {
+	/** Brush settings */
+	brush = new BrushSettings(brushPresets);
+	/** Eraser settings */
+	eraser = new BrushSettings(eraserPresets);
+	/** The user's own and imported brush presets, listed with the brush and eraser presets */
+	customPresets;
+	/** Lasso shape in progress */
+	lasso = new Lasso();
+	/** Brush shapes, loaded per preset */
+	tips = new BrushTipCache();
+	/** Log of strokes started, ended, cancelled and ignored, with timings, for debugging */
+	strokeLog = new StrokeLog();
+	/** Whether the debug log shows (see `showDebugLog`) */
+	debugLogShown = false;
+	/** Slow work that waits for pauses in drawing (syncing, the canvas map and layer thumbnails, saving) */
+	background = new BackgroundWork(this.strokeLog);
+	/** How the user's input devices control the canvas (scrolling, pinching, touch gestures, focus pen mode) */
+	input = new InputSettings();
+	/** The user's pointer position over the canvas, in canvas pixels (undefined when off the canvas) */
+	pointer;
+	/** Selected tool */
+	tool = "brush";
+	/** Tool used temporarily while a key is held (e.g. Space for pan), overriding the selected tool */
+	heldTool = null;
+	/** Open panel, if any */
+	panel = null;
+	/** Whether the interface (toolbar, panels and anything the implementer adds) is visible ("tab" key) */
+	interfaceVisible = true;
+	/**
+	* Whether scaling the Move tool's box keeps its proportions ("Constrain proportions"), from its settings bar and when
+	* dragging a handle. Off by default; while drag-scaling, holding Shift turns it on (when off) and Alt turns it off
+	* (when on), until released.
+	*/
+	constrainProportions = false;
+	/** How the colour sample tool samples ("point" by default) */
+	sampleMode = "point";
+	canvasWidth;
+	canvasHeight;
+	layerStack;
+	view;
+	strokeEngine;
+	currentSelection;
+	transformer;
+	onLayersOrMaskChange = () => {
+		const transformer = this.transformer;
+		if (!transformer.pending || transformer.layer !== this.layerStack.active) this.syncTransform();
+	};
+	onStrokeBegin = () => this.background.strokeStarted();
+	onStrokeEnd = () => this.background.strokeEnded();
+	onStrokeCommit = (event) => {
+		const { layer, area, stroke } = event.detail;
+		this.layerStack.recordImage(layer.id, area);
+		if (!this.sendingStrokes || this.replaying) return;
+		this.emit({
+			protocol: 1,
+			type: CanvasMessageType.Stroke,
+			step: this.history.latestStep ?? crypto.randomUUID(),
+			layer: layer.id,
+			...stroke
+		}).catch(() => void 0);
+	};
+	onHistoryStep = (event) => {
+		if (!this.isSending) return;
+		this.emit({
+			protocol: 1,
+			type: event.type === "undo" ? CanvasMessageType.Undo : CanvasMessageType.Redo,
+			step: event.detail.step
+		}).catch(() => void 0);
+	};
+	/** Whether drawing messages are sent (see `startSending`) */
+	isSending = false;
+	/** Whether finished strokes are sent (see `startSending`) */
+	sendingStrokes = false;
+	/** Whether a stroke from elsewhere is being drawn (it isn't sent again) */
+	replaying = false;
+	currentColour = DEFAULT_COLOUR;
+	/** Image data copied with cut or copy, and the area it was copied from */
+	clipboard;
+	/** Drawings from elsewhere */
+	externalSheets;
+	/** Who receives the drawing messages this canvas sends */
+	messageListeners = /* @__PURE__ */ new Set();
+	/** Sends patches while sending (see `startSending`) */
+	sender;
+	/** The layer stack whose changes are being sent */
+	sendingLayers;
+	onLayersChangeToSend = () => this.sender?.schedule();
+	/** Creates the canvases the app draws on (fake ones in tests) */
+	createCanvas;
+	/** Who the custom presets belong to (passed to the preset store) */
+	ownerId;
+	/** The largest canvas width or height allowed */
+	maxCanvasSize;
+	/** Most layers the user can have */
+	maxLayers;
+	/** Names users see and saved files are called by (see `PaintCanvasNames`) */
+	names;
+	/** Gives the author of presets made with `newPreset` */
+	presetAuthor;
+	/** Keeps the user's layers in a store, while one is used */
+	layerAutosave;
+	constructor(options = {}) {
+		super();
+		this.strokeLog.enabled = false;
+		this.ownerId = options.ownerId ?? "local";
+		this.maxCanvasSize = options.maxCanvasSize ?? 2e3;
+		this.maxLayers = options.maxLayers ?? 5;
+		this.names = {
+			...DEFAULT_NAMES,
+			...options.names
+		};
+		this.presetAuthor = options.presetAuthor ?? (() => ({ name: DEFAULT_AUTHOR }));
+		this.tips.preload(this.brush.presets);
+		this.tips.preload(this.eraser.presets);
+		this.customPresets = new CustomPresets(this.ownerId, options.presetStore);
+		this.customPresets.addEventListener("change", () => this.listCustomPresets());
+		this.customPresets.load().catch(() => void 0);
+		this.createCanvas = options.createCanvas ?? createOffscreenCanvas;
+		this.canvasWidth = DEFAULT_CANVAS_SIZE;
+		this.canvasHeight = DEFAULT_CANVAS_SIZE;
+		this.layerStack = new LayerStack(this.canvasWidth, this.canvasHeight, this.createCanvas, this.maxLayers);
+		this.view = new Viewport(this.canvasWidth, this.canvasHeight);
+		this.strokeEngine = new StrokeEngine(this.canvasWidth, this.canvasHeight, this.createCanvas);
+		this.currentSelection = new Selection(this.canvasWidth, this.canvasHeight, this.createCanvas);
+		this.transformer = new Transformer(this.canvasWidth, this.canvasHeight, this.createCanvas);
+		this.externalSheets = new ExternalSheets(this.canvasWidth, this.canvasHeight, this.createCanvas);
+		this.watchLayersAndMask();
+		if (options.width !== void 0 || options.height !== void 0) this.setCanvasSize(options.width ?? this.canvasWidth, options.height ?? this.canvasHeight);
+		if (options.layerStore) this.useLayerStore(options.layerStore);
+	}
+	/** Canvas width in pixels */
+	get width() {
+		return this.canvasWidth;
+	}
+	/** Canvas height in pixels */
+	get height() {
+		return this.canvasHeight;
+	}
+	/** Drawings from elsewhere (e.g. other people's), drawn under the user's own layers (see `receive`) */
+	get external() {
+		return this.externalSheets;
+	}
+	/** Everything drawn on the canvas, top first: the user's own layers, then drawings from elsewhere */
+	get drawables() {
+		return [...this.layerStack.layers, ...this.externalSheets.sheets];
+	}
+	/**
+	* Listen for the drawing messages this canvas sends, e.g. to pass them to other people. Returns a function that stops
+	* listening.
+	*
+	* @example
+	* const stop = canvas.onMessage((message) => transport.send(message));
+	* canvas.startSending();
+	*/
+	onMessage(listener) {
+		this.messageListeners.add(listener);
+		return () => this.messageListeners.delete(listener);
+	}
+	/**
+	* Give a message to every listener. Rejects if any listener's delivery fails.
+	*/
+	async emit(message) {
+		await Promise.all([...this.messageListeners].map((listener) => listener(message)));
+	}
+	/**
+	* Start sending drawing messages to `onMessage` listeners:
+	* - patches (by default): shortly after the user's layers change (and once drawing pauses), the area of their drawing
+	*   that changed
+	* - strokes (when asked): each finished brush or eraser stroke
+	* - undo and redo: the step undone or redone
+	*
+	* Changing the canvas size stops sending.
+	*/
+	startSending(options = {}) {
+		this.stopSending();
+		this.isSending = true;
+		this.sendingStrokes = options.strokes ?? false;
+		if (options.patches === false) return;
+		this.sender = new PatchSender({
+			width: this.canvasWidth,
+			height: this.canvasHeight,
+			layers: () => this.layerStack.layers,
+			createCanvas: this.createCanvas,
+			delayMs: options.delayMs,
+			whenIdle: (run) => this.background.run("sync", run),
+			send: (message) => this.emit(message)
+		});
+		this.sendingLayers = this.layerStack;
+		this.layerStack.addEventListener("change", this.onLayersChangeToSend);
+	}
+	/**
+	* Stop sending patches. Changes waiting to be sent are dropped.
+	*/
+	stopSending() {
+		this.isSending = false;
+		this.sendingStrokes = false;
+		this.sender?.stop();
+		this.sender = void 0;
+		this.sendingLayers?.removeEventListener("change", this.onLayersChangeToSend);
+		this.sendingLayers = void 0;
+	}
+	/** Whether drawing messages are being sent (see `startSending`) */
+	get sending() {
+		return this.isSending;
+	}
+	/**
+	* Send a patch of what changed now instead of waiting. Resolves once sent (or straight away when not sending
+	* patches).
+	*/
+	async sendNow() {
+		await this.sender?.sync();
+	}
+	/**
+	* Count pixels of the user's drawing as already sent, so they aren't sent again (e.g. their earlier work, restored
+	* from a shared drawing's history).
+	*/
+	markSent(area, rgba) {
+		this.sender?.markSent(area, rgba);
+	}
+	/**
+	* A patch of the user's whole drawing (all their layers, flattened), e.g. for someone who joins late. Undefined if
+	* nothing is drawn.
+	*/
+	async snapshot() {
+		const { canvasWidth: width, canvasHeight: height } = this;
+		const context = this.createCanvas(width, height).getContext("2d", { willReadFrequently: true });
+		drawLayers(context, this.layerStack.layers);
+		const rgba = context.getImageData(0, 0, width, height).data;
+		if (!rgba.some((value, i) => i % 4 === 3 && value > 0)) return void 0;
+		const coords = [
+			0,
+			0,
+			width,
+			height
+		];
+		return createPatchMessage(coords, ImageEncoding.RgbaDeflate, await encodeRgbaDeflate(rgba, coords));
+	}
+	/**
+	* Apply a drawing message received from a source (an ID the implementer chooses, e.g. a user ID): a patch is drawn
+	* onto that source's sheet. Messages are checked first; invalid ones are ignored. Resolves to whether it was applied.
+	*
+	* @example
+	* transport.onMessage((from, message) => canvas.receive(from, message));
+	*/
+	async receive(source, message) {
+		const result = validateCanvasMessage(message);
+		if (!result.valid) return false;
+		const valid = result.value;
+		if (valid.type === CanvasMessageType.Patch) {
+			await this.externalSheets.apply(source, valid);
+			return true;
+		}
+		if (valid.type === CanvasMessageType.Stroke) {
+			const { width, height } = this;
+			await this.externalSheets.paint(source, (canvas) => {
+				const sheetLayer = new Layer({ name: source }, width, height, () => canvas);
+				this.replay(new StrokeEngine(width, height, this.createCanvas), sheetLayer, valid);
+			});
+			return true;
+		}
+		this.dispatchEvent(new CustomEvent("history", { detail: {
+			source,
+			message: valid
+		} }));
+		return true;
+	}
+	/**
+	* The drawing as a document: its size, the user's layers and drawings from elsewhere, with PNG images (see
+	* `PaintCanvasDocument`). Turn it into JSON to save it as a file.
+	*
+	* @example
+	* const json = JSON.stringify(await canvas.exportDocument());
+	*/
+	async exportDocument() {
+		const layers = this.layerStack.layers;
+		return {
+			format: DOCUMENT_FORMAT,
+			version: 1,
+			width: this.canvasWidth,
+			height: this.canvasHeight,
+			layers: await Promise.all(layers.map(async (layer) => {
+				const { name, visible, opacity, blendMode, alphaLock } = layer.toConfig();
+				return {
+					name,
+					visible,
+					opacity,
+					blendMode,
+					alphaLock,
+					image: await toPngDataUrl(layer.canvas)
+				};
+			})),
+			activeLayer: layers.indexOf(this.layerStack.active),
+			external: await Promise.all(this.externalSheets.sheets.map(async ({ source, canvas }) => ({
+				source,
+				image: await toPngDataUrl(canvas)
+			})))
+		};
+	}
+	/**
+	* Replace the drawing with a document (e.g. read from a file): its size, layers and drawings from elsewhere. Undo
+	* history starts again. Returns whether it was loaded: not when the document is invalid or an image can't be
+	* decoded, and then nothing changes.
+	*
+	* @example
+	* await canvas.importDocument(JSON.parse(text));
+	*/
+	async importDocument(document) {
+		const result = isValidDocument(document);
+		if (!result.valid || result.value.layers.length > this.maxLayers) return false;
+		const doc = result.value;
+		const images = await Promise.all([...doc.layers.map((layer) => fromPngDataUrl(layer.image)), ...doc.external.map((sheet) => fromPngDataUrl(sheet.image))]).catch(() => void 0);
+		if (!images) return false;
+		const configs = doc.layers.map(({ name, visible, opacity, blendMode, alphaLock }) => ({
+			id: crypto.randomUUID(),
+			name,
+			visible,
+			opacity,
+			blendMode,
+			alphaLock
+		}));
+		this.restoreLayers(doc.width, doc.height, configs, images, configs[doc.activeLayer].id);
+		doc.external.forEach((sheet, i) => this.externalSheets.restore(sheet.source, images[configs.length + i]));
+		return true;
+	}
+	/**
+	* Replace the canvas size and the user's layers (top first, each with its image) and select one by ID. Undo history
+	* starts again. Throws if the size or number of layers isn't allowed.
+	*
+	* @example
+	* canvas.restoreLayers(800, 600, [{ id: "a", name: "Sketch" }], [sketchImage], "a");
+	*/
+	restoreLayers(width, height, layers, images, activeLayer) {
+		if (layers.length > this.maxLayers) throw new Error(`Cannot have more than ${this.maxLayers} layers`);
+		this.setCanvasSize(width, height);
+		this.layerStack.replace(layers).forEach((layer, i) => layer.context.drawImage(images[i], 0, 0));
+		this.layerStack.select(activeLayer);
+		this.history.clear();
+	}
+	/** Keeps the user's layers in a store, while one is used (see `useLayerStore`) */
+	get autosave() {
+		return this.layerAutosave;
+	}
+	/**
+	* Keep the user's layers in a store (or stop, without one), so the drawing survives reloading the page: the saved
+	* drawing is restored, then changes are saved. Only one window draws on a drawing at a time (see `LayerAutosave`).
+	* Returns the autosave.
+	*
+	* @example
+	* canvas.useLayerStore(new IndexedDbLayerStore("my-drawing"));
+	*/
+	useLayerStore(store, options) {
+		this.layerAutosave?.stop();
+		this.layerAutosave = store ? new LayerAutosave(this, store, options) : void 0;
+		this.layerAutosave?.start();
+		this.notify();
+		return this.layerAutosave;
+	}
+	/**
+	* How much the canvas holds: its size, layers, drawings from elsewhere, memory and undo steps.
+	*/
+	stats() {
+		const sheets = this.layerStack.layers.length + this.externalSheets.sheets.length;
+		return {
+			width: this.canvasWidth,
+			height: this.canvasHeight,
+			layers: this.layerStack.layers.length,
+			externalSheets: this.externalSheets.sheets.length,
+			memoryBytes: this.canvasWidth * this.canvasHeight * 4 * sheets,
+			historySteps: this.history.size,
+			historyLimit: this.history.limit
+		};
+	}
+	/**
+	* Draw a recorded stroke (e.g. received from elsewhere) onto one of the user's layers, as an action they can undo.
+	* It isn't sent as a stroke message. Does nothing during a stroke, or if there's no such layer. Returns whether it was
+	* drawn.
+	*
+	* @example
+	* canvas.drawStroke(canvas.layers.active.id, strokeMessage);
+	*/
+	drawStroke(layerId, stroke) {
+		const layer = this.layerStack.layers.find((existing) => existing.id === layerId);
+		if (!layer || this.strokeEngine.drawing || stroke.points.length === 0) return false;
+		this.replaying = true;
+		try {
+			this.replay(this.strokeEngine, layer, stroke);
+		} finally {
+			this.replaying = false;
+		}
+		return true;
+	}
+	/**
+	* Draw a recorded stroke with a stroke engine, point by point.
+	*/
+	replay(engine, layer, stroke) {
+		const [first, ...rest] = stroke.points;
+		engine.begin({
+			layer,
+			mode: stroke.mode,
+			preset: stroke.preset,
+			size: stroke.size,
+			colour: stroke.colour,
+			tip: this.tips.get(stroke.preset),
+			isPen: stroke.isPen,
+			seed: stroke.seed
+		}, first, first.time);
+		const last = rest.pop() ?? first;
+		for (const point of rest) engine.move(point, point.time);
+		engine.end(last, last.time);
+	}
+	/**
+	* Put a patch's pixels onto one of the user's layers (replacing what was there), as an action they can undo. Returns
+	* whether it was applied: not for an invalid patch, or if there's no such layer.
+	*
+	* @example
+	* await canvas.applyPatch(canvas.layers.active.id, patch);
+	*/
+	async applyPatch(layerId, patch) {
+		const result = validateCanvasMessage(patch);
+		if (!result.valid || result.value.type !== CanvasMessageType.Patch) return false;
+		const valid = result.value;
+		const image = await decodePatch(valid).catch(() => void 0);
+		const layer = this.layerStack.layers.find((existing) => existing.id === layerId);
+		if (!image || !layer) return false;
+		const [x, y] = valid.coords;
+		const { width, height } = boundingBoxSize(valid.coords);
+		this.layerStack.changeImage(layer.id, {
+			x,
+			y,
+			width,
+			height
+		}, (ctx) => {
+			ctx.clearRect(x, y, width, height);
+			if (image instanceof ImageData) ctx.putImageData(image, x, y);
+			else ctx.drawImage(image, x, y);
+		});
+		return true;
+	}
+	/**
+	* The colour shown at a canvas point (every layer mixed as shown, over the white background), or undefined outside the
+	* canvas.
+	*
+	* @example
+	* app.sampleColour({ x: 10.4, y: 20.9 }); // "#ff0000"
+	*/
+	sampleColour(point) {
+		const area = pixelRect(point, point, this.width, this.height);
+		if (!area) return void 0;
+		return averageColour(readPixels(this.flatten(area)));
+	}
+	/**
+	* The average colour shown in the rectangle between two canvas points (cut to the canvas), counting every pixel, or
+	* undefined outside the canvas. With `maxPixels`, it's worked out from the area scaled down to at most that many
+	* pixels across, which is quicker (for a preview while dragging).
+	*
+	* @example
+	* app.sampleAreaColour({ x: 0, y: 0 }, { x: 99, y: 99 }); // the average of 100 × 100 pixels
+	*/
+	sampleAreaColour(a, b, maxPixels = Number.POSITIVE_INFINITY) {
+		const area = pixelRect(a, b, this.width, this.height);
+		if (!area) return void 0;
+		const scale = Math.min(1, maxPixels / Math.max(area.width, area.height));
+		return averageColour(readPixels(this.flatten(area, Math.max(1, Math.round(area.width * scale)), Math.max(1, Math.round(area.height * scale)))));
+	}
+	/**
+	* The `SAMPLE_PIXELS` × `SAMPLE_PIXELS` canvas pixels around a point as shown (the point's pixel is at the middle,
+	* rounding down), for the colour sample tool's enlarged view. Pixels outside the canvas are transparent.
+	*/
+	samplePixels(point) {
+		const half = 5;
+		return this.flatten({
+			x: Math.floor(point.x) - half,
+			y: Math.floor(point.y) - half,
+			width: 10,
+			height: 10
+		});
+	}
+	/** Draw an area of the canvas as shown onto a new canvas (see `flattenArea`) */
+	flatten(area, width, height) {
+		return flattenArea(this.drawables, this.createCanvas, this.width, this.height, area, width, height);
+	}
+	/** The user's view of the canvas (zoom and position) */
+	get viewport() {
+		return this.view;
+	}
+	/** Whether the debug log shows */
+	get debugLog() {
+		return this.debugLogShown;
+	}
+	/**
+	* Show or hide the debug log. Strokes and timings are only recorded while it shows.
+	*/
+	showDebugLog(shown) {
+		this.debugLogShown = shown;
+		this.strokeLog.enabled = shown;
+		this.notify();
+	}
+	/** Draws brush and eraser strokes */
+	get strokes() {
+		return this.strokeEngine;
+	}
+	/** The mask limiting where drawing applies */
+	get selection() {
+		return this.currentSelection;
+	}
+	/** Moves, scales and rotates the active layer's pixels with the Move tool */
+	get transform() {
+		return this.transformer;
+	}
+	/** The user's undoable actions */
+	get history() {
+		return this.layerStack.history;
+	}
+	/**
+	* Listen for layer and mask changes on the current layer stack and selection, and for strokes starting and ending
+	* (background work waits for pauses in drawing).
+	*/
+	watchLayersAndMask() {
+		this.layerStack.addEventListener("change", this.onLayersOrMaskChange);
+		this.currentSelection.addEventListener("change", this.onLayersOrMaskChange);
+		this.strokeEngine.addEventListener(BEFORE_COMMIT_EVENT, this.onStrokeCommit);
+		this.strokeEngine.addEventListener(STROKE_BEGIN_EVENT, this.onStrokeBegin);
+		this.strokeEngine.addEventListener(STROKE_END_EVENT, this.onStrokeEnd);
+		this.history.addEventListener(UNDO_EVENT, this.onHistoryStep);
+		this.history.addEventListener(REDO_EVENT, this.onHistoryStep);
+	}
+	/**
+	* Show the transform box when the Move tool is selected, and apply any transform when switching away or to another layer.
+	*/
+	syncTransform() {
+		const transformer = this.transformer;
+		if (this.tool !== "move") {
+			if (transformer.pending) this.commitTransform();
+			else if (transformer.active) {
+				transformer.reset();
+				transformer.dispatchEvent(new Event("change"));
+			}
+			return;
+		}
+		if (transformer.pending && transformer.layer === this.layerStack.active) return;
+		if (transformer.pending) this.commitTransform();
+		transformer.prepare(this.layerStack.active, this.currentSelection.mask);
+	}
+	/**
+	* Write the transformed pixels into the layer (Enter, or switching tool). The mask moves with them.
+	*/
+	commitTransform() {
+		const layer = this.transformer.layer;
+		const result = this.transformer.commit();
+		if (!layer || !result) return;
+		const { maskPiece, source, box, area, before } = result;
+		this.layerStack.recordImage(layer.id, area, before);
+		if (maskPiece) this.currentSelection.moveArea(maskPiece, source, boxBounds(box), (ctx) => drawTransformed(ctx, maskPiece, box));
+		this.layerStack.markChanged(layer.id);
+	}
+	/**
+	* Undo the user's latest action. A move or rotate that hasn't been applied is cancelled instead, and nothing happens
+	* during a stroke.
+	*/
+	undo() {
+		if (this.canStepHistory()) this.history.undo();
+	}
+	/**
+	* Redo the user's latest undone action. A move or rotate that hasn't been applied is cancelled instead, and nothing
+	* happens during a stroke.
+	*/
+	redo() {
+		if (this.canStepHistory()) this.history.redo();
+	}
+	/**
+	* Whether undo or redo can move along the history now: not during a stroke, and not while a transform is pending (which
+	* is cancelled instead).
+	*/
+	canStepHistory() {
+		if (this.strokeEngine.drawing) return false;
+		if (!this.transformer.pending) return true;
+		this.cancelTransform();
+		return false;
+	}
+	/**
+	* Put transformed pixels back where they were (Escape).
+	*/
+	cancelTransform() {
+		const pasting = this.transformer.pasting;
+		this.transformer.cancel();
+		if (pasting) this.syncTransform();
+	}
+	/**
+	* Copy the masked image data of the selected layer to the clipboard. Needs a mask with image data inside it; does
+	* nothing during a stroke or while a transform is pending. Returns the area copied, if any.
+	*/
+	copy() {
+		const area = this.maskedArea();
+		const mask = this.currentSelection.mask;
+		if (!area || !mask) return void 0;
+		const layer = this.layerStack.active;
+		const image = copyArea(this.createCanvas, layer.canvas, area);
+		applyMask(image, copyArea(this.createCanvas, mask, area));
+		this.clipboard = {
+			image,
+			area
+		};
+		return area;
+	}
+	/**
+	* Copy the masked image data of the selected layer to the clipboard, then erase it from the layer as one undoable
+	* action.
+	*/
+	cut() {
+		const area = this.copy();
+		if (area) this.eraseMasked(area);
+	}
+	/**
+	* Erase the masked image data from the selected layer as one undoable action (Delete or Backspace). Needs a mask with
+	* image data inside it; does nothing during a stroke or while a transform is pending.
+	*/
+	deleteMasked() {
+		const area = this.maskedArea();
+		if (area) this.eraseMasked(area);
+	}
+	/**
+	* 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.
+	*/
+	maskedArea() {
+		const mask = this.currentSelection.mask;
+		if (!mask || this.strokeEngine.drawing || this.transformer.pending) return void 0;
+		const { width, height } = this;
+		return contentBounds(this.layerStack.active.context.getImageData(0, 0, width, height).data, width, height, mask.getContext("2d").getImageData(0, 0, width, height).data);
+	}
+	/**
+	* Erase the mask's part of an area from the selected layer, as one undoable action.
+	*/
+	eraseMasked(area) {
+		const mask = this.currentSelection.mask;
+		const maskPiece = copyArea(this.createCanvas, mask, area);
+		this.layerStack.changeImage(this.layerStack.active.id, area, (ctx) => {
+			ctx.save();
+			ctx.globalCompositeOperation = "destination-out";
+			ctx.drawImage(maskPiece, area.x, area.y);
+			ctx.restore();
+		});
+	}
+	/**
+	* Show the clipboard's image data over the selected layer where it was copied from, and select the Move tool to place,
+	* scale and rotate it. It is written into the layer (and sent) on Enter or when switching to another tool; Escape
+	* discards it. A pending transform is applied first.
+	*/
+	paste() {
+		const clipboard = this.clipboard;
+		if (!clipboard || this.strokeEngine.drawing) return;
+		if (this.transformer.pending) this.commitTransform();
+		this.selectTool("move");
+		this.transformer.float(this.layerStack.active, clipboard.image, clipboard.area);
+	}
+	/**
+	* Apply a finished lasso action to the mask: a shape is added, subtracted or replaces it; a plain click deselects.
+	*/
+	applyLasso(result) {
+		if (!result) return;
+		if ("deselect" in result) this.currentSelection.clear();
+		else this.currentSelection.apply(result.shape, result.mode);
+	}
+	/**
+	* Whether a preset comes with the app (it can't be deleted, replaced or exported).
+	*/
+	isBuiltInPreset(id) {
+		return Object.hasOwn(brushPresets, id);
+	}
+	/**
+	* The handle of the author of presets the user makes (from the `presetAuthor` option), or "" if they have none. Their
+	* own presets are the ones with this handle (see `isOwnAuthor`).
+	*/
+	get authorHandle() {
+		return authorHandle(this.presetAuthor()) ?? "";
+	}
+	/**
+	* Make a new custom preset from settings: a new ID, the given name, and the author from the `presetAuthor` option.
+	*
+	* @example
+	* app.newPreset(app.brush.preset, "My brush"); // { ...settings, id: "0b5c…", name: "My brush", author: { name, handle } }
+	*/
+	newPreset(settings, name) {
+		const copy = structuredClone(settings);
+		delete copy.group;
+		return {
+			...copy,
+			id: crypto.randomUUID(),
+			name: name.trim(),
+			version: "1.0.0",
+			author: this.presetAuthor()
+		};
+	}
+	/**
+	* List the custom presets after the built-in ones, for the brush and the eraser.
+	*/
+	listCustomPresets() {
+		const custom = Object.fromEntries(this.customPresets.presets.map((preset) => [preset.id, preset]));
+		this.brush.setPresets({
+			...brushPresets,
+			...custom
+		});
+		this.eraser.setPresets({
+			...eraserPresets,
+			...custom
+		});
+		this.tips.preload(custom);
+	}
+	/** The tool currently in effect: the held tool if a key is held, otherwise the selected tool */
+	get activeTool() {
+		return this.heldTool ?? this.tool;
+	}
+	/** The user's layers */
+	get layers() {
+		return this.layerStack;
+	}
+	/** Current drawing colour as a hex string, e.g. `#000000` */
+	get colour() {
+		return this.currentColour;
+	}
+	/**
+	* Set the drawing colour. Must be a 6-digit hex colour, e.g. `#ff0000`.
+	*/
+	setColour(colour) {
+		if (!COLOUR_PATTERN.test(colour)) throw new Error(`Invalid colour ${colour}`);
+		this.currentColour = colour.toLowerCase();
+		this.notify();
+	}
+	/**
+	* Change the canvas size, from 1 to the maximum canvas size (`maxCanvasSize` option). Replaces all layers.
+	*/
+	setCanvasSize(width, height) {
+		if (!this.isValidCanvasDimension(width) || !this.isValidCanvasDimension(height)) throw new Error(`Canvas size must be whole numbers from 1 to ${this.maxCanvasSize}`);
+		this.canvasWidth = width;
+		this.canvasHeight = height;
+		this.history.removeEventListener(UNDO_EVENT, this.onHistoryStep);
+		this.history.removeEventListener(REDO_EVENT, this.onHistoryStep);
+		this.layerStack.removeEventListener("change", this.onLayersOrMaskChange);
+		this.currentSelection.removeEventListener("change", this.onLayersOrMaskChange);
+		this.strokeEngine.removeEventListener(BEFORE_COMMIT_EVENT, this.onStrokeCommit);
+		this.strokeEngine.removeEventListener(STROKE_BEGIN_EVENT, this.onStrokeBegin);
+		this.strokeEngine.removeEventListener(STROKE_END_EVENT, this.onStrokeEnd);
+		this.layerStack = new LayerStack(width, height, this.createCanvas, this.maxLayers);
+		this.view = new Viewport(width, height);
+		this.strokeEngine = new StrokeEngine(width, height, this.createCanvas);
+		this.currentSelection = new Selection(width, height, this.createCanvas);
+		this.transformer = new Transformer(width, height, this.createCanvas);
+		this.stopSending();
+		this.externalSheets.resize(width, height);
+		this.canvasResized(width, height);
+		this.clipboard = void 0;
+		this.watchLayersAndMask();
+		this.notify();
+	}
+	/**
+	* Called when the canvas size changes, before `change` is dispatched. Subclasses resize anything of their own here.
+	*/
+	canvasResized(width, height) {}
+	/**
+	* Check a canvas dimension is a whole number from 1 to the maximum canvas size.
+	*/
+	isValidCanvasDimension(value) {
+		return Number.isInteger(value) && value >= 1 && value <= this.maxCanvasSize;
+	}
+	/**
+	* Set whether scaling the Move tool's box keeps its proportions.
+	*/
+	setConstrainProportions(constrain) {
+		this.constrainProportions = constrain;
+		this.notify();
+	}
+	/**
+	* Set how the colour sample tool samples.
+	*/
+	setSampleMode(mode) {
+		this.sampleMode = mode;
+		this.notify();
+	}
+	/**
+	* Set where the user's pointer is over the canvas (undefined when it leaves). Dispatches `pointer` when it moves.
+	*/
+	setPointer(position) {
+		if (position?.x === this.pointer?.x && position?.y === this.pointer?.y) return;
+		this.pointer = position ? {
+			x: position.x,
+			y: position.y
+		} : void 0;
+		this.dispatchEvent(new Event("pointer"));
+	}
+	/**
+	* Select a tool.
+	*
+	* - Clicking a toolbar button (`fromToolbar: true`) only selects the tool: its presets open from the settings bar's
+	*   preset button.
+	* - Pressing a tool's shortcut selects the tool, or toggles its panel if the tool is already selected.
+	*
+	* Switching tools closes the previous tool's panel (the layers panel and app menu stay open).
+	*/
+	selectTool(tool, options = {}) {
+		const toolPanel = TOOL_PANELS[tool];
+		const alreadySelected = this.tool === tool;
+		this.tool = tool;
+		if (toolPanel && alreadySelected && !options.fromToolbar) this.panel = this.panel === toolPanel ? null : toolPanel;
+		else if (!alreadySelected && this.panel !== "layers" && this.panel !== "menu") this.panel = null;
+		this.syncTransform();
+		this.notify();
+	}
+	/**
+	* Use a tool temporarily while a key is held (e.g. Space for pan). The selected tool is unchanged.
+	*/
+	holdTool(tool) {
+		if (this.heldTool === tool) return;
+		this.heldTool = tool;
+		this.notify();
+	}
+	/**
+	* Stop using the held tool and return to the selected tool.
+	*/
+	releaseHeldTool() {
+		if (this.heldTool === null) return;
+		this.heldTool = null;
+		this.notify();
+	}
+	/**
+	* Close the open panel, if any.
+	*/
+	closePanel() {
+		if (this.panel === null) return;
+		this.panel = null;
+		this.notify();
+	}
+	/**
+	* Open a panel, or close it if already open.
+	*/
+	togglePanel(panel) {
+		this.panel = this.panel === panel ? null : panel;
+		this.notify();
+	}
+	/**
+	* Show or hide the interface.
+	*/
+	toggleInterface() {
+		this.interfaceVisible = !this.interfaceVisible;
+		this.notify();
+	}
+	/**
+	* Dispatch a `change` event.
+	*/
+	notify() {
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { DEFAULT_AUTHOR, DEFAULT_CANVAS_SIZE, DEFAULT_COLOUR, DEFAULT_NAMES, DEFAULT_OWNER_ID, MAX_CANVAS_SIZE, Panel, TOOL_PANELS, Tool, PaintCanvas as default };