@lvl99dotcom/paintcanvas 0.0.0-stage → 0.3.0

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

@@ -0,0 +1,149 @@
+/** Default number of log entries kept */
+export declare const DEFAULT_STROKE_LOG_LIMIT = 200;
+/**
+ * What a stroke log entry is about:
+ * - `start`: a stroke started
+ * - `end`: a stroke finished, with its measurements
+ * - `cancel`: a stroke in progress was abandoned, with its measurements so far
+ * - `ignore`: a pointer press didn't start a stroke
+ * - `gesture`: a touch gesture did an action (e.g. undo)
+ * - `work`: other work that kept the page busy (e.g. syncing the drawing)
+ */
+export type StrokeLogKind = "start" | "end" | "cancel" | "ignore" | "gesture" | "work";
+/** A logged event */
+export interface StrokeLogEntry {
+    /** Time the entry was logged (Unix epoch milliseconds) */
+    at: number;
+    kind: StrokeLogKind;
+    /** What happened, e.g. the pointer type, why a stroke was cancelled, or the work done */
+    detail: string;
+    /** Measurements by name: times in milliseconds, otherwise counts */
+    measures: Record<string, number>;
+}
+/** What was on screen when a stroke started */
+export interface StrokeScene {
+    /** Layers drawn (visible, including other people's drawings) */
+    layers: number;
+    /** Zoom as a percentage */
+    zoomPct: number;
+}
+/**
+ * Records when brush and eraser strokes start, end, are cancelled or are ignored, with timings for each stroke, plus
+ * other work done meanwhile (see `BackgroundWork`), for the debug panel. Times are in the same clock as `event.timeStamp` and
+ * `performance.now()`. Keeps only the most recent entries.
+ *
+ * Each finished or cancelled stroke measures (in ms unless noted):
+ * - `gap`: time since the previous stroke ended
+ * - `wait`: how long the press waited before it was handled (the page was busy)
+ * - `begin`: time taken to start the stroke
+ * - `moves`: pointer events handled (count), `maxMoveWait`: longest one waited, `moveMs`: total time handling them
+ * - `frames`: frames drawn (count), `maxFrame`: longest frame to draw, `maxFrameGap`: longest time between frames
+ *   (including after the last one), `overlays`: times the brush cursor was drawn (count)
+ * - `end`: time taken to write the stroke into its layer
+ * - `duration`: from press to release
+ * - `layers`: layers drawn (count) and `zoomPct`: the zoom as a percentage, when the stroke started (if given)
+ *
+ * Records nothing while switched off (`enabled`); work given to `measure` still runs.
+ *
+ * Dispatches a `change` event when entries are added or cleared.
+ *
+ * @example
+ * const log = new StrokeLog();
+ * log.begin("pen", event.timeStamp, 2);
+ * log.move(event.timeStamp, 0.5);
+ * log.end(event.timeStamp, 3); // entry with kind "end" and its measures
+ */
+export default class StrokeLog extends EventTarget {
+    /** Maximum number of entries kept */
+    readonly limit: number;
+    /** Current time in milliseconds (replaceable for tests) */
+    now: () => number;
+    /** Whether anything is recorded */
+    enabled: boolean;
+    private items;
+    private stroke?;
+    /** When the last stroke ended or was cancelled (event time) */
+    private lastEnd?;
+    constructor(limit?: number);
+    /** Logged entries, oldest first */
+    get entries(): readonly StrokeLogEntry[];
+    /** Whether a stroke is being measured */
+    get drawing(): boolean;
+    /**
+     * A stroke started: the pointer type, when it pressed (event time), how long starting the stroke took, and what was on
+     * screen.
+     */
+    begin(pointerType: string, eventTime: number, beginMs: number, scene?: StrokeScene): void;
+    /**
+     * The stroke continued: when the pointer moved (event time) and how long handling it took.
+     */
+    move(eventTime: number, moveMs: number): void;
+    /**
+     * A frame was drawn, taking `ms`; counted towards the stroke in progress, if any.
+     */
+    frame(ms: number): void;
+    /**
+     * The brush cursor was drawn; counted towards the stroke in progress, if any.
+     */
+    overlay(): void;
+    /**
+     * The stroke finished: when the pointer released (event time) and how long writing it into the layer took.
+     */
+    end(eventTime: number, endMs: number): void;
+    /**
+     * The stroke in progress was abandoned, and why.
+     */
+    cancel(reason: string): void;
+    /**
+     * A pointer press didn't start a stroke, and why.
+     */
+    ignore(pointerType: string, reason: string): void;
+    /**
+     * A touch gesture did an action.
+     */
+    gesture(gesture: string, action: string): void;
+    /**
+     * Other work was done, with its measurements: `ms` for how long it kept the page busy, and `total` for how long work
+     * that finishes later took altogether (which can include waiting that doesn't keep the page busy).
+     */
+    work(name: string, measures: {
+        ms?: number;
+        total?: number;
+    }): void;
+    /**
+     * Run some work and return its result, logging how long it kept the page busy, or for work that finishes later (a
+     * promise), how long it took altogether once it settles.
+     *
+     * @example
+     * log.measure("map", () => drawMap()); // logs "map" with how long it took
+     * log.measure("save", () => save()); // logs "save" with how long it took once saved (or failed)
+     */
+    measure<T>(name: string, run: () => T): T;
+    /**
+     * Remove all entries.
+     */
+    clear(): void;
+    /** Log a finished or cancelled stroke with its measurements, and stop measuring it */
+    private finish;
+    /** Add an entry, rounding its measurements (unless switched off) */
+    private add;
+}
+/** The stroke log's CSV columns after time, event and detail: every measurement, in order */
+export declare const STROKE_LOG_COLUMNS: readonly ["gap", "wait", "begin", "moves", "maxMoveWait", "moveMs", "frames", "maxFrame", "maxFrameGap", "overlays", "end", "duration", "layers", "zoomPct", "ms", "total"];
+/**
+ * A CSV field, quoted if it holds a comma, quote or line break.
+ *
+ * @example
+ * csvField('a "b", c'); // '"a ""b"", c"'
+ */
+export declare const csvField: (value: string) => string;
+/**
+ * Stroke log entries as CSV, oldest first, to paste somewhere for analysis: `#` lines describing the context first (e.g.
+ * device and canvas), then a header row and one row per entry. Times are ISO 8601; measurements are in milliseconds
+ * except counts (`moves`, `frames`, `layers`) and `zoomPct`; empty fields don't apply to that entry.
+ *
+ * @example
+ * strokeLogCsv(log.entries, { version: "1.13.0" });
+ * // "# version: 1.13.0\ntime,event,detail,gap,…\n2026-10-31T20:37:55.545Z,start,mouse,6.7,0.2,…"
+ */
+export declare const strokeLogCsv: (entries: readonly StrokeLogEntry[], context?: Record<string, string | number>) => string;

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

@@ -0,0 +1,257 @@
+// src/lib/classes/StrokeLog/index.ts
+/** Default number of log entries kept */
+var DEFAULT_STROKE_LOG_LIMIT = 200;
+/** Round a measurement to 0.1 */
+var round = (value) => Math.round(value * 10) / 10;
+/**
+* Records when brush and eraser strokes start, end, are cancelled or are ignored, with timings for each stroke, plus
+* other work done meanwhile (see `BackgroundWork`), for the debug panel. Times are in the same clock as `event.timeStamp` and
+* `performance.now()`. Keeps only the most recent entries.
+*
+* Each finished or cancelled stroke measures (in ms unless noted):
+* - `gap`: time since the previous stroke ended
+* - `wait`: how long the press waited before it was handled (the page was busy)
+* - `begin`: time taken to start the stroke
+* - `moves`: pointer events handled (count), `maxMoveWait`: longest one waited, `moveMs`: total time handling them
+* - `frames`: frames drawn (count), `maxFrame`: longest frame to draw, `maxFrameGap`: longest time between frames
+*   (including after the last one), `overlays`: times the brush cursor was drawn (count)
+* - `end`: time taken to write the stroke into its layer
+* - `duration`: from press to release
+* - `layers`: layers drawn (count) and `zoomPct`: the zoom as a percentage, when the stroke started (if given)
+*
+* Records nothing while switched off (`enabled`); work given to `measure` still runs.
+*
+* Dispatches a `change` event when entries are added or cleared.
+*
+* @example
+* const log = new StrokeLog();
+* log.begin("pen", event.timeStamp, 2);
+* log.move(event.timeStamp, 0.5);
+* log.end(event.timeStamp, 3); // entry with kind "end" and its measures
+*/
+var StrokeLog = class extends EventTarget {
+	/** Maximum number of entries kept */
+	limit;
+	/** Current time in milliseconds (replaceable for tests) */
+	now = () => performance.now();
+	/** Whether anything is recorded */
+	enabled = true;
+	items = [];
+	stroke;
+	/** When the last stroke ended or was cancelled (event time) */
+	lastEnd;
+	constructor(limit = 200) {
+		super();
+		this.limit = limit;
+	}
+	/** Logged entries, oldest first */
+	get entries() {
+		return this.items;
+	}
+	/** Whether a stroke is being measured */
+	get drawing() {
+		return this.stroke !== void 0;
+	}
+	/**
+	* A stroke started: the pointer type, when it pressed (event time), how long starting the stroke took, and what was on
+	* screen.
+	*/
+	begin(pointerType, eventTime, beginMs, scene) {
+		if (!this.enabled) return;
+		const handled = this.now() - beginMs;
+		this.stroke = {
+			scene,
+			pointerType,
+			startTime: eventTime,
+			startWait: Math.max(0, handled - eventTime),
+			beginMs,
+			moves: 0,
+			maxMoveWait: 0,
+			moveMs: 0,
+			frames: 0,
+			maxFrameMs: 0,
+			lastFrameAt: handled,
+			maxFrameGap: 0,
+			overlays: 0,
+			gap: this.lastEnd === void 0 ? void 0 : eventTime - this.lastEnd
+		};
+		this.add("start", pointerType, {
+			wait: this.stroke.startWait,
+			...this.stroke.gap === void 0 ? {} : { gap: this.stroke.gap },
+			...scene
+		});
+	}
+	/**
+	* The stroke continued: when the pointer moved (event time) and how long handling it took.
+	*/
+	move(eventTime, moveMs) {
+		const stroke = this.stroke;
+		if (!stroke) return;
+		const handled = this.now() - moveMs;
+		stroke.moves++;
+		stroke.moveMs += moveMs;
+		stroke.maxMoveWait = Math.max(stroke.maxMoveWait, handled - eventTime);
+	}
+	/**
+	* A frame was drawn, taking `ms`; counted towards the stroke in progress, if any.
+	*/
+	frame(ms) {
+		const stroke = this.stroke;
+		if (!stroke) return;
+		const now = this.now();
+		stroke.frames++;
+		stroke.maxFrameMs = Math.max(stroke.maxFrameMs, ms);
+		stroke.maxFrameGap = Math.max(stroke.maxFrameGap, now - stroke.lastFrameAt);
+		stroke.lastFrameAt = now;
+	}
+	/**
+	* The brush cursor was drawn; counted towards the stroke in progress, if any.
+	*/
+	overlay() {
+		if (this.stroke) this.stroke.overlays++;
+	}
+	/**
+	* The stroke finished: when the pointer released (event time) and how long writing it into the layer took.
+	*/
+	end(eventTime, endMs) {
+		const stroke = this.stroke;
+		if (!stroke) return;
+		this.finish("end", stroke.pointerType, eventTime, { end: endMs });
+	}
+	/**
+	* The stroke in progress was abandoned, and why.
+	*/
+	cancel(reason) {
+		const stroke = this.stroke;
+		if (!stroke) return;
+		this.finish("cancel", `${stroke.pointerType}: ${reason}`, this.now(), {});
+	}
+	/**
+	* A pointer press didn't start a stroke, and why.
+	*/
+	ignore(pointerType, reason) {
+		this.add("ignore", `${pointerType}: ${reason}`, {});
+	}
+	/**
+	* A touch gesture did an action.
+	*/
+	gesture(gesture, action) {
+		this.add("gesture", `${gesture}: ${action}`, {});
+	}
+	/**
+	* Other work was done, with its measurements: `ms` for how long it kept the page busy, and `total` for how long work
+	* that finishes later took altogether (which can include waiting that doesn't keep the page busy).
+	*/
+	work(name, measures) {
+		this.add("work", name, measures);
+	}
+	/**
+	* Run some work and return its result, logging how long it kept the page busy, or for work that finishes later (a
+	* promise), how long it took altogether once it settles.
+	*
+	* @example
+	* log.measure("map", () => drawMap()); // logs "map" with how long it took
+	* log.measure("save", () => save()); // logs "save" with how long it took once saved (or failed)
+	*/
+	measure(name, run) {
+		if (!this.enabled) return run();
+		const start = this.now();
+		const result = run();
+		if (result instanceof Promise) {
+			const done = () => this.work(name, { total: this.now() - start });
+			result.then(done, done);
+		} else this.work(name, { ms: this.now() - start });
+		return result;
+	}
+	/**
+	* Remove all entries.
+	*/
+	clear() {
+		this.items = [];
+		this.dispatchEvent(new Event("change"));
+	}
+	/** Log a finished or cancelled stroke with its measurements, and stop measuring it */
+	finish(kind, detail, eventTime, extra) {
+		const stroke = this.stroke;
+		this.stroke = void 0;
+		this.lastEnd = eventTime;
+		this.add(kind, detail, {
+			...stroke.gap === void 0 ? {} : { gap: stroke.gap },
+			wait: stroke.startWait,
+			begin: stroke.beginMs,
+			moves: stroke.moves,
+			maxMoveWait: stroke.maxMoveWait,
+			moveMs: stroke.moveMs,
+			frames: stroke.frames,
+			maxFrame: stroke.maxFrameMs,
+			maxFrameGap: Math.max(stroke.maxFrameGap, this.now() - stroke.lastFrameAt),
+			overlays: stroke.overlays,
+			...extra,
+			duration: eventTime - stroke.startTime,
+			...stroke.scene
+		});
+	}
+	/** Add an entry, rounding its measurements (unless switched off) */
+	add(kind, detail, measures) {
+		if (!this.enabled) return;
+		const rounded = Object.fromEntries(Object.entries(measures).map(([name, value]) => [name, round(value)]));
+		this.items = [...this.items, {
+			at: Date.now(),
+			kind,
+			detail,
+			measures: rounded
+		}].slice(-this.limit);
+		this.dispatchEvent(new Event("change"));
+	}
+};
+/** The stroke log's CSV columns after time, event and detail: every measurement, in order */
+var STROKE_LOG_COLUMNS = [
+	"gap",
+	"wait",
+	"begin",
+	"moves",
+	"maxMoveWait",
+	"moveMs",
+	"frames",
+	"maxFrame",
+	"maxFrameGap",
+	"overlays",
+	"end",
+	"duration",
+	"layers",
+	"zoomPct",
+	"ms",
+	"total"
+];
+/**
+* A CSV field, quoted if it holds a comma, quote or line break.
+*
+* @example
+* csvField('a "b", c'); // '"a ""b"", c"'
+*/
+var csvField = (value) => /[",\n\r]/.test(value) ? `"${value.replaceAll("\"", "\"\"")}"` : value;
+/**
+* Stroke log entries as CSV, oldest first, to paste somewhere for analysis: `#` lines describing the context first (e.g.
+* device and canvas), then a header row and one row per entry. Times are ISO 8601; measurements are in milliseconds
+* except counts (`moves`, `frames`, `layers`) and `zoomPct`; empty fields don't apply to that entry.
+*
+* @example
+* strokeLogCsv(log.entries, { version: "1.13.0" });
+* // "# version: 1.13.0\ntime,event,detail,gap,…\n2026-10-31T20:37:55.545Z,start,mouse,6.7,0.2,…"
+*/
+var strokeLogCsv = (entries, context = {}) => [
+	...Object.entries(context).map(([name, value]) => `# ${name}: ${value}`),
+	[
+		"time",
+		"event",
+		"detail",
+		...STROKE_LOG_COLUMNS
+	].join(","),
+	...entries.map(({ at, kind, detail, measures }) => [
+		new Date(at).toISOString(),
+		kind,
+		csvField(detail),
+		...STROKE_LOG_COLUMNS.map((name) => name in measures ? String(measures[name]) : "")
+	].join(","))
+].join("\n");
+export { DEFAULT_STROKE_LOG_LIMIT, STROKE_LOG_COLUMNS, csvField, StrokeLog as default, strokeLogCsv };

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

@@ -0,0 +1,108 @@
+/** A point in screen (CSS pixel) or canvas (image pixel) coordinates */
+export interface Point {
+    x: number;
+    y: number;
+}
+/** A rectangle in canvas pixels */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Space reserved on each side of the screen by the interface (e.g. toolbar and panels), in CSS pixels */
+export interface Insets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** Zoom steps used by the zoom tool, from 1/16 to 32× */
+export declare const ZOOM_LEVELS: readonly [0.0625, 0.125, 0.25, number, 0.5, number, 1, 1.5, 2, 3, 4, 6, 8, 12, 16, 24, 32];
+/** Smallest zoom */
+export declare const MIN_ZOOM: number;
+/** Largest zoom */
+export declare const MAX_ZOOM: number;
+/** Screen space (CSS pixels) of canvas that must stay visible so it can't be panned out of reach */
+export declare const MIN_VISIBLE = 64;
+/** Space left around the canvas when fitting it to the screen, in CSS pixels */
+export declare const FIT_PADDING = 24;
+/**
+ * The user's view of the canvas: zoom level and position. Converts between screen and canvas coordinates.
+ *
+ * The canvas pixel at `(0, 0)` is drawn at screen position `(offsetX, offsetY)`, and one canvas pixel is `zoom` CSS pixels wide.
+ *
+ * Dispatches a `change` event whenever the view moves or zooms.
+ *
+ * @example
+ * const view = new Viewport(2000, 2000);
+ * view.resize(1280, 800);
+ * view.fit();
+ * view.zoomAt({ x: 640, y: 400 }, 2);
+ * view.screenToCanvas({ x: 640, y: 400 }); // canvas point under the screen centre
+ */
+export default class Viewport extends EventTarget {
+    /** Canvas width in pixels */
+    readonly canvasWidth: number;
+    /** Canvas height in pixels */
+    readonly canvasHeight: number;
+    /** Screen width in CSS pixels */
+    width: number;
+    /** Screen height in CSS pixels */
+    height: number;
+    /** CSS pixels per canvas pixel */
+    zoom: number;
+    /** Screen X of the canvas's left edge */
+    offsetX: number;
+    /** Screen Y of the canvas's top edge */
+    offsetY: number;
+    constructor(canvasWidth: number, canvasHeight: number);
+    /**
+     * Convert a screen point to canvas pixels.
+     */
+    screenToCanvas({ x, y }: Point): Point;
+    /**
+     * Convert a canvas point to screen (CSS) pixels.
+     */
+    canvasToScreen({ x, y }: Point): Point;
+    /**
+     * The part of the canvas currently visible on screen, clipped to the canvas.
+     */
+    visibleRect(): Rect;
+    /**
+     * Set the screen size (e.g. when the window resizes). Keeps the view in reach.
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Zoom and centre so the whole canvas fits in the space not covered by the interface (never zooming in past 100%).
+     */
+    fit(insets?: Insets): void;
+    /**
+     * Move the view so a canvas point is in the middle of the space not covered by the interface (e.g. clicking the canvas map).
+     */
+    centreOn({ x, y }: Point, insets?: Insets): void;
+    /**
+     * Move the view by a distance in screen pixels (e.g. while dragging with the pan tool).
+     */
+    panBy(dx: number, dy: number): void;
+    /**
+     * Zoom to a level, keeping the canvas point under `anchor` (a screen point) in place.
+     */
+    zoomAt(anchor: Point, zoom: number): void;
+    /**
+     * Zoom in one step around a screen point (zoom tool click).
+     */
+    zoomIn(anchor: Point): void;
+    /**
+     * Zoom out one step around a screen point (zoom tool Alt+click).
+     */
+    zoomOut(anchor: Point): void;
+    /**
+     * Keep at least `MIN_VISIBLE` pixels of the canvas on screen in each direction.
+     */
+    private constrain;
+    /**
+     * Dispatch a `change` event.
+     */
+    private notify;
+}