@lvl99dotcom/paintcanvas 0.4.0 → 0.5.0

package/README.md

@@ -2,6 +2,8 @@
 
 Open-source painting engine and renderer for the browser, with optional UI.
 
+[Read the docs](https://lvl99.github.io/paintcanvas/), [try PaintCanvas in your browser](https://lvl99.github.io/paintcanvas/app/) or [see the UI elements](https://lvl99.github.io/paintcanvas/app/elements.html).
+
 - **Engine** (`@lvl99dotcom/paintcanvas/lib/*`): layers, brushes and erasers, custom brush presets, selection, transforms, clipboard, undo/redo, viewport, pen/touch/mouse input and rendering. No UI, and nothing is stored unless you ask (e.g. keeping the drawing in the browser).
 - **Messages**: the engine sends and receives small drawing messages (patches of pixels, strokes, undo and redo), so you can share a drawing over any transport you choose.
 - **UI** (`@lvl99dotcom/paintcanvas/ui`), optional: Lit web components, from buttons and sliders up to a full `<paint-canvas>` layout with slots for your own parts.
@@ -69,7 +71,7 @@ Importing `@lvl99dotcom/paintcanvas/ui` registers every element. To load less, i
 
 ## Documentation
 
-Guides and API pages are in [docs/](docs/), a [Docusaurus](https://docusaurus.io) site (`pnpm docs`). The guides:
+The documentation is published at https://lvl99.github.io/paintcanvas/. Its guides and API pages are in [docs/](docs/), a [Docusaurus](https://docusaurus.io) site (`pnpm docs`). The guides:
 
 - [The layout and its slots](docs/docs/layout.md)
 - [Building your own UI on the engine](docs/docs/engine.md)
@@ -81,13 +83,15 @@ Guides and API pages are in [docs/](docs/), a [Docusaurus](https://docusaurus.io
 
 ## Demo
 
+The demo is published at https://lvl99.github.io/paintcanvas/app/. To run it locally:
+
 ```sh
 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, 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/: 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 theme picker (light, dark or system) and a "New drawing" button. The drawing and the settings, including the theme and language, are kept in the browser, so they survive reloads. Below 600px wide, the toolbar and the layers rail sit over the canvas.
 - 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.
@@ -115,18 +119,29 @@ Source layout:
 
 Tests sit in a `tests` folder beside the code. Unit tests (`*.test.ts`) run in jsdom; pixel tests (`*.browser.test.ts`) run in headless Chromium.
 
-| Command                 | Does                                                                              |
-| ----------------------- | --------------------------------------------------------------------------------- |
-| `pnpm typecheck`        | Checks types in the source, tests, scripts and demo                               |
-| `pnpm lint`             | Checks the code with ESLint                                                       |
-| `pnpm format`           | Formats files with Prettier (`pnpm format:check` only checks)                     |
-| `pnpm test`             | Runs the unit tests                                                               |
-| `pnpm test:browser`     | Runs the pixel tests in a real browser                                            |
-| `pnpm test:all`         | Runs both                                                                         |
-| `pnpm coverage`         | Runs both, with a coverage report in `coverage/`                                  |
-| `pnpm build`            | Builds the package into `dist/`: ES modules matching `src/`, with types           |
-| `pnpm build:validators` | Regenerates the validators after changing the preset, message or document schemas |
-| `pnpm dev`              | Starts the demo, reloading it when files change (`pnpm demo` does the same)       |
-| `pnpm docs`             | Starts the documentation site (`pnpm docs:build` builds it into `docs/build/`)    |
+| Command                 | Does                                                                                |
+| ----------------------- | ----------------------------------------------------------------------------------- |
+| `pnpm typecheck`        | Checks types in the source, tests, scripts and demo                                 |
+| `pnpm lint`             | Checks the code with ESLint                                                         |
+| `pnpm format`           | Formats files with Prettier (`pnpm format:check` only checks)                       |
+| `pnpm test`             | Runs the unit tests                                                                 |
+| `pnpm test:browser`     | Runs the pixel tests in a real browser                                              |
+| `pnpm test:all`         | Runs both                                                                           |
+| `pnpm coverage`         | Runs both, with a coverage report in `coverage/`                                    |
+| `pnpm build`            | Builds the package into `dist/`: ES modules matching `src/`, with types             |
+| `pnpm build:validators` | Regenerates the validators after changing the preset, message or document schemas   |
+| `pnpm icons:build`      | Optimises the icons' SVGs and makes their PNGs (`pnpm build` and `pnpm dev` run it) |
+| `pnpm dev`              | Starts the demo, reloading it when files change (`pnpm demo` does the same)         |
+| `pnpm docs`             | Starts the documentation site (`pnpm docs:build` builds it into `docs/build/`)      |
+| `pnpm demo:build`       | Builds the demo pages as a static site into `.pages/app/`                           |
+| `pnpm pages:build`      | Builds the GitHub Pages site (docs and demo) into `.pages/`                         |
+| `pnpm pages:preview`    | Serves the built site at http://localhost:5191/paintcanvas/                         |
+| `pnpm pages:deploy`     | Builds the site from `main` and publishes it to the `gh-pages` branch               |
+
+Icons live in `src/ui/icons/images`, each as `icon-<name>.svg` (the 64 × 64 source artwork) and `icon-<name>@2x.png` (128 × 128, which the UI uses). Edit or add the SVG, then run `pnpm icons:build`: it optimises the SVGs with svgo and makes the PNGs from them. A test fails if a PNG doesn't match its SVG. Register a new icon in `src/ui/icons/index.ts`.
 
 Each folder in `src/lib` and `src/ui` is published as its own import path (e.g. `src/lib/classes/PaintCanvas` as `@lvl99dotcom/paintcanvas/lib/classes/PaintCanvas`). `sideEffects` in `package.json` lists the UI modules that register elements when loaded (`src/ui/index.ts` and each `src/ui/elements/*/index.ts`), so bundlers keep them; add any other module that registers elements there.
+
+### GitHub Pages
+
+The docs and demo are published on GitHub Pages from the `gh-pages` branch, which holds only the built site. `pnpm pages:deploy` updates it: on a clean `main` that matches `origin/main`, it builds the site and commits and pushes it to `gh-pages`. Run it after each release, or whenever `main` has changes to the docs or demo. GitHub Pages is set to serve the root of the `gh-pages` branch (Settings → Pages).

package/dist/lib/brushes/presets/round/index.d.ts

@@ -1,4 +1,4 @@
-import type { BrushConfig, BrushesConfig } from "../../types";
+import { type BrushConfig, type BrushesConfig } from "../../types";
 /** Hard round brushes */
 export declare const round: BrushesConfig;
 /** Soft-edged round brushes, for shading. Stamps are about a quarter of the size apart: closer, the soft edges add up and look hard. */

package/dist/lib/brushes/presets/round/index.js

@@ -1,13 +1,16 @@
 import { BUILT_IN_AUTHOR } from "../../authors/index.js";
+import { SmoothingType } from "../../types/index.js";
 import { sizedPresets } from "../sized/index.js";
 import round_default$1 from "./round.js";
 import soft_round_default from "./soft-round.js";
 // src/lib/brushes/presets/round/index.ts
 /** Settings shared by the round presets */
 var DEFAULT_CONFIG = {
-	version: "1.0.0",
+	version: "1.1.0",
 	author: BUILT_IN_AUTHOR,
-	constrainProportions: true
+	constrainProportions: true,
+	smoothingType: SmoothingType.BezierCubic,
+	sampleRate: 5
 };
 /** Hard round brushes */
 var round = sizedPresets("round", "Round", [
@@ -15,13 +18,16 @@ var round = sizedPresets("round", "Round", [
 	5,
 	10,
 	20,
-	50
+	30,
+	40,
+	50,
+	100,
+	150
 ], {
 	...DEFAULT_CONFIG,
 	image: round_default$1,
-	sampleRate: 20,
 	spacing: 1
-});
+}, (size) => size === 1 ? { snapToPixelGrid: true } : {});
 /** Soft-edged round brushes, for shading. Stamps are about a quarter of the size apart: closer, the soft edges add up and look hard. */
 var softRound = sizedPresets("softRound", "Soft round", [
 	5,
@@ -34,8 +40,7 @@ var softRound = sizedPresets("softRound", "Soft round", [
 	150
 ], {
 	...DEFAULT_CONFIG,
-	image: soft_round_default,
-	sampleRate: 5
+	image: soft_round_default
 }, (size) => ({ spacing: Math.max(1, Math.round(size / 4)) }));
 var round_default = {
 	...round,

package/dist/lib/brushes/presets/square/index.d.ts

@@ -1,4 +1,4 @@
-import type { BrushConfig, BrushesConfig } from "../../types";
+import { type BrushConfig, type BrushesConfig } from "../../types";
 /** Hard square brushes, snapped to the pixel grid */
 export declare const square: BrushesConfig;
 declare const _default: {

package/dist/lib/brushes/presets/square/index.js

@@ -1,4 +1,5 @@
 import { BUILT_IN_AUTHOR } from "../../authors/index.js";
+import { SmoothingType } from "../../types/index.js";
 import { sizedPresets } from "../sized/index.js";
 import square_default$1 from "./square.js";
 /** Hard square brushes, snapped to the pixel grid */
@@ -9,13 +10,16 @@ var square = sizedPresets("square", "Square", [
 	20,
 	30,
 	40,
-	50
+	50,
+	100,
+	150
 ], {
-	version: "1.0.0",
+	version: "1.1.0",
 	author: BUILT_IN_AUTHOR,
 	constrainProportions: true,
 	image: square_default$1,
-	sampleRate: 50,
+	smoothingType: SmoothingType.BezierCubic,
+	sampleRate: 5,
 	snapToPixelGrid: true
 }, (size) => ({ spacing: Math.max(1, Math.round(size / 10)) }));
 var square_default = { ...square };

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

@@ -34,7 +34,11 @@ export interface ShapeImageDependencies {
  */
 export declare const readShapeImage: (blob: Blob, { decode, createCanvas, }?: ShapeImageDependencies) => Promise<ShapeImage>;
 /**
- * Read a brush shape from a PNG image on the clipboard. Throws a `ShapeImageError` if there is none or it can't be
- * used.
+ * Read a brush shape from a PNG image on the clipboard. Without one (or when the browser won't let it be read), the
+ * `fallback` PNG is used if there is one (e.g. image data copied on the canvas, `canvas.copiedPng()`). Throws a
+ * `ShapeImageError` if there is none or it can't be used.
+ *
+ * @example
+ * const shape = await readClipboardShape(navigator.clipboard, {}, () => canvas.copiedPng());
  */
-export declare const readClipboardShape: (clipboard?: Pick<Clipboard, "read">, deps?: ShapeImageDependencies) => Promise<ShapeImage>;
+export declare const readClipboardShape: (clipboard?: Pick<Clipboard, "read">, deps?: ShapeImageDependencies, fallback?: () => Promise<Blob | undefined>) => Promise<ShapeImage>;

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

@@ -44,18 +44,24 @@ var readShapeImage = async (blob, { decode = (file) => createImageBitmap(file),
 	};
 };
 /**
-* Read a brush shape from a PNG image on the clipboard. Throws a `ShapeImageError` if there is none or it can't be
-* used.
+* Read a brush shape from a PNG image on the clipboard. Without one (or when the browser won't let it be read), the
+* `fallback` PNG is used if there is one (e.g. image data copied on the canvas, `canvas.copiedPng()`). Throws a
+* `ShapeImageError` if there is none or it can't be used.
+*
+* @example
+* const shape = await readClipboardShape(navigator.clipboard, {}, () => canvas.copiedPng());
 */
-var readClipboardShape = async (clipboard = navigator.clipboard, deps = {}) => {
-	let items;
+var readClipboardShape = async (clipboard = navigator.clipboard, deps = {}, fallback = async () => void 0) => {
+	const png = await clipboardPng(clipboard) ?? await fallback();
+	if (!png) throw new ShapeImageError(SHAPE_ERRORS.noImage);
+	return readShapeImage(png, deps);
+};
+/** The PNG image on the clipboard, if there is one and it can be read */
+var clipboardPng = async (clipboard) => {
 	try {
-		items = await clipboard.read();
+		return await (await clipboard.read()).find((entry) => entry.types.includes("image/png"))?.getType("image/png");
 	} catch {
-		throw new ShapeImageError(SHAPE_ERRORS.noImage);
+		return;
 	}
-	const item = items.find((entry) => entry.types.includes("image/png"));
-	if (!item) throw new ShapeImageError(SHAPE_ERRORS.noImage);
-	return readShapeImage(await item.getType("image/png"), deps);
 };
 export { MAX_SHAPE_FILE_BYTES, MAX_SHAPE_SIZE, SHAPE_ERRORS, ShapeImageError, readClipboardShape, readShapeImage };

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

@@ -0,0 +1,18 @@
+/** A brush shape that comes with PaintCanvas (all square) */
+export interface BuiltInShape {
+    id: string;
+    name: string;
+    /** PNG data URL */
+    image: string;
+}
+/** The brush shapes that come with PaintCanvas, the ones its presets use */
+export declare const BUILT_IN_SHAPES: readonly BuiltInShape[];
+/**
+ * Which built-in shape a brush uses: its id, "round" for a brush without an image (drawn round), or undefined for one
+ * of the user's own (uploaded or pasted).
+ *
+ * @example
+ * builtInShapeId(undefined); // "round"
+ * builtInShapeId("data:image/png;base64,…"); // undefined, unless it's a built-in shape's image
+ */
+export declare const builtInShapeId: (image: unknown) => string | undefined;

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

@@ -0,0 +1,86 @@
+import round_default from "../presets/round/round.js";
+import soft_round_default from "../presets/round/soft-round.js";
+import square_default from "../presets/square/square.js";
+import pencil_2b_default from "../presets/drawing/pencil-2b.js";
+import pencil_hb_default from "../presets/drawing/pencil-hb.js";
+import felt_pen_default from "../presets/drawing/felt-pen.js";
+import brush_pen_default from "../presets/drawing/brush-pen.js";
+import textured_paint_default from "../presets/painting/textured-paint.js";
+import watery_paint_default from "../presets/painting/watery-paint.js";
+import splatter_default from "../presets/painting/splatter.js";
+import hair_default from "../presets/painting/hair.js";
+import grass_default from "../presets/painting/grass.js";
+// src/lib/brushes/shapes/index.ts
+/** The brush shapes that come with PaintCanvas, the ones its presets use */
+var BUILT_IN_SHAPES = [
+	{
+		id: "round",
+		name: "Round",
+		image: round_default
+	},
+	{
+		id: "softRound",
+		name: "Soft round",
+		image: soft_round_default
+	},
+	{
+		id: "square",
+		name: "Square",
+		image: square_default
+	},
+	{
+		id: "pencil2b",
+		name: "Pencil 2B",
+		image: pencil_2b_default
+	},
+	{
+		id: "pencilHb",
+		name: "Pencil HB",
+		image: pencil_hb_default
+	},
+	{
+		id: "feltPen",
+		name: "Felt pen",
+		image: felt_pen_default
+	},
+	{
+		id: "brushPen",
+		name: "Brush pen",
+		image: brush_pen_default
+	},
+	{
+		id: "texturedPaint",
+		name: "Textured paint",
+		image: textured_paint_default
+	},
+	{
+		id: "wateryPaint",
+		name: "Watery paint",
+		image: watery_paint_default
+	},
+	{
+		id: "splatter",
+		name: "Splatter",
+		image: splatter_default
+	},
+	{
+		id: "hair",
+		name: "Hair",
+		image: hair_default
+	},
+	{
+		id: "grass",
+		name: "Grass",
+		image: grass_default
+	}
+];
+/**
+* Which built-in shape a brush uses: its id, "round" for a brush without an image (drawn round), or undefined for one
+* of the user's own (uploaded or pasted).
+*
+* @example
+* builtInShapeId(undefined); // "round"
+* builtInShapeId("data:image/png;base64,…"); // undefined, unless it's a built-in shape's image
+*/
+var builtInShapeId = (image) => image === void 0 ? "round" : BUILT_IN_SHAPES.find((shape) => shape.image === image)?.id;
+export { BUILT_IN_SHAPES, builtInShapeId };

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

@@ -26,6 +26,19 @@ export declare const clamp: (value: number, min: number, max: number) => number;
  * stepOpacity(1, 1); // 10
  */
 export declare const stepOpacity: (percent: number, direction: 1 | -1) => number;
+/**
+ * A brush size with the given width and proportions (width ÷ height), in whole pixels. The width is kept within the
+ * range where the smaller side is at least `MIN_BRUSH_SIZE` and the larger side at most `MAX_BRUSH_SIZE`, so the
+ * proportions are kept at either end.
+ *
+ * @example
+ * proportionalSize(0, 3); // { width: 3, height: 1 }
+ * proportionalSize(1000, 0.5); // { width: 128, height: 256 }
+ */
+export declare const proportionalSize: (width: number, aspect: number) => {
+    width: number;
+    height: 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
@@ -49,6 +62,11 @@ export default class BrushSettings extends EventTarget {
     presetId: string;
     /** The current settings: a copy of the selected preset, with any changes */
     private current;
+    /**
+     * The brush's proportions (width ÷ height), kept apart from the rounded size so resizing to either end and back
+     * doesn't change them. Set by the preset and by setting the size while proportions aren't constrained.
+     */
+    private aspect;
     constructor(presets: BrushesConfig);
     /** The current settings: the selected preset's, with any changes made since selecting it */
     get preset(): BrushConfig;
@@ -79,13 +97,18 @@ export default class BrushSettings extends EventTarget {
      */
     setHeight(height: number): void;
     /**
-     * Set the size, clamped to 1–256 pixels. If the settings constrain proportions, height follows width.
+     * Set the size, clamped to 1–256 pixels. If the settings constrain proportions, height follows width, and the width
+     * stops where either side would leave that range.
      */
     setSize(width: number, height?: number): void;
     /**
-     * Change the size by a number of pixels (positive = bigger). Used when dragging up/right (bigger) or down/left (smaller).
+     * Change the size by a number of pixels (positive = bigger), keeping the proportions: the larger side changes by
+     * `delta`. Stops when the smaller side reaches 1 pixel or the larger 256. Used when dragging up/right (bigger) or
+     * down/left (smaller).
      */
     resize(delta: number): void;
+    /** The larger side (what `resize` changes), which `grow` and `shrink` step from */
+    get largerSide(): number;
     /**
      * Increase the size by one step (at least 1 pixel).
      */
@@ -108,6 +131,10 @@ export default class BrushSettings extends EventTarget {
      * Use a preset's (or configuration's) default size.
      */
     private applyPresetSize;
+    /**
+     * Set the width, with the height following the stored proportions (see `proportionalSize`).
+     */
+    private setProportionalSize;
     /**
      * Dispatch a `change` event.
      */

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

@@ -30,6 +30,22 @@ var stepOpacity = (percent, direction) => {
 	return clamp((direction > 0 ? Math.floor(steps + 1e-9) + 1 : Math.ceil(steps - 1e-9) - 1) * 10, 1, 100);
 };
 /**
+* A brush size with the given width and proportions (width ÷ height), in whole pixels. The width is kept within the
+* range where the smaller side is at least `MIN_BRUSH_SIZE` and the larger side at most `MAX_BRUSH_SIZE`, so the
+* proportions are kept at either end.
+*
+* @example
+* proportionalSize(0, 3); // { width: 3, height: 1 }
+* proportionalSize(1000, 0.5); // { width: 128, height: 256 }
+*/
+var proportionalSize = (width, aspect) => {
+	const fitted = Math.round(clamp(width, Math.max(1, 1 * aspect), Math.min(256, 256 * aspect)));
+	return {
+		width: fitted,
+		height: Math.round(clamp(fitted / aspect, 1, 256))
+	};
+};
+/**
 * 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.
@@ -52,6 +68,11 @@ var BrushSettings = class extends EventTarget {
 	presetId;
 	/** The current settings: a copy of the selected preset, with any changes */
 	current;
+	/**
+	* The brush's proportions (width ÷ height), kept apart from the rounded size so resizing to either end and back
+	* doesn't change them. Set by the preset and by setting the size while proportions aren't constrained.
+	*/
+	aspect = 1;
 	constructor(presets) {
 		super();
 		const first = Object.values(presets)[0];
@@ -118,39 +139,47 @@ var BrushSettings = class extends EventTarget {
 	* Set the height, clamped to 1–256 pixels. If the settings constrain proportions, width follows height.
 	*/
 	setHeight(height) {
-		if (!this.current.constrainProportions) {
-			this.setSize(this.width, height);
-			return;
-		}
-		const ratio = this.width / this.height;
-		this.setSize(clamp(height, 1, 256) * ratio);
+		if (this.current.constrainProportions) this.setProportionalSize(height * this.aspect);
+		else this.setSize(this.width, height);
 	}
 	/**
-	* Set the size, clamped to 1–256 pixels. If the settings constrain proportions, height follows width.
+	* Set the size, clamped to 1–256 pixels. If the settings constrain proportions, height follows width, and the width
+	* stops where either side would leave that range.
 	*/
 	setSize(width, height = width) {
-		const ratio = this.height / this.width;
+		if (this.current.constrainProportions) {
+			this.setProportionalSize(width);
+			return;
+		}
 		this.width = Math.round(clamp(width, 1, 256));
-		this.height = Math.round(clamp(this.preset.constrainProportions ? this.width * ratio : height, 1, 256));
+		this.height = Math.round(clamp(height, 1, 256));
+		this.aspect = this.width / this.height;
 		this.notify();
 	}
 	/**
-	* Change the size by a number of pixels (positive = bigger). Used when dragging up/right (bigger) or down/left (smaller).
+	* Change the size by a number of pixels (positive = bigger), keeping the proportions: the larger side changes by
+	* `delta`. Stops when the smaller side reaches 1 pixel or the larger 256. Used when dragging up/right (bigger) or
+	* down/left (smaller).
 	*/
 	resize(delta) {
-		this.setSize(this.width + delta, this.height + delta);
+		const larger = Math.max(this.width, this.height) + delta;
+		this.setProportionalSize(this.aspect >= 1 ? larger : larger * this.aspect);
+	}
+	/** The larger side (what `resize` changes), which `grow` and `shrink` step from */
+	get largerSide() {
+		return Math.max(this.width, this.height);
 	}
 	/**
 	* Increase the size by one step (at least 1 pixel).
 	*/
 	grow() {
-		this.resize(Math.max(1, Math.round(this.width * BRUSH_SIZE_STEP)));
+		this.resize(Math.max(1, Math.round(this.largerSide * BRUSH_SIZE_STEP)));
 	}
 	/**
 	* Decrease the size by one step (at least 1 pixel).
 	*/
 	shrink() {
-		this.resize(-Math.max(1, Math.round(this.width * BRUSH_SIZE_STEP)));
+		this.resize(-Math.max(1, Math.round(this.largerSide * BRUSH_SIZE_STEP)));
 	}
 	/**
 	* Increase the opacity by one step (see `stepOpacity`).
@@ -175,6 +204,14 @@ var BrushSettings = class extends EventTarget {
 	applyPresetSize(preset) {
 		this.width = preset.width ?? 1;
 		this.height = preset.height ?? this.width;
+		this.aspect = this.width / this.height;
+	}
+	/**
+	* Set the width, with the height following the stored proportions (see `proportionalSize`).
+	*/
+	setProportionalSize(width) {
+		Object.assign(this, proportionalSize(width, this.aspect));
+		this.notify();
 	}
 	/**
 	* Dispatch a `change` event.
@@ -183,4 +220,4 @@ var BrushSettings = class extends EventTarget {
 		this.dispatchEvent(new Event("change"));
 	}
 };
-export { BRUSH_OPACITY_STEP, BRUSH_SIZE_STEP, MAX_BRUSH_SIZE, MIN_BRUSH_OPACITY, MIN_BRUSH_SIZE, clamp, BrushSettings as default, stepOpacity };
+export { BRUSH_OPACITY_STEP, BRUSH_SIZE_STEP, MAX_BRUSH_SIZE, MIN_BRUSH_OPACITY, MIN_BRUSH_SIZE, clamp, BrushSettings as default, proportionalSize, stepOpacity };

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

@@ -1,5 +1,17 @@
 import { type default as PaintCanvas } from "../PaintCanvas";
 import { type ShortcutAction } from "../../utils/shortcuts";
+/**
+ * How long (milliseconds) the paste shortcut waits for the browser's `paste` event (which carries other apps' images)
+ * before pasting the image data copied here
+ */
+export declare const PASTE_EVENT_WAIT_MS = 50;
+/**
+ * The first image in a paste's clipboard data (e.g. copied in another app), if any.
+ *
+ * @example
+ * pastedImage(event.clipboardData); // File of type "image/png", or undefined
+ */
+export declare const pastedImage: (data: DataTransfer | null) => File | undefined;
 /** Event dispatched on the window for shortcut actions handled elsewhere (e.g. saving) */
 export declare const SHORTCUT_EVENT = "pc-shortcut";
 /**
@@ -9,7 +21,10 @@ export declare const SHORTCUT_EVENT = "pc-shortcut";
  *
  * 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)
+ * and finishing or cancelling a lasso shape are handled here. Pasting (the shortcut, or the browser's own paste, e.g. from
+ * its Edit menu) pastes the image data copied here, unless the window has lost focus since it was copied and the
+ * clipboard has an image (e.g. copied in another app): that image is pasted instead (see `PaintCanvas.pasteImage`).
+ * Other actions 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.
  *
@@ -24,8 +39,15 @@ export default class KeyboardShortcuts {
     private heldKey?;
     private readonly onKeyDown;
     private readonly onKeyUp;
+    /** Turns pasted image files into images (replaceable for tests) */
+    private readonly decodeImage;
+    /** `app.copyCount` when the window last lost focus: copies since then were made here */
+    private copiesBeforeBlur;
+    /** Pastes the image data copied here if the browser doesn't fire `paste` soon after the shortcut */
+    private pasteTimer?;
     private readonly onBlur;
-    constructor(app: PaintCanvas);
+    private readonly onPaste;
+    constructor(app: PaintCanvas, decodeImage?: (blob: Blob) => Promise<ImageBitmap>);
     /**
      * Start listening for key presses on a target (usually `window`).
      */
@@ -38,6 +60,13 @@ export default class KeyboardShortcuts {
      * Run the shortcut for a key press, if any. Returns the action run.
      */
     handle(event: KeyboardEvent): ShortcutAction | undefined;
+    /**
+     * Paste from the browser's `paste` event: the image data copied here if it was copied since the window last lost
+     * focus (or the clipboard has no image), otherwise the clipboard's image. Ignored in text fields and open dialogs.
+     */
+    handlePaste(event: ClipboardEvent): Promise<void>;
+    /** Stop waiting for the browser's `paste` event */
+    private cancelPasteTimer;
     /**
      * Return to the selected tool when the hold-to-pan key is released (whatever modifiers are held by then).
      */