@lvl99dotcom/paintcanvas 0.0.0-stage → 0.2.0

package/dist/lib/rendering/cursors/index.js

@@ -0,0 +1,23 @@
+// src/lib/rendering/cursors/index.ts
+/**
+* Build a CSS cursor from SVG path data drawn on a 24×24 grid: black lines with a white outline so it shows on any colour.
+*
+* @param hotspot - the point (in the 24×24 grid) that is the cursor's exact position
+* @param fallback - standard cursor used if the image cannot be shown
+*
+* @example
+* svgCursor("M4 4 L20 20", [4, 4], "crosshair"); // 'url("data:image/svg+xml,...") 4 4, crosshair'
+*/
+var svgCursor = (path, hotspot, fallback) => {
+	const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke-linecap="round" stroke-linejoin="round"><path d="${path}" stroke="#ffffff" stroke-width="3.5"/><path d="${path}" stroke="#000000" stroke-width="1.5"/></svg>`;
+	return `url("data:image/svg+xml,${encodeURIComponent(svg)}") ${hotspot[0]} ${hotspot[1]}, ${fallback}`;
+};
+/** Colour sample (eyedropper): a pipette pointing down to the left; the point is at its tip */
+var EYEDROPPER_CURSOR = svgCursor("M2 22 L3 18 L12 9 L15 12 L6 21 Z M10 7 L17 14 M14 10 L18 6 C19 5 20 4 21 5 C22 6 21 7 20 8 L16 12", [2, 22], "crosshair");
+/** Polygon lasso: a straight-edged loop with a tail; the point is at the tail's end */
+var POLYGON_LASSO_CURSOR = svgCursor("M3 21 L7 15 M7 15 L5 6 L13 2 L21 7 L17 15 Z", [3, 21], "crosshair");
+/** Freeform lasso: an irregular hand-drawn loop with a tail; the point is at the tail's end */
+var FREEFORM_LASSO_CURSOR = svgCursor("M3 21 C3 19 5 18 7 17 C7 17 5 16 4 14 C2 10 4 6 8 5 C11 4 12 6 15 4 C18 3 22 6 20 10 C19 13 21 15 18 16 C15 17 11 15 9 16 C8 16.5 7.5 17 7 17", [3, 21], "crosshair");
+/** Rotate: the browser's grab cursor, as browsers have no standard rotate cursor */
+var ROTATE_CURSOR = "grab";
+export { EYEDROPPER_CURSOR, FREEFORM_LASSO_CURSOR, POLYGON_LASSO_CURSOR, ROTATE_CURSOR, svgCursor };

package/dist/lib/rendering/maskOutline/index.d.ts

@@ -0,0 +1,22 @@
+import type Viewport from "../../classes/Viewport";
+import type { Point } from "../../classes/Viewport";
+import type { OutlineLoop } from "../outline";
+import type { MaskShape } from "../../selection/Selection";
+/** The drawing operations mask outlines need */
+export type OutlineContext = Pick<CanvasRenderingContext2D, "save" | "restore" | "beginPath" | "moveTo" | "lineTo" | "rect" | "ellipse" | "stroke" | "fill" | "fillRect" | "strokeRect" | "setLineDash" | "strokeStyle" | "fillStyle" | "lineWidth" | "lineDashOffset">;
+/** Length of each dash, in CSS pixels */
+export declare const DASH_LENGTH = 4;
+/** Size of polygon node handles, in CSS pixels */
+export declare const NODE_SIZE = 5;
+/** Colours of the alternating dashes: white, then black */
+export declare const DASH_COLOURS: readonly ["#ffffff", "#000000"];
+/**
+ * Draw the mask's outline as "crawling ants": alternating white and black dashes. Animate by increasing `dashOffset` over time.
+ *
+ * @param loops - outline loops in canvas pixels
+ */
+export declare const drawMaskOutline: (ctx: OutlineContext, loops: readonly OutlineLoop[], view: Viewport, pixelRatio: number, dashOffset: number) => void;
+/**
+ * Draw a lasso shape in progress as alternating white and black dashes, with handles (white with a black border) on polygon nodes.
+ */
+export declare const drawLassoPreview: (ctx: OutlineContext, shape: MaskShape, nodes: readonly Point[], view: Viewport, pixelRatio: number) => void;

package/dist/lib/rendering/maskOutline/index.js

@@ -0,0 +1,78 @@
+// src/lib/rendering/maskOutline/index.ts
+/** Length of each dash, in CSS pixels */
+var DASH_LENGTH = 4;
+/** Size of polygon node handles, in CSS pixels */
+var NODE_SIZE = 5;
+/** Colours of the alternating dashes: white, then black */
+var DASH_COLOURS = ["#ffffff", "#000000"];
+/**
+* Stroke the current path as alternating white and black dashes, 1 px wide in device pixels.
+* One of the two colours always shows, on any background, without blend modes.
+*/
+var strokeAlternating = (ctx, pixelRatio, dashOffset) => {
+	ctx.lineWidth = pixelRatio;
+	ctx.setLineDash([]);
+	ctx.strokeStyle = DASH_COLOURS[0];
+	ctx.stroke();
+	ctx.setLineDash([4 * pixelRatio, 4 * pixelRatio]);
+	ctx.lineDashOffset = dashOffset * pixelRatio;
+	ctx.strokeStyle = DASH_COLOURS[1];
+	ctx.stroke();
+};
+/**
+* Draw the mask's outline as "crawling ants": alternating white and black dashes. Animate by increasing `dashOffset` over time.
+*
+* @param loops - outline loops in canvas pixels
+*/
+var drawMaskOutline = (ctx, loops, view, pixelRatio, dashOffset) => {
+	ctx.save();
+	ctx.beginPath();
+	for (const loop of loops) for (let i = 0; i < loop.length; i += 2) {
+		const { x, y } = view.canvasToScreen({
+			x: loop[i],
+			y: loop[i + 1]
+		});
+		if (i === 0) ctx.moveTo(x * pixelRatio, y * pixelRatio);
+		else ctx.lineTo(x * pixelRatio, y * pixelRatio);
+	}
+	strokeAlternating(ctx, pixelRatio, dashOffset);
+	ctx.restore();
+};
+/**
+* Draw a lasso shape in progress as alternating white and black dashes, with handles (white with a black border) on polygon nodes.
+*/
+var drawLassoPreview = (ctx, shape, nodes, view, pixelRatio) => {
+	const toDevice = (point) => {
+		const { x, y } = view.canvasToScreen(point);
+		return {
+			x: x * pixelRatio,
+			y: y * pixelRatio
+		};
+	};
+	ctx.save();
+	ctx.beginPath();
+	if (shape.type === "polygon") shape.points.forEach((point, i) => {
+		const { x, y } = toDevice(point);
+		if (i === 0) ctx.moveTo(x, y);
+		else ctx.lineTo(x, y);
+	});
+	else {
+		const { x, y } = toDevice(shape.rect);
+		const width = shape.rect.width * view.zoom * pixelRatio;
+		const height = shape.rect.height * view.zoom * pixelRatio;
+		if (shape.type === "rect") ctx.rect(x, y, width, height);
+		else ctx.ellipse(x + width / 2, y + height / 2, width / 2, height / 2, 0, 0, Math.PI * 2);
+	}
+	strokeAlternating(ctx, pixelRatio, 0);
+	const size = 5 * pixelRatio;
+	ctx.setLineDash([]);
+	ctx.fillStyle = DASH_COLOURS[0];
+	ctx.strokeStyle = DASH_COLOURS[1];
+	for (const node of nodes) {
+		const { x, y } = toDevice(node);
+		ctx.fillRect(x - size / 2, y - size / 2, size, size);
+		ctx.strokeRect(x - size / 2, y - size / 2, size, size);
+	}
+	ctx.restore();
+};
+export { DASH_COLOURS, DASH_LENGTH, NODE_SIZE, drawLassoPreview, drawMaskOutline };

package/dist/lib/rendering/outline/index.d.ts

@@ -0,0 +1,36 @@
+/** A line from (x1, y1) to (x2, y2), in coordinates from 0 to 1 across the shape (or pixels, if not normalised) */
+export type OutlineSegment = [x1: number, y1: number, x2: number, y2: number];
+/** Options for tracing an outline */
+export interface TraceOptions {
+    /** Alpha value (0–255) at or above which a pixel is inside */
+    threshold?: number;
+    /** Return coordinates from 0 to 1 (default) or in pixels */
+    normalise?: boolean;
+    /** Only trace within this pixel area (e.g. the mask's bounding box) */
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Trace the outline of a shape from its alpha values (marching squares). Pixels at or above the threshold are inside.
+ * Returns line segments in coordinates from 0 to 1 (so the outline can be drawn at any size), or in pixels.
+ * Outline points lie halfway between pixel centres, so in pixels they are always whole or half numbers.
+ *
+ * @param alpha - one alpha value (0–255) per pixel, row by row
+ *
+ * @example
+ * traceOutline(new Uint8ClampedArray([0, 0, 0, 0, 255, 0, 0, 0, 0]), 3, 3); // segments around the centre pixel
+ */
+export declare const traceOutline: (alpha: ArrayLike<number>, width: number, height: number, { threshold, normalise, bounds }?: TraceOptions) => OutlineSegment[];
+/** A closed outline as a list of points, `[x0, y0, x1, y1, ...]` */
+export type OutlineLoop = number[];
+/**
+ * Join outline segments into closed loops, so dashed lines flow continuously along the outline. Straight runs are merged into single lines.
+ *
+ * @example
+ * chainSegments(traceOutline(alpha, width, height, { normalise: false }));
+ */
+export declare const chainSegments: (segments: readonly OutlineSegment[]) => OutlineLoop[];

package/dist/lib/rendering/outline/index.js

@@ -0,0 +1,120 @@
+// src/lib/rendering/outline/index.ts
+/**
+* Trace the outline of a shape from its alpha values (marching squares). Pixels at or above the threshold are inside.
+* Returns line segments in coordinates from 0 to 1 (so the outline can be drawn at any size), or in pixels.
+* Outline points lie halfway between pixel centres, so in pixels they are always whole or half numbers.
+*
+* @param alpha - one alpha value (0–255) per pixel, row by row
+*
+* @example
+* traceOutline(new Uint8ClampedArray([0, 0, 0, 0, 255, 0, 0, 0, 0]), 3, 3); // segments around the centre pixel
+*/
+var traceOutline = (alpha, width, height, { threshold = 128, normalise = true, bounds } = {}) => {
+	const inside = (x, y) => x >= 0 && y >= 0 && x < width && y < height && alpha[y * width + x] >= threshold;
+	const segments = [];
+	const scaleX = normalise ? width : 1;
+	const scaleY = normalise ? height : 1;
+	const add = (x1, y1, x2, y2) => segments.push([
+		x1 / scaleX,
+		y1 / scaleY,
+		x2 / scaleX,
+		y2 / scaleY
+	]);
+	const fromX = bounds ? Math.max(-1, bounds.x - 1) : -1;
+	const fromY = bounds ? Math.max(-1, bounds.y - 1) : -1;
+	const toX = bounds ? Math.min(width, bounds.x + bounds.width) : width;
+	const toY = bounds ? Math.min(height, bounds.y + bounds.height) : height;
+	for (let y = fromY; y < toY; y++) for (let x = fromX; x < toX; x++) {
+		const tl = inside(x, y);
+		const tr = inside(x + 1, y);
+		const br = inside(x + 1, y + 1);
+		const bl = inside(x, y + 1);
+		const cell = (tl ? 8 : 0) | (tr ? 4 : 0) | (br ? 2 : 0) | (bl ? 1 : 0);
+		if (cell === 0 || cell === 15) continue;
+		const top = [x + 1, y + .5];
+		const right = [x + 1.5, y + 1];
+		const bottom = [x + 1, y + 1.5];
+		const left = [x + .5, y + 1];
+		const line = (a, b) => add(a[0], a[1], b[0], b[1]);
+		switch (cell) {
+			case 1:
+			case 14:
+				line(left, bottom);
+				break;
+			case 2:
+			case 13:
+				line(bottom, right);
+				break;
+			case 3:
+			case 12:
+				line(left, right);
+				break;
+			case 4:
+			case 11:
+				line(top, right);
+				break;
+			case 6:
+			case 9:
+				line(top, bottom);
+				break;
+			case 7:
+			case 8:
+				line(left, top);
+				break;
+			case 5:
+				line(left, top);
+				line(bottom, right);
+				break;
+			case 10:
+				line(top, right);
+				line(left, bottom);
+		}
+	}
+	return segments;
+};
+/**
+* Join outline segments into closed loops, so dashed lines flow continuously along the outline. Straight runs are merged into single lines.
+*
+* @example
+* chainSegments(traceOutline(alpha, width, height, { normalise: false }));
+*/
+var chainSegments = (segments) => {
+	const key = (x, y) => `${x},${y}`;
+	const ends = /* @__PURE__ */ new Map();
+	segments.forEach(([x1, y1, x2, y2], i) => {
+		for (const k of [key(x1, y1), key(x2, y2)]) {
+			const list = ends.get(k);
+			if (list) list.push(i);
+			else ends.set(k, [i]);
+		}
+	});
+	const used = new Uint8Array(segments.length);
+	const loops = [];
+	for (let start = 0; start < segments.length; start++) {
+		if (used[start]) continue;
+		used[start] = 1;
+		const [sx, sy, ex, ey] = segments[start];
+		const loop = [sx, sy];
+		let x = ex;
+		let y = ey;
+		for (;;) {
+			const n = loop.length;
+			if (n >= 4) {
+				const ax = loop[n - 4];
+				const ay = loop[n - 3];
+				const bx = loop[n - 2];
+				const by = loop[n - 1];
+				if ((bx - ax) * (y - ay) === (by - ay) * (x - ax)) loop.length -= 2;
+			}
+			loop.push(x, y);
+			const next = ends.get(key(x, y)).find((i) => !used[i]);
+			if (next === void 0) break;
+			used[next] = 1;
+			const [x1, y1, x2, y2] = segments[next];
+			[x, y] = x1 === x && y1 === y ? [x2, y2] : [x1, y1];
+		}
+		loops.push(loop);
+	}
+	return loops;
+};
+export { chainSegments, traceOutline };

package/dist/lib/rendering/sample/index.d.ts

@@ -0,0 +1,55 @@
+import type { CanvasFactory } from "../../classes/Layer";
+import { type DrawableLayer } from "../compositing";
+/** How many canvas pixels across the sampling window enlarges */
+export declare const SAMPLE_PIXELS = 10;
+/** How much the sampling window enlarges each canvas pixel */
+export declare const SAMPLE_SCALE = 5;
+/** The most pixels across that an area's average is worked out from while dragging (the final average uses them all) */
+export declare const PREVIEW_MAX_PIXELS = 100;
+/** A rectangle of whole canvas pixels */
+export interface PixelRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * Format a colour as `#rrggbb`.
+ *
+ * @example
+ * toHex(255, 0, 128); // "#ff0080"
+ */
+export declare const toHex: (r: number, g: number, b: number) => string;
+/**
+ * The average colour of RGBA pixels, counting every pixel that isn't fully transparent (transparent pixels are outside
+ * the canvas). Undefined if all are transparent.
+ *
+ * @example
+ * averageColour(new Uint8ClampedArray([255, 0, 0, 255, 0, 0, 255, 255])); // "#800080"
+ */
+export declare const averageColour: (pixels: Uint8ClampedArray) => string | undefined;
+/**
+ * The whole canvas pixels a rectangle between two canvas points covers, cut to the canvas. Undefined if it's outside.
+ *
+ * @example
+ * pixelRect({ x: 2.5, y: 8 }, { x: -3, y: 1.2 }, 100, 100); // { x: 0, y: 1, width: 3, height: 8 }
+ */
+export declare const pixelRect: (a: {
+    x: number;
+    y: number;
+}, b: {
+    x: number;
+    y: number;
+}, canvasWidth: number, canvasHeight: number) => PixelRect | undefined;
+/**
+ * Draw an area of the canvas as it's shown (the white background, then every layer mixed as shown) onto a new canvas,
+ * scaled to fit `width` × `height`. Parts outside the canvas stay transparent.
+ *
+ * @example
+ * flattenArea(app.drawables, app.createCanvas, app.width, app.height, { x: 10, y: 10, width: 10, height: 10 });
+ */
+export declare const flattenArea: (layers: readonly DrawableLayer[], createCanvas: CanvasFactory, canvasWidth: number, canvasHeight: number, area: PixelRect, width?: number, height?: number) => OffscreenCanvas;
+/**
+ * Read all of a canvas's pixels as RGBA.
+ */
+export declare const readPixels: (canvas: OffscreenCanvas) => Uint8ClampedArray;

package/dist/lib/rendering/sample/index.js

@@ -0,0 +1,83 @@
+import { CANVAS_BACKGROUND, drawLayers } from "../compositing/index.js";
+// src/lib/rendering/sample/index.ts
+/** How many canvas pixels across the sampling window enlarges */
+var SAMPLE_PIXELS = 10;
+/** How much the sampling window enlarges each canvas pixel */
+var SAMPLE_SCALE = 5;
+/** The most pixels across that an area's average is worked out from while dragging (the final average uses them all) */
+var PREVIEW_MAX_PIXELS = 100;
+/**
+* Format a colour as `#rrggbb`.
+*
+* @example
+* toHex(255, 0, 128); // "#ff0080"
+*/
+var toHex = (r, g, b) => `#${[
+	r,
+	g,
+	b
+].map((c) => Math.round(c).toString(16).padStart(2, "0")).join("")}`;
+/**
+* The average colour of RGBA pixels, counting every pixel that isn't fully transparent (transparent pixels are outside
+* the canvas). Undefined if all are transparent.
+*
+* @example
+* averageColour(new Uint8ClampedArray([255, 0, 0, 255, 0, 0, 255, 255])); // "#800080"
+*/
+var averageColour = (pixels) => {
+	let r = 0;
+	let g = 0;
+	let b = 0;
+	let count = 0;
+	for (let i = 0; i < pixels.length; i += 4) {
+		if (pixels[i + 3] === 0) continue;
+		r += pixels[i];
+		g += pixels[i + 1];
+		b += pixels[i + 2];
+		count++;
+	}
+	return count > 0 ? toHex(r / count, g / count, b / count) : void 0;
+};
+/**
+* The whole canvas pixels a rectangle between two canvas points covers, cut to the canvas. Undefined if it's outside.
+*
+* @example
+* pixelRect({ x: 2.5, y: 8 }, { x: -3, y: 1.2 }, 100, 100); // { x: 0, y: 1, width: 3, height: 8 }
+*/
+var pixelRect = (a, b, canvasWidth, canvasHeight) => {
+	const left = Math.max(0, Math.floor(Math.min(a.x, b.x)));
+	const top = Math.max(0, Math.floor(Math.min(a.y, b.y)));
+	const right = Math.min(canvasWidth, Math.floor(Math.max(a.x, b.x)) + 1);
+	const bottom = Math.min(canvasHeight, Math.floor(Math.max(a.y, b.y)) + 1);
+	if (right <= left || bottom <= top) return void 0;
+	return {
+		x: left,
+		y: top,
+		width: right - left,
+		height: bottom - top
+	};
+};
+/**
+* Draw an area of the canvas as it's shown (the white background, then every layer mixed as shown) onto a new canvas,
+* scaled to fit `width` × `height`. Parts outside the canvas stay transparent.
+*
+* @example
+* flattenArea(app.drawables, app.createCanvas, app.width, app.height, { x: 10, y: 10, width: 10, height: 10 });
+*/
+var flattenArea = (layers, createCanvas, canvasWidth, canvasHeight, area, width = area.width, height = area.height) => {
+	const canvas = createCanvas(width, height);
+	const ctx = canvas.getContext("2d", { willReadFrequently: true });
+	const scaleX = width / area.width;
+	const scaleY = height / area.height;
+	ctx.setTransform(scaleX, 0, 0, scaleY, -area.x * scaleX, -area.y * scaleY);
+	ctx.imageSmoothingEnabled = scaleX < 1 || scaleY < 1;
+	ctx.fillStyle = CANVAS_BACKGROUND;
+	ctx.fillRect(0, 0, canvasWidth, canvasHeight);
+	drawLayers(ctx, layers);
+	return canvas;
+};
+/**
+* Read all of a canvas's pixels as RGBA.
+*/
+var readPixels = (canvas) => canvas.getContext("2d").getImageData(0, 0, canvas.width, canvas.height).data;
+export { PREVIEW_MAX_PIXELS, SAMPLE_PIXELS, SAMPLE_SCALE, averageColour, flattenArea, pixelRect, readPixels, toHex };

package/dist/lib/rendering/screenshot/index.d.ts

@@ -0,0 +1,67 @@
+import { type CanvasFactory } from "../../classes/Layer";
+import { type DrawableLayer, type LayerOverride } from "../compositing";
+/** The parts of the File System Access API used to choose where to save (Chromium browsers only) */
+export interface SaveFilePicker {
+    (options: {
+        suggestedName: string;
+        types: {
+            description: string;
+            accept: Record<string, string[]>;
+        }[];
+    }): Promise<{
+        createWritable(): Promise<{
+            write(data: Blob): Promise<void>;
+            close(): Promise<void>;
+        }>;
+    }>;
+}
+/** A kind of file the save dialog offers */
+export interface SaveFileType {
+    description: string;
+    accept: Record<string, string[]>;
+}
+/** PNG images (screenshots) */
+export declare const PNG_FILE_TYPE: SaveFileType;
+/** JSON files (brush presets) */
+export declare const JSON_FILE_TYPE: SaveFileType;
+/** How a file is saved: with a save dialog (folder picker) or as a browser download */
+export type SaveMethod = "picker" | "download";
+/**
+ * File name for a screenshot taken at a time, starting with a prefix (see `PaintCanvasNames.filePrefix`).
+ *
+ * @example
+ * screenshotName(new Date(2026, 9, 19, 14, 30, 5)); // "paintcanvas-2026-10-19-143005.png"
+ */
+export declare const screenshotName: (date?: Date, prefix?: string) => string;
+/**
+ * Flatten all visible layers onto white at full canvas size and encode the result as a PNG.
+ *
+ * @param override - draw this image instead of one layer's canvas (e.g. a transform in progress)
+ */
+export declare const renderScreenshot: (layers: readonly DrawableLayer[], width: number, height: number, override?: LayerOverride, createCanvas?: CanvasFactory) => Promise<Blob>;
+/** A compressed snapshot: a JPEG and its size in pixels */
+export interface JpegImage {
+    blob: Blob;
+    width: number;
+    height: number;
+}
+/** JPEG qualities tried for a snapshot, best first, before making it smaller */
+export declare const SNAPSHOT_QUALITIES: readonly [0.92, 0.8, 0.7];
+/** How much smaller a snapshot gets each time it is still too large at the lowest quality */
+export declare const SNAPSHOT_SHRINK = 0.75;
+/**
+ * Flatten all visible layers onto white and encode the result as a JPEG no larger than `maxBytes` (e.g. an upload
+ * limit): full size at the best quality that fits, otherwise smaller.
+ *
+ * @param override - draw this image instead of one layer's canvas (e.g. a transform in progress)
+ * @param maxBytes - the largest file allowed (no limit by default)
+ */
+export declare const renderJpegImage: (layers: readonly DrawableLayer[], width: number, height: number, override?: LayerOverride, createCanvas?: CanvasFactory, maxBytes?: number) => Promise<JpegImage>;
+/**
+ * Save a file. Where the browser supports it, a save dialog lets the user choose the folder; otherwise it downloads.
+ * Returns how it was saved, or undefined if the user cancelled the dialog.
+ *
+ * @param picker - `window.showSaveFilePicker` (replaceable for tests)
+ * @param fileType - the kind of file the save dialog offers (PNG by default)
+ */
+export declare const saveFile: (blob: Blob, name: string, picker?: SaveFilePicker | undefined, fileType?: SaveFileType) => Promise<SaveMethod | undefined>;

package/dist/lib/rendering/screenshot/index.js

@@ -0,0 +1,96 @@
+import { createOffscreenCanvas } from "../../classes/Layer/index.js";
+import { drawFlattened } from "../compositing/index.js";
+// src/lib/rendering/screenshot/index.ts
+/** PNG images (screenshots) */
+var PNG_FILE_TYPE = {
+	description: "PNG image",
+	accept: { "image/png": [".png"] }
+};
+/** JSON files (brush presets) */
+var JSON_FILE_TYPE = {
+	description: "JSON file",
+	accept: { "application/json": [".json"] }
+};
+/**
+* File name for a screenshot taken at a time, starting with a prefix (see `PaintCanvasNames.filePrefix`).
+*
+* @example
+* screenshotName(new Date(2026, 9, 19, 14, 30, 5)); // "paintcanvas-2026-10-19-143005.png"
+*/
+var screenshotName = (date = /* @__PURE__ */ new Date(), prefix = "paintcanvas") => {
+	const pad = (n) => String(n).padStart(2, "0");
+	return `${prefix}-${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}.png`;
+};
+/**
+* Flatten all visible layers onto white at full canvas size and encode the result as a PNG.
+*
+* @param override - draw this image instead of one layer's canvas (e.g. a transform in progress)
+*/
+var renderScreenshot = async (layers, width, height, override, createCanvas = createOffscreenCanvas) => {
+	const canvas = createCanvas(width, height);
+	drawFlattened(canvas.getContext("2d"), layers, width, height, width, height, override);
+	return canvas.convertToBlob({ type: "image/png" });
+};
+/** JPEG qualities tried for a snapshot, best first, before making it smaller */
+var SNAPSHOT_QUALITIES = [
+	.92,
+	.8,
+	.7
+];
+/** How much smaller a snapshot gets each time it is still too large at the lowest quality */
+var SNAPSHOT_SHRINK = .75;
+/**
+* Flatten all visible layers onto white and encode the result as a JPEG no larger than `maxBytes` (e.g. an upload
+* limit): full size at the best quality that fits, otherwise smaller.
+*
+* @param override - draw this image instead of one layer's canvas (e.g. a transform in progress)
+* @param maxBytes - the largest file allowed (no limit by default)
+*/
+var renderJpegImage = async (layers, width, height, override, createCanvas = createOffscreenCanvas, maxBytes = Infinity) => {
+	for (let scale = 1;; scale *= SNAPSHOT_SHRINK) {
+		const targetWidth = Math.max(1, Math.round(width * scale));
+		const targetHeight = Math.max(1, Math.round(height * scale));
+		const canvas = createCanvas(targetWidth, targetHeight);
+		drawFlattened(canvas.getContext("2d"), layers, width, height, targetWidth, targetHeight, override);
+		for (const quality of SNAPSHOT_QUALITIES) {
+			const blob = await canvas.convertToBlob({
+				type: "image/jpeg",
+				quality
+			});
+			if (blob.size <= maxBytes || targetWidth === 1 && targetHeight === 1) return {
+				blob,
+				width: targetWidth,
+				height: targetHeight
+			};
+		}
+	}
+};
+/**
+* Save a file. Where the browser supports it, a save dialog lets the user choose the folder; otherwise it downloads.
+* Returns how it was saved, or undefined if the user cancelled the dialog.
+*
+* @param picker - `window.showSaveFilePicker` (replaceable for tests)
+* @param fileType - the kind of file the save dialog offers (PNG by default)
+*/
+var saveFile = async (blob, name, picker = window.showSaveFilePicker?.bind(window), fileType = PNG_FILE_TYPE) => {
+	if (picker) try {
+		const writable = await (await picker({
+			suggestedName: name,
+			types: [fileType]
+		})).createWritable();
+		await writable.write(blob);
+		await writable.close();
+		return "picker";
+	} catch (error) {
+		if (error.name === "AbortError") return void 0;
+		throw error;
+	}
+	const url = URL.createObjectURL(blob);
+	const link = document.createElement("a");
+	link.href = url;
+	link.download = name;
+	link.click();
+	setTimeout(() => URL.revokeObjectURL(url), 1e3);
+	return "download";
+};
+export { JSON_FILE_TYPE, PNG_FILE_TYPE, SNAPSHOT_QUALITIES, SNAPSHOT_SHRINK, renderJpegImage, renderScreenshot, saveFile, screenshotName };

package/dist/lib/rendering/transformBox/index.d.ts

@@ -0,0 +1,10 @@
+import type Viewport from "../../classes/Viewport";
+import { type Handle, type TransformBox } from "../../transform/geometry";
+import { type OutlineContext } from "../maskOutline";
+/** Size of transform handles, in CSS pixels */
+export declare const HANDLE_SIZE: number;
+/**
+ * Draw a transform box: a white outline with a black inner line (visible on any colour), square handles (white with a
+ * black border), and the round rotate handle on a line out from the top-centre handle.
+ */
+export declare const drawTransformBox: (ctx: OutlineContext, box: TransformBox, handles: readonly Handle[], view: Viewport, pixelRatio: number) => void;

package/dist/lib/rendering/transformBox/index.js

@@ -0,0 +1,57 @@
+import { boxCorners, handlePosition, rotateHandle } from "../../transform/geometry/index.js";
+import { DASH_COLOURS } from "../maskOutline/index.js";
+// src/lib/rendering/transformBox/index.ts
+/** Size of transform handles, in CSS pixels */
+var HANDLE_SIZE = 7;
+/**
+* Draw a transform box: a white outline with a black inner line (visible on any colour), square handles (white with a
+* black border), and the round rotate handle on a line out from the top-centre handle.
+*/
+var drawTransformBox = (ctx, box, handles, view, pixelRatio) => {
+	const toDevice = (point) => {
+		const { x, y } = view.canvasToScreen(point);
+		return {
+			x: x * pixelRatio,
+			y: y * pixelRatio
+		};
+	};
+	ctx.save();
+	ctx.setLineDash([]);
+	ctx.beginPath();
+	boxCorners(box).forEach((corner, i) => {
+		const { x, y } = toDevice(corner);
+		if (i === 0) ctx.moveTo(x, y);
+		else ctx.lineTo(x, y);
+	});
+	const first = toDevice(boxCorners(box)[0]);
+	ctx.lineTo(first.x, first.y);
+	ctx.lineWidth = pixelRatio * 3;
+	ctx.strokeStyle = DASH_COLOURS[0];
+	ctx.stroke();
+	ctx.lineWidth = pixelRatio;
+	ctx.strokeStyle = DASH_COLOURS[1];
+	ctx.stroke();
+	const rotation = rotateHandle(box, toDevice, 24 * pixelRatio);
+	ctx.beginPath();
+	ctx.moveTo(rotation.anchor.x, rotation.anchor.y);
+	ctx.lineTo(rotation.handle.x, rotation.handle.y);
+	ctx.lineWidth = pixelRatio * 3;
+	ctx.strokeStyle = DASH_COLOURS[0];
+	ctx.stroke();
+	ctx.lineWidth = pixelRatio;
+	ctx.strokeStyle = DASH_COLOURS[1];
+	ctx.stroke();
+	const size = HANDLE_SIZE * pixelRatio;
+	ctx.fillStyle = DASH_COLOURS[0];
+	ctx.beginPath();
+	ctx.ellipse(rotation.handle.x, rotation.handle.y, size / 2, size / 2, 0, 0, Math.PI * 2);
+	ctx.fill();
+	ctx.stroke();
+	for (const handle of handles) {
+		const { x, y } = toDevice(handlePosition(box, handle));
+		ctx.fillRect(x - size / 2, y - size / 2, size, size);
+		ctx.strokeRect(x - size / 2, y - size / 2, size, size);
+	}
+	ctx.restore();
+};
+export { HANDLE_SIZE, drawTransformBox };