@lvl99dotcom/paintcanvas 0.3.0 → 0.4.0

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

@@ -1,4 +1,6 @@
 import StrokeLog from "../StrokeLog/index.js";
+import { Tool } from "./tool.js";
+import { isHexColour } from "../../utils/colour/index.js";
 import BackgroundWork from "../BackgroundWork/index.js";
 import BrushSettings from "../BrushSettings/index.js";
 import LayerStack from "../LayerStack/index.js";
@@ -13,9 +15,15 @@ import Layer, { 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";
-import { BRUSH_PRESET_FILE_FORMAT } from "../../presets/schema.js";
+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 Palette from "../Palette/index.js";
+import ShortcutSettings from "../ShortcutSettings/index.js";
+import { PALETTE_FILE_FORMAT } from "../../palette/schema.js";
+import "../../palette/index.js";
+import { SETTINGS_FILE_FORMAT } from "../../settings/schema.js";
 import ExternalSheets from "../ExternalSheets/index.js";
 import PatchSender from "../../messages/PatchSender/index.js";
 import { createPatchMessage, validateCanvasMessage } from "../../messages/index.js";
@@ -27,22 +35,6 @@ import { DOCUMENT_FORMAT } from "../../document/schema.js";
 import { isValidDocument } from "../../document/index.js";
 import { averageColour, flattenArea, pixelRect, readPixels } from "../../rendering/sample/index.js";
 // src/lib/classes/PaintCanvas/index.ts
-/** Drawing and navigation tools */
-var Tool = /* @__PURE__ */ function(Tool) {
-	Tool["Brush"] = "brush";
-	Tool["Eraser"] = "eraser";
-	/** Move, scale and rotate */
-	Tool["Move"] = "move";
-	Tool["RectangleLasso"] = "rectangle-lasso";
-	Tool["CircleLasso"] = "circle-lasso";
-	Tool["PolygonLasso"] = "polygon-lasso";
-	Tool["FreeformLasso"] = "freeform-lasso";
-	Tool["Pan"] = "pan";
-	Tool["Zoom"] = "zoom";
-	/** Set the current colour from the canvas (eyedropper) */
-	Tool["ColourSample"] = "colour-sample";
-	return Tool;
-}({});
 /** Toggleable panels */
 var Panel = /* @__PURE__ */ function(Panel) {
 	Panel["Brush"] = "brush";
@@ -50,19 +42,23 @@ var Panel = /* @__PURE__ */ function(Panel) {
 	Panel["Layers"] = "layers";
 	/** The implementer's own app menu */
 	Panel["Menu"] = "menu";
+	/** The colour palette: the foreground and background colours, their values and the saved colours */
+	Panel["Palette"] = "palette";
 	return Panel;
 }({});
 /** Panels opened by tools */
 var TOOL_PANELS = {
-	["brush"]: "brush",
-	["eraser"]: "eraser"
+	[Tool.Brush]: "brush",
+	[Tool.Eraser]: "eraser"
 };
 /** Canvas width and height when none is given */
 var DEFAULT_CANVAS_SIZE = 2e3;
 /** Largest canvas width or height allowed when the `maxCanvasSize` option isn't given */
 var MAX_CANVAS_SIZE = 2e3;
-/** Drawing colour to start with */
+/** Foreground colour to start with */
 var DEFAULT_COLOUR = "#000000";
+/** Background colour to start with */
+var DEFAULT_BACKGROUND_COLOUR = "#ffffff";
 /** Owner of the custom presets when the `ownerId` option isn't given */
 var DEFAULT_OWNER_ID = "local";
 /** Author name of presets made with `newPreset` when the `presetAuthor` option isn't given */
@@ -72,10 +68,10 @@ var DEFAULT_NAMES = {
 	app: BUILT_IN_AUTHOR,
 	filePrefix: "paintcanvas",
 	presetFileFormat: BRUSH_PRESET_FILE_FORMAT,
+	paletteFileFormat: PALETTE_FILE_FORMAT,
+	settingsFileFormat: SETTINGS_FILE_FORMAT,
 	unknownAuthor: UNKNOWN_AUTHOR
 };
-/** Pattern for colour input values */
-var COLOUR_PATTERN = /^#[0-9a-f]{6}$/i;
 /**
 * A canvas's pixels as a PNG data URL.
 */
@@ -97,7 +93,7 @@ var decodePatch = async (patch) => {
 	return new ImageData(await decodeRgbaDeflate(patch.data, patch.coords), width, height);
 };
 /**
-* The painting engine: canvas size, layers, brush and eraser settings, custom presets, the selected tool, colour,
+* The painting engine: canvas size, layers, brush and eraser settings, custom presets, the selected tool, foreground and background colours,
 * selection, transforms, clipboard, undo/redo history, viewport and input settings. Where its data is kept and who it
 * is shared with are up to the implementer (see `onMessage` and `receive`).
 *
@@ -108,6 +104,7 @@ var decodePatch = async (patch) => {
 * const canvas = new PaintCanvas({ width: 1000, height: 800 });
 * canvas.selectTool(Tool.Brush, { fromToolbar: true });
 * canvas.setColour("#ff0000");
+* canvas.setColour("#ffffff", "background");
 */
 var PaintCanvas = class extends EventTarget {
 	/** Brush settings */
@@ -128,10 +125,14 @@ 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 saved colours, shown as swatches */
+	palette = new Palette();
+	/** 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) */
 	pointer;
 	/** Selected tool */
-	tool = "brush";
+	tool = Tool.Brush;
 	/** Tool used temporarily while a key is held (e.g. Space for pan), overriding the selected tool */
 	heldTool = null;
 	/** Open panel, if any */
@@ -185,7 +186,11 @@ var PaintCanvas = class extends EventTarget {
 	sendingStrokes = false;
 	/** Whether a stroke from elsewhere is being drawn (it isn't sent again) */
 	replaying = false;
-	currentColour = DEFAULT_COLOUR;
+	currentColours = {
+		foreground: DEFAULT_COLOUR,
+		background: DEFAULT_BACKGROUND_COLOUR
+	};
+	currentSelectedColour = "foreground";
 	/** Image data copied with cut or copy, and the area it was copied from */
 	clipboard;
 	/** Drawings from elsewhere */
@@ -641,7 +646,7 @@ var PaintCanvas = class extends EventTarget {
 	*/
 	syncTransform() {
 		const transformer = this.transformer;
-		if (this.tool !== "move") {
+		if (this.tool !== Tool.Move) {
 			if (transformer.pending) this.commitTransform();
 			else if (transformer.active) {
 				transformer.reset();
@@ -715,20 +720,51 @@ var PaintCanvas = class extends EventTarget {
 		return area;
 	}
 	/**
-	* Copy the masked image data of the selected layer to the clipboard, then erase it from the layer as one undoable
-	* action.
+	* Copy the masked image data of the selected layer to the clipboard, then remove it from the layer as one undoable
+	* action (see `deleteMasked`).
 	*/
 	cut() {
 		const area = this.copy();
-		if (area) this.eraseMasked(area);
+		if (area) this.clearMasked(area);
 	}
 	/**
-	* Erase the masked image data from the selected layer as one undoable action (Delete or Backspace). Needs a mask with
+	* Erase the masked image data from the selected layer as one undoable action (Delete or Backspace). When the layer's
+	* alpha lock is on, it is painted with the background colour instead, keeping its transparency. Needs a mask with
 	* image data inside it; does nothing during a stroke or while a transform is pending.
 	*/
 	deleteMasked() {
 		const area = this.maskedArea();
-		if (area) this.eraseMasked(area);
+		if (area) this.clearMasked(area);
+	}
+	/**
+	* Fill the selected layer with the foreground or background colour as one undoable action: only the masked area when
+	* there is a mask (partly where it is partly), and only existing pixels when the layer's alpha lock is on. Does
+	* nothing during a stroke or while a transform is pending.
+	*
+	* @example
+	* canvas.fill("foreground");
+	*/
+	fill(slot) {
+		if (this.strokeEngine.drawing || this.transformer.pending) return;
+		const area = this.fillArea();
+		if (area) this.paintArea(area, this.currentColours[slot]);
+	}
+	/**
+	* The area a fill changes: the mask's bounds (or the whole canvas without a mask), cut to the selected layer's image
+	* data when its alpha lock is on. None if that is empty.
+	*/
+	fillArea() {
+		const { width, height } = this;
+		const layer = this.layerStack.active;
+		const mask = this.currentSelection.mask;
+		const maskData = mask ? mask.getContext("2d").getImageData(0, 0, width, height).data : void 0;
+		if (layer.alphaLock) return contentBounds(layer.context.getImageData(0, 0, width, height).data, width, height, maskData);
+		return maskData ? contentBounds(maskData, width, height) : {
+			x: 0,
+			y: 0,
+			width,
+			height
+		};
 	}
 	/**
 	* The bounds of the selected layer's image data inside the mask, if there is a mask with image data inside it. None
@@ -741,12 +777,18 @@ var PaintCanvas = class extends EventTarget {
 		return contentBounds(this.layerStack.active.context.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, as one undoable action.
+	* Erase the mask's part of an area from the selected layer, or paint it with the background colour when the layer's
+	* alpha lock is on, as one undoable action.
 	*/
-	eraseMasked(area) {
+	clearMasked(area) {
+		const layer = this.layerStack.active;
+		if (layer.alphaLock) {
+			this.paintArea(area, this.currentColours.background);
+			return;
+		}
 		const mask = this.currentSelection.mask;
 		const maskPiece = copyArea(this.createCanvas, mask, area);
-		this.layerStack.changeImage(this.layerStack.active.id, area, (ctx) => {
+		this.layerStack.changeImage(layer.id, area, (ctx) => {
 			ctx.save();
 			ctx.globalCompositeOperation = "destination-out";
 			ctx.drawImage(maskPiece, area.x, area.y);
@@ -754,6 +796,28 @@ var PaintCanvas = class extends EventTarget {
 		});
 	}
 	/**
+	* Paint a colour over an area of the selected layer, cut to the mask if there is one (partly where it is partly), as
+	* one undoable action. Only existing pixels are painted when the layer's alpha lock is on.
+	*/
+	paintArea(area, colour) {
+		const layer = this.layerStack.active;
+		const mask = this.currentSelection.mask;
+		const paint = this.createCanvas(area.width, area.height);
+		const paintCtx = paint.getContext("2d");
+		if (mask) {
+			paintCtx.drawImage(copyArea(this.createCanvas, mask, area), 0, 0);
+			paintCtx.globalCompositeOperation = "source-in";
+		}
+		paintCtx.fillStyle = colour;
+		paintCtx.fillRect(0, 0, area.width, area.height);
+		this.layerStack.changeImage(layer.id, area, (ctx) => {
+			ctx.save();
+			ctx.globalCompositeOperation = layer.alphaLock ? "source-atop" : "source-over";
+			ctx.drawImage(paint, area.x, area.y);
+			ctx.restore();
+		});
+	}
+	/**
 	* Show the clipboard's image data over the selected layer where it was copied from, and select the Move tool to place,
 	* scale and rotate it. It is written into the layer (and sent) on Enter or when switching to another tool; Escape
 	* discards it. A pending transform is applied first.
@@ -762,7 +826,7 @@ var PaintCanvas = class extends EventTarget {
 		const clipboard = this.clipboard;
 		if (!clipboard || this.strokeEngine.drawing) return;
 		if (this.transformer.pending) this.commitTransform();
-		this.selectTool("move");
+		this.selectTool(Tool.Move);
 		this.transformer.float(this.layerStack.active, clipboard.image, clipboard.area);
 	}
 	/**
@@ -826,16 +890,53 @@ var PaintCanvas = class extends EventTarget {
 	get layers() {
 		return this.layerStack;
 	}
-	/** Current drawing colour as a hex string, e.g. `#000000` */
+	/** Current foreground colour as a hex string, e.g. `#000000` (the same as `colours.foreground`) */
 	get colour() {
-		return this.currentColour;
+		return this.currentColours.foreground;
+	}
+	/** Current foreground and background colours as hex strings, e.g. `{ foreground: "#000000", background: "#ffffff" }` */
+	get colours() {
+		return this.currentColours;
+	}
+	/** Which colour is selected for configuration, e.g. by a colour picker or the colour sample tool ("foreground" by default) */
+	get selectedColour() {
+		return this.currentSelectedColour;
 	}
 	/**
-	* Set the drawing colour. Must be a 6-digit hex colour, e.g. `#ff0000`.
+	* Set the foreground colour, or the background colour. Must be a 6-digit hex colour, e.g. `#ff0000`.
+	*
+	* @example
+	* canvas.setColour("#ff0000"); // foreground
+	* canvas.setColour("#ffffff", "background");
 	*/
-	setColour(colour) {
-		if (!COLOUR_PATTERN.test(colour)) throw new Error(`Invalid colour ${colour}`);
-		this.currentColour = colour.toLowerCase();
+	setColour(colour, slot = "foreground") {
+		if (!isHexColour(colour)) throw new Error(`Invalid colour ${colour}`);
+		this.currentColours = {
+			...this.currentColours,
+			[slot]: colour.toLowerCase()
+		};
+		this.notify();
+	}
+	/**
+	* Select which colour is configured, e.g. by a colour picker or the colour sample tool. One colour is always selected.
+	*
+	* @example
+	* canvas.selectColour("background");
+	*/
+	selectColour(slot) {
+		if (slot === this.currentSelectedColour) return;
+		this.currentSelectedColour = slot;
+		this.notify();
+	}
+	/**
+	* Swap the foreground and background colours. The selected colour stays the same slot.
+	*/
+	swapColours() {
+		const { foreground, background } = this.currentColours;
+		this.currentColours = {
+			foreground: background,
+			background: foreground
+		};
 		this.notify();
 	}
 	/**
@@ -962,4 +1063,4 @@ var PaintCanvas = class extends EventTarget {
 		this.dispatchEvent(new Event("change"));
 	}
 };
-export { DEFAULT_AUTHOR, DEFAULT_CANVAS_SIZE, DEFAULT_COLOUR, DEFAULT_NAMES, DEFAULT_OWNER_ID, MAX_CANVAS_SIZE, Panel, TOOL_PANELS, Tool, PaintCanvas as default };
+export { DEFAULT_AUTHOR, DEFAULT_BACKGROUND_COLOUR, DEFAULT_CANVAS_SIZE, DEFAULT_COLOUR, DEFAULT_NAMES, DEFAULT_OWNER_ID, MAX_CANVAS_SIZE, Panel, TOOL_PANELS, Tool, PaintCanvas as default, isHexColour };

package/dist/lib/classes/PaintCanvas/tool.d.ts

@@ -0,0 +1,15 @@
+/** Drawing and navigation tools */
+export declare enum Tool {
+    Brush = "brush",
+    Eraser = "eraser",
+    /** Move, scale and rotate */
+    Move = "move",
+    RectangleLasso = "rectangle-lasso",
+    CircleLasso = "circle-lasso",
+    PolygonLasso = "polygon-lasso",
+    FreeformLasso = "freeform-lasso",
+    Pan = "pan",
+    Zoom = "zoom",
+    /** Set the current colour from the canvas (eyedropper) */
+    ColourSample = "colour-sample"
+}

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

@@ -0,0 +1,18 @@
+// src/lib/classes/PaintCanvas/tool.ts
+/** Drawing and navigation tools */
+var Tool = /* @__PURE__ */ function(Tool) {
+	Tool["Brush"] = "brush";
+	Tool["Eraser"] = "eraser";
+	/** Move, scale and rotate */
+	Tool["Move"] = "move";
+	Tool["RectangleLasso"] = "rectangle-lasso";
+	Tool["CircleLasso"] = "circle-lasso";
+	Tool["PolygonLasso"] = "polygon-lasso";
+	Tool["FreeformLasso"] = "freeform-lasso";
+	Tool["Pan"] = "pan";
+	Tool["Zoom"] = "zoom";
+	/** Set the current colour from the canvas (eyedropper) */
+	Tool["ColourSample"] = "colour-sample";
+	return Tool;
+}({});
+export { Tool };

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

@@ -0,0 +1,58 @@
+/**
+ * Keep only valid colours from an untrusted value (e.g. stored or imported): lowercase `#rrggbb` strings, each once, up
+ * to `MAX_PALETTE_COLOURS`. Undefined if the value isn't an array.
+ *
+ * @example
+ * sanitisePalette(["#FF0000", "red", "#ff0000", "#00ff00"]); // ["#ff0000", "#00ff00"]
+ * sanitisePalette("#ff0000"); // undefined
+ */
+export declare const sanitisePalette: (input: unknown) => string[] | undefined;
+/**
+ * The user's saved colours, shown as swatches. Each colour is kept once, as lowercase `#rrggbb`, up to
+ * `MAX_PALETTE_COLOURS`. Kept in memory; the implementer saves and restores them (see `set` and the `change` event).
+ *
+ * Dispatches a `change` event when the colours change.
+ *
+ * @example
+ * const palette = new Palette();
+ * palette.add("#123456");
+ * palette.colours.at(-1); // "#123456"
+ */
+export default class Palette extends EventTarget {
+    private values;
+    /** Start with some colours (invalid ones are left out), or `DEFAULT_PALETTE` */
+    constructor(colours?: readonly string[]);
+    /** The colours in order (read-only copy) */
+    get colours(): readonly string[];
+    /**
+     * Add a colour at the end. Returns whether it was added: not if it's already there, the palette is full, or it isn't a
+     * `#rrggbb` colour.
+     *
+     * @example
+     * palette.add("#FF0000"); // true, added as "#ff0000"
+     */
+    add(colour: string): boolean;
+    /**
+     * Add colours at the end, e.g. from an imported palette file, leaving out ones already there. Returns how many were
+     * added.
+     *
+     * @example
+     * palette.merge(["#ff0000", "#00ff00"]); // 1, if "#ff0000" was already there
+     */
+    merge(colours: readonly string[]): number;
+    /**
+     * Remove the colour at a position.
+     *
+     * @example
+     * palette.remove(0);
+     */
+    remove(index: number): void;
+    /**
+     * Replace all the colours (e.g. when restoring saved ones), keeping only valid ones, and dispatch `change` if they
+     * changed.
+     *
+     * @example
+     * palette.set(["#000000", "#ffffff"]);
+     */
+    set(colours: unknown): void;
+}

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

@@ -0,0 +1,92 @@
+import { isHexColour } from "../../utils/colour/index.js";
+import "../../palette/schema.js";
+import { DEFAULT_PALETTE } from "../../palette/index.js";
+// src/lib/classes/Palette/index.ts
+/**
+* Keep only valid colours from an untrusted value (e.g. stored or imported): lowercase `#rrggbb` strings, each once, up
+* to `MAX_PALETTE_COLOURS`. Undefined if the value isn't an array.
+*
+* @example
+* sanitisePalette(["#FF0000", "red", "#ff0000", "#00ff00"]); // ["#ff0000", "#00ff00"]
+* sanitisePalette("#ff0000"); // undefined
+*/
+var sanitisePalette = (input) => {
+	if (!Array.isArray(input)) return void 0;
+	const colours = /* @__PURE__ */ new Set();
+	for (const value of input) {
+		if (colours.size >= 1e3) break;
+		if (isHexColour(value)) colours.add(value.toLowerCase());
+	}
+	return [...colours];
+};
+/**
+* The user's saved colours, shown as swatches. Each colour is kept once, as lowercase `#rrggbb`, up to
+* `MAX_PALETTE_COLOURS`. Kept in memory; the implementer saves and restores them (see `set` and the `change` event).
+*
+* Dispatches a `change` event when the colours change.
+*
+* @example
+* const palette = new Palette();
+* palette.add("#123456");
+* palette.colours.at(-1); // "#123456"
+*/
+var Palette = class extends EventTarget {
+	values;
+	/** Start with some colours (invalid ones are left out), or `DEFAULT_PALETTE` */
+	constructor(colours = DEFAULT_PALETTE) {
+		super();
+		this.values = sanitisePalette(colours);
+	}
+	/** The colours in order (read-only copy) */
+	get colours() {
+		return this.values;
+	}
+	/**
+	* Add a colour at the end. Returns whether it was added: not if it's already there, the palette is full, or it isn't a
+	* `#rrggbb` colour.
+	*
+	* @example
+	* palette.add("#FF0000"); // true, added as "#ff0000"
+	*/
+	add(colour) {
+		const before = this.values.length;
+		this.set([...this.values, colour]);
+		return this.values.length > before;
+	}
+	/**
+	* Add colours at the end, e.g. from an imported palette file, leaving out ones already there. Returns how many were
+	* added.
+	*
+	* @example
+	* palette.merge(["#ff0000", "#00ff00"]); // 1, if "#ff0000" was already there
+	*/
+	merge(colours) {
+		const before = this.values.length;
+		this.set([...this.values, ...colours]);
+		return this.values.length - before;
+	}
+	/**
+	* Remove the colour at a position.
+	*
+	* @example
+	* palette.remove(0);
+	*/
+	remove(index) {
+		if (index < 0 || index >= this.values.length) return;
+		this.set(this.values.filter((_, i) => i !== index));
+	}
+	/**
+	* Replace all the colours (e.g. when restoring saved ones), keeping only valid ones, and dispatch `change` if they
+	* changed.
+	*
+	* @example
+	* palette.set(["#000000", "#ffffff"]);
+	*/
+	set(colours) {
+		const next = sanitisePalette(colours);
+		if (!next || next.length === this.values.length && next.every((colour, i) => colour === this.values[i])) return;
+		this.values = next;
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { Palette as default, sanitisePalette };

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

@@ -0,0 +1,52 @@
+import type PaintCanvas from "../PaintCanvas";
+import type { SettingsStoreLike } from "../../storage";
+/** How long to wait after settings change before saving, so quick changes (e.g. dragging a colour slider) are saved together (milliseconds) */
+export declare const SETTINGS_SAVE_DELAY_MS = 500;
+/** Event dispatched when loading or saving settings fails (detail: the error) */
+export declare const SETTINGS_AUTOSAVE_ERROR_EVENT = "error";
+/** Options for `SettingsAutosave` */
+export interface SettingsAutosaveOptions {
+    /** How long to wait after settings change before saving (default `SETTINGS_SAVE_DELAY_MS`) */
+    delayMs?: number;
+}
+/**
+ * Keeps a canvas's app settings (input settings, keyboard shortcuts, colour palette and colours) in a store: the saved
+ * settings are restored when it starts (invalid ones are ignored), then changes are saved soon after they happen.
+ *
+ * Dispatches an `error` event (with the error as `detail`) when loading or saving fails.
+ *
+ * @example
+ * const autosave = new SettingsAutosave(canvas, new IndexedDbSettingsStore());
+ * await autosave.ready;
+ * autosave.stop(); // saves any pending change
+ */
+export default class SettingsAutosave extends EventTarget {
+    /** Where the settings are kept */
+    readonly store: SettingsStoreLike;
+    /** Resolves once the saved settings are restored (or there were none) */
+    readonly ready: Promise<void>;
+    private readonly app;
+    private readonly delayMs;
+    private timer?;
+    /** The settings last saved or restored, as JSON, to skip saving unchanged settings */
+    private saved?;
+    private stopped;
+    private readonly onChange;
+    constructor(app: PaintCanvas, store: SettingsStoreLike, options?: SettingsAutosaveOptions);
+    /** The canvas parts whose changes are saved */
+    private get sources();
+    /**
+     * Stop saving changes, saving any that are waiting.
+     */
+    stop(): void;
+    /**
+     * Save the settings now if they changed since they were last saved.
+     */
+    save(): Promise<void>;
+    /** Restore the saved settings, then listen for changes */
+    private start;
+    /** Save soon, after changes stop for a moment */
+    private schedule;
+    /** Tell listeners loading or saving failed */
+    private fail;
+}

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

@@ -0,0 +1,96 @@
+import { applySettings, collectSettings, isValidSettings } from "../../settings/index.js";
+// src/lib/classes/SettingsAutosave/index.ts
+/** How long to wait after settings change before saving, so quick changes (e.g. dragging a colour slider) are saved together (milliseconds) */
+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 and colours) in a store: the saved
+* settings are restored when it starts (invalid ones are ignored), then changes are saved soon after they happen.
+*
+* Dispatches an `error` event (with the error as `detail`) when loading or saving fails.
+*
+* @example
+* const autosave = new SettingsAutosave(canvas, new IndexedDbSettingsStore());
+* await autosave.ready;
+* autosave.stop(); // saves any pending change
+*/
+var SettingsAutosave = class extends EventTarget {
+	/** Where the settings are kept */
+	store;
+	/** Resolves once the saved settings are restored (or there were none) */
+	ready;
+	app;
+	delayMs;
+	timer;
+	/** The settings last saved or restored, as JSON, to skip saving unchanged settings */
+	saved;
+	stopped = false;
+	onChange = () => this.schedule();
+	constructor(app, store, options = {}) {
+		super();
+		this.app = app;
+		this.store = store;
+		this.delayMs = options.delayMs ?? 500;
+		this.ready = this.start();
+	}
+	/** The canvas parts whose changes are saved */
+	get sources() {
+		const { app } = this;
+		return [
+			app,
+			app.input,
+			app.shortcuts,
+			app.palette
+		];
+	}
+	/**
+	* Stop saving changes, saving any that are waiting.
+	*/
+	stop() {
+		if (this.stopped) return;
+		this.stopped = true;
+		for (const source of this.sources) source.removeEventListener("change", this.onChange);
+		if (this.timer === void 0) return;
+		clearTimeout(this.timer);
+		this.save();
+	}
+	/**
+	* Save the settings now if they changed since they were last saved.
+	*/
+	async save() {
+		this.timer = void 0;
+		const settings = collectSettings(this.app);
+		const json = JSON.stringify(settings);
+		if (json === this.saved) return;
+		this.saved = json;
+		try {
+			await this.store.save(settings);
+		} catch (error) {
+			this.saved = void 0;
+			this.fail(error);
+		}
+	}
+	/** Restore the saved settings, then listen for changes */
+	async start() {
+		try {
+			const result = isValidSettings(await this.store.load());
+			if (result.valid && !this.stopped) applySettings(this.app, result.value);
+		} catch (error) {
+			this.fail(error);
+		}
+		if (this.stopped) return;
+		this.saved = JSON.stringify(collectSettings(this.app));
+		for (const source of this.sources) source.addEventListener("change", this.onChange);
+	}
+	/** Save soon, after changes stop for a moment */
+	schedule() {
+		clearTimeout(this.timer);
+		this.timer = setTimeout(() => void this.save(), this.delayMs);
+	}
+	/** Tell listeners loading or saving failed */
+	fail(error) {
+		this.dispatchEvent(new CustomEvent(SETTINGS_AUTOSAVE_ERROR_EVENT, { detail: error }));
+	}
+};
+export { SETTINGS_AUTOSAVE_ERROR_EVENT, SETTINGS_SAVE_DELAY_MS, SettingsAutosave as default };