@lvl99dotcom/paintcanvas 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,132 @@
-# Temporary Holding Version
+# PaintCanvas
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Open-source painting engine and renderer for the browser, with optional UI.
+
+- **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.
+
+Licensed under the [Apache License 2.0](LICENSE). See [CONTRIBUTING.md](CONTRIBUTING.md) to help.
+
+## Contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Documentation](#documentation)
+- [Demo](#demo)
+- [Development](#development)
+
+## Installation
+
+```sh
+npm install @lvl99dotcom/paintcanvas lit
+```
+
+[Lit](https://lit.dev) is a peer dependency, used by the UI only.
+
+## Quick start
+
+A full-page drawing app:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+      html,
+      body,
+      paint-canvas {
+        height: 100%;
+        margin: 0;
+      }
+    </style>
+  </head>
+  <body>
+    <paint-canvas></paint-canvas>
+    <script type="module">
+      import "@lvl99dotcom/paintcanvas/ui";
+      import { translations } from "@lvl99dotcom/paintcanvas/lib/i18n";
+
+      await translations.useDeviceLocale();
+    </script>
+  </body>
+</html>
+```
+
+To keep the drawing through page reloads, give it a name to store it under in the browser: `<paint-canvas store="my-drawing">`.
+
+`<paint-canvas>` creates its own engine (a 2000 × 2000 pixel canvas). To choose the size or other options, give it one:
+
+```ts
+import PaintCanvas from "@lvl99dotcom/paintcanvas/lib/classes/PaintCanvas";
+
+const layout = document.querySelector("paint-canvas");
+layout.app = new PaintCanvas({ width: 1200, height: 800, maxLayers: 10 });
+```
+
+Importing `@lvl99dotcom/paintcanvas/ui` registers every element. To load less, import single elements, e.g. `@lvl99dotcom/paintcanvas/ui/elements/PaintCanvas`.
+
+## Documentation
+
+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)
+- [Messages and events](docs/docs/messages.md)
+- [Saving and opening drawings](docs/docs/documents.md)
+- [Translations, and adding your app's own](docs/docs/translations.md)
+- [Icons](docs/docs/icons.md)
+- [Theming](docs/docs/theming.md)
+
+## Demo
+
+```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/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.
+
+The UI text follows your device's languages: on an English (UK) device, edit `locales/en-GB.json` to see text changes. The demo's own text (e.g. the "New drawing" button) is in `demo/locales/`, added the way an app adds its translations.
+
+## Development
+
+You need [Node.js](https://nodejs.org) 22.18 or later (scripts run TypeScript directly) and [pnpm](https://pnpm.io) (`corepack enable` installs the version in `package.json`).
+
+```sh
+pnpm install
+pnpm exec playwright install chromium   # once, for the browser tests
+```
+
+Source layout:
+
+- `src/lib/`: engine code (brushes, rendering, selection, transform, classes, messages, document, i18n, image, presets, validation, utils). No UI.
+- `src/ui/`: tokens, icons, base elements, drawing elements and the layout.
+- `src/testing/`: test helpers (fake and recording canvases), published as `@lvl99dotcom/paintcanvas/testing/*`. Some use Vitest.
+- `locales/`: UI text per locale.
+- `scripts/`: build scripts, e.g. the validator generator.
+- `demo/`: the demo pages.
+- `docs/`: the documentation site (its own pnpm package): guides in `docs/docs/`, and API pages TypeDoc generates from the source's comments.
+
+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/`)    |
+
+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.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+/** PaintCanvas's version, from its package.json */
+export declare const VERSION: string;

package/dist/index.js

@@ -0,0 +1,5 @@
+import { version } from "./package.js";
+// src/index.ts
+/** PaintCanvas's version, from its package.json */
+var VERSION = version;
+export { VERSION };

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

@@ -0,0 +1,32 @@
+import type { BrushConfig, BrushesConfig } from "../types";
+import BrushTip, { type ImageDecoder } from "../../rendering/BrushTip";
+import { type CanvasFactory } from "../../classes/Layer";
+/**
+ * Loads and keeps each shape's brush tip. Until a shape's image has loaded, the round tip is used.
+ *
+ * Dispatches a `change` event when a tip finishes loading.
+ *
+ * @example
+ * const tips = new BrushTipCache();
+ * const tip = tips.get(preset); // round until the image loads
+ */
+export default class BrushTipCache extends EventTarget {
+    private readonly tips;
+    private readonly loading;
+    private readonly round;
+    private readonly decode;
+    private readonly createCanvas;
+    constructor(decode?: ImageDecoder, createCanvas?: CanvasFactory);
+    /**
+     * Get a preset's tip, starting to load it if needed. Returns the round tip while loading or if loading fails.
+     */
+    get(preset: BrushConfig): BrushTip;
+    /**
+     * Start loading every preset's tip, so the first stroke with each preset already uses its shape.
+     */
+    preload(presets: BrushesConfig): void;
+    /**
+     * Load a preset's tip and remember it under its key.
+     */
+    private load;
+}

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

@@ -0,0 +1,60 @@
+import BrushTip, { decodeImage } from "../../rendering/BrushTip/index.js";
+import { createOffscreenCanvas } from "../../classes/Layer/index.js";
+// src/lib/brushes/BrushTipCache/index.ts
+/**
+* The key a preset's tip is kept under: its shape image (so presets and edited settings with the same shape share a
+* tip, and a changed shape loads anew), or its ID for shapes given as bytes.
+*/
+var tipKey = (preset) => typeof preset.image === "string" ? preset.image : preset.id;
+/**
+* Loads and keeps each shape's brush tip. Until a shape's image has loaded, the round tip is used.
+*
+* Dispatches a `change` event when a tip finishes loading.
+*
+* @example
+* const tips = new BrushTipCache();
+* const tip = tips.get(preset); // round until the image loads
+*/
+var BrushTipCache = class extends EventTarget {
+	tips = /* @__PURE__ */ new Map();
+	loading = /* @__PURE__ */ new Set();
+	round;
+	decode;
+	createCanvas;
+	constructor(decode = decodeImage, createCanvas = createOffscreenCanvas) {
+		super();
+		this.decode = decode;
+		this.createCanvas = createCanvas;
+		this.round = new BrushTip(void 0, void 0, createCanvas);
+	}
+	/**
+	* Get a preset's tip, starting to load it if needed. Returns the round tip while loading or if loading fails.
+	*/
+	get(preset) {
+		if (!preset.image) return this.round;
+		const key = tipKey(preset);
+		const tip = this.tips.get(key);
+		if (tip) return tip;
+		if (!this.loading.has(key)) this.load(preset, key);
+		return this.round;
+	}
+	/**
+	* Start loading every preset's tip, so the first stroke with each preset already uses its shape.
+	*/
+	preload(presets) {
+		for (const preset of Object.values(presets)) this.get(preset);
+	}
+	/**
+	* Load a preset's tip and remember it under its key.
+	*/
+	async load(preset, key) {
+		this.loading.add(key);
+		try {
+			this.tips.set(key, await BrushTip.load(preset, this.decode, this.createCanvas));
+			this.dispatchEvent(new Event("change"));
+		} catch {
+			this.tips.set(key, this.round);
+		}
+	}
+};
+export { BrushTipCache as default };

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

@@ -0,0 +1,171 @@
+import { type RandomFn } from "../../utils/random";
+import type { TimedStrokePoint } from "../../messages/schema";
+import type { BrushConfig, BrushStrokePoint } from "../types";
+import type Layer from "../../classes/Layer";
+import type { Rect } from "../../classes/Viewport";
+import { type CanvasFactory } from "../../classes/Layer";
+import type BrushTip from "../../rendering/BrushTip";
+import type { LayerOverride } from "../../rendering/compositing";
+/** Whether a stroke adds paint or erases */
+export type StrokeMode = "paint" | "erase";
+/** Everything needed to draw one stroke */
+export interface StrokeOptions {
+    /** Layer the stroke is drawn on */
+    layer: Layer;
+    mode: StrokeMode;
+    preset: BrushConfig;
+    /** Size chosen by the user */
+    size: {
+        width: number;
+        height: number;
+    };
+    /** Paint colour as a hex string */
+    colour: string;
+    tip: BrushTip;
+    /** Whether input comes from a pen (enables pressure and tilt) */
+    isPen: boolean;
+    /** Mask limiting where the stroke applies (its alpha scales the stroke), if a selection is active */
+    mask?: OffscreenCanvas;
+    /** Seed for the stroke's random variation, to draw a recorded stroke the same way again (a new one by default) */
+    seed?: number;
+    /** Random source for parameter variation, instead of one from `seed` (replaceable for tests) */
+    random?: RandomFn;
+}
+/** What a finished stroke was drawn from, so it can be sent and drawn again */
+export interface RecordedStroke {
+    mode: StrokeMode;
+    preset: BrushConfig;
+    size: {
+        width: number;
+        height: number;
+    };
+    colour: string;
+    isPen: boolean;
+    /** Seed of the stroke's random variation */
+    seed: number;
+    /** Input points as they arrived, before sampling and smoothing */
+    points: TimedStrokePoint[];
+}
+/**
+ * Grow a rectangle to include another (the first may be empty).
+ *
+ * @example
+ * unionRect({ x: 0, y: 0, width: 10, height: 10 }, { x: 20, y: 5, width: 5, height: 5 });
+ * // { x: 0, y: 0, width: 25, height: 10 }
+ */
+export declare const unionRect: (a: Rect | undefined, b: Rect) => Rect;
+/**
+ * Snap a rectangle outwards to whole pixels and clip it to the canvas. Returns undefined if nothing is left.
+ */
+export declare const clipRect: (rect: Rect, width: number, height: number) => Rect | undefined;
+/** Event dispatched just before a finished stroke is written into its layer */
+export declare const BEFORE_COMMIT_EVENT = "beforecommit";
+/** Event dispatched when a stroke starts */
+export declare const STROKE_BEGIN_EVENT = "strokebegin";
+/** Event dispatched when a stroke ends: written into its layer, or cancelled */
+export declare const STROKE_END_EVENT = "strokeend";
+/** Details of a `beforecommit` event: the layer, the area of it the stroke will change, and the stroke itself */
+export interface StrokeCommitDetail {
+    layer: Layer;
+    area: Rect;
+    stroke: RecordedStroke;
+}
+/**
+ * Draws brush and eraser strokes.
+ *
+ * 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).
+ * - 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.
+ *
+ * Dispatches a `change` event whenever the preview changes, and when a stroke is committed or cancelled. Dispatches a
+ * `beforecommit` event (with `StrokeCommitDetail`) just before a stroke that changes its layer is written into it, so
+ * the area can be recorded for undo. Dispatches `strokebegin` when a stroke starts and `strokeend` when it's committed or
+ * cancelled.
+ *
+ * @example
+ * engine.begin(options, { x: 10, y: 10, pressure: 0.5 }, event.timeStamp);
+ * engine.move({ x: 20, y: 12 }, event.timeStamp);
+ * engine.end({ x: 25, y: 15 }, event.timeStamp);
+ */
+export default class StrokeEngine extends EventTarget {
+    /** Canvas width in pixels */
+    readonly width: number;
+    /** Canvas height in pixels */
+    readonly height: number;
+    private readonly createCanvas;
+    private bufferCanvas?;
+    private workingCanvas?;
+    private maskedCanvas?;
+    private active?;
+    /** Area of the preview changed since `takeChangedArea` was last called */
+    private changedArea?;
+    /** Whether strokes record their points and stamps for the debug overlay */
+    debugEnabled: boolean;
+    /** Points recorded and stamps placed by the current or last stroke (only while `debugEnabled`) */
+    readonly debugTrace: {
+        points: BrushStrokePoint[];
+        stamps: BrushStrokePoint[];
+    };
+    constructor(width: number, height: number, createCanvas?: CanvasFactory);
+    /**
+     * The area of the canvas whose preview changed since this was last called (stamps placed, or a stroke cancelled or
+     * written into its layer), to redraw only that area; undefined if nothing changed.
+     */
+    takeChangedArea(): Rect | undefined;
+    /** Whether a stroke is in progress */
+    get drawing(): boolean;
+    /** The layer with the stroke in progress merged in, to draw in its place; undefined when not drawing */
+    get preview(): LayerOverride | undefined;
+    /** The stroke buffer (created on first use) */
+    private get buffer();
+    /** The preview canvas (created on first use) */
+    private get working();
+    /**
+     * Turn recording of stroke points and stamps (for the debug overlay) on or off.
+     */
+    setDebug(enabled: boolean): void;
+    /**
+     * Record a sampled point for the debug overlay.
+     */
+    private trace;
+    /**
+     * Start a stroke at the pointer-down point. Cancels any stroke already in progress.
+     */
+    begin(options: StrokeOptions, point: BrushStrokePoint, time: number): void;
+    /**
+     * Continue the stroke as the pointer moves. Points are recorded at the preset's sample rate.
+     */
+    move(point: BrushStrokePoint, time: number): void;
+    /**
+     * Finish the stroke at the pointer-up point and write it into the layer.
+     */
+    end(point: BrushStrokePoint, time: number): void;
+    /**
+     * Abandon the stroke in progress without changing the layer.
+     */
+    cancel(): void;
+    /**
+     * Stamp the shape at each point into the buffer, then refresh the preview where it changed.
+     */
+    private place;
+    /**
+     * Merge the buffer into a target canvas within an area. For the preview, the area is first reset to the layer's pixels.
+     */
+    private mergeInto;
+    /**
+     * The stroke buffer, cut to the mask within an area when a mask is active (partially masked areas let partial paint through).
+     */
+    private strokeImage;
+    /**
+     * Write the finished stroke into its layer and reset for the next stroke.
+     */
+    private commit;
+    /**
+     * Clear an area of the stroke buffer.
+     */
+    private clearBuffer;
+}