@lvl99dotcom/paintcanvas 0.6.0 → 0.8.0

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

@@ -0,0 +1,119 @@
+// src/lib/classes/RemoteDocumentAutosave/index.ts
+/** How often changes are saved to the remote store, at most (milliseconds): every 5 minutes */
+var REMOTE_SAVE_INTERVAL_MS = 3e5;
+/** Event dispatched when saving fails (detail: the error) */
+var REMOTE_AUTOSAVE_ERROR_EVENT = "error";
+/**
+* Keeps a canvas's drawing in a remote store (e.g. a user's account online), less often than the browser keeps it:
+* every `intervalMs` while there are changes not saved yet, or when asked (`save`). The whole document is saved each
+* time, with a thumbnail.
+*
+* Dispatches `change` when saving starts, makes progress or ends, and `error` (detail: the error) when it fails (the
+* changes are tried again next time).
+*
+* @example
+* const autosave = new RemoteDocumentAutosave(canvas, myAccountStore);
+* autosave.start();
+* saveButton.onclick = () => autosave.save();
+*/
+var RemoteDocumentAutosave = class extends EventTarget {
+	/** Where the drawing is kept */
+	store;
+	/** The last saving error, until a save succeeds */
+	error;
+	/** When the drawing was last saved, if it has been */
+	lastSaved;
+	/** How much of the save under way is done (0 to 1), if known */
+	progress;
+	canvas;
+	intervalMs;
+	timer;
+	/** The layers being watched for changes */
+	watched;
+	/** Whether there are changes not saved yet */
+	dirty = false;
+	/** The save being written, if any */
+	current;
+	onChange = () => {
+		this.dirty = true;
+	};
+	onCanvasChange = () => {
+		this.dirty = true;
+		if (this.canvas.layers === this.watched) return;
+		this.watched?.removeEventListener("change", this.onChange);
+		this.watched = this.canvas.layers;
+		this.watched.addEventListener("change", this.onChange);
+	};
+	constructor(canvas, store, options = {}) {
+		super();
+		this.canvas = canvas;
+		this.store = store;
+		this.intervalMs = options.intervalMs ?? 3e5;
+	}
+	/** Whether a save is under way */
+	get saving() {
+		return this.current !== void 0;
+	}
+	/** Whether there are changes not saved yet */
+	get hasChanges() {
+		return this.dirty;
+	}
+	/**
+	* Start saving changes every `intervalMs`.
+	*/
+	start() {
+		if (this.timer !== void 0) return;
+		this.watched = this.canvas.layers;
+		this.watched.addEventListener("change", this.onChange);
+		this.canvas.addEventListener("change", this.onCanvasChange);
+		this.timer = setInterval(() => {
+			if (this.dirty) this.save();
+		}, this.intervalMs);
+	}
+	/**
+	* Stop saving changes (a save under way finishes). Changes not saved yet aren't saved.
+	*/
+	stop() {
+		clearInterval(this.timer);
+		this.timer = void 0;
+		this.watched?.removeEventListener("change", this.onChange);
+		this.watched = void 0;
+		this.canvas.removeEventListener("change", this.onCanvasChange);
+	}
+	/**
+	* Save the drawing now (e.g. when the user asks). While a save is under way, that save is returned.
+	*/
+	save() {
+		if (this.current) return this.current;
+		this.dirty = false;
+		this.progress = void 0;
+		this.current = this.write().finally(() => {
+			this.current = void 0;
+			this.progress = void 0;
+			this.notify();
+		});
+		this.notify();
+		return this.current;
+	}
+	/** Save the whole drawing */
+	async write() {
+		try {
+			const document = await this.canvas.createDocument();
+			await this.store.save(document, (done) => {
+				this.progress = Math.min(1, Math.max(0, done));
+				this.notify();
+			});
+			this.lastSaved = /* @__PURE__ */ new Date();
+			this.error = void 0;
+		} catch (error) {
+			this.dirty = true;
+			this.error = error;
+			this.dispatchEvent(new CustomEvent(REMOTE_AUTOSAVE_ERROR_EVENT, { detail: error }));
+		}
+	}
+	/** Tell listeners something changed */
+	notify() {
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { REMOTE_AUTOSAVE_ERROR_EVENT, REMOTE_SAVE_INTERVAL_MS, RemoteDocumentAutosave as default };

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

@@ -10,9 +10,11 @@ export interface SettingsAutosaveOptions {
     delayMs?: number;
 }
 /**
- * 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.
+ * Keeps a canvas's app settings (input settings, keyboard shortcuts, colour palettes, 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. While the canvas keeps colour palettes or profile graphs in stores of their own (see
+ * `PaintCanvas.useAssetStores`), they are left out of the saved settings (ones restored from older settings are added,
+ * so those stores keep them).
  *
  * Dispatches an `error` event (with the error as `detail`) when loading or saving fails.
  *
@@ -46,6 +48,8 @@ export default class SettingsAutosave extends EventTarget {
     save(): Promise<void>;
     /** Restore the saved settings, then listen for changes */
     private start;
+    /** The canvas's settings to save, without the assets kept in stores of their own */
+    private collect;
     /** Save soon, after changes stop for a moment */
     private schedule;
     /** Tell listeners loading or saving failed */

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

@@ -5,9 +5,11 @@ 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, 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.
+* Keeps a canvas's app settings (input settings, keyboard shortcuts, colour palettes, 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. While the canvas keeps colour palettes or profile graphs in stores of their own (see
+* `PaintCanvas.useAssetStores`), they are left out of the saved settings (ones restored from older settings are added,
+* so those stores keep them).
 *
 * Dispatches an `error` event (with the error as `detail`) when loading or saving fails.
 *
@@ -42,8 +44,10 @@ var SettingsAutosave = class extends EventTarget {
 			app,
 			app.input,
 			app.shortcuts,
-			app.palette,
+			app.palettes,
 			app.profiles,
+			app.customPresets,
+			app.settingsExtensions,
 			app.ui
 		];
 	}
@@ -63,7 +67,7 @@ var SettingsAutosave = class extends EventTarget {
 	*/
 	async save() {
 		this.timer = void 0;
-		const settings = collectSettings(this.app);
+		const settings = this.collect();
 		const json = JSON.stringify(settings);
 		if (json === this.saved) return;
 		this.saved = json;
@@ -76,15 +80,32 @@ var SettingsAutosave = class extends EventTarget {
 	}
 	/** Restore the saved settings, then listen for changes */
 	async start() {
+		let older = false;
 		try {
 			const result = isValidSettings(await this.store.load());
-			if (result.valid && !this.stopped) applySettings(this.app, result.value);
+			if (result.valid && !this.stopped) {
+				await applySettings(this.app, result.value);
+				older = result.value.palette !== void 0;
+			}
 		} catch (error) {
 			this.fail(error);
 		}
 		if (this.stopped) return;
-		this.saved = JSON.stringify(collectSettings(this.app));
+		this.saved = JSON.stringify(this.collect());
 		for (const source of this.sources) source.addEventListener("change", this.onChange);
+		if (older) {
+			this.saved = void 0;
+			await this.save();
+		}
+	}
+	/** The canvas's settings to save, without the assets kept in stores of their own */
+	collect() {
+		const stores = this.app.assetStores;
+		return collectSettings(this.app, { without: [
+			"brushes",
+			"palettes",
+			"profiles"
+		].filter((kind) => stores[kind] !== void 0) });
 	}
 	/** Save soon, after changes stop for a moment */
 	schedule() {

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

@@ -0,0 +1,67 @@
+/** Keys of app settings PaintCanvas uses (and those of settings files), which extensions can't use */
+export declare const RESERVED_SETTINGS_KEYS: readonly string[];
+/**
+ * Settings a wrapper app adds to PaintCanvas's app settings, under a key of its own (e.g. `livecanvas`). They're kept,
+ * exported and imported with the app settings, wherever those are kept.
+ *
+ * @example
+ * const extension: SettingsExtension<{ sound: boolean }> = {
+ *   key: "livecanvas",
+ *   validate: (value): value is { sound: boolean } => typeof (value as { sound?: unknown })?.sound === "boolean",
+ *   collect: () => ({ sound: mySettings.sound }),
+ *   apply: (value) => mySettings.update(value),
+ *   target: mySettings, // dispatches `change`
+ * };
+ */
+export interface SettingsExtension<T = unknown> {
+    /** Key of its settings in the app settings (not one of `RESERVED_SETTINGS_KEYS`) */
+    key: string;
+    /** Whether a value (read from a store or a file, so untrusted) is valid settings for it */
+    validate(value: unknown): value is T;
+    /** Its current settings (JSON-friendly) */
+    collect(): T;
+    /** Use settings read from a store or a file */
+    apply(value: T): void;
+    /** Dispatches `change` when its settings change, so they're saved */
+    target?: EventTarget;
+}
+/**
+ * The settings extensions of a canvas (see `SettingsExtension`). Settings read for an extension that isn't added yet are
+ * kept, so they're used when it's added and aren't lost when the settings are saved meanwhile.
+ *
+ * Dispatches `change` when an extension's settings change, or one is added or removed.
+ *
+ * @example
+ * canvas.settingsExtensions.add(liveCanvasSettings);
+ */
+export default class SettingsExtensions extends EventTarget {
+    private readonly extensions;
+    /** Settings read for extensions not added yet, by key */
+    private readonly pending;
+    private readonly onChange;
+    /** The extensions added, in order */
+    get items(): readonly SettingsExtension[];
+    /**
+     * Add an extension, using settings already read for it if they're valid. Throws if its key is PaintCanvas's or
+     * another extension's.
+     */
+    add<T>(extension: SettingsExtension<T>): void;
+    /**
+     * Remove an extension by key. Returns whether it was there.
+     */
+    remove(key: string): boolean;
+    /**
+     * Every extension's settings, by key, with settings kept for extensions not added yet.
+     *
+     * @example
+     * canvas.settingsExtensions.collect(); // { livecanvas: { sound: true } }
+     */
+    collect(): Record<string, unknown>;
+    /**
+     * Use the parts of app settings that aren't PaintCanvas's: each extension's, if valid; ones for extensions not added
+     * yet are kept for them.
+     */
+    apply(settings: Record<string, unknown>): void;
+    /** Tell listeners something changed */
+    private notify;
+}

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

@@ -0,0 +1,88 @@
+// src/lib/classes/SettingsExtensions/index.ts
+/** Keys of app settings PaintCanvas uses (and those of settings files), which extensions can't use */
+var RESERVED_SETTINGS_KEYS = [
+	"$schema",
+	"@type",
+	"input",
+	"shortcuts",
+	"palette",
+	"palettes",
+	"colours",
+	"profiles",
+	"brushes",
+	"ui"
+];
+/**
+* The settings extensions of a canvas (see `SettingsExtension`). Settings read for an extension that isn't added yet are
+* kept, so they're used when it's added and aren't lost when the settings are saved meanwhile.
+*
+* Dispatches `change` when an extension's settings change, or one is added or removed.
+*
+* @example
+* canvas.settingsExtensions.add(liveCanvasSettings);
+*/
+var SettingsExtensions = class extends EventTarget {
+	extensions = /* @__PURE__ */ new Map();
+	/** Settings read for extensions not added yet, by key */
+	pending = /* @__PURE__ */ new Map();
+	onChange = () => this.notify();
+	/** The extensions added, in order */
+	get items() {
+		return [...this.extensions.values()];
+	}
+	/**
+	* Add an extension, using settings already read for it if they're valid. Throws if its key is PaintCanvas's or
+	* another extension's.
+	*/
+	add(extension) {
+		const { key } = extension;
+		if (RESERVED_SETTINGS_KEYS.includes(key) || this.extensions.has(key)) throw new Error(`Settings key "${key}" is already used`);
+		this.extensions.set(key, extension);
+		if (this.pending.has(key)) {
+			const value = this.pending.get(key);
+			this.pending.delete(key);
+			if (extension.validate(value)) extension.apply(value);
+		}
+		extension.target?.addEventListener("change", this.onChange);
+		this.notify();
+	}
+	/**
+	* Remove an extension by key. Returns whether it was there.
+	*/
+	remove(key) {
+		const extension = this.extensions.get(key);
+		if (!extension) return false;
+		extension.target?.removeEventListener("change", this.onChange);
+		this.extensions.delete(key);
+		this.notify();
+		return true;
+	}
+	/**
+	* Every extension's settings, by key, with settings kept for extensions not added yet.
+	*
+	* @example
+	* canvas.settingsExtensions.collect(); // { livecanvas: { sound: true } }
+	*/
+	collect() {
+		const parts = Object.fromEntries(this.pending);
+		for (const [key, extension] of this.extensions) parts[key] = extension.collect();
+		return parts;
+	}
+	/**
+	* Use the parts of app settings that aren't PaintCanvas's: each extension's, if valid; ones for extensions not added
+	* yet are kept for them.
+	*/
+	apply(settings) {
+		for (const [key, value] of Object.entries(settings)) {
+			if (RESERVED_SETTINGS_KEYS.includes(key) || value === void 0) continue;
+			const extension = this.extensions.get(key);
+			if (!extension) this.pending.set(key, value);
+			else if (extension.validate(value)) extension.apply(value);
+		}
+	}
+	/** Tell listeners something changed */
+	notify() {
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { RESERVED_SETTINGS_KEYS, SettingsExtensions as default };

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 };

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

@@ -1,17 +1,74 @@
-import type { PaintCanvasDocument } from "./schema";
+import type { AssetAuthor, AssetAuthorDetails } from "../assets/schema";
+import { type DocumentFile, type DocumentInfo, type DrawingDocument } from "./schema";
 export * from "./schema";
-/** Result of checking a document */
+/** The `format` of documents from before versioned schemas */
+export declare const LEGACY_DOCUMENT_FORMAT = "paintcanvas-document";
+/** Name of a new document, or one from before documents had names */
+export declare const UNTITLED_DOCUMENT_NAME = "Untitled";
+/** Result of checking a document file */
 export type DocumentValidationResult = {
     valid: true;
-    value: PaintCanvasDocument;
+    value: DocumentFile;
 } | {
     valid: false;
     errors: string[];
 };
 /**
- * Check a document (e.g. read from a file) against `documentSchema`, and that its selected layer exists.
+ * Check a document file (e.g. read from a file) against `documentSchema`, and that its selected layer exists.
  *
  * @example
  * isValidDocument(JSON.parse(text)).valid; // true
  */
 export declare const isValidDocument: (input: unknown) => DocumentValidationResult;
+/**
+ * An author's details: their name alone becomes `{ name }`.
+ *
+ * @example
+ * authorDetails("Ada"); // { name: "Ada" }
+ */
+export declare const authorDetails: (author: AssetAuthor) => AssetAuthorDetails;
+/**
+ * Whether two authors are the same person: by DID when both have one, otherwise by handle when both have one,
+ * otherwise by name.
+ *
+ * @example
+ * sameAuthor({ name: "Ada", handle: "ada.test" }, { name: "Ada L", handle: "ada.test" }); // true
+ */
+export declare const sameAuthor: (a: AssetAuthorDetails, b: AssetAuthorDetails) => boolean;
+/**
+ * A document's authors with another added at the end, unless they're already one of them.
+ *
+ * @example
+ * withAuthor([{ name: "Ada" }], "Ann"); // [{ name: "Ada" }, { name: "Ann" }]
+ */
+export declare const withAuthor: (authors: readonly AssetAuthorDetails[], author: AssetAuthor) => AssetAuthorDetails[];
+/**
+ * Details for a new document: a new ID, a name, an author and the time now.
+ *
+ * @example
+ * newDocumentInfo("Ada"); // { id: "1b9d…", name: "Untitled", author: [{ name: "Ada" }], dateCreated: "2026-…", … }
+ */
+export declare const newDocumentInfo: (author?: AssetAuthor, name?: string, now?: Date) => DocumentInfo;
+/**
+ * A document as a file (JSON), with its images as PNG data URLs.
+ *
+ * @example
+ * JSON.stringify(await documentToFile(await canvas.createDocument()));
+ */
+export declare const documentToFile: (document: DrawingDocument) => Promise<DocumentFile>;
+/**
+ * Read a document file (e.g. parsed from JSON), with its images as PNG blobs. Files from before versioned schemas are
+ * migrated. Throws an `AssetFileError`: `invalid` if it isn't a document or doesn't match its schema, `unsupported` if
+ * it's a version the app can't read.
+ *
+ * @example
+ * await canvas.openDocument(documentFromFile(JSON.parse(text)));
+ */
+export declare const documentFromFile: (data: unknown, now?: Date) => DrawingDocument;
+/**
+ * The name of the file a document is exported to, starting with a prefix (see `PaintCanvasNames.filePrefix`).
+ *
+ * @example
+ * documentFileName("Sunset at sea"); // "paintcanvas-sunset-at-sea.json"
+ */
+export declare const documentFileName: (name: string, prefix?: string) => string;