@lvl99dotcom/paintcanvas 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,346 @@
+import { pixelFingerprint } from "../../image/index.js";
+import "../../storage/index.js";
+// src/lib/classes/LayerAutosave/index.ts
+/** How long to wait after the layers change before saving, so quick changes are saved together (milliseconds) */
+var SAVE_DELAY_MS = 500;
+/** Name of the save in the canvas's background work */
+var SAVE_WORK = "save";
+/** Event dispatched when loading or saving fails (detail: the error) */
+var AUTOSAVE_ERROR_EVENT = "error";
+/** Where autosaving is up to */
+var AutosaveState = {
+	/** Waiting to draw (another window may have the drawing) or loading the saved drawing */
+	Starting: "starting",
+	/** Another window has the drawing; this one doesn't save (see `takeOver`) */
+	Elsewhere: "elsewhere",
+	/** The saved drawing is shown, and changes are saved */
+	Ready: "ready",
+	/** Not saving any more (see `stop`) */
+	Stopped: "stopped"
+};
+/**
+* Encode a canvas as a PNG.
+*/
+var encodePng = (canvas) => {
+	canvas.getContext("2d");
+	return canvas.convertToBlob({ type: "image/png" });
+};
+/**
+* Whether a saved drawing has the expected shape and an image for each layer.
+*/
+var isComplete = (drawing, images) => drawing.version === 1 && drawing.layers.length > 0 && drawing.layers.every((layer) => images.has(layer.id)) && drawing.layers.some((layer) => layer.id === drawing.activeLayer);
+/**
+* Keeps a canvas's layers in a store, so the drawing survives reloading the page: restores the saved drawing when it
+* starts, then saves soon after the layers change (once drawing pauses), and straight away when the page is hidden.
+* Only layers whose pixels changed are encoded and saved again; a quick fingerprint of each layer's pixels tells
+* which.
+*
+* Only one window draws on a drawing at a time: the first to start has it, and others wait in the `elsewhere` state
+* (the UI blocks drawing there). When the page is shown again it tries again, and `takeOver` takes the drawing from
+* the other window, which then waits instead. Without Web Locks, every window draws.
+*
+* If the saved drawing can't be loaded or restored, autosaving stops (`stopped`) so the drawing isn't saved over; clear
+* the store to start again. Dispatches `change` when its state or `storedBytes` changes, and `error` (detail: the
+* error) when loading or saving fails. Undo history isn't saved.
+*
+* @example
+* const autosave = new LayerAutosave(canvas, new IndexedDbLayerStore("my-drawing"));
+* autosave.start();
+* autosave.addEventListener("change", () => (blocked.hidden = autosave.state !== AutosaveState.Elsewhere));
+*/
+var LayerAutosave = class extends EventTarget {
+	/** Where the layers are kept */
+	store;
+	/** The last loading or saving error, until a save succeeds */
+	error;
+	currentState = AutosaveState.Starting;
+	canvas;
+	locks;
+	document;
+	encode;
+	decode;
+	delayMs;
+	/** The layers being watched for changes */
+	watched;
+	/** Fingerprints of each layer's pixels as last saved, by layer ID */
+	prints = /* @__PURE__ */ new Map();
+	/** Size in bytes of each layer's image as last saved or restored, by layer ID */
+	sizes = /* @__PURE__ */ new Map();
+	/** Layers whose pixels changed since the last save */
+	changed = /* @__PURE__ */ new Set();
+	/** Whether any layer may have changed since the last save (not only those in `changed`) */
+	checkAll = false;
+	timer;
+	/** The save being written, if any */
+	saving;
+	/** Whether to save again once the current save finishes */
+	again = false;
+	/** Lets go of the drawing's lock, while held */
+	release;
+	onLayersChange = () => {
+		const id = this.watched?.changedLayerId;
+		if (id) this.changed.add(id);
+		else this.checkAll = true;
+		this.schedule();
+	};
+	onCanvasChange = () => {
+		if (this.canvas.layers === this.watched) return;
+		this.watch();
+		this.onLayersChange();
+	};
+	onVisibilityChange = (event) => {
+		if (event.target.visibilityState === "hidden") this.save();
+		else if (this.currentState === AutosaveState.Elsewhere) this.claim(false);
+	};
+	constructor(canvas, store, options = {}) {
+		super();
+		this.canvas = canvas;
+		this.store = store;
+		this.locks = options.locks === void 0 ? globalThis.navigator?.locks ?? null : options.locks;
+		this.document = options.document === void 0 ? globalThis.document ?? null : options.document;
+		this.encode = options.encode ?? encodePng;
+		this.decode = options.decode ?? ((image) => createImageBitmap(image));
+		this.delayMs = options.delayMs ?? 500;
+	}
+	/** Where autosaving is up to (see `AutosaveState`) */
+	get state() {
+		return this.currentState;
+	}
+	/** Total size in bytes of the layer images kept in the store (as last saved or restored) */
+	get storedBytes() {
+		let total = 0;
+		for (const size of this.sizes.values()) total += size;
+		return total;
+	}
+	/** Name of the Web Lock that only one window holds per drawing */
+	get lockName() {
+		return `paintcanvas:${this.store.name}`;
+	}
+	/**
+	* Start: wait for the drawing (unless another window has it), restore it, then save changes.
+	*/
+	start() {
+		this.document?.addEventListener("visibilitychange", this.onVisibilityChange);
+		this.claim(false);
+	}
+	/**
+	* Take the drawing from the window that has it: that window stops saving, and this one restores the drawing as last
+	* saved and saves its changes. Does nothing unless another window has it.
+	*/
+	takeOver() {
+		if (this.currentState === AutosaveState.Elsewhere) this.claim(true);
+	}
+	/**
+	* Stop saving and let other windows have the drawing, after saving any changes not saved yet.
+	*/
+	async stop() {
+		if (this.currentState === AutosaveState.Stopped) return;
+		this.document?.removeEventListener("visibilitychange", this.onVisibilityChange);
+		await this.save();
+		this.unwatch();
+		this.setState(AutosaveState.Stopped);
+		this.letGo();
+	}
+	/**
+	* Save the changes not saved yet now, without waiting. While a save is being written, another follows it.
+	*/
+	save() {
+		clearTimeout(this.timer);
+		this.timer = void 0;
+		if (this.currentState !== AutosaveState.Ready) return Promise.resolve();
+		if (this.saving) {
+			this.again = true;
+			return this.saving;
+		}
+		this.saving = this.write().finally(() => {
+			this.saving = void 0;
+			if (!this.again) return;
+			this.again = false;
+			this.save();
+		});
+		return this.saving;
+	}
+	/**
+	* Ask for the drawing's lock, if there are locks: only if no other window has it, or taking it from the one that
+	* does. Without locks, start straight away.
+	*/
+	claim(steal) {
+		if (!this.locks) {
+			this.begin();
+			return;
+		}
+		this.locks.request(this.lockName, steal ? { steal: true } : { ifAvailable: true }, (lock) => {
+			if (this.currentState === AutosaveState.Stopped) return void 0;
+			if (!lock) {
+				this.setState(AutosaveState.Elsewhere);
+				return;
+			}
+			return new Promise((release) => {
+				this.release = release;
+				this.begin();
+			});
+		}).catch((error) => {
+			if (error?.name === "AbortError") this.lostLock();
+			else this.begin();
+		});
+	}
+	/**
+	* Restore the saved drawing (if any), then watch for changes; with nothing saved, the current drawing is saved. If
+	* the saved drawing can't be loaded or restored (e.g. it's from another version, or an image can't be decoded),
+	* autosaving stops instead, so it isn't saved over.
+	*/
+	async begin() {
+		if (this.currentState === AutosaveState.Stopped) return;
+		this.setState(AutosaveState.Starting);
+		let restored;
+		try {
+			const saved = await this.store.load();
+			restored = saved !== void 0 && await this.restore(saved);
+		} catch (error) {
+			this.fail(error);
+			this.stop();
+			return;
+		}
+		if (this.currentState !== AutosaveState.Starting) return;
+		this.prints = /* @__PURE__ */ new Map();
+		this.watch();
+		if (restored) this.remember();
+		this.setState(AutosaveState.Ready);
+		if (!restored) this.onLayersChange();
+	}
+	/**
+	* Draw a saved drawing onto the canvas. Returns false if autosaving stopped or another window took the drawing
+	* meanwhile. Throws if the drawing is incomplete or from another version, or the canvas can't take it.
+	*/
+	async restore({ drawing, images }) {
+		if (!isComplete(drawing, images)) throw new Error("The saved drawing is incomplete or from another version");
+		const decoded = await Promise.all(drawing.layers.map((layer) => this.decode(images.get(layer.id))));
+		if (this.currentState !== AutosaveState.Starting) return false;
+		this.unwatch();
+		this.canvas.restoreLayers(drawing.width, drawing.height, drawing.layers, decoded, drawing.activeLayer);
+		this.sizes = new Map(drawing.layers.map((layer) => [layer.id, images.get(layer.id).size]));
+		return true;
+	}
+	/**
+	* Remember each layer's pixels as saved (just restored).
+	*/
+	remember() {
+		for (const layer of this.canvas.layers.layers) this.prints.set(layer.id, this.fingerprint(layer.id));
+		this.changed.clear();
+		this.checkAll = false;
+	}
+	/**
+	* Save the drawing, encoding only the layers whose pixels changed since they were last saved.
+	*/
+	async write() {
+		const stack = this.canvas.layers;
+		const { checkAll, changed } = this;
+		this.checkAll = false;
+		this.changed = /* @__PURE__ */ new Set();
+		const prints = /* @__PURE__ */ new Map();
+		try {
+			const encoding = [];
+			for (const layer of stack.layers) {
+				if (!!this.prints.has(layer.id) && !checkAll && !changed.has(layer.id)) continue;
+				const print = this.fingerprint(layer.id);
+				if (print === this.prints.get(layer.id)) continue;
+				prints.set(layer.id, print);
+				encoding.push(this.encode(layer.canvas).then((image) => [layer.id, image]));
+			}
+			const drawing = {
+				version: 1,
+				width: stack.width,
+				height: stack.height,
+				layers: stack.layers.map((layer) => layer.toConfig()),
+				activeLayer: stack.active.id
+			};
+			const images = new Map(await Promise.all(encoding));
+			if (this.currentState !== AutosaveState.Ready) return;
+			await this.store.save(drawing, images);
+			const kept = new Set(drawing.layers.map((layer) => layer.id));
+			for (const id of this.prints.keys()) if (!kept.has(id)) this.prints.delete(id);
+			for (const [id, print] of prints) this.prints.set(id, print);
+			this.error = void 0;
+			this.rememberSizes(kept, images);
+		} catch (error) {
+			for (const id of [...changed, ...prints.keys()]) this.changed.add(id);
+			this.checkAll ||= checkAll;
+			this.fail(error);
+		}
+	}
+	/**
+	* Remember the sizes of the layer images just saved, forgetting layers that are gone, and tell listeners if the total
+	* changed.
+	*/
+	rememberSizes(kept, images) {
+		const before = this.storedBytes;
+		for (const id of this.sizes.keys()) if (!kept.has(id)) this.sizes.delete(id);
+		for (const [id, image] of images) this.sizes.set(id, image.size);
+		if (this.storedBytes !== before) this.dispatchEvent(new Event("change"));
+	}
+	/**
+	* A fingerprint of a layer's pixels.
+	*/
+	fingerprint(id) {
+		const layer = this.canvas.layers.get(id);
+		return pixelFingerprint(layer.context.getImageData(0, 0, layer.width, layer.height).data);
+	}
+	/**
+	* Save once the layers have stopped changing for a moment and drawing pauses.
+	*/
+	schedule() {
+		clearTimeout(this.timer);
+		this.timer = setTimeout(() => this.canvas.background.run(SAVE_WORK, () => void this.save()), this.delayMs);
+	}
+	/**
+	* Watch the canvas and its current layers for changes.
+	*/
+	watch() {
+		this.unwatch();
+		this.watched = this.canvas.layers;
+		this.watched.addEventListener("change", this.onLayersChange);
+		this.canvas.addEventListener("change", this.onCanvasChange);
+	}
+	/**
+	* Stop watching for changes, forgetting a save that hasn't started.
+	*/
+	unwatch() {
+		this.watched?.removeEventListener("change", this.onLayersChange);
+		this.watched = void 0;
+		this.canvas.removeEventListener("change", this.onCanvasChange);
+		clearTimeout(this.timer);
+		this.timer = void 0;
+		this.canvas.background.cancel(SAVE_WORK);
+	}
+	/**
+	* Another window took the drawing: stop saving and wait.
+	*/
+	lostLock() {
+		this.release = void 0;
+		this.unwatch();
+		this.setState(AutosaveState.Elsewhere);
+	}
+	/**
+	* Let other windows have the drawing.
+	*/
+	letGo() {
+		this.release?.();
+		this.release = void 0;
+	}
+	/**
+	* Remember an error and tell listeners.
+	*/
+	fail(error) {
+		this.error = error;
+		this.dispatchEvent(new CustomEvent(AUTOSAVE_ERROR_EVENT, { detail: error }));
+	}
+	/**
+	* Change state and tell listeners.
+	*/
+	setState(state) {
+		if (state === this.currentState) return;
+		this.currentState = state;
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { AUTOSAVE_ERROR_EVENT, AutosaveState, SAVE_DELAY_MS, SAVE_WORK, LayerAutosave as default };

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

@@ -0,0 +1,177 @@
+import Layer, { type CanvasFactory, type LayerConfig } from "../Layer";
+import History from "../History";
+import type { Rect } from "../Viewport";
+/** Most layers a stack can have unless another limit is given */
+export declare const DEFAULT_MAX_LAYERS = 5;
+/**
+ * Manages one user's ordered list of layers. Index 0 is the top-most layer.
+ *
+ * Dispatches a `change` event whenever layers or the active layer change.
+ *
+ * The user's actions are recorded in `history` so they can be undone: creating, duplicating, deleting and moving layers,
+ * changing a layer's blend mode or opacity, and changes to image data (only the changed area).
+ *
+ * @example
+ * const stack = new LayerStack(2000, 2000);
+ * stack.create(); // "Layer 2", placed above and selected
+ * stack.addEventListener("change", render);
+ */
+export default class LayerStack extends EventTarget {
+    /** Canvas width in pixels */
+    readonly width: number;
+    /** Canvas height in pixels */
+    readonly height: number;
+    /** The user's undoable actions on these layers */
+    readonly history: History;
+    private items;
+    private activeId;
+    private createdCount;
+    /** The layer the change being announced is about, when only its pixels changed (see `changedLayerId`) */
+    private onlyChanged?;
+    private readonly createCanvas;
+    /** Most layers the stack can have */
+    readonly maxLayers: number;
+    constructor(width: number, height: number, createCanvas?: CanvasFactory, maxLayers?: number);
+    /** Layers from top to bottom */
+    get layers(): readonly Layer[];
+    /** The selected layer that drawing applies to */
+    get active(): Layer;
+    /** Whether another layer can be created */
+    get canCreate(): boolean;
+    /**
+     * Get a layer by ID. Throws if not found.
+     */
+    get(id: string): Layer;
+    /**
+     * Get a layer's index (0 = top). Throws if not found.
+     */
+    indexOf(id: string): number;
+    /**
+     * Select a layer.
+     */
+    select(id: string): void;
+    /**
+     * Create an empty layer above the active layer and select it.
+     */
+    create(): Layer;
+    /**
+     * Duplicate a layer (settings and image data) above the active layer and select it.
+     */
+    duplicate(id: string): Layer;
+    /**
+     * Replace all layers with new, empty ones (e.g. to restore a saved drawing into), top first, and select the top one.
+     * Returns the new layers.
+     *
+     * @example
+     * const [top, bottom] = stack.replace([{ name: "Sketch" }, { name: "Background", opacity: 0.5 }]);
+     */
+    replace(configs: readonly LayerConfig[]): readonly Layer[];
+    /**
+     * While a `change` event is being dispatched: the layer it's about, when only that layer's image data changed (from
+     * `markChanged`, e.g. a brush stroke); undefined when anything may have changed.
+     */
+    get changedLayerId(): string | undefined;
+    /**
+     * Tell listeners a layer's image data changed (e.g. after a brush stroke), so thumbnails and the map redraw.
+     */
+    markChanged(id: string): void;
+    /**
+     * Remove all image data from a layer, as one undoable action.
+     */
+    clear(id: string): void;
+    /**
+     * Record a layer's image data in an area just before it changes, so the change can be undone. Pass `before` when the
+     * layer has already changed (a copy of the area's image data from before the change, the size of the area).
+     *
+     * @example
+     * stack.recordImage(layer.id, { x: 10, y: 10, width: 50, height: 20 });
+     * layer.context.fillRect(10, 10, 50, 20);
+     * stack.markChanged(layer.id);
+     */
+    recordImage(id: string, area: Rect, before?: OffscreenCanvas): void;
+    /**
+     * Change a layer's image data within an area as one undoable action, then tell listeners.
+     *
+     * @example
+     * stack.changeImage(layer.id, area, (ctx) => ctx.clearRect(area.x, area.y, area.width, area.height));
+     */
+    changeImage(id: string, area: Rect, change: (ctx: OffscreenCanvasRenderingContext2D) => void): void;
+    /**
+     * Whether a layer can be merged into the layer under it: there is one, and both are visible.
+     */
+    canMergeDown(id: string): boolean;
+    /**
+     * Merge a layer into the layer under it as one undoable action, making the two one layer: its pixels are drawn onto
+     * the layer under it as they look (with its opacity and blend mode, whatever the alpha lock), and it is deleted. The
+     * merged layer keeps the lower layer's name and settings, and is selected. Does nothing unless `canMergeDown`.
+     *
+     * @example
+     * stack.mergeDown(stack.active.id);
+     */
+    mergeDown(id: string): void;
+    /**
+     * Delete a layer. The last remaining layer cannot be deleted. If the active layer is deleted, the layer below it (or above, if it was the bottom) is selected.
+     */
+    remove(id: string): void;
+    /**
+     * Move a layer to a new index (0 = top). Layers in between shift to fill the gap.
+     */
+    move(id: string, toIndex: number): void;
+    /**
+     * Move a layer up one place.
+     */
+    moveUp(id: string): void;
+    /**
+     * Move a layer down one place.
+     */
+    moveDown(id: string): void;
+    /**
+     * Move a layer to the top.
+     */
+    moveToTop(id: string): void;
+    /**
+     * Move a layer to the bottom.
+     */
+    moveToBottom(id: string): void;
+    /**
+     * Rename a layer.
+     */
+    rename(id: string, name: string): void;
+    /**
+     * Change a layer's settings (anything except ID and name). Changes to blend mode and opacity can be undone; visibility
+     * and alpha lock cannot.
+     */
+    update(id: string, changes: Partial<Pick<Layer, "blendMode" | "opacity" | "visible" | "alphaLock">>): void;
+    /**
+     * Move a layer to an index and select it.
+     */
+    private moveAndSelect;
+    /**
+     * An undoable change of image data: undo and redo both swap the stored pixels with the layer's, then select the layer.
+     */
+    private imageEntry;
+    /**
+     * Create a layer with the stack's size and canvas factory.
+     */
+    private newLayer;
+    /**
+     * Get the next default layer name, e.g. "Layer 2".
+     */
+    private nextDefaultName;
+    /**
+     * Throw if the layer limit has been reached.
+     */
+    private assertCanCreate;
+    /**
+     * Insert a layer directly above the active layer and select it, as one undoable action. Undo selects `previousId`.
+     */
+    private insertAboveActive;
+    /**
+     * Insert a layer at an index (0 = top) and select it.
+     */
+    private insertAt;
+    /**
+     * Dispatch a `change` event.
+     */
+    private notify;
+}