@lvl99dotcom/paintcanvas 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,91 @@
+import type { BrushConfig, BrushesConfig } from "../../brushes/types";
+/** Smallest brush size in pixels */
+export declare const MIN_BRUSH_SIZE = 1;
+/** Largest brush size in pixels */
+export declare const MAX_BRUSH_SIZE = 256;
+/** Fraction of the current size added or removed by `grow` and `shrink` ("]" and "[" keys) */
+export declare const BRUSH_SIZE_STEP = 0.1;
+/**
+ * Clamp a value between min and max.
+ *
+ * @example
+ * clamp(300, 1, 256); // 256
+ */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * The settings of a brush or eraser: the selected preset, an editable copy of its settings (changed from the tool
+ * settings bar or the configuration window, without changing the preset) and the size. The brush and eraser each have
+ * their own instance.
+ *
+ * Dispatches a `change` event whenever the presets, settings or size change.
+ *
+ * @example
+ * const brush = new BrushSettings(standardBrushes);
+ * brush.grow(); // "]" key
+ * brush.update({ alpha: 0.5 }); // half opacity, until another preset is selected
+ */
+export default class BrushSettings extends EventTarget {
+    /** Available presets */
+    presets: BrushesConfig;
+    /** Current width in pixels */
+    width: number;
+    /** Current height in pixels */
+    height: number;
+    /** ID of the selected preset */
+    presetId: string;
+    /** The current settings: a copy of the selected preset, with any changes */
+    private current;
+    constructor(presets: BrushesConfig);
+    /** The current settings: the selected preset's, with any changes made since selecting it */
+    get preset(): BrushConfig;
+    /** The selected preset as saved, or undefined if it no longer exists */
+    get selectedPreset(): BrushConfig | undefined;
+    /**
+     * Select a preset: use a fresh copy of its settings and its default size.
+     */
+    select(id: string): void;
+    /**
+     * Change the current settings (not the preset). The size is changed with `setSize`.
+     *
+     * @example
+     * brush.update({ alpha: 0.5, widthConfig: { usePressure: true } });
+     */
+    update(changes: Partial<BrushConfig>): void;
+    /**
+     * Replace the current settings and size with a whole configuration (the configuration window's "Save").
+     */
+    apply(config: BrushConfig): void;
+    /**
+     * Replace the available presets (e.g. when custom presets are added or removed). If the selected preset is gone, the
+     * current settings stay until another preset is selected.
+     */
+    setPresets(presets: BrushesConfig): void;
+    /**
+     * Set the height, clamped to 1–256 pixels. If the settings constrain proportions, width follows height.
+     */
+    setHeight(height: number): void;
+    /**
+     * Set the size, clamped to 1–256 pixels. If the settings constrain proportions, height follows width.
+     */
+    setSize(width: number, height?: number): void;
+    /**
+     * Change the size by a number of pixels (positive = bigger). Used when dragging up/right (bigger) or down/left (smaller).
+     */
+    resize(delta: number): void;
+    /**
+     * Increase the size by one step (at least 1 pixel).
+     */
+    grow(): void;
+    /**
+     * Decrease the size by one step (at least 1 pixel).
+     */
+    shrink(): void;
+    /**
+     * Use a preset's (or configuration's) default size.
+     */
+    private applyPresetSize;
+    /**
+     * Dispatch a `change` event.
+     */
+    private notify;
+}

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

@@ -0,0 +1,152 @@
+// src/lib/classes/BrushSettings/index.ts
+/** Smallest brush size in pixels */
+var MIN_BRUSH_SIZE = 1;
+/** Largest brush size in pixels */
+var MAX_BRUSH_SIZE = 256;
+/** Fraction of the current size added or removed by `grow` and `shrink` ("]" and "[" keys) */
+var BRUSH_SIZE_STEP = .1;
+/**
+* Clamp a value between min and max.
+*
+* @example
+* clamp(300, 1, 256); // 256
+*/
+var clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+/**
+* The settings of a brush or eraser: the selected preset, an editable copy of its settings (changed from the tool
+* settings bar or the configuration window, without changing the preset) and the size. The brush and eraser each have
+* their own instance.
+*
+* Dispatches a `change` event whenever the presets, settings or size change.
+*
+* @example
+* const brush = new BrushSettings(standardBrushes);
+* brush.grow(); // "]" key
+* brush.update({ alpha: 0.5 }); // half opacity, until another preset is selected
+*/
+var BrushSettings = class extends EventTarget {
+	/** Available presets */
+	presets;
+	/** Current width in pixels */
+	width = 1;
+	/** Current height in pixels */
+	height = 1;
+	/** ID of the selected preset */
+	presetId;
+	/** The current settings: a copy of the selected preset, with any changes */
+	current;
+	constructor(presets) {
+		super();
+		const first = Object.values(presets)[0];
+		if (!first) throw new Error("At least one brush preset is required");
+		this.presets = presets;
+		this.presetId = first.id;
+		this.current = structuredClone(first);
+		this.applyPresetSize(first);
+	}
+	/** The current settings: the selected preset's, with any changes made since selecting it */
+	get preset() {
+		return this.current;
+	}
+	/** The selected preset as saved, or undefined if it no longer exists */
+	get selectedPreset() {
+		return this.presets[this.presetId];
+	}
+	/**
+	* Select a preset: use a fresh copy of its settings and its default size.
+	*/
+	select(id) {
+		const preset = this.presets[id];
+		if (!preset) throw new Error(`Brush preset ${id} not found`);
+		this.presetId = id;
+		this.current = structuredClone(preset);
+		this.applyPresetSize(preset);
+		this.notify();
+	}
+	/**
+	* Change the current settings (not the preset). The size is changed with `setSize`.
+	*
+	* @example
+	* brush.update({ alpha: 0.5, widthConfig: { usePressure: true } });
+	*/
+	update(changes) {
+		this.current = {
+			...this.current,
+			...changes,
+			id: this.current.id
+		};
+		this.notify();
+	}
+	/**
+	* Replace the current settings and size with a whole configuration (the configuration window's "Save").
+	*/
+	apply(config) {
+		this.current = {
+			...structuredClone(config),
+			id: this.current.id
+		};
+		this.applyPresetSize(config);
+		this.notify();
+	}
+	/**
+	* Replace the available presets (e.g. when custom presets are added or removed). If the selected preset is gone, the
+	* current settings stay until another preset is selected.
+	*/
+	setPresets(presets) {
+		if (Object.keys(presets).length === 0) throw new Error("At least one brush preset is required");
+		this.presets = presets;
+		this.notify();
+	}
+	/**
+	* Set the height, clamped to 1–256 pixels. If the settings constrain proportions, width follows height.
+	*/
+	setHeight(height) {
+		if (!this.current.constrainProportions) {
+			this.setSize(this.width, height);
+			return;
+		}
+		const ratio = this.width / this.height;
+		this.setSize(clamp(height, 1, 256) * ratio);
+	}
+	/**
+	* Set the size, clamped to 1–256 pixels. If the settings constrain proportions, height follows width.
+	*/
+	setSize(width, height = width) {
+		const ratio = this.height / this.width;
+		this.width = Math.round(clamp(width, 1, 256));
+		this.height = Math.round(clamp(this.preset.constrainProportions ? this.width * ratio : height, 1, 256));
+		this.notify();
+	}
+	/**
+	* Change the size by a number of pixels (positive = bigger). Used when dragging up/right (bigger) or down/left (smaller).
+	*/
+	resize(delta) {
+		this.setSize(this.width + delta, this.height + delta);
+	}
+	/**
+	* Increase the size by one step (at least 1 pixel).
+	*/
+	grow() {
+		this.resize(Math.max(1, Math.round(this.width * BRUSH_SIZE_STEP)));
+	}
+	/**
+	* Decrease the size by one step (at least 1 pixel).
+	*/
+	shrink() {
+		this.resize(-Math.max(1, Math.round(this.width * BRUSH_SIZE_STEP)));
+	}
+	/**
+	* Use a preset's (or configuration's) default size.
+	*/
+	applyPresetSize(preset) {
+		this.width = preset.width ?? 1;
+		this.height = preset.height ?? this.width;
+	}
+	/**
+	* Dispatch a `change` event.
+	*/
+	notify() {
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { BRUSH_SIZE_STEP, MAX_BRUSH_SIZE, MIN_BRUSH_SIZE, clamp, BrushSettings as default };

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

@@ -0,0 +1,53 @@
+import type { BrushConfig } from "../../brushes/types";
+/** Where custom presets are kept (see `PresetStore`) */
+export interface PresetStoreLike {
+    /** The owner's presets, in the order they were saved */
+    list(ownerId: string): Promise<BrushConfig[]>;
+    /** Save one of the owner's presets (replacing one with the same ID) */
+    put(ownerId: string, preset: BrushConfig): Promise<void>;
+    /** Delete one of the owner's presets */
+    remove(ownerId: string, id: string): Promise<void>;
+}
+/**
+ * The user's own and imported brush presets, shared by the brush and eraser. They are kept in a store when one is
+ * given (otherwise only until the page closes).
+ *
+ * Dispatches a `change` event when presets are loaded, saved or removed.
+ *
+ * @example
+ * const custom = new CustomPresets("user-1", myPresetStore);
+ * await custom.load();
+ * await custom.save({ id: crypto.randomUUID(), name: "My brush", author: { name: "Ada", handle } });
+ */
+export default class CustomPresets extends EventTarget {
+    /** Presets, in the order they were added */
+    presets: BrushConfig[];
+    private readonly ownerId;
+    private readonly store?;
+    constructor(ownerId: string, store?: PresetStoreLike);
+    /**
+     * Load the user's presets from the store.
+     */
+    load(): Promise<void>;
+    /**
+     * A preset by ID.
+     */
+    get(id: string): BrushConfig | undefined;
+    /**
+     * One of the user's own presets with a name (ignoring case), to ask before replacing it.
+     *
+     * @param handle - the user's handle (empty if they have none)
+     * @param unknownName - the author name of presets made by a user without a handle (see `isOwnAuthor`)
+     */
+    findOwn(name: string, handle: string, unknownName?: string): BrushConfig | undefined;
+    /**
+     * Add presets, replacing any with the same ID, and keep them.
+     */
+    save(...presets: BrushConfig[]): Promise<void>;
+    /**
+     * Delete a preset.
+     */
+    remove(id: string): Promise<void>;
+    /** Dispatch a `change` event */
+    private notify;
+}

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

@@ -0,0 +1,71 @@
+import { isOwnAuthor } from "../../brushes/authors/index.js";
+// src/lib/classes/CustomPresets/index.ts
+/**
+* The user's own and imported brush presets, shared by the brush and eraser. They are kept in a store when one is
+* given (otherwise only until the page closes).
+*
+* Dispatches a `change` event when presets are loaded, saved or removed.
+*
+* @example
+* const custom = new CustomPresets("user-1", myPresetStore);
+* await custom.load();
+* await custom.save({ id: crypto.randomUUID(), name: "My brush", author: { name: "Ada", handle } });
+*/
+var CustomPresets = class extends EventTarget {
+	/** Presets, in the order they were added */
+	presets = [];
+	ownerId;
+	store;
+	constructor(ownerId, store) {
+		super();
+		this.ownerId = ownerId;
+		this.store = store;
+	}
+	/**
+	* Load the user's presets from the store.
+	*/
+	async load() {
+		if (!this.store) return;
+		this.presets = await this.store.list(this.ownerId);
+		this.notify();
+	}
+	/**
+	* A preset by ID.
+	*/
+	get(id) {
+		return this.presets.find((preset) => preset.id === id);
+	}
+	/**
+	* One of the user's own presets with a name (ignoring case), to ask before replacing it.
+	*
+	* @param handle - the user's handle (empty if they have none)
+	* @param unknownName - the author name of presets made by a user without a handle (see `isOwnAuthor`)
+	*/
+	findOwn(name, handle, unknownName) {
+		const wanted = name.trim().toLowerCase();
+		return this.presets.find((preset) => isOwnAuthor(preset.author, handle, unknownName) && preset.name?.trim().toLowerCase() === wanted);
+	}
+	/**
+	* Add presets, replacing any with the same ID, and keep them.
+	*/
+	async save(...presets) {
+		for (const preset of presets) await this.store?.put(this.ownerId, preset);
+		const kept = this.presets.map((existing) => presets.find((preset) => preset.id === existing.id) ?? existing);
+		const added = presets.filter((preset) => !this.presets.some((existing) => existing.id === preset.id));
+		this.presets = [...kept, ...added];
+		if (presets.length > 0) this.notify();
+	}
+	/**
+	* Delete a preset.
+	*/
+	async remove(id) {
+		await this.store?.remove(this.ownerId, id);
+		this.presets = this.presets.filter((preset) => preset.id !== id);
+		this.notify();
+	}
+	/** Dispatch a `change` event */
+	notify() {
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { CustomPresets as default };

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

@@ -0,0 +1,64 @@
+import { type CanvasFactory } from "../Layer";
+import type { DrawableLayer } from "../../rendering/compositing";
+import type { PatchMessage } from "../../messages";
+/** A drawing from elsewhere (e.g. another person's), flattened into one sheet */
+export interface ExternalSheet extends DrawableLayer {
+    /** Where the drawing comes from: an ID the implementer chooses (e.g. a user ID), which PaintCanvas doesn't interpret */
+    source: string;
+    canvas: OffscreenCanvas;
+}
+/** Decodes a PNG into pixels (replaceable for tests) */
+export type DecodePng = (bytes: Uint8Array<ArrayBuffer>) => Promise<ImageBitmap>;
+/**
+ * Drawings from elsewhere (e.g. other people's), one flattened sheet per source. They are drawn under the user's own
+ * layers, so their own work is always in focus; the sheets are ordered by when each source's first drawing arrived
+ * (newest on top).
+ *
+ * Dispatches a `change` event when a sheet changes.
+ *
+ * @example
+ * const external = new ExternalSheets(2000, 2000);
+ * await external.apply("user-2", patchMessage);
+ * drawLayers(ctx, [...ownLayers, ...external.sheets]);
+ */
+export default class ExternalSheets extends EventTarget {
+    private width;
+    private height;
+    private readonly createCanvas;
+    private readonly decodePng;
+    /** Sheets from top to bottom, as layer lists are ordered */
+    private list;
+    /** Updates are applied one at a time, in the order they arrive */
+    private queue;
+    constructor(width: number, height: number, createCanvas?: CanvasFactory, decodePng?: DecodePng);
+    /** Sheets from top to bottom */
+    get sheets(): readonly ExternalSheet[];
+    /**
+     * A source's sheet, created (on top of the others) if it doesn't exist yet.
+     */
+    private sheetOf;
+    /**
+     * Draw a patch's pixels onto a source's sheet, replacing what was there. Updates are applied in order. Returns once
+     * this update is applied; a patch whose data can't be decoded is skipped.
+     */
+    apply(source: string, message: PatchMessage): Promise<void>;
+    /**
+     * Draw onto a source's sheet with a drawing function (e.g. a received stroke), after any updates before it. Returns
+     * once drawn; a drawing that throws is skipped.
+     */
+    paint(source: string, draw: (canvas: OffscreenCanvas) => void | Promise<void>): Promise<void>;
+    /** Decode and draw one patch */
+    private draw;
+    /**
+     * Put a saved drawing back onto a source's sheet (e.g. other people's drawing in a saved drawing).
+     */
+    restore(source: string, image: CanvasImageSource): void;
+    /**
+     * Change the canvas size, removing all sheets.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Remove all sheets (e.g. when a shared drawing ends).
+     */
+    clear(): void;
+}

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

@@ -0,0 +1,112 @@
+import { ImageEncoding, base64ToBytes, boundingBoxSize, decodeRgbaDeflate } from "../../image/index.js";
+import { BlendMode, createOffscreenCanvas } from "../Layer/index.js";
+// src/lib/classes/ExternalSheets/index.ts
+/**
+* Drawings from elsewhere (e.g. other people's), one flattened sheet per source. They are drawn under the user's own
+* layers, so their own work is always in focus; the sheets are ordered by when each source's first drawing arrived
+* (newest on top).
+*
+* Dispatches a `change` event when a sheet changes.
+*
+* @example
+* const external = new ExternalSheets(2000, 2000);
+* await external.apply("user-2", patchMessage);
+* drawLayers(ctx, [...ownLayers, ...external.sheets]);
+*/
+var ExternalSheets = class extends EventTarget {
+	width;
+	height;
+	createCanvas;
+	decodePng;
+	/** Sheets from top to bottom, as layer lists are ordered */
+	list = [];
+	/** Updates are applied one at a time, in the order they arrive */
+	queue = Promise.resolve();
+	constructor(width, height, createCanvas = createOffscreenCanvas, decodePng = (bytes) => createImageBitmap(new Blob([bytes], { type: "image/png" }))) {
+		super();
+		this.width = width;
+		this.height = height;
+		this.createCanvas = createCanvas;
+		this.decodePng = decodePng;
+	}
+	/** Sheets from top to bottom */
+	get sheets() {
+		return this.list;
+	}
+	/**
+	* A source's sheet, created (on top of the others) if it doesn't exist yet.
+	*/
+	sheetOf(source) {
+		let sheet = this.list.find((existing) => existing.source === source);
+		if (!sheet) {
+			sheet = {
+				source,
+				canvas: this.createCanvas(this.width, this.height),
+				visible: true,
+				opacity: 1,
+				blendMode: BlendMode.Normal
+			};
+			this.list = [sheet, ...this.list];
+		}
+		return sheet;
+	}
+	/**
+	* Draw a patch's pixels onto a source's sheet, replacing what was there. Updates are applied in order. Returns once
+	* this update is applied; a patch whose data can't be decoded is skipped.
+	*/
+	apply(source, message) {
+		this.queue = this.queue.then(() => this.draw(source, message)).catch(() => void 0);
+		return this.queue;
+	}
+	/**
+	* Draw onto a source's sheet with a drawing function (e.g. a received stroke), after any updates before it. Returns
+	* once drawn; a drawing that throws is skipped.
+	*/
+	paint(source, draw) {
+		this.queue = this.queue.then(async () => {
+			await draw(this.sheetOf(source).canvas);
+			this.dispatchEvent(new Event("change"));
+		}).catch(() => void 0);
+		return this.queue;
+	}
+	/** Decode and draw one patch */
+	async draw(source, message) {
+		const [x, y] = message.coords;
+		const { width, height } = boundingBoxSize(message.coords);
+		const context = this.sheetOf(source).canvas.getContext("2d");
+		if (message.encoding === ImageEncoding.Png) {
+			const image = await this.decodePng(base64ToBytes(message.data));
+			context.clearRect(x, y, width, height);
+			context.drawImage(image, x, y);
+		} else {
+			const rgba = await decodeRgbaDeflate(message.data, message.coords);
+			context.putImageData(new ImageData(rgba, width, height), x, y);
+		}
+		this.dispatchEvent(new Event("change"));
+	}
+	/**
+	* Put a saved drawing back onto a source's sheet (e.g. other people's drawing in a saved drawing).
+	*/
+	restore(source, image) {
+		const context = this.sheetOf(source).canvas.getContext("2d");
+		context.clearRect(0, 0, this.width, this.height);
+		context.drawImage(image, 0, 0);
+		this.dispatchEvent(new Event("change"));
+	}
+	/**
+	* Change the canvas size, removing all sheets.
+	*/
+	resize(width, height) {
+		this.width = width;
+		this.height = height;
+		this.clear();
+	}
+	/**
+	* Remove all sheets (e.g. when a shared drawing ends).
+	*/
+	clear() {
+		this.list = [];
+		this.dispatchEvent(new Event("change"));
+	}
+};
+export { ExternalSheets as default };

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

@@ -0,0 +1,62 @@
+import type { Point } from "../Viewport";
+import type { TouchGesture } from "../../utils/gestures";
+/** A tap's fingers must all lift within this long of the first touching down */
+export declare const TAP_MAX_MS = 300;
+/** How far a finger can move and still be tapping (screen pixels); two-finger pan and pinch wait until a finger moves further */
+export declare const TAP_SLOP_PX = 10;
+/** How far three fingers must move together, or spread apart or close together, to swipe (screen pixels) */
+export declare const SWIPE_MIN_PX = 40;
+/**
+ * The swipe three fingers made from where they were to where they are: in or out if their spread changed more than
+ * they moved together, otherwise left, right, up or down (whichever way they moved most). Undefined if they moved less
+ * than `SWIPE_MIN_PX`.
+ *
+ * @example
+ * swipeOf([{ x: 0, y: 0 }, { x: 10, y: 0 }, { x: 20, y: 0 }], [{ x: 50, y: 0 }, { x: 60, y: 0 }, { x: 70, y: 0 }]); // "swipeRight3"
+ */
+export declare const swipeOf: (from: readonly Point[], to: readonly Point[]) => TouchGesture | undefined;
+/**
+ * Recognises touch gestures from the fingers on the canvas, from the first finger down to the last one up: a tap with
+ * two or three fingers (all lifted within `TAP_MAX_MS`, none moving more than `TAP_SLOP_PX`), or a swipe with three
+ * fingers (see `swipeOf`, measured from when the third finger touched down to when the first of them lifted). Four or
+ * more fingers, or a cancelled touch (e.g. taken by a system gesture), make no gesture.
+ *
+ * @example
+ * const tracker = new GestureTracker();
+ * tracker.down(1, { x: 0, y: 0 }, 0);
+ * tracker.down(2, { x: 50, y: 0 }, 10);
+ * tracker.up(1, 100);
+ * tracker.up(2, 120); // "tap2"
+ */
+export default class GestureTracker {
+    /** Where each finger on the screen touched down, and where it is now */
+    private readonly fingers;
+    /** When the first finger touched down */
+    private startTime;
+    /** Most fingers down at once */
+    private most;
+    /** Whether any finger moved too far to tap */
+    private moved;
+    /** Whether a touch was cancelled */
+    private cancelled;
+    /** The three fingers' positions when the third touched down, and when the first of them lifted */
+    private swipe?;
+    /** How many fingers are on the screen */
+    get count(): number;
+    /**
+     * Whether any finger moved further than a tap allows since touching down.
+     */
+    get dragging(): boolean;
+    /** A finger touched down */
+    down(id: number, point: Point, time: number): void;
+    /** A finger moved */
+    move(id: number, point: Point): void;
+    /**
+     * A finger lifted. Returns the gesture made once the last finger lifts, if any.
+     */
+    up(id: number, time: number): TouchGesture | undefined;
+    /** A touch was cancelled: no gesture until all fingers have lifted */
+    cancel(id: number): void;
+    /** Start tracking a new gesture */
+    private reset;
+}