@lvl99dotcom/paintcanvas 0.3.1 → 0.5.0

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

@@ -1,4 +1,6 @@
 import StrokeLog from "../StrokeLog";
+import { Tool } from "./tool";
+import { isHexColour } from "../../utils/colour";
 import BackgroundWork from "../BackgroundWork";
 import type { DrawableLayer } from "../../rendering/compositing";
 import BrushSettings from "../BrushSettings";
@@ -16,25 +18,14 @@ import type { LayerStoreLike } from "../../storage";
 import type { AssetAuthor, BrushConfig } from "../../brushes/types";
 import CustomPresets, { type PresetStoreLike } from "../CustomPresets";
 import InputSettings from "../InputSettings";
+import UiSettings from "../UiSettings";
+import Palette from "../Palette";
+import ShortcutSettings from "../ShortcutSettings";
 import ExternalSheets from "../ExternalSheets";
 import { type CanvasMessage, type PatchMessage, type StrokeMessage } from "../../messages";
 import { type BoundingBox } from "../../image";
 import { type PaintCanvasDocument } from "../../document";
-/** Drawing and navigation tools */
-export declare enum Tool {
-    Brush = "brush",
-    Eraser = "eraser",
-    /** Move, scale and rotate */
-    Move = "move",
-    RectangleLasso = "rectangle-lasso",
-    CircleLasso = "circle-lasso",
-    PolygonLasso = "polygon-lasso",
-    FreeformLasso = "freeform-lasso",
-    Pan = "pan",
-    Zoom = "zoom",
-    /** Set the current colour from the canvas (eyedropper) */
-    ColourSample = "colour-sample"
-}
+export { Tool };
 /** How the colour sample tool samples: the pixel under the pointer, or the average of a dragged rectangle */
 export type SampleMode = "point" | "area";
 /** Toggleable panels */
@@ -43,7 +34,9 @@ export declare enum Panel {
     Eraser = "eraser",
     Layers = "layers",
     /** The implementer's own app menu */
-    Menu = "menu"
+    Menu = "menu",
+    /** The colour palette: the foreground and background colours, their values and the saved colours */
+    Palette = "palette"
 }
 /** Panels opened by tools */
 export declare const TOOL_PANELS: Partial<Record<Tool, Panel>>;
@@ -51,8 +44,15 @@ export declare const TOOL_PANELS: Partial<Record<Tool, Panel>>;
 export declare const DEFAULT_CANVAS_SIZE = 2000;
 /** Largest canvas width or height allowed when the `maxCanvasSize` option isn't given */
 export declare const MAX_CANVAS_SIZE = 2000;
-/** Drawing colour to start with */
+/** Foreground colour to start with */
 export declare const DEFAULT_COLOUR = "#000000";
+/** Background colour to start with */
+export declare const DEFAULT_BACKGROUND_COLOUR = "#ffffff";
+/**
+ * One of the two colours: the foreground colour (painted by the brush and foreground fills) or the background colour
+ * (painted by the eraser and Delete when the layer's alpha lock is on, and by background fills).
+ */
+export type ColourSlot = "foreground" | "background";
 /** Owner of the custom presets when the `ownerId` option isn't given */
 export declare const DEFAULT_OWNER_ID = "local";
 /** Author name of presets made with `newPreset` when the `presetAuthor` option isn't given */
@@ -65,11 +65,16 @@ export interface PaintCanvasNames {
     filePrefix: string;
     /** The `format` written in exported brush preset files */
     presetFileFormat: string;
+    /** The `format` written in exported colour palette files */
+    paletteFileFormat: string;
+    /** The `format` written in exported settings files */
+    settingsFileFormat: string;
     /** Author name of presets made by a user without a handle, e.g. from `presetAuthor` */
     unknownAuthor: string;
 }
 /** PaintCanvas's own names */
 export declare const DEFAULT_NAMES: Readonly<PaintCanvasNames>;
+export { isHexColour };
 /** How much the canvas holds, e.g. to show in a stats panel */
 export interface CanvasStats {
     /** Canvas width in pixels */
@@ -121,9 +126,16 @@ export interface PaintCanvasOptions {
     names?: Partial<PaintCanvasNames>;
     /** Where to keep the user's layers so the drawing survives reloading the page (see `useLayerStore`) */
     layerStore?: LayerStoreLike;
+    /**
+     * The system clipboard, which copying and cutting also put a PNG of the copied image data on so other apps (and brush
+     * shapes) can use it (the browser's by default; `null` for none)
+     */
+    systemClipboard?: SystemClipboardLike | null;
 }
+/** The part of the system clipboard PaintCanvas writes to (the browser's `navigator.clipboard`) */
+export type SystemClipboardLike = Pick<Clipboard, "write">;
 /**
- * The painting engine: canvas size, layers, brush and eraser settings, custom presets, the selected tool, colour,
+ * The painting engine: canvas size, layers, brush and eraser settings, custom presets, the selected tool, foreground and background colours,
  * 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`).
  *
@@ -134,6 +146,7 @@ export interface PaintCanvasOptions {
  * const canvas = new PaintCanvas({ width: 1000, height: 800 });
  * canvas.selectTool(Tool.Brush, { fromToolbar: true });
  * canvas.setColour("#ff0000");
+ * canvas.setColour("#ffffff", "background");
  */
 export default class PaintCanvas extends EventTarget {
     /** Brush settings */
@@ -154,6 +167,12 @@ export default class PaintCanvas extends EventTarget {
     readonly background: BackgroundWork;
     /** How the user's input devices control the canvas (scrolling, pinching, touch gestures, focus pen mode) */
     readonly input: InputSettings;
+    /** The user's interface choices (theme and language), kept with the other app settings */
+    readonly ui: UiSettings;
+    /** The user's saved colours, shown as swatches */
+    readonly palette: Palette;
+    /** 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) */
     pointer?: Point;
     /** Selected tool */
@@ -190,9 +209,14 @@ export default class PaintCanvas extends EventTarget {
     private sendingStrokes;
     /** Whether a stroke from elsewhere is being drawn (it isn't sent again) */
     private replaying;
-    private currentColour;
+    private currentColours;
+    private currentSelectedColour;
     /** Image data copied with cut or copy, and the area it was copied from */
     private clipboard?;
+    /** How many times image data has been copied (see `copyCount`) */
+    private copies;
+    /** The system clipboard copies are also put on, if any */
+    private readonly systemClipboard?;
     /** Drawings from elsewhere */
     private externalSheets;
     /** Who receives the drawing messages this canvas sends */
@@ -416,30 +440,83 @@ export default class PaintCanvas extends EventTarget {
      */
     copy(): Rect | undefined;
     /**
-     * Copy the masked image data of the selected layer to the clipboard, then erase it from the layer as one undoable
-     * action.
+     * 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`).
+     */
+    get copyCount(): number;
+    /** Whether there is copied image data to paste (see `copy` and `cut`) */
+    get hasClipboard(): boolean;
+    /**
+     * The copied image data as a PNG, if there is any (e.g. to use as a brush shape).
+     *
+     * @example
+     * const png = await canvas.copiedPng(); // Blob of type "image/png", or undefined
+     */
+    copiedPng(): Promise<Blob | undefined>;
+    /**
+     * Put copied image data on the system clipboard as a PNG, if there is one and the browser can. The item is made
+     * straight away (some browsers only allow writing while handling the key press or click) with the PNG to follow.
+     * Failing (e.g. the page isn't focused) changes nothing: the image data can still be pasted here.
+     */
+    private writeSystemClipboard;
+    /**
+     * Copy the masked image data of the selected layer to the clipboard, then remove it from the layer as one undoable
+     * action (see `deleteMasked`).
      */
     cut(): void;
     /**
-     * Erase the masked image data from the selected layer as one undoable action (Delete or Backspace). Needs a mask with
+     * Erase the masked image data from the selected layer as one undoable action (Delete or Backspace). When the layer's
+     * alpha lock is on, it is painted with the background colour instead, keeping its transparency. Needs a mask with
      * image data inside it; does nothing during a stroke or while a transform is pending.
      */
     deleteMasked(): void;
+    /**
+     * Fill the selected layer with the foreground or background colour as one undoable action: only the masked area when
+     * there is a mask (partly where it is partly), and only existing pixels when the layer's alpha lock is on. Does
+     * nothing during a stroke or while a transform is pending.
+     *
+     * @example
+     * canvas.fill("foreground");
+     */
+    fill(slot: ColourSlot): void;
+    /**
+     * The area a fill changes: the mask's bounds (or the whole canvas without a mask), cut to the selected layer's image
+     * data when its alpha lock is on. None if that is empty.
+     */
+    private fillArea;
     /**
      * 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.
      */
     private maskedArea;
     /**
-     * Erase the mask's part of an area from the selected layer, as one undoable action.
+     * Erase the mask's part of an area from the selected layer, or paint it with the background colour when the layer's
+     * alpha lock is on, as one undoable action.
+     */
+    private clearMasked;
+    /**
+     * Paint a colour over an area of the selected layer, cut to the mask if there is one (partly where it is partly), as
+     * one undoable action. Only existing pixels are painted when the layer's alpha lock is on.
      */
-    private eraseMasked;
+    private paintArea;
     /**
      * 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(): void;
+    /**
+     * Show an image from elsewhere (e.g. pasted from another app) over the selected layer, in the middle of the part of
+     * the canvas in view, and select the Move tool to place, scale and rotate it, like `paste`. An image larger than the
+     * canvas is shrunk to fit it. Does nothing during a stroke.
+     *
+     * @example
+     * canvas.pasteImage(await createImageBitmap(file));
+     */
+    pasteImage(source: CanvasImageSource & {
+        width: number;
+        height: number;
+    }): void;
     /**
      * Apply a finished lasso action to the mask: a shape is added, subtracted or replaces it; a plain click deselects.
      */
@@ -468,12 +545,31 @@ export default class PaintCanvas extends EventTarget {
     get activeTool(): Tool;
     /** The user's layers */
     get layers(): LayerStack;
-    /** Current drawing colour as a hex string, e.g. `#000000` */
+    /** Current foreground colour as a hex string, e.g. `#000000` (the same as `colours.foreground`) */
     get colour(): string;
+    /** Current foreground and background colours as hex strings, e.g. `{ foreground: "#000000", background: "#ffffff" }` */
+    get colours(): Readonly<Record<ColourSlot, string>>;
+    /** Which colour is selected for configuration, e.g. by a colour picker or the colour sample tool ("foreground" by default) */
+    get selectedColour(): ColourSlot;
+    /**
+     * Set the foreground colour, or the background colour. Must be a 6-digit hex colour, e.g. `#ff0000`.
+     *
+     * @example
+     * canvas.setColour("#ff0000"); // foreground
+     * canvas.setColour("#ffffff", "background");
+     */
+    setColour(colour: string, slot?: ColourSlot): void;
+    /**
+     * Select which colour is configured, e.g. by a colour picker or the colour sample tool. One colour is always selected.
+     *
+     * @example
+     * canvas.selectColour("background");
+     */
+    selectColour(slot: ColourSlot): void;
     /**
-     * Set the drawing colour. Must be a 6-digit hex colour, e.g. `#ff0000`.
+     * Swap the foreground and background colours. The selected colour stays the same slot.
      */
-    setColour(colour: string): void;
+    swapColours(): void;
     /**
      * Change the canvas size, from 1 to the maximum canvas size (`maxCanvasSize` option). Replaces all layers.
      */

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

@@ -1,4 +1,6 @@
 import StrokeLog from "../StrokeLog/index.js";
+import { Tool } from "./tool.js";
+import { isHexColour } from "../../utils/colour/index.js";
 import BackgroundWork from "../BackgroundWork/index.js";
 import BrushSettings from "../BrushSettings/index.js";
 import LayerStack from "../LayerStack/index.js";
@@ -17,6 +19,12 @@ import "../../presets/index.js";
 import CustomPresets from "../CustomPresets/index.js";
 import { BRUSH_PRESET_FILE_FORMAT } from "../../presets/schema.js";
 import InputSettings from "../InputSettings/index.js";
+import UiSettings from "../UiSettings/index.js";
+import Palette from "../Palette/index.js";
+import ShortcutSettings from "../ShortcutSettings/index.js";
+import { PALETTE_FILE_FORMAT } from "../../palette/schema.js";
+import "../../palette/index.js";
+import { SETTINGS_FILE_FORMAT } from "../../settings/schema.js";
 import ExternalSheets from "../ExternalSheets/index.js";
 import PatchSender from "../../messages/PatchSender/index.js";
 import { createPatchMessage, validateCanvasMessage } from "../../messages/index.js";
@@ -28,22 +36,6 @@ 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";
@@ -51,19 +43,23 @@ var Panel = /* @__PURE__ */ function(Panel) {
 	Panel["Layers"] = "layers";
 	/** The implementer's own app menu */
 	Panel["Menu"] = "menu";
+	/** The colour palette: the foreground and background colours, their values and the saved colours */
+	Panel["Palette"] = "palette";
 	return Panel;
 }({});
 /** Panels opened by tools */
 var TOOL_PANELS = {
-	["brush"]: "brush",
-	["eraser"]: "eraser"
+	[Tool.Brush]: "brush",
+	[Tool.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 */
+/** Foreground colour to start with */
 var DEFAULT_COLOUR = "#000000";
+/** Background colour to start with */
+var DEFAULT_BACKGROUND_COLOUR = "#ffffff";
 /** 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 */
@@ -73,10 +69,10 @@ var DEFAULT_NAMES = {
 	app: BUILT_IN_AUTHOR,
 	filePrefix: "paintcanvas",
 	presetFileFormat: BRUSH_PRESET_FILE_FORMAT,
+	paletteFileFormat: PALETTE_FILE_FORMAT,
+	settingsFileFormat: SETTINGS_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.
 */
@@ -98,7 +94,7 @@ var decodePatch = async (patch) => {
 	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,
+* The painting engine: canvas size, layers, brush and eraser settings, custom presets, the selected tool, foreground and background colours,
 * 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`).
 *
@@ -109,6 +105,7 @@ var decodePatch = async (patch) => {
 * const canvas = new PaintCanvas({ width: 1000, height: 800 });
 * canvas.selectTool(Tool.Brush, { fromToolbar: true });
 * canvas.setColour("#ff0000");
+* canvas.setColour("#ffffff", "background");
 */
 var PaintCanvas = class extends EventTarget {
 	/** Brush settings */
@@ -129,10 +126,16 @@ var PaintCanvas = class extends EventTarget {
 	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 interface choices (theme and language), kept with the other app settings */
+	ui = new UiSettings();
+	/** The user's saved colours, shown as swatches */
+	palette = new Palette();
+	/** The user's keyboard shortcuts: each configurable action's key combination */
+	shortcuts = new ShortcutSettings();
 	/** The user's pointer position over the canvas, in canvas pixels (undefined when off the canvas) */
 	pointer;
 	/** Selected tool */
-	tool = "brush";
+	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 */
@@ -186,9 +189,17 @@ var PaintCanvas = class extends EventTarget {
 	sendingStrokes = false;
 	/** Whether a stroke from elsewhere is being drawn (it isn't sent again) */
 	replaying = false;
-	currentColour = DEFAULT_COLOUR;
+	currentColours = {
+		foreground: DEFAULT_COLOUR,
+		background: DEFAULT_BACKGROUND_COLOUR
+	};
+	currentSelectedColour = "foreground";
 	/** Image data copied with cut or copy, and the area it was copied from */
 	clipboard;
+	/** How many times image data has been copied (see `copyCount`) */
+	copies = 0;
+	/** The system clipboard copies are also put on, if any */
+	systemClipboard;
 	/** Drawings from elsewhere */
 	externalSheets;
 	/** Who receives the drawing messages this canvas sends */
@@ -229,6 +240,7 @@ var PaintCanvas = class extends EventTarget {
 		this.customPresets.addEventListener("change", () => this.listCustomPresets());
 		this.customPresets.load().catch(() => void 0);
 		this.createCanvas = options.createCanvas ?? createOffscreenCanvas;
+		this.systemClipboard = options.systemClipboard === null ? void 0 : options.systemClipboard ?? globalThis.navigator?.clipboard;
 		this.canvasWidth = DEFAULT_CANVAS_SIZE;
 		this.canvasHeight = DEFAULT_CANVAS_SIZE;
 		this.layerStack = new LayerStack(this.canvasWidth, this.canvasHeight, this.createCanvas, this.maxLayers);
@@ -642,7 +654,7 @@ var PaintCanvas = class extends EventTarget {
 	*/
 	syncTransform() {
 		const transformer = this.transformer;
-		if (this.tool !== "move") {
+		if (this.tool !== Tool.Move) {
 			if (transformer.pending) this.commitTransform();
 			else if (transformer.active) {
 				transformer.reset();
@@ -713,23 +725,87 @@ var PaintCanvas = class extends EventTarget {
 			image,
 			area
 		};
+		this.copies++;
+		this.writeSystemClipboard(image);
+		this.notify();
 		return area;
 	}
 	/**
-	* Copy the masked image data of the selected layer to the clipboard, then erase it from the layer as one undoable
-	* action.
+	* 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`).
+	*/
+	get copyCount() {
+		return this.copies;
+	}
+	/** Whether there is copied image data to paste (see `copy` and `cut`) */
+	get hasClipboard() {
+		return this.clipboard !== void 0;
+	}
+	/**
+	* The copied image data as a PNG, if there is any (e.g. to use as a brush shape).
+	*
+	* @example
+	* const png = await canvas.copiedPng(); // Blob of type "image/png", or undefined
+	*/
+	async copiedPng() {
+		return this.clipboard?.image.convertToBlob({ type: "image/png" });
+	}
+	/**
+	* Put copied image data on the system clipboard as a PNG, if there is one and the browser can. The item is made
+	* straight away (some browsers only allow writing while handling the key press or click) with the PNG to follow.
+	* Failing (e.g. the page isn't focused) changes nothing: the image data can still be pasted here.
+	*/
+	writeSystemClipboard(image) {
+		if (!this.systemClipboard || typeof ClipboardItem === "undefined") return;
+		const item = new ClipboardItem({ "image/png": image.convertToBlob({ type: "image/png" }) });
+		this.systemClipboard.write([item]).catch(() => void 0);
+	}
+	/**
+	* Copy the masked image data of the selected layer to the clipboard, then remove it from the layer as one undoable
+	* action (see `deleteMasked`).
 	*/
 	cut() {
 		const area = this.copy();
-		if (area) this.eraseMasked(area);
+		if (area) this.clearMasked(area);
 	}
 	/**
-	* Erase the masked image data from the selected layer as one undoable action (Delete or Backspace). Needs a mask with
+	* Erase the masked image data from the selected layer as one undoable action (Delete or Backspace). When the layer's
+	* alpha lock is on, it is painted with the background colour instead, keeping its transparency. 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);
+		if (area) this.clearMasked(area);
+	}
+	/**
+	* Fill the selected layer with the foreground or background colour as one undoable action: only the masked area when
+	* there is a mask (partly where it is partly), and only existing pixels when the layer's alpha lock is on. Does
+	* nothing during a stroke or while a transform is pending.
+	*
+	* @example
+	* canvas.fill("foreground");
+	*/
+	fill(slot) {
+		if (this.strokeEngine.drawing || this.transformer.pending) return;
+		const area = this.fillArea();
+		if (area) this.paintArea(area, this.currentColours[slot]);
+	}
+	/**
+	* The area a fill changes: the mask's bounds (or the whole canvas without a mask), cut to the selected layer's image
+	* data when its alpha lock is on. None if that is empty.
+	*/
+	fillArea() {
+		const { width, height } = this;
+		const layer = this.layerStack.active;
+		const mask = this.currentSelection.mask;
+		const maskData = mask ? mask.getContext("2d").getImageData(0, 0, width, height).data : void 0;
+		if (layer.alphaLock) return contentBounds(layer.context.getImageData(0, 0, width, height).data, width, height, maskData);
+		return maskData ? contentBounds(maskData, width, height) : {
+			x: 0,
+			y: 0,
+			width,
+			height
+		};
 	}
 	/**
 	* The bounds of the selected layer's image data inside the mask, if there is a mask with image data inside it. None
@@ -742,12 +818,18 @@ var PaintCanvas = class extends EventTarget {
 		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.
+	* Erase the mask's part of an area from the selected layer, or paint it with the background colour when the layer's
+	* alpha lock is on, as one undoable action.
 	*/
-	eraseMasked(area) {
+	clearMasked(area) {
+		const layer = this.layerStack.active;
+		if (layer.alphaLock) {
+			this.paintArea(area, this.currentColours.background);
+			return;
+		}
 		const mask = this.currentSelection.mask;
 		const maskPiece = copyArea(this.createCanvas, mask, area);
-		this.layerStack.changeImage(this.layerStack.active.id, area, (ctx) => {
+		this.layerStack.changeImage(layer.id, area, (ctx) => {
 			ctx.save();
 			ctx.globalCompositeOperation = "destination-out";
 			ctx.drawImage(maskPiece, area.x, area.y);
@@ -755,6 +837,28 @@ var PaintCanvas = class extends EventTarget {
 		});
 	}
 	/**
+	* Paint a colour over an area of the selected layer, cut to the mask if there is one (partly where it is partly), as
+	* one undoable action. Only existing pixels are painted when the layer's alpha lock is on.
+	*/
+	paintArea(area, colour) {
+		const layer = this.layerStack.active;
+		const mask = this.currentSelection.mask;
+		const paint = this.createCanvas(area.width, area.height);
+		const paintCtx = paint.getContext("2d");
+		if (mask) {
+			paintCtx.drawImage(copyArea(this.createCanvas, mask, area), 0, 0);
+			paintCtx.globalCompositeOperation = "source-in";
+		}
+		paintCtx.fillStyle = colour;
+		paintCtx.fillRect(0, 0, area.width, area.height);
+		this.layerStack.changeImage(layer.id, area, (ctx) => {
+			ctx.save();
+			ctx.globalCompositeOperation = layer.alphaLock ? "source-atop" : "source-over";
+			ctx.drawImage(paint, 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.
@@ -763,10 +867,36 @@ var PaintCanvas = class extends EventTarget {
 		const clipboard = this.clipboard;
 		if (!clipboard || this.strokeEngine.drawing) return;
 		if (this.transformer.pending) this.commitTransform();
-		this.selectTool("move");
+		this.selectTool(Tool.Move);
 		this.transformer.float(this.layerStack.active, clipboard.image, clipboard.area);
 	}
 	/**
+	* Show an image from elsewhere (e.g. pasted from another app) over the selected layer, in the middle of the part of
+	* the canvas in view, and select the Move tool to place, scale and rotate it, like `paste`. An image larger than the
+	* canvas is shrunk to fit it. Does nothing during a stroke.
+	*
+	* @example
+	* canvas.pasteImage(await createImageBitmap(file));
+	*/
+	pasteImage(source) {
+		if (this.strokeEngine.drawing) return;
+		const scale = Math.min(1, this.canvasWidth / source.width, this.canvasHeight / source.height);
+		const width = Math.max(1, Math.round(source.width * scale));
+		const height = Math.max(1, Math.round(source.height * scale));
+		const image = this.createCanvas(width, height);
+		image.getContext("2d").drawImage(source, 0, 0, width, height);
+		const view = this.view.visibleRect();
+		const area = {
+			x: Math.round(view.x + (view.width - width) / 2),
+			y: Math.round(view.y + (view.height - height) / 2),
+			width,
+			height
+		};
+		if (this.transformer.pending) this.commitTransform();
+		this.selectTool(Tool.Move);
+		this.transformer.float(this.layerStack.active, image, area);
+	}
+	/**
 	* Apply a finished lasso action to the mask: a shape is added, subtracted or replaces it; a plain click deselects.
 	*/
 	applyLasso(result) {
@@ -827,16 +957,53 @@ var PaintCanvas = class extends EventTarget {
 	get layers() {
 		return this.layerStack;
 	}
-	/** Current drawing colour as a hex string, e.g. `#000000` */
+	/** Current foreground colour as a hex string, e.g. `#000000` (the same as `colours.foreground`) */
 	get colour() {
-		return this.currentColour;
+		return this.currentColours.foreground;
+	}
+	/** Current foreground and background colours as hex strings, e.g. `{ foreground: "#000000", background: "#ffffff" }` */
+	get colours() {
+		return this.currentColours;
+	}
+	/** Which colour is selected for configuration, e.g. by a colour picker or the colour sample tool ("foreground" by default) */
+	get selectedColour() {
+		return this.currentSelectedColour;
+	}
+	/**
+	* Set the foreground colour, or the background colour. Must be a 6-digit hex colour, e.g. `#ff0000`.
+	*
+	* @example
+	* canvas.setColour("#ff0000"); // foreground
+	* canvas.setColour("#ffffff", "background");
+	*/
+	setColour(colour, slot = "foreground") {
+		if (!isHexColour(colour)) throw new Error(`Invalid colour ${colour}`);
+		this.currentColours = {
+			...this.currentColours,
+			[slot]: colour.toLowerCase()
+		};
+		this.notify();
+	}
+	/**
+	* Select which colour is configured, e.g. by a colour picker or the colour sample tool. One colour is always selected.
+	*
+	* @example
+	* canvas.selectColour("background");
+	*/
+	selectColour(slot) {
+		if (slot === this.currentSelectedColour) return;
+		this.currentSelectedColour = slot;
+		this.notify();
 	}
 	/**
-	* Set the drawing colour. Must be a 6-digit hex colour, e.g. `#ff0000`.
+	* Swap the foreground and background colours. The selected colour stays the same slot.
 	*/
-	setColour(colour) {
-		if (!COLOUR_PATTERN.test(colour)) throw new Error(`Invalid colour ${colour}`);
-		this.currentColour = colour.toLowerCase();
+	swapColours() {
+		const { foreground, background } = this.currentColours;
+		this.currentColours = {
+			foreground: background,
+			background: foreground
+		};
 		this.notify();
 	}
 	/**
@@ -963,4 +1130,4 @@ var PaintCanvas = class extends EventTarget {
 		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 };
+export { DEFAULT_AUTHOR, DEFAULT_BACKGROUND_COLOUR, DEFAULT_CANVAS_SIZE, DEFAULT_COLOUR, DEFAULT_NAMES, DEFAULT_OWNER_ID, MAX_CANVAS_SIZE, Panel, TOOL_PANELS, Tool, PaintCanvas as default, isHexColour };

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

@@ -0,0 +1,15 @@
+/** Drawing and navigation tools */
+export declare enum Tool {
+    Brush = "brush",
+    Eraser = "eraser",
+    /** Move, scale and rotate */
+    Move = "move",
+    RectangleLasso = "rectangle-lasso",
+    CircleLasso = "circle-lasso",
+    PolygonLasso = "polygon-lasso",
+    FreeformLasso = "freeform-lasso",
+    Pan = "pan",
+    Zoom = "zoom",
+    /** Set the current colour from the canvas (eyedropper) */
+    ColourSample = "colour-sample"
+}