@lvl99dotcom/paintcanvas 0.3.1 → 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, 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 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/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/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

@@ -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,29 @@ 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;
+/**
+ * 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
@@ -35,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;
@@ -65,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).
      */
@@ -80,10 +117,24 @@ 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.
      */
     private applyPresetSize;
+    /**
+     * Set the width, with the height following the stored proportions (see `proportionalSize`).
+     */
+    private setProportionalSize;
     /**
      * Dispatch a `change` event.
      */