@lvl99dotcom/paintcanvas 0.3.1 → 0.4.0

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

@@ -0,0 +1,63 @@
+import { type KeyCombo, type Shortcut, type ShortcutBindings } from "../../utils/shortcuts";
+/** What happened when setting an action's key combination */
+export interface ShortcutChangeResult {
+    /** Whether the key combination was set */
+    changed: boolean;
+    /** The action that had the key combination and lost it, if any */
+    movedFrom?: string;
+    /** The fixed action that uses the key combination, so it wasn't set */
+    fixed?: string;
+}
+/**
+ * The user's keyboard shortcuts: the key combination of each configurable action (see `CONFIGURABLE_SHORTCUTS`), each
+ * used by one action at most. Kept in memory; the implementer saves and restores them (see `load` and the `change`
+ * event).
+ *
+ * Dispatches a `change` event when a key combination changes.
+ *
+ * @example
+ * const shortcuts = new ShortcutSettings();
+ * shortcuts.set("tool-brush", { key: "p" });
+ * shortcuts.combo("tool-brush"); // { key: "p" }
+ */
+export default class ShortcutSettings extends EventTarget {
+    private values;
+    private list;
+    constructor(initial?: unknown);
+    /** Each configurable action's key combination, by ID (read-only copy) */
+    get bindings(): Readonly<ShortcutBindings>;
+    /** The shortcuts key presses are matched against (except the hold-to-pan key) */
+    get shortcuts(): readonly Shortcut[];
+    /** The key held to pan, returning to the last tool when released (null when it has none) */
+    get holdToPan(): KeyCombo | null;
+    /**
+     * A configurable action's key combination (null when it has none or there's no such action).
+     *
+     * @example
+     * shortcuts.combo("deselect"); // { key: "d", cmd: true }
+     */
+    combo(id: string): KeyCombo | null;
+    /**
+     * Set or remove (null) a configurable action's key combination. If another configurable action has it, that action
+     * loses it (`movedFrom`). Nothing changes for a key combination a fixed action uses (`fixed`), or an unknown action.
+     *
+     * @example
+     * shortcuts.set("tool-brush", { key: "e" }); // { changed: true, movedFrom: "tool-eraser" }
+     * shortcuts.set("deselect", { key: "z", cmd: true }); // { changed: false, fixed: "undo" }
+     */
+    set(id: string, combo: KeyCombo | null): ShortcutChangeResult;
+    /**
+     * Go back to the default key combinations.
+     */
+    reset(): void;
+    /**
+     * Replace the key combinations, e.g. with saved or imported ones (see `sanitiseShortcutBindings`; actions left out
+     * get their defaults), and dispatch `change` if anything changed.
+     *
+     * @example
+     * shortcuts.load({ "tool-brush": { key: "p" } });
+     */
+    load(input: unknown): void;
+    /** Use new key combinations and tell listeners */
+    private apply;
+}

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

@@ -0,0 +1,110 @@
+import { CONFIGURABLE_SHORTCUTS, defaultShortcutBindings, fixedShortcutFor, normaliseCombo, sameCombo, sanitiseShortcutBindings, shortcutsFor } from "../../utils/shortcuts/index.js";
+// src/lib/classes/ShortcutSettings/index.ts
+/**
+* The user's keyboard shortcuts: the key combination of each configurable action (see `CONFIGURABLE_SHORTCUTS`), each
+* used by one action at most. Kept in memory; the implementer saves and restores them (see `load` and the `change`
+* event).
+*
+* Dispatches a `change` event when a key combination changes.
+*
+* @example
+* const shortcuts = new ShortcutSettings();
+* shortcuts.set("tool-brush", { key: "p" });
+* shortcuts.combo("tool-brush"); // { key: "p" }
+*/
+var ShortcutSettings = class extends EventTarget {
+	values;
+	list;
+	constructor(initial) {
+		super();
+		this.values = sanitiseShortcutBindings(initial, defaultShortcutBindings());
+		this.list = shortcutsFor(this.values);
+	}
+	/** Each configurable action's key combination, by ID (read-only copy) */
+	get bindings() {
+		return this.values;
+	}
+	/** The shortcuts key presses are matched against (except the hold-to-pan key) */
+	get shortcuts() {
+		return this.list;
+	}
+	/** The key held to pan, returning to the last tool when released (null when it has none) */
+	get holdToPan() {
+		return this.values["pan"] ?? null;
+	}
+	/**
+	* A configurable action's key combination (null when it has none or there's no such action).
+	*
+	* @example
+	* shortcuts.combo("deselect"); // { key: "d", cmd: true }
+	*/
+	combo(id) {
+		return this.values[id] ?? null;
+	}
+	/**
+	* Set or remove (null) a configurable action's key combination. If another configurable action has it, that action
+	* loses it (`movedFrom`). Nothing changes for a key combination a fixed action uses (`fixed`), or an unknown action.
+	*
+	* @example
+	* shortcuts.set("tool-brush", { key: "e" }); // { changed: true, movedFrom: "tool-eraser" }
+	* shortcuts.set("deselect", { key: "z", cmd: true }); // { changed: false, fixed: "undo" }
+	*/
+	set(id, combo) {
+		if (!CONFIGURABLE_SHORTCUTS.some((definition) => definition.id === id)) return { changed: false };
+		const next = combo && normaliseCombo(combo);
+		const current = this.values[id] ?? null;
+		if (next ? current && sameCombo(current, next) : !current) return { changed: false };
+		if (!next) {
+			this.apply({
+				...this.values,
+				[id]: null
+			});
+			return { changed: true };
+		}
+		const fixed = fixedShortcutFor(next);
+		if (fixed) return {
+			changed: false,
+			fixed: fixed.id
+		};
+		const movedFrom = Object.keys(this.values).find((other) => {
+			const otherCombo = this.values[other];
+			return other !== id && otherCombo && sameCombo(otherCombo, next);
+		});
+		this.apply({
+			...this.values,
+			...movedFrom && { [movedFrom]: null },
+			[id]: next
+		});
+		return movedFrom ? {
+			changed: true,
+			movedFrom
+		} : { changed: true };
+	}
+	/**
+	* Go back to the default key combinations.
+	*/
+	reset() {
+		this.load(defaultShortcutBindings());
+	}
+	/**
+	* Replace the key combinations, e.g. with saved or imported ones (see `sanitiseShortcutBindings`; actions left out
+	* get their defaults), and dispatch `change` if anything changed.
+	*
+	* @example
+	* shortcuts.load({ "tool-brush": { key: "p" } });
+	*/
+	load(input) {
+		const next = sanitiseShortcutBindings(input, defaultShortcutBindings());
+		if (Object.keys(next).some((id) => {
+			const [a, b] = [next[id], this.values[id]];
+			return a && b ? !sameCombo(a, b) : a !== b;
+		})) this.apply(next);
+	}
+	/** Use new key combinations and tell listeners */
+	apply(bindings) {
+		this.values = bindings;
+		this.list = shortcutsFor(bindings);
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { ShortcutSettings as default };

package/dist/lib/palette/index.d.ts

@@ -0,0 +1,49 @@
+import { type PaletteFile } from "./schema";
+export * from "./schema";
+/** The colours a palette starts with */
+export declare const DEFAULT_PALETTE: readonly string[];
+/** Messages shown when importing or exporting a palette fails */
+export declare const PALETTE_FILE_ERRORS: {
+    readonly incompatible: "Colour palette JSON file not compatible";
+    readonly read: "Failed to read colour palette JSON file";
+};
+/** Importing a palette failed, with a message for the user */
+export declare class PaletteFileError extends Error {
+}
+/** Result of checking a palette file */
+export type PaletteValidationResult = {
+    valid: true;
+    value: PaletteFile;
+} | {
+    valid: false;
+    errors: string[];
+};
+/**
+ * Check a colour palette file against `paletteFileSchema`.
+ *
+ * @example
+ * isValidPaletteFile({ format: "paintcanvas-palette", version: 1, colours: ["#ff0000"] }).valid; // true
+ */
+export declare const isValidPaletteFile: (input: unknown) => PaletteValidationResult;
+/**
+ * The file name a palette is exported to on a day, starting with a prefix (see `PaintCanvasNames.filePrefix`).
+ *
+ * @example
+ * paletteFileName(new Date(2026, 10, 4)); // "paintcanvas-palette-2026-11-04.json"
+ */
+export declare const paletteFileName: (date?: Date, prefix?: string) => string;
+/**
+ * Write colours to a colour palette file (JSON) of a format (see `PaintCanvasNames.paletteFileFormat`).
+ *
+ * @example
+ * exportPaletteFile(["#ff0000"]); // '{ "format": "paintcanvas-palette", "version": 1, "colours": ["#ff0000"] }'
+ */
+export declare const exportPaletteFile: (colours: readonly string[], format?: string) => string;
+/**
+ * Read the colours (as lowercase `#rrggbb`) in a colour palette file of one of the given formats (PaintCanvas's by
+ * default). Throws a `PaletteFileError` if it isn't valid JSON or a compatible file.
+ *
+ * @example
+ * parsePaletteFile('{ "format": "paintcanvas-palette", "version": 1, "colours": ["#FF0000"] }'); // ["#ff0000"]
+ */
+export declare const parsePaletteFile: (text: string, formats?: readonly string[]) => string[];

package/dist/lib/palette/index.js

@@ -0,0 +1,82 @@
+import { formatErrors } from "../presets/index.js";
+import { validatePaletteFile } from "../validation/validators.generated.js";
+import { HEX_COLOUR_PATTERN, MAX_PALETTE_COLOURS, MAX_PALETTE_FILE_FORMAT_LENGTH, PALETTE_FILE_FORMAT, PALETTE_FILE_FORMATS, PALETTE_FILE_VERSION, paletteFileSchema } from "./schema.js";
+// src/lib/palette/index.ts
+/** The colours a palette starts with */
+var DEFAULT_PALETTE = [
+	"#2c6bff",
+	"#8f3de8",
+	"#f40f95",
+	"#fb234a",
+	"#fe7e07",
+	"#ffd52c",
+	"#6dc905",
+	"#21e887",
+	"#13c3f4",
+	"#000000",
+	"#333333",
+	"#666666",
+	"#999999",
+	"#cccccc",
+	"#ffffff"
+];
+/** Messages shown when importing or exporting a palette fails */
+var PALETTE_FILE_ERRORS = {
+	incompatible: "Colour palette JSON file not compatible",
+	read: "Failed to read colour palette JSON file"
+};
+/** Importing a palette failed, with a message for the user */
+var PaletteFileError = class extends Error {};
+/**
+* Check a colour palette file against `paletteFileSchema`.
+*
+* @example
+* isValidPaletteFile({ format: "paintcanvas-palette", version: 1, colours: ["#ff0000"] }).valid; // true
+*/
+var isValidPaletteFile = (input) => validatePaletteFile(input) ? {
+	valid: true,
+	value: input
+} : {
+	valid: false,
+	errors: formatErrors(validatePaletteFile.errors)
+};
+/**
+* The file name a palette is exported to on a day, starting with a prefix (see `PaintCanvasNames.filePrefix`).
+*
+* @example
+* paletteFileName(new Date(2026, 10, 4)); // "paintcanvas-palette-2026-11-04.json"
+*/
+var paletteFileName = (date = /* @__PURE__ */ new Date(), prefix = "paintcanvas") => {
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${prefix}-palette-${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}.json`;
+};
+/**
+* Write colours to a colour palette file (JSON) of a format (see `PaintCanvasNames.paletteFileFormat`).
+*
+* @example
+* exportPaletteFile(["#ff0000"]); // '{ "format": "paintcanvas-palette", "version": 1, "colours": ["#ff0000"] }'
+*/
+var exportPaletteFile = (colours, format = PALETTE_FILE_FORMAT) => JSON.stringify({
+	format,
+	version: 1,
+	colours
+}, null, 2);
+/**
+* Read the colours (as lowercase `#rrggbb`) in a colour palette file of one of the given formats (PaintCanvas's by
+* default). Throws a `PaletteFileError` if it isn't valid JSON or a compatible file.
+*
+* @example
+* parsePaletteFile('{ "format": "paintcanvas-palette", "version": 1, "colours": ["#FF0000"] }'); // ["#ff0000"]
+*/
+var parsePaletteFile = (text, formats = PALETTE_FILE_FORMATS) => {
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		throw new PaletteFileError(PALETTE_FILE_ERRORS.incompatible);
+	}
+	const result = isValidPaletteFile(data);
+	if (!result.valid || !formats.includes(result.value.format)) throw new PaletteFileError(PALETTE_FILE_ERRORS.incompatible);
+	return result.value.colours.map((colour) => colour.toLowerCase());
+};
+export { DEFAULT_PALETTE, HEX_COLOUR_PATTERN, MAX_PALETTE_COLOURS, MAX_PALETTE_FILE_FORMAT_LENGTH, PALETTE_FILE_ERRORS, PALETTE_FILE_FORMAT, PALETTE_FILE_FORMATS, PALETTE_FILE_VERSION, PaletteFileError, exportPaletteFile, isValidPaletteFile, paletteFileName, paletteFileSchema, parsePaletteFile };

package/dist/lib/palette/schema.d.ts

@@ -0,0 +1,45 @@
+/** The `format` of a colour palette file, unless the implementer names their own (see `PaintCanvasNames`) */
+export declare const PALETTE_FILE_FORMAT = "paintcanvas-palette";
+/** Formats of colour palette files that are imported by default */
+export declare const PALETTE_FILE_FORMATS: readonly string[];
+/** The version of the colour palette file format */
+export declare const PALETTE_FILE_VERSION = 1;
+/** Most colours in a palette (and in one file) */
+export declare const MAX_PALETTE_COLOURS = 1000;
+/** Longest palette file format name (characters) */
+export declare const MAX_PALETTE_FILE_FORMAT_LENGTH = 100;
+/** Matches a `#rrggbb` colour in any case */
+export declare const HEX_COLOUR_PATTERN = "^#[0-9a-fA-F]{6}$";
+/** A colour palette file: what users export and import */
+export interface PaletteFile {
+    /** Names the app or kind of file, e.g. `PALETTE_FILE_FORMAT` */
+    format: string;
+    version: typeof PALETTE_FILE_VERSION;
+    /** Colours as `#rrggbb`, in palette order */
+    colours: string[];
+}
+/** Schema of a colour palette file */
+export declare const paletteFileSchema: {
+    readonly $id: "paintcanvas/palette-file";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["format", "version", "colours"];
+    readonly properties: {
+        readonly format: {
+            readonly type: "string";
+            readonly minLength: 1;
+            readonly maxLength: 100;
+        };
+        readonly version: {
+            readonly const: 1;
+        };
+        readonly colours: {
+            readonly type: "array";
+            readonly maxItems: 1000;
+            readonly items: {
+                readonly type: "string";
+                readonly pattern: "^#[0-9a-fA-F]{6}$";
+            };
+        };
+    };
+};

package/dist/lib/palette/schema.js

@@ -0,0 +1,41 @@
+// src/lib/palette/schema.ts
+/** The `format` of a colour palette file, unless the implementer names their own (see `PaintCanvasNames`) */
+var PALETTE_FILE_FORMAT = "paintcanvas-palette";
+/** Formats of colour palette files that are imported by default */
+var PALETTE_FILE_FORMATS = [PALETTE_FILE_FORMAT];
+/** The version of the colour palette file format */
+var PALETTE_FILE_VERSION = 1;
+/** Most colours in a palette (and in one file) */
+var MAX_PALETTE_COLOURS = 1e3;
+/** Longest palette file format name (characters) */
+var MAX_PALETTE_FILE_FORMAT_LENGTH = 100;
+/** Matches a `#rrggbb` colour in any case */
+var HEX_COLOUR_PATTERN = "^#[0-9a-fA-F]{6}$";
+/** Schema of a colour palette file */
+var paletteFileSchema = {
+	$id: "paintcanvas/palette-file",
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"format",
+		"version",
+		"colours"
+	],
+	properties: {
+		format: {
+			type: "string",
+			minLength: 1,
+			maxLength: 100
+		},
+		version: { const: 1 },
+		colours: {
+			type: "array",
+			maxItems: MAX_PALETTE_COLOURS,
+			items: {
+				type: "string",
+				pattern: HEX_COLOUR_PATTERN
+			}
+		}
+	}
+};
+export { HEX_COLOUR_PATTERN, MAX_PALETTE_COLOURS, MAX_PALETTE_FILE_FORMAT_LENGTH, PALETTE_FILE_FORMAT, PALETTE_FILE_FORMATS, PALETTE_FILE_VERSION, paletteFileSchema };

package/dist/lib/rendering/cursors/index.d.ts

@@ -8,6 +8,8 @@
  * svgCursor("M4 4 L20 20", [4, 4], "crosshair"); // 'url("data:image/svg+xml,...") 4 4, crosshair'
  */
 export declare const svgCursor: (path: string, hotspot: [number, number], fallback: string) => string;
+/** Deleting: an "X", e.g. over a brush preset or saved colour that a click deletes (Alt/Option held); the point is its middle */
+export declare const DELETE_CURSOR: string;
 /** Colour sample (eyedropper): a pipette pointing down to the left; the point is at its tip */
 export declare const EYEDROPPER_CURSOR: string;
 /** Polygon lasso: a straight-edged loop with a tail; the point is at the tail's end */

package/dist/lib/rendering/cursors/index.js

@@ -12,6 +12,8 @@ var svgCursor = (path, hotspot, fallback) => {
 	const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke-linecap="round" stroke-linejoin="round"><path d="${path}" stroke="#ffffff" stroke-width="3.5"/><path d="${path}" stroke="#000000" stroke-width="1.5"/></svg>`;
 	return `url("data:image/svg+xml,${encodeURIComponent(svg)}") ${hotspot[0]} ${hotspot[1]}, ${fallback}`;
 };
+/** Deleting: an "X", e.g. over a brush preset or saved colour that a click deletes (Alt/Option held); the point is its middle */
+var DELETE_CURSOR = svgCursor("M6 6 L18 18 M18 6 L6 18", [12, 12], "not-allowed");
 /** Colour sample (eyedropper): a pipette pointing down to the left; the point is at its tip */
 var EYEDROPPER_CURSOR = svgCursor("M2 22 L3 18 L12 9 L15 12 L6 21 Z M10 7 L17 14 M14 10 L18 6 C19 5 20 4 21 5 C22 6 21 7 20 8 L16 12", [2, 22], "crosshair");
 /** Polygon lasso: a straight-edged loop with a tail; the point is at the tail's end */
@@ -20,4 +22,4 @@ var POLYGON_LASSO_CURSOR = svgCursor("M3 21 L7 15 M7 15 L5 6 L13 2 L21 7 L17 15
 var FREEFORM_LASSO_CURSOR = svgCursor("M3 21 C3 19 5 18 7 17 C7 17 5 16 4 14 C2 10 4 6 8 5 C11 4 12 6 15 4 C18 3 22 6 20 10 C19 13 21 15 18 16 C15 17 11 15 9 16 C8 16.5 7.5 17 7 17", [3, 21], "crosshair");
 /** Rotate: the browser's grab cursor, as browsers have no standard rotate cursor */
 var ROTATE_CURSOR = "grab";
-export { EYEDROPPER_CURSOR, FREEFORM_LASSO_CURSOR, POLYGON_LASSO_CURSOR, ROTATE_CURSOR, svgCursor };
+export { DELETE_CURSOR, EYEDROPPER_CURSOR, FREEFORM_LASSO_CURSOR, POLYGON_LASSO_CURSOR, ROTATE_CURSOR, svgCursor };

package/dist/lib/rendering/sample/index.js

@@ -1,3 +1,4 @@
+import { rgbToHex } from "../../utils/colour/index.js";
 import { CANVAS_BACKGROUND, drawLayers } from "../compositing/index.js";
 // src/lib/rendering/sample/index.ts
 /** How many canvas pixels across the sampling window enlarges */
@@ -12,11 +13,11 @@ var PREVIEW_MAX_PIXELS = 100;
 * @example
 * toHex(255, 0, 128); // "#ff0080"
 */
-var toHex = (r, g, b) => `#${[
+var toHex = (r, g, b) => rgbToHex({
 	r,
 	g,
 	b
-].map((c) => Math.round(c).toString(16).padStart(2, "0")).join("")}`;
+});
 /**
 * The average colour of RGBA pixels, counting every pixel that isn't fully transparent (transparent pixels are outside
 * the canvas). Undefined if all are transparent.

package/dist/lib/settings/index.d.ts

@@ -0,0 +1,63 @@
+import type PaintCanvas from "../classes/PaintCanvas";
+import { type AppSettings } from "./schema";
+export * from "./schema";
+/** Messages shown when importing settings fails */
+export declare const SETTINGS_FILE_ERRORS: {
+    readonly incompatible: "Settings JSON file not compatible";
+    readonly read: "Failed to read settings JSON file";
+};
+/** Importing settings failed, with a message for the user */
+export declare class SettingsFileError extends Error {
+}
+/** Result of checking settings */
+export type SettingsValidationResult = {
+    valid: true;
+    value: AppSettings;
+} | {
+    valid: false;
+    errors: string[];
+};
+/**
+ * Check app settings (e.g. kept in the browser) against `settingsSchema`.
+ *
+ * @example
+ * isValidSettings({ palette: ["#ff0000"] }).valid; // true
+ */
+export declare const isValidSettings: (input: unknown) => SettingsValidationResult;
+/**
+ * The app settings of a canvas: its input settings, keyboard shortcuts, colour palette and colours.
+ *
+ * @example
+ * collectSettings(canvas).palette; // ["#2c6bff", ...]
+ */
+export declare const collectSettings: (app: PaintCanvas) => AppSettings;
+/**
+ * Use app settings on a canvas, e.g. ones kept in the browser or imported. Parts left out stay as they are; invalid
+ * values within a part are left out (see each part's sanitising).
+ *
+ * @example
+ * applySettings(canvas, { colours: { foreground: "#ff0000", background: "#ffffff" } });
+ */
+export declare const applySettings: (app: PaintCanvas, settings: AppSettings) => void;
+/**
+ * The file name settings are exported to on a day, starting with a prefix (see `PaintCanvasNames.filePrefix`).
+ *
+ * @example
+ * settingsFileName(new Date(2026, 10, 4)); // "paintcanvas-settings-2026-11-04.json"
+ */
+export declare const settingsFileName: (date?: Date, prefix?: string) => string;
+/**
+ * Write app settings to a settings file (JSON) of a format (see `PaintCanvasNames.settingsFileFormat`).
+ *
+ * @example
+ * exportSettingsFile(collectSettings(canvas)); // '{ "format": "paintcanvas-settings", "version": 1, "settings": {...} }'
+ */
+export declare const exportSettingsFile: (settings: AppSettings, format?: string) => string;
+/**
+ * Read the app settings in a settings file of one of the given formats (PaintCanvas's by default). Throws a
+ * `SettingsFileError` if it isn't valid JSON or a compatible file.
+ *
+ * @example
+ * applySettings(canvas, parseSettingsFile(text));
+ */
+export declare const parseSettingsFile: (text: string, formats?: readonly string[]) => AppSettings;

package/dist/lib/settings/index.js

@@ -0,0 +1,91 @@
+import { formatErrors } from "../presets/index.js";
+import { validateSettings, validateSettingsFile } from "../validation/validators.generated.js";
+import { MAX_SAVED_SHORTCUTS, MAX_SETTINGS_FILE_FORMAT_LENGTH, SETTINGS_FILE_FORMAT, SETTINGS_FILE_FORMATS, SETTINGS_FILE_VERSION, keyComboSchema, settingsFileSchema, settingsSchema } from "./schema.js";
+// src/lib/settings/index.ts
+/** Messages shown when importing settings fails */
+var SETTINGS_FILE_ERRORS = {
+	incompatible: "Settings JSON file not compatible",
+	read: "Failed to read settings JSON file"
+};
+/** Importing settings failed, with a message for the user */
+var SettingsFileError = class extends Error {};
+/**
+* Check app settings (e.g. kept in the browser) against `settingsSchema`.
+*
+* @example
+* isValidSettings({ palette: ["#ff0000"] }).valid; // true
+*/
+var isValidSettings = (input) => validateSettings(input) ? {
+	valid: true,
+	value: input
+} : {
+	valid: false,
+	errors: formatErrors(validateSettings.errors)
+};
+/**
+* The app settings of a canvas: its input settings, keyboard shortcuts, colour palette and colours.
+*
+* @example
+* collectSettings(canvas).palette; // ["#2c6bff", ...]
+*/
+var collectSettings = (app) => ({
+	input: structuredClone(app.input.data),
+	shortcuts: structuredClone(app.shortcuts.bindings),
+	palette: [...app.palette.colours],
+	colours: { ...app.colours }
+});
+/**
+* Use app settings on a canvas, e.g. ones kept in the browser or imported. Parts left out stay as they are; invalid
+* values within a part are left out (see each part's sanitising).
+*
+* @example
+* applySettings(canvas, { colours: { foreground: "#ff0000", background: "#ffffff" } });
+*/
+var applySettings = (app, settings) => {
+	if (settings.input) app.input.update(settings.input);
+	if (settings.shortcuts) app.shortcuts.load(settings.shortcuts);
+	if (settings.palette) app.palette.set(settings.palette);
+	if (settings.colours) {
+		app.setColour(settings.colours.foreground, "foreground");
+		app.setColour(settings.colours.background, "background");
+	}
+};
+/**
+* The file name settings are exported to on a day, starting with a prefix (see `PaintCanvasNames.filePrefix`).
+*
+* @example
+* settingsFileName(new Date(2026, 10, 4)); // "paintcanvas-settings-2026-11-04.json"
+*/
+var settingsFileName = (date = /* @__PURE__ */ new Date(), prefix = "paintcanvas") => {
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${prefix}-settings-${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}.json`;
+};
+/**
+* Write app settings to a settings file (JSON) of a format (see `PaintCanvasNames.settingsFileFormat`).
+*
+* @example
+* exportSettingsFile(collectSettings(canvas)); // '{ "format": "paintcanvas-settings", "version": 1, "settings": {...} }'
+*/
+var exportSettingsFile = (settings, format = SETTINGS_FILE_FORMAT) => JSON.stringify({
+	format,
+	version: 1,
+	settings
+}, null, 2);
+/**
+* Read the app settings in a settings file of one of the given formats (PaintCanvas's by default). Throws a
+* `SettingsFileError` if it isn't valid JSON or a compatible file.
+*
+* @example
+* applySettings(canvas, parseSettingsFile(text));
+*/
+var parseSettingsFile = (text, formats = SETTINGS_FILE_FORMATS) => {
+	let data;
+	try {
+		data = JSON.parse(text);
+	} catch {
+		throw new SettingsFileError(SETTINGS_FILE_ERRORS.incompatible);
+	}
+	if (!validateSettingsFile(data) || !formats.includes(data.format)) throw new SettingsFileError(SETTINGS_FILE_ERRORS.incompatible);
+	return data.settings;
+};
+export { MAX_SAVED_SHORTCUTS, MAX_SETTINGS_FILE_FORMAT_LENGTH, SETTINGS_FILE_ERRORS, SETTINGS_FILE_FORMAT, SETTINGS_FILE_FORMATS, SETTINGS_FILE_VERSION, SettingsFileError, applySettings, collectSettings, exportSettingsFile, isValidSettings, keyComboSchema, parseSettingsFile, settingsFileName, settingsFileSchema, settingsSchema };