@lvl99dotcom/paintcanvas 0.0.0-stage → 0.2.0

package/dist/lib/presets/schema.js

@@ -0,0 +1,181 @@
+// src/lib/presets/schema.ts
+/** Matches a lowercase UUID */
+var UUID_PATTERN = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$";
+/** The `format` of a brush preset file, unless the implementer names their own (see `PaintCanvasNames`) */
+var BRUSH_PRESET_FILE_FORMAT = "paintcanvas-brush-presets";
+/** Formats of brush preset files that are imported by default */
+var BRUSH_PRESET_FILE_FORMATS = [BRUSH_PRESET_FILE_FORMAT];
+/** Longest brush preset file format name (characters) */
+var MAX_PRESET_FILE_FORMAT_LENGTH = 100;
+/** The version of the brush preset file format */
+var BRUSH_PRESET_FILE_VERSION = 1;
+/** Most presets in one file */
+var MAX_PRESETS_PER_FILE = 1e3;
+/** Longest preset name, author name or handle (characters) */
+var MAX_PRESET_TEXT_LENGTH = 100;
+/** Longest brush shape data URL (characters): a 2 MB PNG as base64 */
+var MAX_SHAPE_DATA_URL_LENGTH = Math.ceil(2097152 / 3) * 4 + 22;
+/** Matches a PNG data URL */
+var PNG_DATA_URL_PATTERN = "^data:image/png;base64,[A-Za-z0-9+/]+={0,2}$";
+/** A 0–1 factor */
+var factor = {
+	type: "number",
+	minimum: 0,
+	maximum: 1
+};
+/** How a brush parameter varies per stamp (see `BrushParamConfig` in the app) */
+var paramConfig = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		useRandomise: { type: "boolean" },
+		minRandomise: factor,
+		maxRandomise: factor,
+		usePressure: { type: "boolean" },
+		minPressure: factor,
+		maxPressure: factor,
+		useTilt: { type: "boolean" },
+		minTilt: factor,
+		maxTilt: factor
+	}
+};
+/** A colour value: a number, or a number as text */
+var colourValue = { anyOf: [{ type: "number" }, {
+	type: "string",
+	maxLength: 20
+}] };
+/** Short text, such as a name */
+var text = {
+	type: "string",
+	minLength: 1,
+	maxLength: 100
+};
+/** JSON schema for a brush preset a user made or imported (see `BrushConfig` in the app) */
+var brushPresetSchema = {
+	$id: "paintcanvas/brush-preset",
+	type: "object",
+	additionalProperties: false,
+	required: ["id"],
+	properties: {
+		id: {
+			type: "string",
+			pattern: UUID_PATTERN
+		},
+		name: text,
+		group: text,
+		version: {
+			type: "string",
+			maxLength: 20
+		},
+		author: { anyOf: [text, {
+			type: "object",
+			additionalProperties: false,
+			required: ["name"],
+			properties: {
+				name: text,
+				handle: text,
+				email: {
+					type: "string",
+					maxLength: 254
+				},
+				website: {
+					type: "string",
+					maxLength: 2048
+				}
+			}
+		}] },
+		image: {
+			type: "string",
+			pattern: PNG_DATA_URL_PATTERN,
+			maxLength: MAX_SHAPE_DATA_URL_LENGTH
+		},
+		colourMode: { enum: [0, 1] },
+		hue: colourValue,
+		hueConfig: paramConfig,
+		saturation: colourValue,
+		saturationConfig: paramConfig,
+		lightness: colourValue,
+		lightnessConfig: paramConfig,
+		red: colourValue,
+		redConfig: paramConfig,
+		green: colourValue,
+		greenConfig: paramConfig,
+		blue: colourValue,
+		blueConfig: paramConfig,
+		alpha: factor,
+		alphaConfig: paramConfig,
+		width: {
+			type: "number",
+			minimum: 1,
+			maximum: 256
+		},
+		widthConfig: paramConfig,
+		height: {
+			type: "number",
+			minimum: 1,
+			maximum: 256
+		},
+		heightConfig: paramConfig,
+		constrainProportions: { type: "boolean" },
+		rotation: {
+			type: "number",
+			minimum: -360,
+			maximum: 360
+		},
+		rotationConfig: paramConfig,
+		offsetX: {
+			type: "number",
+			minimum: -256,
+			maximum: 256
+		},
+		offsetXConfig: paramConfig,
+		offsetY: {
+			type: "number",
+			minimum: -256,
+			maximum: 256
+		},
+		offsetYConfig: paramConfig,
+		sampleRate: {
+			type: "number",
+			minimum: 5,
+			maximum: 400
+		},
+		smoothingType: { enum: [
+			0,
+			1,
+			2,
+			3
+		] },
+		spacing: {
+			type: "number",
+			minimum: 0,
+			maximum: 200
+		},
+		snapToPixelGrid: { type: "boolean" }
+	}
+};
+/** JSON schema for a brush preset file */
+var brushPresetFileSchema = {
+	$id: "paintcanvas/brush-preset-file",
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"format",
+		"version",
+		"presets"
+	],
+	properties: {
+		format: {
+			type: "string",
+			minLength: 1,
+			maxLength: 100
+		},
+		version: { const: 1 },
+		presets: {
+			type: "array",
+			maxItems: MAX_PRESETS_PER_FILE,
+			items: { $ref: "brush-preset" }
+		}
+	}
+};
+export { BRUSH_PRESET_FILE_FORMAT, BRUSH_PRESET_FILE_FORMATS, BRUSH_PRESET_FILE_VERSION, MAX_PRESETS_PER_FILE, MAX_PRESET_FILE_FORMAT_LENGTH, MAX_PRESET_TEXT_LENGTH, MAX_SHAPE_DATA_URL_LENGTH, PNG_DATA_URL_PATTERN, UUID_PATTERN, brushPresetFileSchema, brushPresetSchema };

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

@@ -0,0 +1,63 @@
+import type { BrushConfig } from "../../brushes/types";
+import type { StampParams } from "../../brushes/params";
+import { type CanvasFactory } from "../../classes/Layer";
+import { type OutlineSegment } from "../outline";
+/** The drawing operations a stamp needs */
+export type StampContext = Pick<OffscreenCanvasRenderingContext2D, "save" | "restore" | "translate" | "rotate" | "beginPath" | "ellipse" | "fill" | "drawImage" | "fillStyle" | "globalAlpha">;
+/** A decoded image usable as a brush shape */
+export type TipImage = CanvasImageSource & {
+    width: number;
+    height: number;
+};
+/** Turns a preset's `image` (data URL or bytes) into a decoded image; replaceable for tests */
+export type ImageDecoder = (image: string | Uint8Array) => Promise<TipImage>;
+/**
+ * The bytes and media type in a `data:` URL, read without `fetch()` (which the site's Content Security Policy doesn't
+ * allow for `data:` URLs). Throws for anything that isn't a `data:` URL.
+ *
+ * @example
+ * dataUrlBytes("data:image/png;base64,iVBO..."); // { type: "image/png", bytes: Uint8Array [137, 80, 78, 71, ...] }
+ * dataUrlBytes("data:text/plain,a%20b"); // { type: "text/plain", bytes: Uint8Array [97, 32, 98] }
+ */
+export declare const dataUrlBytes: (url: string) => {
+    type: string;
+    bytes: Uint8Array<ArrayBuffer>;
+};
+/**
+ * Decode a data URL or image file bytes using the browser's image decoder.
+ */
+export declare const decodeImage: ImageDecoder;
+/**
+ * A brush shape that can be stamped in any colour, size and rotation.
+ *
+ * Presets without an image use a hard round shape drawn as a vector ellipse, so it stays crisp at every size.
+ * Presets with an image use only its alpha values; tinted copies are cached per colour.
+ *
+ * @example
+ * const tip = await BrushTip.load(preset);
+ * tip.stamp(ctx, 100, 100, params, "#ff0000");
+ */
+export default class BrushTip {
+    /** Alpha mask of the shape image, or undefined for the round shape */
+    readonly mask?: OffscreenCanvas;
+    /** Outline of the shape in 0–1 coordinates (for the brush cursor), or undefined for the round shape */
+    readonly outline?: OutlineSegment[];
+    private readonly createCanvas;
+    private tintedColour;
+    private tinted?;
+    constructor(mask?: OffscreenCanvas, outline?: OutlineSegment[], createCanvas?: CanvasFactory);
+    /** Whether this is the built-in round shape */
+    get isRound(): boolean;
+    /**
+     * Load a preset's shape: decodes its image and keeps only the alpha. Presets without an image get the round shape.
+     */
+    static load(preset: BrushConfig, decode?: ImageDecoder, createCanvas?: CanvasFactory): Promise<BrushTip>;
+    /**
+     * The shape image tinted with a colour (cached until the colour changes).
+     */
+    private tint;
+    /**
+     * Stamp the shape centred on a point, with the stamp's size, rotation, offset and alpha.
+     */
+    stamp(ctx: StampContext, x: number, y: number, params: StampParams, colour: string): void;
+}

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

@@ -0,0 +1,112 @@
+import { createOffscreenCanvas } from "../../classes/Layer/index.js";
+import { traceOutline } from "../outline/index.js";
+// src/lib/rendering/BrushTip/index.ts
+/**
+* The bytes and media type in a `data:` URL, read without `fetch()` (which the site's Content Security Policy doesn't
+* allow for `data:` URLs). Throws for anything that isn't a `data:` URL.
+*
+* @example
+* dataUrlBytes("data:image/png;base64,iVBO..."); // { type: "image/png", bytes: Uint8Array [137, 80, 78, 71, ...] }
+* dataUrlBytes("data:text/plain,a%20b"); // { type: "text/plain", bytes: Uint8Array [97, 32, 98] }
+*/
+var dataUrlBytes = (url) => {
+	const match = /^data:([^,]*?)(;base64)?,(.*)$/s.exec(url);
+	if (!match) throw new Error("Brush shapes must be data URLs");
+	const [, type = "", base64, data = ""] = match;
+	const text = base64 ? atob(data) : decodeURIComponent(data);
+	return {
+		type,
+		bytes: base64 ? Uint8Array.from(text, (char) => char.charCodeAt(0)) : new TextEncoder().encode(text)
+	};
+};
+/**
+* Decode a data URL or image file bytes using the browser's image decoder.
+*/
+var decodeImage = async (image) => {
+	if (typeof image === "string") {
+		const { type, bytes } = dataUrlBytes(image);
+		return createImageBitmap(new Blob([bytes], { type }));
+	}
+	return createImageBitmap(new Blob([image]));
+};
+/**
+* A brush shape that can be stamped in any colour, size and rotation.
+*
+* Presets without an image use a hard round shape drawn as a vector ellipse, so it stays crisp at every size.
+* Presets with an image use only its alpha values; tinted copies are cached per colour.
+*
+* @example
+* const tip = await BrushTip.load(preset);
+* tip.stamp(ctx, 100, 100, params, "#ff0000");
+*/
+var BrushTip = class BrushTip {
+	/** Alpha mask of the shape image, or undefined for the round shape */
+	mask;
+	/** Outline of the shape in 0–1 coordinates (for the brush cursor), or undefined for the round shape */
+	outline;
+	createCanvas;
+	tintedColour = "";
+	tinted;
+	constructor(mask, outline, createCanvas = createOffscreenCanvas) {
+		this.mask = mask;
+		this.outline = outline;
+		this.createCanvas = createCanvas;
+	}
+	/** Whether this is the built-in round shape */
+	get isRound() {
+		return this.mask === void 0;
+	}
+	/**
+	* Load a preset's shape: decodes its image and keeps only the alpha. Presets without an image get the round shape.
+	*/
+	static async load(preset, decode = decodeImage, createCanvas = createOffscreenCanvas) {
+		if (!preset.image) return new BrushTip(void 0, void 0, createCanvas);
+		const image = await decode(preset.image);
+		const mask = createCanvas(image.width, image.height);
+		const ctx = mask.getContext("2d");
+		ctx.drawImage(image, 0, 0);
+		ctx.globalCompositeOperation = "source-in";
+		ctx.fillStyle = "#000000";
+		ctx.fillRect(0, 0, image.width, image.height);
+		const pixels = ctx.getImageData(0, 0, image.width, image.height).data;
+		const alpha = new Uint8ClampedArray(image.width * image.height);
+		for (let i = 0; i < alpha.length; i++) alpha[i] = pixels[i * 4 + 3];
+		return new BrushTip(mask, traceOutline(alpha, image.width, image.height), createCanvas);
+	}
+	/**
+	* The shape image tinted with a colour (cached until the colour changes).
+	*/
+	tint(mask, colour) {
+		if (this.tinted && this.tintedColour === colour) return this.tinted;
+		const canvas = this.tinted ?? this.createCanvas(mask.width, mask.height);
+		const ctx = canvas.getContext("2d");
+		ctx.globalCompositeOperation = "copy";
+		ctx.drawImage(mask, 0, 0);
+		ctx.globalCompositeOperation = "source-in";
+		ctx.fillStyle = colour;
+		ctx.fillRect(0, 0, mask.width, mask.height);
+		ctx.globalCompositeOperation = "source-over";
+		this.tinted = canvas;
+		this.tintedColour = colour;
+		return canvas;
+	}
+	/**
+	* Stamp the shape centred on a point, with the stamp's size, rotation, offset and alpha.
+	*/
+	stamp(ctx, x, y, params, colour) {
+		if (params.width <= 0 || params.height <= 0 || params.alpha <= 0) return;
+		ctx.save();
+		ctx.globalAlpha = params.alpha;
+		ctx.translate(x + params.offsetX, y + params.offsetY);
+		if (params.rotation) ctx.rotate(params.rotation * Math.PI / 180);
+		if (this.mask) ctx.drawImage(this.tint(this.mask, colour), -params.width / 2, -params.height / 2, params.width, params.height);
+		else {
+			ctx.fillStyle = colour;
+			ctx.beginPath();
+			ctx.ellipse(0, 0, params.width / 2, params.height / 2, 0, 0, Math.PI * 2);
+			ctx.fill();
+		}
+		ctx.restore();
+	}
+};
+export { dataUrlBytes, decodeImage, BrushTip as default };

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

@@ -0,0 +1,22 @@
+import type { DrawingContext } from "../compositing";
+/** Light square colour of the transparency checkerboard */
+export declare const CHECKER_LIGHT = "#ffffff";
+/** Dark square colour of the transparency checkerboard */
+export declare const CHECKER_DARK = "#cccccc";
+/**
+ * Fill an area with a grey and white checkerboard, the usual way of showing transparency.
+ *
+ * @example
+ * drawCheckerboard(ctx, 30, 30, 5);
+ */
+export declare const drawCheckerboard: (ctx: Pick<DrawingContext, "fillStyle" | "fillRect">, width: number, height: number, squareSize: number) => void;
+/**
+ * Size of an image scaled to fit inside a box, keeping its proportions.
+ *
+ * @example
+ * fitSize(2000, 1000, 90, 90); // { width: 90, height: 45 }
+ */
+export declare const fitSize: (width: number, height: number, boxWidth: number, boxHeight: number) => {
+    width: number;
+    height: number;
+};

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

@@ -0,0 +1,31 @@
+// src/lib/rendering/checkerboard/index.ts
+/** Light square colour of the transparency checkerboard */
+var CHECKER_LIGHT = "#ffffff";
+/** Dark square colour of the transparency checkerboard */
+var CHECKER_DARK = "#cccccc";
+/**
+* Fill an area with a grey and white checkerboard, the usual way of showing transparency.
+*
+* @example
+* drawCheckerboard(ctx, 30, 30, 5);
+*/
+var drawCheckerboard = (ctx, width, height, squareSize) => {
+	ctx.fillStyle = CHECKER_LIGHT;
+	ctx.fillRect(0, 0, width, height);
+	ctx.fillStyle = CHECKER_DARK;
+	for (let y = 0; y * squareSize < height; y++) for (let x = y % 2; x * squareSize < width; x += 2) ctx.fillRect(x * squareSize, y * squareSize, squareSize, squareSize);
+};
+/**
+* Size of an image scaled to fit inside a box, keeping its proportions.
+*
+* @example
+* fitSize(2000, 1000, 90, 90); // { width: 90, height: 45 }
+*/
+var fitSize = (width, height, boxWidth, boxHeight) => {
+	const scale = Math.min(boxWidth / width, boxHeight / height);
+	return {
+		width: width * scale,
+		height: height * scale
+	};
+};
+export { CHECKER_DARK, CHECKER_LIGHT, drawCheckerboard, fitSize };

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

@@ -0,0 +1,64 @@
+import type Layer from "../../classes/Layer";
+import type Viewport from "../../classes/Viewport";
+import type { Rect } from "../../classes/Viewport";
+/** Colour of the canvas itself (the "paper") */
+export declare const CANVAS_BACKGROUND = "#ffffff";
+/** Colour of the area around the canvas */
+export declare const PASTEBOARD_COLOUR = "#808080";
+/** Anything drawn like a layer: the user's own layers, and drawings from elsewhere (external sheets) */
+export type DrawableLayer = Pick<Layer, "visible" | "opacity" | "blendMode" | "canvas">;
+/** A layer image to draw in place of a layer's own canvas (e.g. the layer with the stroke in progress) */
+export interface LayerOverride {
+    layer: DrawableLayer;
+    image: CanvasImageSource;
+}
+/** The 2D drawing operations used for compositing; satisfied by both on-screen and offscreen canvas contexts */
+export type DrawingContext = Pick<CanvasRenderingContext2D, "setTransform" | "fillRect" | "drawImage" | "save" | "restore" | "fillStyle" | "globalAlpha" | "globalCompositeOperation" | "imageSmoothingEnabled" | "beginPath" | "rect" | "clip">;
+/**
+ * Draw layers onto a context that is already transformed to canvas coordinates, from the bottom layer to the top.
+ *
+ * Hidden and fully transparent layers are skipped. Each layer uses its opacity and blend mode.
+ *
+ * @param layers - layers from top (index 0) to bottom, as `LayerStack.layers` lists them
+ * @param override - draw this image instead of one layer's canvas (the stroke preview)
+ * @param area - draw only this area of each layer (canvas pixels), in place
+ */
+export declare const drawLayers: (ctx: DrawingContext, layers: readonly DrawableLayer[], override?: LayerOverride, area?: Rect) => void;
+/**
+ * Draw the canvas onto a context of any size, scaled to fit exactly: white background, then all layers.
+ * Used for the canvas map, thumbnails and screenshots.
+ *
+ * @param override - draw this image instead of one layer's canvas (e.g. a transform in progress)
+ *
+ * @example
+ * drawFlattened(mapContext, layers, 2000, 2000, 90, 90);
+ */
+export declare const drawFlattened: (ctx: DrawingContext, layers: readonly DrawableLayer[], canvasWidth: number, canvasHeight: number, targetWidth: number, targetHeight: number, override?: LayerOverride) => void;
+/**
+ * The screen pixels (device pixels) showing an area of the canvas, rounded outwards with one more pixel on each side.
+ *
+ * @example
+ * screenArea({ x: 10, y: 10, width: 5, height: 5 }, view, 2); // at zoom 1 and no offset: { x: 19, y: 19, width: 12, height: 12 }
+ */
+export declare const screenArea: (area: Rect, view: Pick<Viewport, "zoom" | "offsetX" | "offsetY">, pixelRatio: number) => Rect;
+/**
+ * An area of the canvas grown by enough canvas pixels to cover two screen pixels at a scale (screen pixels per canvas
+ * pixel), within the canvas, so drawing just that area smooths its edges as drawing everything would.
+ *
+ * @example
+ * sourceArea({ x: 10, y: 10, width: 5, height: 5 }, 0.5, 2000, 2000); // grown by 5: { x: 5, y: 5, width: 15, height: 15 }
+ */
+export declare const sourceArea: (area: Rect, scale: number, canvasWidth: number, canvasHeight: number) => Rect;
+/**
+ * Draw the visible part of the canvas onto the screen canvas: grey surround, white canvas, then all layers, positioned by the viewport.
+ *
+ * Pixels stay sharp when zoomed in past 100% and are smoothed when zoomed out.
+ *
+ * With an area, only the screen pixels showing that area of the canvas are redrawn (see `screenArea`), blending only
+ * that part of each layer, which is much quicker than redrawing everything while a stroke is drawn.
+ *
+ * @param pixelRatio - device pixels per CSS pixel (`window.devicePixelRatio`), for sharp drawing on high-resolution screens
+ * @param override - draw this image instead of one layer's canvas (the stroke preview)
+ * @param area - redraw only this area of the canvas (canvas pixels)
+ */
+export declare const drawScene: (ctx: DrawingContext, layers: readonly DrawableLayer[], view: Viewport, pixelRatio: number, override?: LayerOverride, area?: Rect) => void;

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

@@ -0,0 +1,124 @@
+// src/lib/rendering/compositing/index.ts
+/** Colour of the canvas itself (the "paper") */
+var CANVAS_BACKGROUND = "#ffffff";
+/** Colour of the area around the canvas */
+var PASTEBOARD_COLOUR = "#808080";
+/**
+* Draw layers onto a context that is already transformed to canvas coordinates, from the bottom layer to the top.
+*
+* Hidden and fully transparent layers are skipped. Each layer uses its opacity and blend mode.
+*
+* @param layers - layers from top (index 0) to bottom, as `LayerStack.layers` lists them
+* @param override - draw this image instead of one layer's canvas (the stroke preview)
+* @param area - draw only this area of each layer (canvas pixels), in place
+*/
+var drawLayers = (ctx, layers, override, area) => {
+	for (let i = layers.length - 1; i >= 0; i--) {
+		const layer = layers[i];
+		if (!layer.visible || layer.opacity === 0) continue;
+		ctx.globalAlpha = layer.opacity;
+		ctx.globalCompositeOperation = layer.blendMode;
+		const image = override?.layer === layer ? override.image : layer.canvas;
+		if (area) {
+			const { x, y, width, height } = area;
+			ctx.drawImage(image, x, y, width, height, x, y, width, height);
+		} else ctx.drawImage(image, 0, 0);
+	}
+	ctx.globalAlpha = 1;
+	ctx.globalCompositeOperation = "source-over";
+};
+/**
+* Draw the canvas onto a context of any size, scaled to fit exactly: white background, then all layers.
+* Used for the canvas map, thumbnails and screenshots.
+*
+* @param override - draw this image instead of one layer's canvas (e.g. a transform in progress)
+*
+* @example
+* drawFlattened(mapContext, layers, 2000, 2000, 90, 90);
+*/
+var drawFlattened = (ctx, layers, canvasWidth, canvasHeight, targetWidth, targetHeight, override) => {
+	ctx.save();
+	ctx.setTransform(targetWidth / canvasWidth, 0, 0, targetHeight / canvasHeight, 0, 0);
+	ctx.imageSmoothingEnabled = true;
+	ctx.fillStyle = CANVAS_BACKGROUND;
+	ctx.fillRect(0, 0, canvasWidth, canvasHeight);
+	drawLayers(ctx, layers, override);
+	ctx.restore();
+};
+/**
+* The screen pixels (device pixels) showing an area of the canvas, rounded outwards with one more pixel on each side.
+*
+* @example
+* screenArea({ x: 10, y: 10, width: 5, height: 5 }, view, 2); // at zoom 1 and no offset: { x: 19, y: 19, width: 12, height: 12 }
+*/
+var screenArea = (area, view, pixelRatio) => {
+	const scale = view.zoom * pixelRatio;
+	const left = Math.floor(area.x * scale + view.offsetX * pixelRatio) - 1;
+	const top = Math.floor(area.y * scale + view.offsetY * pixelRatio) - 1;
+	const right = Math.ceil((area.x + area.width) * scale + view.offsetX * pixelRatio) + 1;
+	const bottom = Math.ceil((area.y + area.height) * scale + view.offsetY * pixelRatio) + 1;
+	return {
+		x: left,
+		y: top,
+		width: right - left,
+		height: bottom - top
+	};
+};
+/**
+* An area of the canvas grown by enough canvas pixels to cover two screen pixels at a scale (screen pixels per canvas
+* pixel), within the canvas, so drawing just that area smooths its edges as drawing everything would.
+*
+* @example
+* sourceArea({ x: 10, y: 10, width: 5, height: 5 }, 0.5, 2000, 2000); // grown by 5: { x: 5, y: 5, width: 15, height: 15 }
+*/
+var sourceArea = (area, scale, canvasWidth, canvasHeight) => {
+	const margin = Math.ceil(2 / Math.min(1, scale)) + 1;
+	const x = Math.max(0, area.x - margin);
+	const y = Math.max(0, area.y - margin);
+	return {
+		x,
+		y,
+		width: Math.min(canvasWidth, area.x + area.width + margin) - x,
+		height: Math.min(canvasHeight, area.y + area.height + margin) - y
+	};
+};
+/**
+* Draw the visible part of the canvas onto the screen canvas: grey surround, white canvas, then all layers, positioned by the viewport.
+*
+* Pixels stay sharp when zoomed in past 100% and are smoothed when zoomed out.
+*
+* With an area, only the screen pixels showing that area of the canvas are redrawn (see `screenArea`), blending only
+* that part of each layer, which is much quicker than redrawing everything while a stroke is drawn.
+*
+* @param pixelRatio - device pixels per CSS pixel (`window.devicePixelRatio`), for sharp drawing on high-resolution screens
+* @param override - draw this image instead of one layer's canvas (the stroke preview)
+* @param area - redraw only this area of the canvas (canvas pixels)
+*/
+var drawScene = (ctx, layers, view, pixelRatio, override, area) => {
+	ctx.save();
+	ctx.setTransform(1, 0, 0, 1, 0, 0);
+	ctx.fillStyle = PASTEBOARD_COLOUR;
+	const scale = view.zoom * pixelRatio;
+	let source;
+	if (area) {
+		const clip = screenArea(area, view, pixelRatio);
+		ctx.beginPath();
+		ctx.rect(clip.x, clip.y, clip.width, clip.height);
+		ctx.clip();
+		ctx.fillRect(clip.x, clip.y, clip.width, clip.height);
+		source = sourceArea(area, scale, view.canvasWidth, view.canvasHeight);
+	} else ctx.fillRect(0, 0, view.width * pixelRatio, view.height * pixelRatio);
+	ctx.setTransform(scale, 0, 0, scale, view.offsetX * pixelRatio, view.offsetY * pixelRatio);
+	ctx.imageSmoothingEnabled = view.zoom < 1;
+	ctx.fillStyle = CANVAS_BACKGROUND;
+	const { x, y, width, height } = source ?? {
+		x: 0,
+		y: 0,
+		width: view.canvasWidth,
+		height: view.canvasHeight
+	};
+	ctx.fillRect(x, y, width, height);
+	drawLayers(ctx, layers, override, source);
+	ctx.restore();
+};
+export { CANVAS_BACKGROUND, PASTEBOARD_COLOUR, drawFlattened, drawLayers, drawScene, screenArea, sourceArea };

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

@@ -0,0 +1,14 @@
+import type BrushTip from "../BrushTip";
+/** The drawing operations the brush cursor needs */
+export type CursorContext = Pick<CanvasRenderingContext2D, "save" | "restore" | "translate" | "rotate" | "beginPath" | "ellipse" | "moveTo" | "lineTo" | "stroke" | "strokeStyle" | "lineWidth">;
+/** Below this on-screen size (CSS pixels) a crosshair is shown instead of the outline */
+export declare const MIN_OUTLINE_SIZE = 4;
+/**
+ * Draw the brush cursor: a 1:1 white outline of the brush shape at the pointer. The overlay canvas uses the "difference" blend mode,
+ * so white inverts whatever is underneath and stays visible on any colour. Very small brushes show a crosshair instead.
+ *
+ * @param x - pointer position on screen (CSS pixels)
+ * @param width - brush width on screen (CSS pixels, already multiplied by zoom)
+ * @param pixelRatio - device pixels per CSS pixel
+ */
+export declare const drawBrushCursor: (ctx: CursorContext, tip: BrushTip, x: number, y: number, width: number, height: number, rotation: number, pixelRatio: number) => void;

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

@@ -0,0 +1,39 @@
+// src/lib/rendering/cursor/index.ts
+/** Below this on-screen size (CSS pixels) a crosshair is shown instead of the outline */
+var MIN_OUTLINE_SIZE = 4;
+/** Half-length of the small crosshair, in CSS pixels */
+var CROSSHAIR = 4;
+/**
+* Draw the brush cursor: a 1:1 white outline of the brush shape at the pointer. The overlay canvas uses the "difference" blend mode,
+* so white inverts whatever is underneath and stays visible on any colour. Very small brushes show a crosshair instead.
+*
+* @param x - pointer position on screen (CSS pixels)
+* @param width - brush width on screen (CSS pixels, already multiplied by zoom)
+* @param pixelRatio - device pixels per CSS pixel
+*/
+var drawBrushCursor = (ctx, tip, x, y, width, height, rotation, pixelRatio) => {
+	ctx.save();
+	ctx.strokeStyle = "#ffffff";
+	ctx.lineWidth = 1;
+	ctx.translate(x * pixelRatio, y * pixelRatio);
+	ctx.beginPath();
+	if (Math.max(width, height) < 4) {
+		const arm = CROSSHAIR * pixelRatio;
+		ctx.moveTo(-arm, 0);
+		ctx.lineTo(arm, 0);
+		ctx.moveTo(0, -arm);
+		ctx.lineTo(0, arm);
+	} else {
+		if (rotation) ctx.rotate(rotation * Math.PI / 180);
+		const w = width * pixelRatio;
+		const h = height * pixelRatio;
+		if (tip.outline) for (const [x1, y1, x2, y2] of tip.outline) {
+			ctx.moveTo((x1 - .5) * w, (y1 - .5) * h);
+			ctx.lineTo((x2 - .5) * w, (y2 - .5) * h);
+		}
+		else ctx.ellipse(0, 0, w / 2, h / 2, 0, 0, Math.PI * 2);
+	}
+	ctx.stroke();
+	ctx.restore();
+};
+export { MIN_OUTLINE_SIZE, drawBrushCursor };

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

@@ -0,0 +1,18 @@
+/**
+ * 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'
+ */
+export declare const svgCursor: (path: string, hotspot: [number, number], fallback: string) => string;
+/** Colour sample (eyedropper): a pipette pointing down to the left; the point is at its tip */
+export declare const EYEDROPPER_CURSOR: string;
+/** Polygon lasso: a straight-edged loop with a tail; the point is at the tail's end */
+export declare const POLYGON_LASSO_CURSOR: string;
+/** Freeform lasso: an irregular hand-drawn loop with a tail; the point is at the tail's end */
+export declare const FREEFORM_LASSO_CURSOR: string;
+/** Rotate: the browser's grab cursor, as browsers have no standard rotate cursor */
+export declare const ROTATE_CURSOR = "grab";