@lvl99dotcom/paintcanvas 0.5.0 → 0.7.0

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

@@ -11,7 +11,7 @@ import Selection from "../../selection/Selection/index.js";
 import Lasso from "../../selection/Lasso/index.js";
 import Transformer, { applyMask, contentBounds, copyArea, drawTransformed } from "../../transform/Transformer/index.js";
 import { boxBounds } from "../../transform/geometry/index.js";
-import Layer, { createOffscreenCanvas } from "../Layer/index.js";
+import Layer, { createMemoryCanvas, createOffscreenCanvas } from "../Layer/index.js";
 import LayerAutosave from "../LayerAutosave/index.js";
 import { brushPresets, eraserPresets } from "../../brushes/index.js";
 import { BUILT_IN_AUTHOR, UNKNOWN_AUTHOR, authorHandle } from "../../brushes/authors/index.js";
@@ -19,10 +19,11 @@ import "../../presets/index.js";
 import CustomPresets from "../CustomPresets/index.js";
 import { BRUSH_PRESET_FILE_FORMAT } from "../../presets/schema.js";
 import InputSettings from "../InputSettings/index.js";
-import UiSettings from "../UiSettings/index.js";
+import UiSettings, { DEFAULT_UI_SETTINGS } from "../UiSettings/index.js";
 import Palette from "../Palette/index.js";
-import ShortcutSettings from "../ShortcutSettings/index.js";
 import { PALETTE_FILE_FORMAT } from "../../palette/schema.js";
+import ProfileGraphs from "../ProfileGraphs/index.js";
+import ShortcutSettings from "../ShortcutSettings/index.js";
 import "../../palette/index.js";
 import { SETTINGS_FILE_FORMAT } from "../../settings/schema.js";
 import ExternalSheets from "../ExternalSheets/index.js";
@@ -126,10 +127,12 @@ var PaintCanvas = class extends EventTarget {
 	background = new BackgroundWork(this.strokeLog);
 	/** How the user's input devices control the canvas (scrolling, pinching, touch gestures, focus pen mode) */
 	input = new InputSettings();
-	/** The user's interface choices (theme and language), kept with the other app settings */
-	ui = new UiSettings();
+	/** The user's interface choices (theme, language and where canvases draw), kept with the other app settings */
+	ui;
 	/** The user's saved colours, shown as swatches */
 	palette = new Palette();
+	/** The user's own profile graphs (and the presets), for shaping how brush settings vary */
+	profiles = new ProfileGraphs();
 	/** The user's keyboard shortcuts: each configurable action's key combination */
 	shortcuts = new ShortcutSettings();
 	/** The user's pointer position over the canvas, in canvas pixels (undefined when off the canvas) */
@@ -209,6 +212,8 @@ var PaintCanvas = class extends EventTarget {
 	/** The layer stack whose changes are being sent */
 	sendingLayers;
 	onLayersChangeToSend = () => this.sender?.schedule();
+	/** Where the canvases draw, chosen when the canvas started (the user's choice for next time is `ui.data.rendering`) */
+	rendering;
 	/** Creates the canvases the app draws on (fake ones in tests) */
 	createCanvas;
 	/** Who the custom presets belong to (passed to the preset store) */
@@ -239,7 +244,9 @@ var PaintCanvas = class extends EventTarget {
 		this.customPresets = new CustomPresets(this.ownerId, options.presetStore);
 		this.customPresets.addEventListener("change", () => this.listCustomPresets());
 		this.customPresets.load().catch(() => void 0);
-		this.createCanvas = options.createCanvas ?? createOffscreenCanvas;
+		this.rendering = options.rendering ?? DEFAULT_UI_SETTINGS.rendering;
+		this.ui = new UiSettings({ rendering: this.rendering });
+		this.createCanvas = options.createCanvas ?? (this.rendering === "gpu" ? createOffscreenCanvas : createMemoryCanvas);
 		this.systemClipboard = options.systemClipboard === null ? void 0 : options.systemClipboard ?? globalThis.navigator?.clipboard;
 		this.canvasWidth = DEFAULT_CANVAS_SIZE;
 		this.canvasHeight = DEFAULT_CANVAS_SIZE;
@@ -715,11 +722,31 @@ var PaintCanvas = class extends EventTarget {
 	* nothing during a stroke or while a transform is pending. Returns the area copied, if any.
 	*/
 	copy() {
-		const area = this.maskedArea();
+		return this.copyMasked(this.layerStack.active.canvas);
+	}
+	/**
+	* Copy the masked image data of all the shown layers, mixed as they're shown (each layer's opacity and blend mode,
+	* without the white background), to the clipboard. Hidden layers are left out. Like `copy`, it needs a mask with image
+	* data inside it, and does nothing during a stroke or while a transform is pending. Returns the area copied, if any.
+	*
+	* @example
+	* app.selection.selectAll();
+	* app.copyMerged(); // { x: 10, y: 20, width: 30, height: 5 }: the part of the canvas with paint on any shown layer
+	*/
+	copyMerged() {
+		if (!this.canCopy) return void 0;
+		const merged = this.createCanvas(this.width, this.height);
+		drawLayers(merged.getContext("2d"), this.layerStack.layers);
+		return this.copyMasked(merged);
+	}
+	/**
+	* Copy the masked part of a canvas-sized image to the clipboard (see `copy`), returning the area copied, if any.
+	*/
+	copyMasked(source) {
+		const area = this.maskedArea(source);
 		const mask = this.currentSelection.mask;
 		if (!area || !mask) return void 0;
-		const layer = this.layerStack.active;
-		const image = copyArea(this.createCanvas, layer.canvas, area);
+		const image = copyArea(this.createCanvas, source, area);
 		applyMask(image, copyArea(this.createCanvas, mask, area));
 		this.clipboard = {
 			image,
@@ -807,15 +834,19 @@ var PaintCanvas = class extends EventTarget {
 			height
 		};
 	}
+	/** Whether image data can be copied now: not during a stroke or while a transform is pending */
+	get canCopy() {
+		return !this.strokeEngine.drawing && !this.transformer.pending;
+	}
 	/**
-	* The bounds of the selected layer's image data inside the mask, if there is a mask with image data inside it. None
-	* during a stroke or while a transform is pending.
+	* The bounds of a canvas-sized image's data (the selected layer's by default) inside the mask, if there is a mask
+	* with image data inside it. None during a stroke or while a transform is pending.
 	*/
-	maskedArea() {
+	maskedArea(source = this.layerStack.active.canvas) {
 		const mask = this.currentSelection.mask;
-		if (!mask || this.strokeEngine.drawing || this.transformer.pending) return void 0;
+		if (!mask || !this.canCopy) return void 0;
 		const { width, height } = this;
-		return contentBounds(this.layerStack.active.context.getImageData(0, 0, width, height).data, width, height, mask.getContext("2d").getImageData(0, 0, width, height).data);
+		return contentBounds(source.getContext("2d").getImageData(0, 0, width, height).data, width, height, mask.getContext("2d").getImageData(0, 0, width, height).data);
 	}
 	/**
 	* Erase the mask's part of an area from the selected layer, or paint it with the background colour when the layer's

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

@@ -0,0 +1,41 @@
+/**
+ * Encode a canvas as a PNG on the page's own thread (which blocks the page while it runs: seconds on phones for a large
+ * canvas).
+ *
+ * @example
+ * const png = await encodePngHere(layer.canvas);
+ */
+export declare const encodePngHere: (canvas: OffscreenCanvas) => Promise<Blob>;
+/** The worker's code: draws the image it's sent onto its own canvas and encodes that as a PNG */
+export declare const PNG_WORKER_SOURCE = "self.onmessage = async (event) => {\n  const { id, bitmap } = event.data;\n  try {\n    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);\n    canvas.getContext(\"2d\").drawImage(bitmap, 0, 0);\n    bitmap.close();\n    self.postMessage({ id, blob: await canvas.convertToBlob({ type: \"image/png\" }) });\n  } catch (error) {\n    self.postMessage({ id, error: String(error) });\n  }\n};";
+/** Makes the worker, or gives null where workers can't be used */
+export type WorkerFactory = () => Worker | null;
+/**
+ * Make the PNG worker from its code (no separate file, so any bundler works), or null where there are no workers or
+ * `createImageBitmap`, or the page doesn't allow workers from `blob:` addresses.
+ */
+export declare const createPngWorker: WorkerFactory;
+/**
+ * Encodes canvases as PNGs in a background worker, so the page keeps responding while large layers are saved. The
+ * canvas is copied (`createImageBitmap`) and sent to the worker, which encodes the copy. Where a worker can't be used,
+ * or it fails, it encodes on the page's own thread instead (see `encodePngHere`).
+ *
+ * @example
+ * const encoder = new PngEncoder();
+ * const png = await encoder.encode(layer.canvas);
+ */
+export default class PngEncoder {
+    private readonly createWorker;
+    /** The worker, once made (null when it can't be used) */
+    private worker?;
+    private nextId;
+    /** Encodings waiting for the worker, by ID */
+    private readonly waiting;
+    constructor(createWorker?: WorkerFactory);
+    /**
+     * Encode a canvas as a PNG, in the worker where it can be used.
+     */
+    encode: (canvas: OffscreenCanvas) => Promise<Blob>;
+    /** The worker, made on first use */
+    private getWorker;
+}

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

@@ -0,0 +1,104 @@
+// src/lib/classes/PngEncoder/index.ts
+/**
+* Encode a canvas as a PNG on the page's own thread (which blocks the page while it runs: seconds on phones for a large
+* canvas).
+*
+* @example
+* const png = await encodePngHere(layer.canvas);
+*/
+var encodePngHere = (canvas) => {
+	canvas.getContext("2d");
+	return canvas.convertToBlob({ type: "image/png" });
+};
+/** The worker's code: draws the image it's sent onto its own canvas and encodes that as a PNG */
+var PNG_WORKER_SOURCE = `self.onmessage = async (event) => {
+  const { id, bitmap } = event.data;
+  try {
+    const canvas = new OffscreenCanvas(bitmap.width, bitmap.height);
+    canvas.getContext("2d").drawImage(bitmap, 0, 0);
+    bitmap.close();
+    self.postMessage({ id, blob: await canvas.convertToBlob({ type: "image/png" }) });
+  } catch (error) {
+    self.postMessage({ id, error: String(error) });
+  }
+};`;
+/**
+* Make the PNG worker from its code (no separate file, so any bundler works), or null where there are no workers or
+* `createImageBitmap`, or the page doesn't allow workers from `blob:` addresses.
+*/
+var createPngWorker = () => {
+	if (typeof Worker === "undefined" || typeof createImageBitmap === "undefined") return null;
+	try {
+		const url = URL.createObjectURL(new Blob([PNG_WORKER_SOURCE], { type: "text/javascript" }));
+		return new Worker(url);
+	} catch {
+		return null;
+	}
+};
+/**
+* Encodes canvases as PNGs in a background worker, so the page keeps responding while large layers are saved. The
+* canvas is copied (`createImageBitmap`) and sent to the worker, which encodes the copy. Where a worker can't be used,
+* or it fails, it encodes on the page's own thread instead (see `encodePngHere`).
+*
+* @example
+* const encoder = new PngEncoder();
+* const png = await encoder.encode(layer.canvas);
+*/
+var PngEncoder = class {
+	createWorker;
+	/** The worker, once made (null when it can't be used) */
+	worker;
+	nextId = 0;
+	/** Encodings waiting for the worker, by ID */
+	waiting = /* @__PURE__ */ new Map();
+	constructor(createWorker = createPngWorker) {
+		this.createWorker = createWorker;
+	}
+	/**
+	* Encode a canvas as a PNG, in the worker where it can be used.
+	*/
+	encode = async (canvas) => {
+		const worker = this.getWorker();
+		if (!worker) return encodePngHere(canvas);
+		try {
+			canvas.getContext("2d");
+			const bitmap = await createImageBitmap(canvas);
+			const id = this.nextId++;
+			return await new Promise((resolve, reject) => {
+				this.waiting.set(id, {
+					resolve,
+					reject
+				});
+				worker.postMessage({
+					id,
+					bitmap
+				}, [bitmap]);
+			});
+		} catch {
+			return encodePngHere(canvas);
+		}
+	};
+	/** The worker, made on first use */
+	getWorker() {
+		if (this.worker !== void 0) return this.worker;
+		const worker = this.createWorker();
+		this.worker = worker;
+		if (!worker) return null;
+		worker.addEventListener("message", (event) => {
+			const { id, blob, error } = event.data;
+			const waiting = this.waiting.get(id);
+			if (!waiting) return;
+			this.waiting.delete(id);
+			if (blob) waiting.resolve(blob);
+			else waiting.reject(new Error(error));
+		});
+		worker.addEventListener("error", () => {
+			worker.terminate();
+			this.worker = null;
+			for (const { reject } of this.waiting.values()) reject(/* @__PURE__ */ new Error("PNG worker failed"));
+			this.waiting.clear();
+		});
+		return worker;
+	}
+};
+export { PNG_WORKER_SOURCE, createPngWorker, PngEncoder as default, encodePngHere };

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

@@ -0,0 +1,87 @@
+import { type ProfileGraph, type ProfilePoint } from "../../profiles";
+/**
+ * Keep only valid points from an untrusted value, in order from left to right: each on the grid, with a known
+ * interpolation. Undefined if there aren't 2 to `MAX_PROFILE_POINTS` of them.
+ *
+ * @example
+ * sanitisePoints([{ x: 10, y: 0, i: "linear" }, { x: 0, y: -10, i: "linear" }]); // sorted by x
+ */
+export declare const sanitisePoints: (input: unknown) => ProfilePoint[] | undefined;
+/**
+ * Keep only valid profile graphs from an untrusted value (e.g. stored or imported): each with an ID and name and valid
+ * points (see `sanitisePoints`), each ID once and none of the presets', up to `MAX_SAVED_PROFILES`. Undefined if the
+ * value isn't an array.
+ *
+ * @example
+ * sanitiseProfiles([{ id: "a", name: "Soft", points: [...] }, { id: "a", name: "Again", points: [...] }]); // the first
+ */
+export declare const sanitiseProfiles: (input: unknown) => ProfileGraph[] | undefined;
+/** What a profile graph is saved from: its name and points, and its ID when replacing one */
+export interface ProfileGraphDraft {
+    id?: string;
+    name: string;
+    points: readonly ProfilePoint[];
+}
+/**
+ * The user's own profile graphs, alongside the ones PaintCanvas comes with (`PROFILE_PRESETS`). Kept in memory; the app
+ * settings save and restore them (see `set` and the `change` event). Each gets a UUID when it's first saved.
+ *
+ * Dispatches a `change` event when the user's graphs change.
+ *
+ * @example
+ * const profiles = new ProfileGraphs();
+ * const soft = profiles.save({ name: "Soft", points: PROFILE_PRESETS[1].points });
+ * profiles.get(soft.id)?.name; // "Soft"
+ */
+export default class ProfileGraphs extends EventTarget {
+    private values;
+    /** The user's own graphs, in the order they were first saved */
+    get graphs(): readonly ProfileGraph[];
+    /** Every graph: the presets, then the user's own */
+    get all(): readonly ProfileGraph[];
+    /**
+     * A graph by its ID: a preset or one of the user's own.
+     *
+     * @example
+     * profiles.get("overweight")?.name; // "Overweight"
+     */
+    get(id: string | undefined): ProfileGraph | undefined;
+    /** Whether a graph is one PaintCanvas comes with (so it can't be renamed, replaced or deleted) */
+    isPreset(id: string | undefined): boolean;
+    /**
+     * One of the user's own graphs with a name, ignoring case and spaces around it.
+     *
+     * @example
+     * profiles.findByName(" soft "); // the graph called "Soft"
+     */
+    findByName(name: string): ProfileGraph | undefined;
+    /**
+     * Save a graph as one of the user's own: as a new one (with a new UUID), or in place of the one with its ID. Returns
+     * the saved graph, or undefined if it can't be saved (no name, invalid points, a preset's ID, or no room).
+     *
+     * @example
+     * profiles.save({ name: "Soft", points }); // { id: "1b9d…", name: "Soft", points }
+     */
+    save(draft: ProfileGraphDraft): ProfileGraph | undefined;
+    /**
+     * Rename one of the user's own graphs. Returns whether it was renamed.
+     *
+     * @example
+     * profiles.rename(id, "Softer");
+     */
+    rename(id: string, name: string): boolean;
+    /**
+     * Delete one of the user's own graphs. Returns whether it was deleted.
+     *
+     * @example
+     * profiles.remove(id);
+     */
+    remove(id: string): boolean;
+    /**
+     * Replace all the user's graphs (e.g. when restoring saved ones), keeping only valid ones (see `sanitiseProfiles`).
+     *
+     * @example
+     * profiles.set(settings.profiles);
+     */
+    set(graphs: unknown): void;
+}

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

@@ -0,0 +1,148 @@
+import { Interpolation, PROFILE_PRESETS } from "../../profiles/index.js";
+import "../../profiles/schema.js";
+// src/lib/classes/ProfileGraphs/index.ts
+/** The interpolations a point can have */
+var INTERPOLATIONS = Object.values(Interpolation);
+/** Whether a value is text of a usable length for an ID or name */
+var isText = (value) => typeof value === "string" && value.trim().length > 0 && value.length <= 100;
+/**
+* Keep only valid points from an untrusted value, in order from left to right: each on the grid, with a known
+* interpolation. Undefined if there aren't 2 to `MAX_PROFILE_POINTS` of them.
+*
+* @example
+* sanitisePoints([{ x: 10, y: 0, i: "linear" }, { x: 0, y: -10, i: "linear" }]); // sorted by x
+*/
+var sanitisePoints = (input) => {
+	if (!Array.isArray(input)) return void 0;
+	const points = input.filter((point) => typeof point?.x === "number" && typeof point.y === "number" && point.x >= 0 && point.x <= 10 && point.y >= -10 && point.y <= 0 && INTERPOLATIONS.includes(point.i)).map(({ x, y, i }) => ({
+		x,
+		y,
+		i
+	})).sort((a, b) => a.x - b.x);
+	return points.length >= 2 && points.length <= 32 ? points : void 0;
+};
+/**
+* Keep only valid profile graphs from an untrusted value (e.g. stored or imported): each with an ID and name and valid
+* points (see `sanitisePoints`), each ID once and none of the presets', up to `MAX_SAVED_PROFILES`. Undefined if the
+* value isn't an array.
+*
+* @example
+* sanitiseProfiles([{ id: "a", name: "Soft", points: [...] }, { id: "a", name: "Again", points: [...] }]); // the first
+*/
+var sanitiseProfiles = (input) => {
+	if (!Array.isArray(input)) return void 0;
+	const graphs = /* @__PURE__ */ new Map();
+	for (const graph of input) {
+		if (graphs.size >= 100) break;
+		const points = sanitisePoints(graph?.points);
+		if (!points || !isText(graph.id) || !isText(graph.name) || graphs.has(graph.id) || PROFILE_PRESETS.some((preset) => preset.id === graph.id)) continue;
+		graphs.set(graph.id, {
+			id: graph.id,
+			name: graph.name.trim(),
+			points
+		});
+	}
+	return [...graphs.values()];
+};
+/**
+* The user's own profile graphs, alongside the ones PaintCanvas comes with (`PROFILE_PRESETS`). Kept in memory; the app
+* settings save and restore them (see `set` and the `change` event). Each gets a UUID when it's first saved.
+*
+* Dispatches a `change` event when the user's graphs change.
+*
+* @example
+* const profiles = new ProfileGraphs();
+* const soft = profiles.save({ name: "Soft", points: PROFILE_PRESETS[1].points });
+* profiles.get(soft.id)?.name; // "Soft"
+*/
+var ProfileGraphs = class extends EventTarget {
+	values = [];
+	/** The user's own graphs, in the order they were first saved */
+	get graphs() {
+		return this.values;
+	}
+	/** Every graph: the presets, then the user's own */
+	get all() {
+		return [...PROFILE_PRESETS, ...this.values];
+	}
+	/**
+	* A graph by its ID: a preset or one of the user's own.
+	*
+	* @example
+	* profiles.get("overweight")?.name; // "Overweight"
+	*/
+	get(id) {
+		return this.all.find((graph) => graph.id === id);
+	}
+	/** Whether a graph is one PaintCanvas comes with (so it can't be renamed, replaced or deleted) */
+	isPreset(id) {
+		return PROFILE_PRESETS.some((graph) => graph.id === id);
+	}
+	/**
+	* One of the user's own graphs with a name, ignoring case and spaces around it.
+	*
+	* @example
+	* profiles.findByName(" soft "); // the graph called "Soft"
+	*/
+	findByName(name) {
+		const wanted = name.trim().toLowerCase();
+		return this.values.find((graph) => graph.name.toLowerCase() === wanted);
+	}
+	/**
+	* Save a graph as one of the user's own: as a new one (with a new UUID), or in place of the one with its ID. Returns
+	* the saved graph, or undefined if it can't be saved (no name, invalid points, a preset's ID, or no room).
+	*
+	* @example
+	* profiles.save({ name: "Soft", points }); // { id: "1b9d…", name: "Soft", points }
+	*/
+	save(draft) {
+		const index = this.values.findIndex((graph) => graph.id === draft.id);
+		const [graph] = sanitiseProfiles([{
+			...draft,
+			id: index >= 0 ? draft.id : crypto.randomUUID()
+		}]);
+		if (!graph || index < 0 && this.values.length >= 100) return void 0;
+		this.values = index >= 0 ? this.values.map((saved, i) => i === index ? graph : saved) : [...this.values, graph];
+		this.dispatchEvent(new Event("change"));
+		return graph;
+	}
+	/**
+	* Rename one of the user's own graphs. Returns whether it was renamed.
+	*
+	* @example
+	* profiles.rename(id, "Softer");
+	*/
+	rename(id, name) {
+		const graph = this.values.find((saved) => saved.id === id);
+		return graph !== void 0 && this.save({
+			...graph,
+			name
+		}) !== void 0;
+	}
+	/**
+	* Delete one of the user's own graphs. Returns whether it was deleted.
+	*
+	* @example
+	* profiles.remove(id);
+	*/
+	remove(id) {
+		const next = this.values.filter((graph) => graph.id !== id);
+		if (next.length === this.values.length) return false;
+		this.values = next;
+		this.dispatchEvent(new Event("change"));
+		return true;
+	}
+	/**
+	* Replace all the user's graphs (e.g. when restoring saved ones), keeping only valid ones (see `sanitiseProfiles`).
+	*
+	* @example
+	* profiles.set(settings.profiles);
+	*/
+	set(graphs) {
+		const next = sanitiseProfiles(graphs);
+		if (!next) return;
+		this.values = next;
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { ProfileGraphs as default, sanitisePoints, sanitiseProfiles };

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

@@ -10,7 +10,7 @@ export interface SettingsAutosaveOptions {
     delayMs?: number;
 }
 /**
- * Keeps a canvas's app settings (input settings, keyboard shortcuts, colour palette, colours, theme and language) in a
+ * Keeps a canvas's app settings (input settings, keyboard shortcuts, colour palette, colours, profile graphs, theme and language) in a
  * store: the saved settings are restored when it starts (invalid ones are ignored), then changes are saved soon after
  * they happen.
  *

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

@@ -5,7 +5,7 @@ var SETTINGS_SAVE_DELAY_MS = 500;
 /** Event dispatched when loading or saving settings fails (detail: the error) */
 var SETTINGS_AUTOSAVE_ERROR_EVENT = "error";
 /**
-* Keeps a canvas's app settings (input settings, keyboard shortcuts, colour palette, colours, theme and language) in a
+* Keeps a canvas's app settings (input settings, keyboard shortcuts, colour palette, colours, profile graphs, theme and language) in a
 * store: the saved settings are restored when it starts (invalid ones are ignored), then changes are saved soon after
 * they happen.
 *
@@ -43,6 +43,7 @@ var SettingsAutosave = class extends EventTarget {
 			app.input,
 			app.shortcuts,
 			app.palette,
+			app.profiles,
 			app.ui
 		];
 	}

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

@@ -1,6 +1,12 @@
 /** The themes: light, dark, or following the device's (system) */
 export declare const THEMES: readonly ["light", "dark", "system"];
 export type Theme = (typeof THEMES)[number];
+/**
+ * Where canvases draw: `cpu` keeps their pixels in regular memory (reading and saving them never waits for the GPU),
+ * `gpu` asks the browser to keep them on the GPU (drawing may be quicker; the browser can still use the CPU)
+ */
+export declare const RENDERINGS: readonly ["cpu", "gpu"];
+export type Rendering = (typeof RENDERINGS)[number];
 /** Longest locale tag kept in UI settings (characters) */
 export declare const MAX_LOCALE_LENGTH = 35;
 /** A locale tag's characters: letters, digits and hyphens (e.g. `zh-Hant`) */
@@ -13,6 +19,14 @@ export declare const LOCALE_PATTERN = "^[A-Za-z0-9-]+$";
  * isTheme(undefined); // false
  */
 export declare const isTheme: (value: unknown) => value is Theme;
+/**
+ * Whether a value is one of the renderings.
+ *
+ * @example
+ * isRendering("gpu"); // true
+ * isRendering("webgl"); // false
+ */
+export declare const isRendering: (value: unknown) => value is Rendering;
 /**
  * Whether a value can be a locale tag (letters, digits and hyphens, at most `MAX_LOCALE_LENGTH` characters).
  *
@@ -27,7 +41,14 @@ export interface UiSettingsData {
     theme: Theme;
     /** The language's locale tag, e.g. `fr`, or undefined to follow the device's languages */
     locale?: string;
+    /**
+     * Where canvases draw (`cpu` by default). Browsers fix this when a canvas is made, so a change applies the next time
+     * the canvas starts (e.g. after reloading the page; see `PaintCanvasOptions.rendering`).
+     */
+    rendering: Rendering;
 }
+/** UI settings used for anything not given */
+export declare const DEFAULT_UI_SETTINGS: Readonly<UiSettingsData>;
 /** UI settings the UI can show and change: PaintCanvas's `UiSettings`, or anything with the same data and `update` */
 export interface UiSettingsLike extends EventTarget {
     readonly data: Readonly<UiSettingsData>;
@@ -38,11 +59,12 @@ export interface UiSettingsLike extends EventTarget {
  * or invalid. Other properties are left out.
  *
  * @example
- * sanitiseUiSettings({ theme: "dark", locale: 42 }, { theme: "system" }); // { theme: "dark" }
+ * sanitiseUiSettings({ theme: "dark", locale: 42 }, { theme: "system", rendering: "cpu" });
+ * // { theme: "dark", rendering: "cpu" }
  */
 export declare const sanitiseUiSettings: (input: unknown, defaults: UiSettingsData) => UiSettingsData;
 /**
- * The user's interface choices: the theme and the language. Kept in memory; the implementer saves and restores them
+ * The user's interface choices: the theme, the language and where canvases draw. Kept in memory; the implementer saves and restores them
  * with the other app settings (see `SettingsAutosave`), and the UI shows and applies them (e.g. `<pc-theme-picker>` and
  * `<pc-input-settings>`).
  *

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

@@ -5,6 +5,11 @@ var THEMES = [
 	"dark",
 	"system"
 ];
+/**
+* Where canvases draw: `cpu` keeps their pixels in regular memory (reading and saving them never waits for the GPU),
+* `gpu` asks the browser to keep them on the GPU (drawing may be quicker; the browser can still use the CPU)
+*/
+var RENDERINGS = ["cpu", "gpu"];
 /** Longest locale tag kept in UI settings (characters) */
 var MAX_LOCALE_LENGTH = 35;
 /** A locale tag's characters: letters, digits and hyphens (e.g. `zh-Hant`) */
@@ -18,6 +23,14 @@ var LOCALE_PATTERN = "^[A-Za-z0-9-]+$";
 */
 var isTheme = (value) => THEMES.includes(value);
 /**
+* Whether a value is one of the renderings.
+*
+* @example
+* isRendering("gpu"); // true
+* isRendering("webgl"); // false
+*/
+var isRendering = (value) => RENDERINGS.includes(value);
+/**
 * Whether a value can be a locale tag (letters, digits and hyphens, at most `MAX_LOCALE_LENGTH` characters).
 *
 * @example
@@ -25,24 +38,35 @@ var isTheme = (value) => THEMES.includes(value);
 * isLocaleTag("<script>"); // false
 */
 var isLocaleTag = (value) => typeof value === "string" && value.length <= 35 && (/* @__PURE__ */ new RegExp("^[A-Za-z0-9-]+$")).test(value);
+/** UI settings used for anything not given */
+var DEFAULT_UI_SETTINGS = {
+	theme: "system",
+	rendering: "cpu"
+};
 /**
 * Keep only valid UI settings from an untrusted value (e.g. stored or imported), using `defaults` for anything missing
 * or invalid. Other properties are left out.
 *
 * @example
-* sanitiseUiSettings({ theme: "dark", locale: 42 }, { theme: "system" }); // { theme: "dark" }
+* sanitiseUiSettings({ theme: "dark", locale: 42 }, { theme: "system", rendering: "cpu" });
+* // { theme: "dark", rendering: "cpu" }
 */
 var sanitiseUiSettings = (input, defaults) => {
 	const value = typeof input === "object" && input !== null ? input : {};
 	const theme = isTheme(value.theme) ? value.theme : defaults.theme;
 	const locale = isLocaleTag(value.locale) ? value.locale : defaults.locale;
-	return locale === void 0 ? { theme } : {
+	const rendering = isRendering(value.rendering) ? value.rendering : defaults.rendering;
+	return locale === void 0 ? {
+		theme,
+		rendering
+	} : {
 		theme,
-		locale
+		locale,
+		rendering
 	};
 };
 /**
-* The user's interface choices: the theme and the language. Kept in memory; the implementer saves and restores them
+* The user's interface choices: the theme, the language and where canvases draw. Kept in memory; the implementer saves and restores them
 * with the other app settings (see `SettingsAutosave`), and the UI shows and applies them (e.g. `<pc-theme-picker>` and
 * `<pc-input-settings>`).
 *
@@ -57,7 +81,7 @@ var UiSettings = class extends EventTarget {
 	values;
 	constructor(initial) {
 		super();
-		this.values = sanitiseUiSettings(initial, { theme: "system" });
+		this.values = sanitiseUiSettings(initial, DEFAULT_UI_SETTINGS);
 	}
 	/** Current settings (read-only copy) */
 	get data() {
@@ -74,9 +98,10 @@ var UiSettings = class extends EventTarget {
 			...this.values,
 			...changes
 		}, this.values);
-		if (next.theme === this.values.theme && next.locale === this.values.locale) return;
+		const keys = Object.keys(next);
+		if (keys.length === Object.keys(this.values).length && keys.every((key) => next[key] === this.values[key])) return;
 		this.values = next;
 		this.dispatchEvent(new Event("change"));
 	}
 };
-export { LOCALE_PATTERN, MAX_LOCALE_LENGTH, THEMES, UiSettings as default, isLocaleTag, isTheme, sanitiseUiSettings };
+export { DEFAULT_UI_SETTINGS, LOCALE_PATTERN, MAX_LOCALE_LENGTH, RENDERINGS, THEMES, UiSettings as default, isLocaleTag, isRendering, isTheme, sanitiseUiSettings };