@lvl99dotcom/paintcanvas 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,48 @@
+import { type default as PaintCanvas } from "../PaintCanvas";
+import { type ShortcutAction } from "../../utils/shortcuts";
+/** Event dispatched on the window for shortcut actions handled elsewhere (e.g. saving) */
+export declare const SHORTCUT_EVENT = "pc-shortcut";
+/**
+ * Listens for key presses and runs the matching shortcut on the app. Shortcuts are ignored while typing in text fields.
+ *
+ * Tool selection, brush/eraser size, interface visibility, select all/deselect, undo/redo, cut/copy/paste, deleting the
+ * masked image data (Delete or Backspace) and finishing or cancelling a
+ * lasso shape are handled here; other actions (and Escape/Enter for later features) dispatch an `pc-shortcut` event with the action as `detail`.
+ * Holding Space pans temporarily; releasing it returns to the selected tool.
+ *
+ * @example
+ * const shortcuts = new KeyboardShortcuts(app);
+ * shortcuts.attach(window);
+ */
+export default class KeyboardShortcuts {
+    private readonly app;
+    private target;
+    private readonly onKeyDown;
+    private readonly onKeyUp;
+    private readonly onBlur;
+    constructor(app: PaintCanvas);
+    /**
+     * Start listening for key presses on a target (usually `window`).
+     */
+    attach(target: EventTarget): void;
+    /**
+     * Stop listening for key presses.
+     */
+    detach(): void;
+    /**
+     * Run the shortcut for a key press, if any. Returns the action run.
+     */
+    handle(event: KeyboardEvent): ShortcutAction | undefined;
+    /**
+     * Return to the selected tool when the hold-to-pan key is released.
+     */
+    handleKeyUp(event: KeyboardEvent): void;
+    /**
+     * Run a shortcut action.
+     */
+    run(action: ShortcutAction): void;
+    /**
+     * Dispatch an action as an `pc-shortcut` event for features handled elsewhere.
+     */
+    private dispatch;
+}

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

@@ -0,0 +1,137 @@
+import { Tool } from "../PaintCanvas/index.js";
+import { isTypingTarget, matchShortcut } from "../../utils/shortcuts/index.js";
+// src/lib/classes/KeyboardShortcuts/index.ts
+/** Event dispatched on the window for shortcut actions handled elsewhere (e.g. saving) */
+var SHORTCUT_EVENT = "pc-shortcut";
+/**
+* Listens for key presses and runs the matching shortcut on the app. Shortcuts are ignored while typing in text fields.
+*
+* Tool selection, brush/eraser size, interface visibility, select all/deselect, undo/redo, cut/copy/paste, deleting the
+* masked image data (Delete or Backspace) and finishing or cancelling a
+* lasso shape are handled here; other actions (and Escape/Enter for later features) dispatch an `pc-shortcut` event with the action as `detail`.
+* Holding Space pans temporarily; releasing it returns to the selected tool.
+*
+* @example
+* const shortcuts = new KeyboardShortcuts(app);
+* shortcuts.attach(window);
+*/
+var KeyboardShortcuts = class {
+	app;
+	target = null;
+	onKeyDown = (event) => this.handle(event);
+	onKeyUp = (event) => this.handleKeyUp(event);
+	onBlur = () => this.app.releaseHeldTool();
+	constructor(app) {
+		this.app = app;
+	}
+	/**
+	* Start listening for key presses on a target (usually `window`).
+	*/
+	attach(target) {
+		this.detach();
+		this.target = target;
+		target.addEventListener("keydown", this.onKeyDown);
+		target.addEventListener("keyup", this.onKeyUp);
+		target.addEventListener("blur", this.onBlur);
+	}
+	/**
+	* Stop listening for key presses.
+	*/
+	detach() {
+		this.target?.removeEventListener("keydown", this.onKeyDown);
+		this.target?.removeEventListener("keyup", this.onKeyUp);
+		this.target?.removeEventListener("blur", this.onBlur);
+		this.target = null;
+	}
+	/**
+	* Run the shortcut for a key press, if any. Returns the action run.
+	*/
+	handle(event) {
+		if (isTypingTarget(event.composedPath()[0] ?? event.target)) return void 0;
+		if (event.key === " " && !event.metaKey && !event.ctrlKey && !event.altKey) {
+			event.preventDefault();
+			this.app.holdTool(Tool.Pan);
+			return;
+		}
+		const action = matchShortcut(event);
+		if (!action) return void 0;
+		event.preventDefault();
+		this.run(action);
+		return action;
+	}
+	/**
+	* Return to the selected tool when the hold-to-pan key is released.
+	*/
+	handleKeyUp(event) {
+		if (event.key === " ") this.app.releaseHeldTool();
+	}
+	/**
+	* Run a shortcut action.
+	*/
+	run(action) {
+		const app = this.app;
+		switch (action.type) {
+			case "tool":
+				app.selectTool(action.tool);
+				break;
+			case "brush-smaller":
+			case "brush-bigger": {
+				const settings = app.tool === Tool.Eraser ? app.eraser : app.tool === Tool.Brush ? app.brush : void 0;
+				if (action.type === "brush-bigger") settings?.grow();
+				else settings?.shrink();
+				break;
+			}
+			case "toggle-interface":
+				app.toggleInterface();
+				break;
+			case "select-all":
+				app.selection.selectAll();
+				break;
+			case "deselect":
+				app.selection.clear();
+				break;
+			case "undo":
+				app.undo();
+				break;
+			case "redo":
+				app.redo();
+				break;
+			case "cut":
+				app.cut();
+				break;
+			case "delete":
+				app.deleteMasked();
+				break;
+			case "copy":
+				app.copy();
+				break;
+			case "paste":
+				app.paste();
+				break;
+			case "commit":
+				if (app.transform.pending) {
+					app.commitTransform();
+					break;
+				}
+				if (app.lasso.active) {
+					app.applyLasso(app.lasso.close());
+					break;
+				}
+				this.dispatch(action);
+				break;
+			case "cancel":
+				app.lasso.cancel();
+				app.cancelTransform();
+				this.dispatch(action);
+				break;
+			default: this.dispatch(action);
+		}
+	}
+	/**
+	* Dispatch an action as an `pc-shortcut` event for features handled elsewhere.
+	*/
+	dispatch(action) {
+		(this.target ?? this.app).dispatchEvent(new CustomEvent(SHORTCUT_EVENT, { detail: action }));
+	}
+};
+export { SHORTCUT_EVENT, KeyboardShortcuts as default };

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

@@ -0,0 +1,86 @@
+/** Layer blending modes, mapped to canvas `globalCompositeOperation` values */
+export declare enum BlendMode {
+    Normal = "source-over",
+    Screen = "screen",
+    Lighten = "lighten",
+    Multiply = "multiply",
+    Darken = "darken",
+    Overlay = "overlay"
+}
+/** Maximum length of a layer name */
+export declare const MAX_LAYER_NAME_LENGTH = 64;
+export interface LayerConfig {
+    /** Unique ID (generated if not given) */
+    id?: string;
+    /** Layer name */
+    name: string;
+    /** Affects how the layer blends with layers below */
+    blendMode?: BlendMode;
+    /** Opacity (0–1) */
+    opacity?: number;
+    /** Visibility */
+    visible?: boolean;
+    /** When enabled, drawing cannot add or remove alpha data on the layer */
+    alphaLock?: boolean;
+}
+/** Creates the canvas that stores a layer's image data. Replaceable so tests can run without a real canvas. */
+export type CanvasFactory = (width: number, height: number) => OffscreenCanvas;
+/**
+ * Create an `OffscreenCanvas` of the given size.
+ */
+export declare const createOffscreenCanvas: CanvasFactory;
+/**
+ * Clamp an opacity value to 0–1.
+ *
+ * @example
+ * clampOpacity(1.5); // 1
+ */
+export declare const clampOpacity: (value: number) => number;
+/**
+ * A single drawing layer. Layers are local to each user and never sent to other users; only the flattened result of all a user's layers is sent.
+ *
+ * @example
+ * const layer = new Layer({ name: "Layer 1" }, 2000, 2000);
+ * layer.opacity = 0.5;
+ */
+export default class Layer {
+    /** Unique ID */
+    readonly id: string;
+    /** Width in pixels */
+    readonly width: number;
+    /** Height in pixels */
+    readonly height: number;
+    /** Image data */
+    readonly canvas: OffscreenCanvas;
+    /** Blending mode */
+    blendMode: BlendMode;
+    /** Visibility */
+    visible: boolean;
+    /** Alpha lock */
+    alphaLock: boolean;
+    private layerName;
+    private layerOpacity;
+    constructor(config: LayerConfig, width: number, height: number, createCanvas?: CanvasFactory);
+    /** Layer name (trimmed, 1–64 characters) */
+    get name(): string;
+    set name(value: string);
+    /** Opacity (clamped to 0–1) */
+    get opacity(): number;
+    set opacity(value: number);
+    /**
+     * Get the 2D drawing context of the layer's canvas.
+     */
+    get context(): OffscreenCanvasRenderingContext2D;
+    /**
+     * Remove all image data from the layer.
+     */
+    clear(): void;
+    /**
+     * Replace this layer's image data with a copy of another layer's image data.
+     */
+    copyImageFrom(source: Layer): void;
+    /**
+     * Get the layer's settings (without image data).
+     */
+    toConfig(): Required<LayerConfig>;
+}

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

@@ -0,0 +1,111 @@
+// src/lib/classes/Layer/index.ts
+/** Layer blending modes, mapped to canvas `globalCompositeOperation` values */
+var BlendMode = /* @__PURE__ */ function(BlendMode) {
+	BlendMode["Normal"] = "source-over";
+	BlendMode["Screen"] = "screen";
+	BlendMode["Lighten"] = "lighten";
+	BlendMode["Multiply"] = "multiply";
+	BlendMode["Darken"] = "darken";
+	BlendMode["Overlay"] = "overlay";
+	return BlendMode;
+}({});
+/** Maximum length of a layer name */
+var MAX_LAYER_NAME_LENGTH = 64;
+/**
+* Create an `OffscreenCanvas` of the given size.
+*/
+var createOffscreenCanvas = (width, height) => new OffscreenCanvas(width, height);
+/**
+* Clamp an opacity value to 0–1.
+*
+* @example
+* clampOpacity(1.5); // 1
+*/
+var clampOpacity = (value) => Number.isNaN(value) ? 1 : Math.max(0, Math.min(1, value));
+/**
+* A single drawing layer. Layers are local to each user and never sent to other users; only the flattened result of all a user's layers is sent.
+*
+* @example
+* const layer = new Layer({ name: "Layer 1" }, 2000, 2000);
+* layer.opacity = 0.5;
+*/
+var Layer = class {
+	/** Unique ID */
+	id;
+	/** Width in pixels */
+	width;
+	/** Height in pixels */
+	height;
+	/** Image data */
+	canvas;
+	/** Blending mode */
+	blendMode;
+	/** Visibility */
+	visible;
+	/** Alpha lock */
+	alphaLock;
+	layerName = "";
+	layerOpacity = 1;
+	constructor(config, width, height, createCanvas = createOffscreenCanvas) {
+		this.id = config.id ?? crypto.randomUUID();
+		this.name = config.name;
+		this.width = width;
+		this.height = height;
+		this.canvas = createCanvas(width, height);
+		this.blendMode = config.blendMode ?? "source-over";
+		this.opacity = config.opacity ?? 1;
+		this.visible = config.visible ?? true;
+		this.alphaLock = config.alphaLock ?? false;
+	}
+	/** Layer name (trimmed, 1–64 characters) */
+	get name() {
+		return this.layerName;
+	}
+	set name(value) {
+		const name = value.trim().slice(0, 64);
+		if (name.length === 0) throw new Error("Layer name cannot be empty");
+		this.layerName = name;
+	}
+	/** Opacity (clamped to 0–1) */
+	get opacity() {
+		return this.layerOpacity;
+	}
+	set opacity(value) {
+		this.layerOpacity = clampOpacity(value);
+	}
+	/**
+	* Get the 2D drawing context of the layer's canvas.
+	*/
+	get context() {
+		const context = this.canvas.getContext("2d");
+		if (!context) throw new Error("Layer canvas has no 2D context");
+		return context;
+	}
+	/**
+	* Remove all image data from the layer.
+	*/
+	clear() {
+		this.context.clearRect(0, 0, this.width, this.height);
+	}
+	/**
+	* Replace this layer's image data with a copy of another layer's image data.
+	*/
+	copyImageFrom(source) {
+		this.clear();
+		this.context.drawImage(source.canvas, 0, 0);
+	}
+	/**
+	* Get the layer's settings (without image data).
+	*/
+	toConfig() {
+		return {
+			id: this.id,
+			name: this.name,
+			blendMode: this.blendMode,
+			opacity: this.opacity,
+			visible: this.visible,
+			alphaLock: this.alphaLock
+		};
+	}
+};
+export { BlendMode, MAX_LAYER_NAME_LENGTH, clampOpacity, createOffscreenCanvas, Layer as default };

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

@@ -0,0 +1,180 @@
+import type LayerStack from "../LayerStack";
+import type BackgroundWork from "../BackgroundWork";
+import { type LayerStoreLike, type SavedLayer } from "../../storage";
+/** How long to wait after the layers change before saving, so quick changes are saved together (milliseconds) */
+export declare const SAVE_DELAY_MS = 500;
+/** Name of the save in the canvas's background work */
+export declare const SAVE_WORK = "save";
+/** Event dispatched when loading or saving fails (detail: the error) */
+export declare const AUTOSAVE_ERROR_EVENT = "error";
+/** Where autosaving is up to */
+export declare const AutosaveState: {
+    /** Waiting to draw (another window may have the drawing) or loading the saved drawing */
+    readonly Starting: "starting";
+    /** Another window has the drawing; this one doesn't save (see `takeOver`) */
+    readonly Elsewhere: "elsewhere";
+    /** The saved drawing is shown, and changes are saved */
+    readonly Ready: "ready";
+    /** Not saving any more (see `stop`) */
+    readonly Stopped: "stopped";
+};
+export type AutosaveState = (typeof AutosaveState)[keyof typeof AutosaveState];
+/** The canvas whose layers are saved (`PaintCanvas`) */
+export interface AutosaveCanvas extends EventTarget {
+    /** The user's layers (replaced when the canvas size changes, followed by a `change` event) */
+    readonly layers: LayerStack;
+    /** Slow work that waits for pauses in drawing */
+    readonly background: BackgroundWork;
+    /** Replace the canvas size and layers with saved ones, drawing each layer's image, and select one */
+    restoreLayers(width: number, height: number, layers: readonly SavedLayer[], images: readonly CanvasImageSource[], activeLayer: string): void;
+}
+/** Options for `LayerAutosave` */
+export interface AutosaveOptions {
+    /** Makes sure only one window draws on a drawing (the browser's Web Locks by default; none to skip) */
+    locks?: LockManager | null;
+    /** Tells when the page is hidden or shown again (the page's document by default) */
+    document?: Pick<Document, "visibilityState" | "addEventListener" | "removeEventListener"> | null;
+    /** Turns a layer's canvas into a PNG (replaceable for tests) */
+    encode?: (canvas: OffscreenCanvas) => Promise<Blob>;
+    /** Turns a saved PNG into an image to draw (replaceable for tests) */
+    decode?: (image: Blob) => Promise<CanvasImageSource>;
+    /** How long to wait after the layers change before saving (default `SAVE_DELAY_MS`) */
+    delayMs?: number;
+}
+/**
+ * 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));
+ */
+export default class LayerAutosave extends EventTarget {
+    /** Where the layers are kept */
+    readonly store: LayerStoreLike;
+    /** The last loading or saving error, until a save succeeds */
+    error?: unknown;
+    private currentState;
+    private readonly canvas;
+    private readonly locks;
+    private readonly document;
+    private readonly encode;
+    private readonly decode;
+    private readonly delayMs;
+    /** The layers being watched for changes */
+    private watched?;
+    /** Fingerprints of each layer's pixels as last saved, by layer ID */
+    private prints;
+    /** Size in bytes of each layer's image as last saved or restored, by layer ID */
+    private sizes;
+    /** Layers whose pixels changed since the last save */
+    private changed;
+    /** Whether any layer may have changed since the last save (not only those in `changed`) */
+    private checkAll;
+    private timer?;
+    /** The save being written, if any */
+    private saving?;
+    /** Whether to save again once the current save finishes */
+    private again;
+    /** Lets go of the drawing's lock, while held */
+    private release?;
+    private readonly onLayersChange;
+    private readonly onCanvasChange;
+    private readonly onVisibilityChange;
+    constructor(canvas: AutosaveCanvas, store: LayerStoreLike, options?: AutosaveOptions);
+    /** Where autosaving is up to (see `AutosaveState`) */
+    get state(): AutosaveState;
+    /** Total size in bytes of the layer images kept in the store (as last saved or restored) */
+    get storedBytes(): number;
+    /** Name of the Web Lock that only one window holds per drawing */
+    get lockName(): string;
+    /**
+     * Start: wait for the drawing (unless another window has it), restore it, then save changes.
+     */
+    start(): void;
+    /**
+     * 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(): void;
+    /**
+     * Stop saving and let other windows have the drawing, after saving any changes not saved yet.
+     */
+    stop(): Promise<void>;
+    /**
+     * Save the changes not saved yet now, without waiting. While a save is being written, another follows it.
+     */
+    save(): Promise<void>;
+    /**
+     * 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.
+     */
+    private claim;
+    /**
+     * 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.
+     */
+    private begin;
+    /**
+     * 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.
+     */
+    private restore;
+    /**
+     * Remember each layer's pixels as saved (just restored).
+     */
+    private remember;
+    /**
+     * Save the drawing, encoding only the layers whose pixels changed since they were last saved.
+     */
+    private write;
+    /**
+     * Remember the sizes of the layer images just saved, forgetting layers that are gone, and tell listeners if the total
+     * changed.
+     */
+    private rememberSizes;
+    /**
+     * A fingerprint of a layer's pixels.
+     */
+    private fingerprint;
+    /**
+     * Save once the layers have stopped changing for a moment and drawing pauses.
+     */
+    private schedule;
+    /**
+     * Watch the canvas and its current layers for changes.
+     */
+    private watch;
+    /**
+     * Stop watching for changes, forgetting a save that hasn't started.
+     */
+    private unwatch;
+    /**
+     * Another window took the drawing: stop saving and wait.
+     */
+    private lostLock;
+    /**
+     * Let other windows have the drawing.
+     */
+    private letGo;
+    /**
+     * Remember an error and tell listeners.
+     */
+    private fail;
+    /**
+     * Change state and tell listeners.
+     */
+    private setState;
+}