@lvl99dotcom/paintcanvas 0.4.0 → 0.6.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/configRanges/index.d.ts

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

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

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

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

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

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

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

package/dist/lib/brushes/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/brushes/types/index.d.ts

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

package/dist/lib/classes/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 };