@lvl99dotcom/paintcanvas 0.3.0 → 0.4.0

package/README.md

@@ -87,7 +87,7 @@ pnpm dev
 
 Starts a development server and opens the demo in your browser. It uses the source directly, so saving a change to `src/`, `demo/` or `locales/` reloads the page with the change straight away. (The whole page reloads because custom elements can't be redefined in a running page, so the drawing starts again.)
 
-- http://localhost:5190/: a full-page PaintCanvas with a layers panel, a menu with input settings, a dark theme switch and a "New drawing" button. The drawing is kept in the browser, so it survives reloads.
+- http://localhost:5190/: a full-page PaintCanvas with a layers panel, the colour palette (from the colours at the top of the toolbar), a menu with input settings, keyboard shortcuts, settings import and export, a dark theme switch and a "New drawing" button. The drawing and the settings are kept in the browser, so they survive reloads.
 - http://localhost:5190/elements.html: the base elements.
 
 To try it with a pen or touch on another device (e.g. a tablet) on the same network, run `pnpm dev --host` and open the network address it prints. This makes the server reachable by anyone on that network.

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

@@ -19,7 +19,7 @@ export interface StrokeOptions {
         width: number;
         height: number;
     };
-    /** Paint colour as a hex string */
+    /** Paint colour as a hex string (for the eraser, the colour it paints when the layer's alpha lock is on) */
     colour: string;
     tip: BrushTip;
     /** Whether input comes from a pen (enables pressure and tilt) */
@@ -76,7 +76,7 @@ export interface StrokeCommitDetail {
  * Stamps are drawn at full strength into a stroke buffer, so overlapping stamps within one stroke do not build up opacity.
  * The buffer is merged into the layer with the stroke's opacity (the preset's `alpha`):
  * - Brush: painted over the layer (or only onto existing pixels when the layer's alpha lock is on).
- * - Eraser: removes the buffer's shape from the layer (does nothing when alpha lock is on).
+ * - Eraser: removes the buffer's shape from the layer (or paints its colour onto existing pixels when alpha lock is on).
  * - With a mask, the buffer is first cut to the mask, so the stroke only applies inside it.
  *
  * While drawing, `preview` provides the layer with the stroke merged in, to draw instead of the layer. The stroke is written into the layer when it ends.

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

@@ -39,10 +39,13 @@ var clipRect = (rect, width, height) => {
 		height: bottom - y
 	} : void 0;
 };
-/** How the stroke buffer is merged into the layer, or null if the stroke cannot change it */
+/**
+* How the stroke buffer is merged into the layer: with alpha lock on, both brush and eraser paint only onto existing
+* pixels; otherwise the brush paints over the layer and the eraser removes from it.
+*/
 var compositeOperation = (mode, alphaLock) => {
-	if (mode === "erase") return alphaLock ? null : "destination-out";
-	return alphaLock ? "source-atop" : "source-over";
+	if (alphaLock) return "source-atop";
+	return mode === "erase" ? "destination-out" : "source-over";
 };
 /** Event dispatched just before a finished stroke is written into its layer */
 var BEFORE_COMMIT_EVENT = "beforecommit";
@@ -56,7 +59,7 @@ var STROKE_END_EVENT = "strokeend";
 * Stamps are drawn at full strength into a stroke buffer, so overlapping stamps within one stroke do not build up opacity.
 * The buffer is merged into the layer with the stroke's opacity (the preset's `alpha`):
 * - Brush: painted over the layer (or only onto existing pixels when the layer's alpha lock is on).
-* - Eraser: removes the buffer's shape from the layer (does nothing when alpha lock is on).
+* - Eraser: removes the buffer's shape from the layer (or paints its colour onto existing pixels when alpha lock is on).
 * - With a mask, the buffer is first cut to the mask, so the stroke only applies inside it.
 *
 * While drawing, `preview` provides the layer with the stroke merged in, to draw instead of the layer. The stroke is written into the layer when it ends.
@@ -215,7 +218,7 @@ var StrokeEngine = class extends EventTarget {
 		const active = this.active;
 		if (points.length === 0) return;
 		if (this.debugEnabled) this.debugTrace.stamps.push(...points);
-		const { preset, size, tip, colour, mode, isPen } = active.options;
+		const { preset, size, tip, colour, isPen } = active.options;
 		const { random } = active;
 		const ctx = this.buffer.getContext("2d");
 		const stampPreset = {
@@ -230,7 +233,7 @@ var StrokeEngine = class extends EventTarget {
 				y: point.y,
 				params: varied
 			};
-			tip.stamp(ctx, x, y, params, mode === "erase" ? "#000000" : colour);
+			tip.stamp(ctx, x, y, params, colour);
 			const reach = Math.hypot(params.width, params.height) / 2 + STAMP_MARGIN;
 			changed = unionRect(changed, {
 				x: x + params.offsetX - reach,
@@ -258,12 +261,9 @@ var StrokeEngine = class extends EventTarget {
 			ctx.clearRect(x, y, width, height);
 			ctx.drawImage(layer.canvas, x, y, width, height, x, y, width, height);
 		}
-		const operation = compositeOperation(mode, layer.alphaLock);
-		if (operation) {
-			ctx.globalAlpha = Math.max(0, Math.min(1, preset.alpha ?? 1));
-			ctx.globalCompositeOperation = operation;
-			ctx.drawImage(this.strokeImage(active, area), x, y, width, height, x, y, width, height);
-		}
+		ctx.globalAlpha = Math.max(0, Math.min(1, preset.alpha ?? 1));
+		ctx.globalCompositeOperation = compositeOperation(mode, layer.alphaLock);
+		ctx.drawImage(this.strokeImage(active, area), x, y, width, height, x, y, width, height);
 		ctx.restore();
 	}
 	/**
@@ -289,22 +289,20 @@ var StrokeEngine = class extends EventTarget {
 	commit(active) {
 		const { layer, mode, preset, size, colour, isPen } = active.options;
 		if (active.dirty) {
-			if (compositeOperation(mode, layer.alphaLock)) {
-				const stroke = {
-					mode,
-					preset,
-					size,
-					colour,
-					isPen,
-					seed: active.seed,
-					points: active.points
-				};
-				this.dispatchEvent(new CustomEvent(BEFORE_COMMIT_EVENT, { detail: {
-					layer,
-					area: active.dirty,
-					stroke
-				} }));
-			}
+			const stroke = {
+				mode,
+				preset,
+				size,
+				colour,
+				isPen,
+				seed: active.seed,
+				points: active.points
+			};
+			this.dispatchEvent(new CustomEvent(BEFORE_COMMIT_EVENT, { detail: {
+				layer,
+				area: active.dirty,
+				stroke
+			} }));
 			this.mergeInto(active.options.layer.canvas, active, active.dirty, false);
 			this.clearBuffer(active.dirty);
 			this.changedArea = unionRect(this.changedArea, active.dirty);

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

@@ -5,6 +5,10 @@ export declare const MIN_BRUSH_SIZE = 1;
 export declare const MAX_BRUSH_SIZE = 256;
 /** Fraction of the current size added or removed by `grow` and `shrink` ("]" and "[" keys) */
 export declare const BRUSH_SIZE_STEP = 0.1;
+/** Opacity step for the opacity keyboard shortcuts, in percent */
+export declare const BRUSH_OPACITY_STEP = 10;
+/** Lowest opacity the opacity keyboard shortcuts go to, in percent */
+export declare const MIN_BRUSH_OPACITY = 1;
 /**
  * Clamp a value between min and max.
  *
@@ -12,6 +16,16 @@ export declare const BRUSH_SIZE_STEP = 0.1;
  * clamp(300, 1, 256); // 256
  */
 export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * The next opacity step up or down, in percent: to the next multiple of `BRUSH_OPACITY_STEP`, from
+ * `MIN_BRUSH_OPACITY` to 100.
+ *
+ * @example
+ * stepOpacity(45, 1); // 50
+ * stepOpacity(10, -1); // 1
+ * stepOpacity(1, 1); // 10
+ */
+export declare const stepOpacity: (percent: number, direction: 1 | -1) => number;
 /**
  * The settings of a brush or eraser: the selected preset, an editable copy of its settings (changed from the tool
  * settings bar or the configuration window, without changing the preset) and the size. The brush and eraser each have
@@ -80,6 +94,16 @@ export default class BrushSettings extends EventTarget {
      * Decrease the size by one step (at least 1 pixel).
      */
     shrink(): void;
+    /**
+     * Increase the opacity by one step (see `stepOpacity`).
+     */
+    moreOpaque(): void;
+    /**
+     * Decrease the opacity by one step (see `stepOpacity`).
+     */
+    lessOpaque(): void;
+    /** Change the opacity by one step up or down */
+    private stepOpacity;
     /**
      * Use a preset's (or configuration's) default size.
      */

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

@@ -5,6 +5,10 @@ var MIN_BRUSH_SIZE = 1;
 var MAX_BRUSH_SIZE = 256;
 /** Fraction of the current size added or removed by `grow` and `shrink` ("]" and "[" keys) */
 var BRUSH_SIZE_STEP = .1;
+/** Opacity step for the opacity keyboard shortcuts, in percent */
+var BRUSH_OPACITY_STEP = 10;
+/** Lowest opacity the opacity keyboard shortcuts go to, in percent */
+var MIN_BRUSH_OPACITY = 1;
 /**
 * Clamp a value between min and max.
 *
@@ -13,6 +17,19 @@ var BRUSH_SIZE_STEP = .1;
 */
 var clamp = (value, min, max) => Math.max(min, Math.min(max, value));
 /**
+* The next opacity step up or down, in percent: to the next multiple of `BRUSH_OPACITY_STEP`, from
+* `MIN_BRUSH_OPACITY` to 100.
+*
+* @example
+* stepOpacity(45, 1); // 50
+* stepOpacity(10, -1); // 1
+* stepOpacity(1, 1); // 10
+*/
+var stepOpacity = (percent, direction) => {
+	const steps = percent / 10;
+	return clamp((direction > 0 ? Math.floor(steps + 1e-9) + 1 : Math.ceil(steps - 1e-9) - 1) * 10, 1, 100);
+};
+/**
 * The settings of a brush or eraser: the selected preset, an editable copy of its settings (changed from the tool
 * settings bar or the configuration window, without changing the preset) and the size. The brush and eraser each have
 * their own instance.
@@ -136,6 +153,23 @@ var BrushSettings = class extends EventTarget {
 		this.resize(-Math.max(1, Math.round(this.width * BRUSH_SIZE_STEP)));
 	}
 	/**
+	* Increase the opacity by one step (see `stepOpacity`).
+	*/
+	moreOpaque() {
+		this.stepOpacity(1);
+	}
+	/**
+	* Decrease the opacity by one step (see `stepOpacity`).
+	*/
+	lessOpaque() {
+		this.stepOpacity(-1);
+	}
+	/** Change the opacity by one step up or down */
+	stepOpacity(direction) {
+		const percent = Math.round((this.current.alpha ?? 1) * 100);
+		this.update({ alpha: stepOpacity(percent, direction) / 100 });
+	}
+	/**
 	* Use a preset's (or configuration's) default size.
 	*/
 	applyPresetSize(preset) {
@@ -149,4 +183,4 @@ var BrushSettings = class extends EventTarget {
 		this.dispatchEvent(new Event("change"));
 	}
 };
-export { BRUSH_SIZE_STEP, MAX_BRUSH_SIZE, MIN_BRUSH_SIZE, clamp, BrushSettings as default };
+export { BRUSH_OPACITY_STEP, BRUSH_SIZE_STEP, MAX_BRUSH_SIZE, MIN_BRUSH_OPACITY, MIN_BRUSH_SIZE, clamp, BrushSettings as default, stepOpacity };

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

@@ -3,12 +3,15 @@ import { type ShortcutAction } from "../../utils/shortcuts";
 /** Event dispatched on the window for shortcut actions handled elsewhere (e.g. saving) */
 export declare const SHORTCUT_EVENT = "pc-shortcut";
 /**
- * Listens for key presses and runs the matching shortcut on the app. Shortcuts are ignored while typing in text fields.
+ * Listens for key presses and runs the matching shortcut on the app, using the user's key combinations
+ * (`app.shortcuts`). Shortcuts are ignored while typing in text fields and inside open `<dialog>` elements. Key presses are matched on keyboards with
+ * different layouts (see `comboFromEvent`).
  *
- * Tool selection, brush/eraser size, interface visibility, select all/deselect, undo/redo, cut/copy/paste, deleting the
- * masked image data (Delete or Backspace) and finishing or cancelling a
- * lasso shape are handled here; other actions (and Escape/Enter for later features) dispatch an `pc-shortcut` event with the action as `detail`.
- * Holding Space pans temporarily; releasing it returns to the selected tool.
+ * Tool selection, brush/eraser size and opacity, interface visibility, select all/invert/deselect, undo/redo,
+ * cut/copy/paste, deleting the masked image data (Delete or Backspace), fills, swapping colours, zooming, layer opacity
+ * and finishing or cancelling a lasso shape are handled here; other actions (and Escape/Enter for later features)
+ * dispatch an `pc-shortcut` event with the action as `detail`. Holding the hold-to-pan key (Space by default) pans
+ * temporarily; releasing it returns to the selected tool.
  *
  * @example
  * const shortcuts = new KeyboardShortcuts(app);
@@ -17,6 +20,8 @@ export declare const SHORTCUT_EVENT = "pc-shortcut";
 export default class KeyboardShortcuts {
     private readonly app;
     private target;
+    /** The hold-to-pan key while it is held */
+    private heldKey?;
     private readonly onKeyDown;
     private readonly onKeyUp;
     private readonly onBlur;
@@ -34,13 +39,19 @@ export default class KeyboardShortcuts {
      */
     handle(event: KeyboardEvent): ShortcutAction | undefined;
     /**
-     * Return to the selected tool when the hold-to-pan key is released.
+     * Return to the selected tool when the hold-to-pan key is released (whatever modifiers are held by then).
      */
     handleKeyUp(event: KeyboardEvent): void;
+    /** Stop holding the hold-to-pan key */
+    private release;
     /**
      * Run a shortcut action.
      */
     run(action: ShortcutAction): void;
+    /** The brush or eraser settings while that tool is selected */
+    private brushSettings;
+    /** The middle of the viewport, which zoom shortcuts zoom around */
+    private viewportCentre;
     /**
      * Dispatch an action as an `pc-shortcut` event for features handled elsewhere.
      */

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

@@ -1,15 +1,24 @@
-import { Tool } from "../PaintCanvas/index.js";
-import { isTypingTarget, matchShortcut } from "../../utils/shortcuts/index.js";
+import { Tool } from "../PaintCanvas/tool.js";
+import "../PaintCanvas/index.js";
+import { comboFromEvent, isTypingTarget, sameCombo } from "../../utils/shortcuts/index.js";
 // src/lib/classes/KeyboardShortcuts/index.ts
+/**
+* Whether a key press happened inside an open `<dialog>` (e.g. a settings window), where shortcuts must not apply and
+* Escape is left to close it.
+*/
+var inOpenDialog = (path) => path.some((target) => target instanceof HTMLDialogElement && target.open);
 /** Event dispatched on the window for shortcut actions handled elsewhere (e.g. saving) */
 var SHORTCUT_EVENT = "pc-shortcut";
 /**
-* Listens for key presses and runs the matching shortcut on the app. Shortcuts are ignored while typing in text fields.
+* Listens for key presses and runs the matching shortcut on the app, using the user's key combinations
+* (`app.shortcuts`). Shortcuts are ignored while typing in text fields and inside open `<dialog>` elements. Key presses are matched on keyboards with
+* different layouts (see `comboFromEvent`).
 *
-* Tool selection, brush/eraser size, interface visibility, select all/deselect, undo/redo, cut/copy/paste, deleting the
-* masked image data (Delete or Backspace) and finishing or cancelling a
-* lasso shape are handled here; other actions (and Escape/Enter for later features) dispatch an `pc-shortcut` event with the action as `detail`.
-* Holding Space pans temporarily; releasing it returns to the selected tool.
+* Tool selection, brush/eraser size and opacity, interface visibility, select all/invert/deselect, undo/redo,
+* cut/copy/paste, deleting the masked image data (Delete or Backspace), fills, swapping colours, zooming, layer opacity
+* and finishing or cancelling a lasso shape are handled here; other actions (and Escape/Enter for later features)
+* dispatch an `pc-shortcut` event with the action as `detail`. Holding the hold-to-pan key (Space by default) pans
+* temporarily; releasing it returns to the selected tool.
 *
 * @example
 * const shortcuts = new KeyboardShortcuts(app);
@@ -18,9 +27,11 @@ var SHORTCUT_EVENT = "pc-shortcut";
 var KeyboardShortcuts = class {
 	app;
 	target = null;
+	/** The hold-to-pan key while it is held */
+	heldKey;
 	onKeyDown = (event) => this.handle(event);
 	onKeyUp = (event) => this.handleKeyUp(event);
-	onBlur = () => this.app.releaseHeldTool();
+	onBlur = () => this.release();
 	constructor(app) {
 		this.app = app;
 	}
@@ -47,23 +58,33 @@ var KeyboardShortcuts = class {
 	* Run the shortcut for a key press, if any. Returns the action run.
 	*/
 	handle(event) {
-		if (isTypingTarget(event.composedPath()[0] ?? event.target)) return void 0;
-		if (event.key === " " && !event.metaKey && !event.ctrlKey && !event.altKey) {
+		const path = event.composedPath();
+		if (isTypingTarget(path[0] ?? event.target) || inOpenDialog(path)) return void 0;
+		const combo = comboFromEvent(event);
+		if (!combo) return void 0;
+		const { holdToPan, shortcuts } = this.app.shortcuts;
+		if (holdToPan && sameCombo(combo, holdToPan)) {
 			event.preventDefault();
+			this.heldKey = combo.key;
 			this.app.holdTool(Tool.Pan);
 			return;
 		}
-		const action = matchShortcut(event);
+		const action = shortcuts.find((shortcut) => sameCombo(shortcut, combo))?.action;
 		if (!action) return void 0;
 		event.preventDefault();
 		this.run(action);
 		return action;
 	}
 	/**
-	* Return to the selected tool when the hold-to-pan key is released.
+	* Return to the selected tool when the hold-to-pan key is released (whatever modifiers are held by then).
 	*/
 	handleKeyUp(event) {
-		if (event.key === " ") this.app.releaseHeldTool();
+		if (this.heldKey !== void 0 && comboFromEvent(event)?.key === this.heldKey) this.release();
+	}
+	/** Stop holding the hold-to-pan key */
+	release() {
+		this.heldKey = void 0;
+		this.app.releaseHeldTool();
 	}
 	/**
 	* Run a shortcut action.
@@ -75,21 +96,41 @@ var KeyboardShortcuts = class {
 				app.selectTool(action.tool);
 				break;
 			case "brush-smaller":
-			case "brush-bigger": {
-				const settings = app.tool === Tool.Eraser ? app.eraser : app.tool === Tool.Brush ? app.brush : void 0;
-				if (action.type === "brush-bigger") settings?.grow();
-				else settings?.shrink();
+				this.brushSettings()?.shrink();
+				break;
+			case "brush-bigger":
+				this.brushSettings()?.grow();
+				break;
+			case "brush-less-opaque":
+				this.brushSettings()?.lessOpaque();
+				break;
+			case "brush-more-opaque":
+				this.brushSettings()?.moreOpaque();
 				break;
-			}
 			case "toggle-interface":
 				app.toggleInterface();
 				break;
 			case "select-all":
 				app.selection.selectAll();
 				break;
+			case "invert-selection":
+				app.selection.invert();
+				break;
 			case "deselect":
 				app.selection.clear();
 				break;
+			case "zoom-in":
+				app.viewport.zoomIn(this.viewportCentre());
+				break;
+			case "zoom-out":
+				app.viewport.zoomOut(this.viewportCentre());
+				break;
+			case "reset-zoom":
+				app.viewport.zoomAt(this.viewportCentre(), 1);
+				break;
+			case "layer-opacity":
+				app.layers.update(app.layers.active.id, { opacity: action.opacity });
+				break;
 			case "undo":
 				app.undo();
 				break;
@@ -102,6 +143,15 @@ var KeyboardShortcuts = class {
 			case "delete":
 				app.deleteMasked();
 				break;
+			case "fill-foreground":
+				app.fill("foreground");
+				break;
+			case "fill-background":
+				app.fill("background");
+				break;
+			case "swap-colours":
+				app.swapColours();
+				break;
 			case "copy":
 				app.copy();
 				break;
@@ -127,6 +177,19 @@ var KeyboardShortcuts = class {
 			default: this.dispatch(action);
 		}
 	}
+	/** The brush or eraser settings while that tool is selected */
+	brushSettings() {
+		const { app } = this;
+		return app.tool === Tool.Eraser ? app.eraser : app.tool === Tool.Brush ? app.brush : void 0;
+	}
+	/** The middle of the viewport, which zoom shortcuts zoom around */
+	viewportCentre() {
+		const { width, height } = this.app.viewport;
+		return {
+			x: width / 2,
+			y: height / 2
+		};
+	}
 	/**
 	* Dispatch an action as an `pc-shortcut` event for features handled elsewhere.
 	*/

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,13 @@ import type { LayerStoreLike } from "../../storage";
 import type { AssetAuthor, BrushConfig } from "../../brushes/types";
 import CustomPresets, { type PresetStoreLike } from "../CustomPresets";
 import InputSettings from "../InputSettings";
+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 +33,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 +43,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 +64,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 */
@@ -123,7 +127,7 @@ export interface PaintCanvasOptions {
     layerStore?: LayerStoreLike;
 }
 /**
- * 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 +138,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 +159,10 @@ 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 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,7 +199,8 @@ 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?;
     /** Drawings from elsewhere */
@@ -416,24 +426,45 @@ 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.
+     * 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 eraseMasked;
+    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 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
@@ -468,12 +499,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.
      */