@lvl99dotcom/paintcanvas 0.0.0-stage → 0.2.0

package/dist/lib/brushes/authors/index.d.ts

@@ -0,0 +1,55 @@
+import type { AssetAuthor, BrushConfig } from "../types";
+/** The author of the presets that come with PaintCanvas, and their heading unless the implementer names it */
+export declare const BUILT_IN_AUTHOR = "PaintCanvas";
+/** The heading of the user's own presets */
+export declare const MY_PRESETS = "My presets";
+/** The heading of presets without an author, and the author name of presets made by a user with no name or handle */
+export declare const UNKNOWN_AUTHOR = "Unknown";
+/** Names used when grouping presets, instead of PaintCanvas's own */
+export interface AuthorNames {
+    /** Heading of the presets that come with the app (default `BUILT_IN_AUTHOR`) */
+    builtIn?: string;
+    /** Author name of presets made by a user without a handle (default `UNKNOWN_AUTHOR`) */
+    unknown?: string;
+}
+/** Presets listed under one heading */
+export interface PresetGroup {
+    label: string;
+    presets: BrushConfig[];
+}
+/**
+ * An author's name.
+ *
+ * @example
+ * authorName({ name: "Ada", handle: "ada.example" }); // "Ada"
+ * authorName(undefined); // "Unknown"
+ */
+export declare const authorName: (author: AssetAuthor | undefined) => string;
+/**
+ * An author's handle, if known.
+ */
+export declare const authorHandle: (author: AssetAuthor | undefined) => string | undefined;
+/**
+ * Whether a preset's author is the user: their handle matches, or for a user without a handle, the author has the
+ * unknown author's name (`unknownName`) and no handle.
+ *
+ * @example
+ * isOwnAuthor({ name: "Ada", handle: "ada.example" }, "ada.example"); // true
+ * isOwnAuthor({ name: "Unknown" }, ""); // true
+ */
+export declare const isOwnAuthor: (author: AssetAuthor | undefined, userHandle: string, unknownName?: string) => boolean;
+/**
+ * The heading a preset is listed under: the built-in heading (the app's name) for the presets that come with the app,
+ * "My presets" for the user's own (see `isOwnAuthor`), otherwise the author's name.
+ *
+ * @example
+ * authorGroup(preset, false, "ada.example"); // "My presets"
+ */
+export declare const authorGroup: (preset: BrushConfig, builtIn: boolean, userHandle: string, names?: AuthorNames) => string;
+/**
+ * Group presets by author, in their order within each group: the user's own first, then the presets that come with
+ * the app (under the built-in heading), then other authors alphabetically.
+ *
+ * @param isBuiltIn - whether a preset comes with the app
+ */
+export declare const groupPresetsByAuthor: (presets: BrushConfig[], isBuiltIn: (id: string) => boolean, userHandle: string, names?: AuthorNames) => PresetGroup[];

package/dist/lib/brushes/authors/index.js

@@ -0,0 +1,60 @@
+// src/lib/brushes/authors/index.ts
+/** The author of the presets that come with PaintCanvas, and their heading unless the implementer names it */
+var BUILT_IN_AUTHOR = "PaintCanvas";
+/** The heading of the user's own presets */
+var MY_PRESETS = "My presets";
+/** The heading of presets without an author, and the author name of presets made by a user with no name or handle */
+var UNKNOWN_AUTHOR = "Unknown";
+/**
+* An author's name.
+*
+* @example
+* authorName({ name: "Ada", handle: "ada.example" }); // "Ada"
+* authorName(undefined); // "Unknown"
+*/
+var authorName = (author) => (typeof author === "string" ? author : author?.name) || "Unknown";
+/**
+* An author's handle, if known.
+*/
+var authorHandle = (author) => typeof author === "object" ? author.handle : void 0;
+/**
+* Whether a preset's author is the user: their handle matches, or for a user without a handle, the author has the
+* unknown author's name (`unknownName`) and no handle.
+*
+* @example
+* isOwnAuthor({ name: "Ada", handle: "ada.example" }, "ada.example"); // true
+* isOwnAuthor({ name: "Unknown" }, ""); // true
+*/
+var isOwnAuthor = (author, userHandle, unknownName = UNKNOWN_AUTHOR) => userHandle ? authorHandle(author) === userHandle : typeof author === "object" && !author.handle && author.name === unknownName;
+/**
+* The heading a preset is listed under: the built-in heading (the app's name) for the presets that come with the app,
+* "My presets" for the user's own (see `isOwnAuthor`), otherwise the author's name.
+*
+* @example
+* authorGroup(preset, false, "ada.example"); // "My presets"
+*/
+var authorGroup = (preset, builtIn, userHandle, names = {}) => {
+	if (builtIn) return names.builtIn ?? "PaintCanvas";
+	if (isOwnAuthor(preset.author, userHandle, names.unknown)) return MY_PRESETS;
+	return authorName(preset.author);
+};
+/**
+* Group presets by author, in their order within each group: the user's own first, then the presets that come with
+* the app (under the built-in heading), then other authors alphabetically.
+*
+* @param isBuiltIn - whether a preset comes with the app
+*/
+var groupPresetsByAuthor = (presets, isBuiltIn, userHandle, names = {}) => {
+	const builtInLabel = names.builtIn ?? "PaintCanvas";
+	const groups = /* @__PURE__ */ new Map();
+	for (const preset of presets) {
+		const label = authorGroup(preset, isBuiltIn(preset.id), userHandle, names);
+		groups.set(label, [...groups.get(label) ?? [], preset]);
+	}
+	const rank = (label) => label === "My presets" ? 0 : label === builtInLabel ? 1 : 2;
+	return [...groups].map(([label, list]) => ({
+		label,
+		presets: list
+	})).sort((a, b) => rank(a.label) - rank(b.label) || a.label.localeCompare(b.label));
+};
+export { BUILT_IN_AUTHOR, MY_PRESETS, UNKNOWN_AUTHOR, authorGroup, authorHandle, authorName, groupPresetsByAuthor, isOwnAuthor };

package/dist/lib/brushes/configRanges/index.d.ts

@@ -0,0 +1,52 @@
+import type { BrushConfig } from "../types";
+/** The brush settings the configuration window can vary with pressure, tilt or randomness */
+export type VaryingParam = "width" | "height" | "alpha" | "rotation" | "offsetX" | "offsetY";
+/** What a setting can vary with */
+export type VariationSource = "pressure" | "tilt" | "randomise";
+/** All variation sources, in the order they are shown */
+export declare const VARIATION_SOURCES: readonly VariationSource[];
+/** A setting as the configuration window shows it, in its unit (pixels, percent or degrees) */
+export interface ParamRange {
+    /** The setting's value when it doesn't vary */
+    value: number;
+    /** Lowest value when it varies */
+    min: number;
+    /** Highest value when it varies */
+    max: number;
+    /** Which sources it varies with */
+    sources: Record<VariationSource, boolean>;
+    /** Whether it varies with any source */
+    varies: boolean;
+}
+/** Each setting's unit range in the window */
+export declare const PARAM_LIMITS: Record<VaryingParam, {
+    min: number;
+    max: number;
+}>;
+/**
+ * Read a setting as the configuration window shows it. When it varies, its range comes from the first source turned
+ * on: scale settings (width, height, opacity) go from `value × min factor` to the value; rotation goes from the angle
+ * to the angle plus up to 360° × the factors; offsets scatter up to the factors × the brush width.
+ *
+ * @example
+ * readRange({ id: "a", width: 40, widthConfig: { usePressure: true, minPressure: 0.25 } }, "width");
+ * // { value: 40, min: 10, max: 40, sources: { pressure: true, tilt: false, randomise: false }, varies: true }
+ */
+export declare const readRange: (config: BrushConfig, param: VaryingParam) => ParamRange;
+/**
+ * Write a setting's range (in the window's unit) to every source turned on, as config changes. For a setting that
+ * doesn't vary, only `value` is used.
+ *
+ * @example
+ * writeRange(config, "width", { min: 10, max: 40 }); // { width: 40, widthConfig: { usePressure: true, minPressure: 0.25, maxPressure: 1 } }
+ */
+export declare const writeRange: (config: BrushConfig, param: VaryingParam, range: {
+    value?: number;
+    min?: number;
+    max?: number;
+}) => Partial<BrushConfig>;
+/**
+ * Turn a source on or off for a setting, as config changes. A source turned on takes the setting's current range, or
+ * when it is the first, a starting range (half to full size, the angle itself, or no scatter).
+ */
+export declare const toggleSource: (config: BrushConfig, param: VaryingParam, source: VariationSource, on: boolean) => Partial<BrushConfig>;

package/dist/lib/brushes/configRanges/index.js

@@ -0,0 +1,206 @@
+// src/lib/brushes/configRanges/index.ts
+/** All variation sources, in the order they are shown */
+var VARIATION_SOURCES = [
+	"pressure",
+	"tilt",
+	"randomise"
+];
+/** Each setting's unit range in the window */
+var PARAM_LIMITS = {
+	width: {
+		min: 1,
+		max: 256
+	},
+	height: {
+		min: 1,
+		max: 256
+	},
+	alpha: {
+		min: 0,
+		max: 100
+	},
+	rotation: {
+		min: 0,
+		max: 360
+	},
+	offsetX: {
+		min: 0,
+		max: 256
+	},
+	offsetY: {
+		min: 0,
+		max: 256
+	}
+};
+/** How settings are varied (see `BrushParamConfig`) */
+var KINDS = {
+	width: "scale",
+	height: "scale",
+	alpha: "scale",
+	rotation: "angle",
+	offsetX: "offset",
+	offsetY: "offset"
+};
+/** The config keys of each source's switch and range */
+var SOURCE_KEYS = {
+	pressure: [
+		"usePressure",
+		"minPressure",
+		"maxPressure"
+	],
+	tilt: [
+		"useTilt",
+		"minTilt",
+		"maxTilt"
+	],
+	randomise: [
+		"useRandomise",
+		"minRandomise",
+		"maxRandomise"
+	]
+};
+/** Each source's range when not set (see `BrushParamConfig`) */
+var SOURCE_DEFAULTS = {
+	pressure: [0, 1],
+	tilt: [0, 1],
+	randomise: [1, 1]
+};
+var configKey = (param) => `${param}Config`;
+var clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+/** A setting's value as stored (alpha as 0–1) */
+var storedValue = (config, param) => {
+	if (param === "alpha") return config.alpha ?? 1;
+	if (param === "width") return config.width ?? 1;
+	if (param === "height") return config.height ?? config.width ?? 1;
+	return config[param] ?? 0;
+};
+/** A stored value in the window's unit */
+var toUnit = (param, value) => param === "alpha" ? value * 100 : value;
+/** A value in the window's unit as stored */
+var fromUnit = (param, value) => param === "alpha" ? value / 100 : value;
+/**
+* Read a setting as the configuration window shows it. When it varies, its range comes from the first source turned
+* on: scale settings (width, height, opacity) go from `value × min factor` to the value; rotation goes from the angle
+* to the angle plus up to 360° × the factors; offsets scatter up to the factors × the brush width.
+*
+* @example
+* readRange({ id: "a", width: 40, widthConfig: { usePressure: true, minPressure: 0.25 } }, "width");
+* // { value: 40, min: 10, max: 40, sources: { pressure: true, tilt: false, randomise: false }, varies: true }
+*/
+var readRange = (config, param) => {
+	const variation = config[configKey(param)] ?? {};
+	const sources = Object.fromEntries(VARIATION_SOURCES.map((source) => [source, Boolean(variation[SOURCE_KEYS[source][0]])]));
+	const first = VARIATION_SOURCES.find((source) => sources[source]);
+	const value = toUnit(param, storedValue(config, param));
+	if (!first) return {
+		value,
+		min: value,
+		max: value,
+		sources,
+		varies: false
+	};
+	const [, minKey, maxKey] = SOURCE_KEYS[first];
+	const [minDefault, maxDefault] = SOURCE_DEFAULTS[first];
+	const low = variation[minKey] ?? minDefault;
+	const high = variation[maxKey] ?? maxDefault;
+	const width = config.width ?? 1;
+	switch (KINDS[param]) {
+		case "scale": return {
+			value,
+			min: value * low,
+			max: value * high,
+			sources,
+			varies: true
+		};
+		case "angle": return {
+			value,
+			min: value + low * 360,
+			max: value + high * 360,
+			sources,
+			varies: true
+		};
+		default: return {
+			value,
+			min: low * width,
+			max: high * width,
+			sources,
+			varies: true
+		};
+	}
+};
+/**
+* Write a setting's range (in the window's unit) to every source turned on, as config changes. For a setting that
+* doesn't vary, only `value` is used.
+*
+* @example
+* writeRange(config, "width", { min: 10, max: 40 }); // { width: 40, widthConfig: { usePressure: true, minPressure: 0.25, maxPressure: 1 } }
+*/
+var writeRange = (config, param, range) => {
+	const current = readRange(config, param);
+	const limits = PARAM_LIMITS[param];
+	if (!current.varies) {
+		const value = clamp(range.value ?? current.value, limits.min, limits.max);
+		return KINDS[param] === "offset" ? {} : { [param]: fromUnit(param, value) };
+	}
+	let min = clamp(range.min ?? current.min, limits.min, limits.max);
+	let max = clamp(range.max ?? current.max, limits.min, limits.max);
+	if (min > max) [min, max] = [max, min];
+	const width = config.width ?? 1;
+	let changes;
+	let factors;
+	switch (KINDS[param]) {
+		case "scale":
+			changes = { [param]: fromUnit(param, Math.max(max, limits.min || 1e-6)) };
+			factors = [max > 0 ? min / max : 0, 1];
+			break;
+		case "angle":
+			changes = { rotation: min };
+			factors = [0, (max - min) / 360];
+			break;
+		default:
+			changes = {};
+			factors = [clamp(min / width, 0, 1), clamp(max / width, 0, 1)];
+	}
+	const variation = { ...config[configKey(param)] };
+	for (const source of VARIATION_SOURCES) {
+		if (!current.sources[source]) continue;
+		const [, minKey, maxKey] = SOURCE_KEYS[source];
+		variation[minKey] = factors[0];
+		variation[maxKey] = factors[1];
+	}
+	return {
+		...changes,
+		[configKey(param)]: variation
+	};
+};
+/**
+* Turn a source on or off for a setting, as config changes. A source turned on takes the setting's current range, or
+* when it is the first, a starting range (half to full size, the angle itself, or no scatter).
+*/
+var toggleSource = (config, param, source, on) => {
+	const key = configKey(param);
+	const [useKey, minKey, maxKey] = SOURCE_KEYS[source];
+	const current = readRange(config, param);
+	const variation = {
+		...config[key],
+		[useKey]: on
+	};
+	if (on && !current.varies) {
+		const starting = {
+			scale: [.5, 1],
+			angle: [0, 0],
+			offset: [0, .5]
+		};
+		[variation[minKey], variation[maxKey]] = starting[KINDS[param]];
+		return { [key]: variation };
+	}
+	if (on) return writeRange({
+		...config,
+		[key]: variation
+	}, param, {
+		min: current.min,
+		max: current.max
+	});
+	return { [key]: variation };
+};
+export { PARAM_LIMITS, VARIATION_SOURCES, readRange, toggleSource, writeRange };

package/dist/lib/brushes/index.d.ts

@@ -0,0 +1,5 @@
+import type { BrushesConfig } from "./types";
+/** Brush presets */
+export declare const brushPresets: BrushesConfig;
+/** Eraser presets (a separate copy of the brush presets) */
+export declare const eraserPresets: BrushesConfig;

package/dist/lib/brushes/index.js

@@ -0,0 +1,19 @@
+import round_default from "./presets/round/index.js";
+import square_default from "./presets/square/index.js";
+import drawing_default from "./presets/drawing/index.js";
+import painting_default from "./presets/painting/index.js";
+import sketching from "./presets/sketching/index.js";
+// src/lib/brushes/index.ts
+/** All presets, in the order they are listed: round, square and soft round, pencils and pens, paints and textures, then sketching presets */
+var allPresets = {
+	...round_default,
+	...square_default,
+	...drawing_default,
+	...painting_default,
+	...sketching
+};
+/** Brush presets */
+var brushPresets = structuredClone(allPresets);
+/** Eraser presets (a separate copy of the brush presets) */
+var eraserPresets = structuredClone(allPresets);
+export { brushPresets, eraserPresets };

package/dist/lib/brushes/params/index.d.ts

@@ -0,0 +1,108 @@
+import type { BrushConfig, BrushParamConfig, BrushStrokePoint } from "../types";
+import type { RandomFn } from "../../utils/random";
+/** A stamp's final size, rotation, offset and alpha after variation */
+export interface StampParams {
+    /** Width in pixels */
+    width: number;
+    /** Height in pixels */
+    height: number;
+    /** Rotation in degrees */
+    rotation: number;
+    /** Horizontal offset from the stroke point, in pixels */
+    offsetX: number;
+    /** Vertical offset from the stroke point, in pixels */
+    offsetY: number;
+    /** Alpha (0–1) */
+    alpha: number;
+}
+/** What the input device reports for a point */
+export interface PointInput {
+    /** Pressure (0–1), only meaningful for pens */
+    pressure?: number;
+    /** Tilt in degrees along X and Y (-90–90), only meaningful for pens */
+    tiltX?: number;
+    tiltY?: number;
+    /** Whether the point came from a pen (mouse and touch report no real pressure or tilt) */
+    isPen: boolean;
+}
+/**
+ * Linear interpolation between two values.
+ *
+ * @example
+ * lerp(0, 10, 0.25); // 2.5
+ */
+export declare const lerp: (from: number, to: number, amount: number) => number;
+/**
+ * How far the pen leans: 0 when upright, 1 when flat.
+ *
+ * @example
+ * tiltAmount(0, 0); // 0
+ * tiltAmount(90, 0); // 1
+ */
+export declare const tiltAmount: (tiltX?: number, tiltY?: number) => number;
+/**
+ * The direction the pen leans, in degrees (0 = towards +X, 90 = towards +Y).
+ *
+ * @example
+ * tiltDirection(0, 45); // 90
+ */
+export declare const tiltDirection: (tiltX?: number, tiltY?: number) => number;
+/**
+ * Combine a parameter's randomise, pressure and tilt factors into one factor (they multiply). Returns 1 when nothing is enabled.
+ * Pressure and tilt only apply to pens; for other devices they count as full (`maxPressure`/`maxTilt`).
+ *
+ * @example
+ * variationFactor({ useRandomise: true, minRandomise: 0.5, maxRandomise: 1 }, { isPen: false }, () => 0); // 0.5
+ */
+export declare const variationFactor: (config: BrushParamConfig | undefined, input: PointInput, random?: RandomFn) => number;
+/**
+ * Work out one stamp's size, rotation, offset and alpha from the preset, the user's chosen size and the input at that point.
+ *
+ * - Size and alpha are scaled by their factor.
+ * - Rotation adds `factor × 360°`; with `useTilt`, it follows the pen's lean direction instead.
+ * - Offsets scatter up to `factor × size` in a random direction.
+ *
+ * @example
+ * stampParams(preset, { width: 20, height: 20 }, { isPen: true, pressure: 0.5 });
+ */
+export declare const stampParams: (preset: BrushConfig, size: {
+    width: number;
+    height: number;
+}, input: PointInput, random?: RandomFn) => StampParams;
+/** An area on whole pixels, given by its centre and size */
+export interface PixelArea {
+    /** Centre X, in pixels */
+    x: number;
+    /** Centre Y, in pixels */
+    y: number;
+    /** Width in whole pixels */
+    width: number;
+    /** Height in whole pixels */
+    height: number;
+}
+/**
+ * Move an area centred on a point onto whole pixels. The size is rounded to whole pixels and the top-left corner is
+ * rounded down, so the pixel under the point is always covered.
+ *
+ * @example
+ * snapToPixelGrid(10.7, 4.2, 1, 1); // { x: 10.5, y: 4.5, width: 1, height: 1 }: the pixel at (10, 4)
+ * snapToPixelGrid(10.7, 4.2, 2, 2); // { x: 10, y: 4, width: 2, height: 2 }: pixels 9–10 and 3–4
+ */
+export declare const snapToPixelGrid: (x: number, y: number, width: number, height: number) => PixelArea;
+/**
+ * Move a stamp onto whole pixels (see {@link snapToPixelGrid}). Its offset is included in the returned point, so the
+ * returned params have no offset.
+ *
+ * @example
+ * snapStamp(10.7, 4.2, { width: 1, height: 1, rotation: 0, offsetX: 2, offsetY: 0, alpha: 1 });
+ * // { x: 12.5, y: 4.5, params: { width: 1, height: 1, rotation: 0, offsetX: 0, offsetY: 0, alpha: 1 } }
+ */
+export declare const snapStamp: (x: number, y: number, params: StampParams) => {
+    x: number;
+    y: number;
+    params: StampParams;
+};
+/**
+ * Describe a stroke point's input for parameter variation.
+ */
+export declare const pointInput: (point: BrushStrokePoint, isPen: boolean) => PointInput;

package/dist/lib/brushes/params/index.js

@@ -0,0 +1,139 @@
+// src/lib/brushes/params/index.ts
+/**
+* Linear interpolation between two values.
+*
+* @example
+* lerp(0, 10, 0.25); // 2.5
+*/
+var lerp = (from, to, amount) => from + (to - from) * amount;
+/**
+* Clamp a value between 0 and 1.
+*/
+var clamp01 = (value) => Math.max(0, Math.min(1, value));
+/**
+* How far the pen leans: 0 when upright, 1 when flat.
+*
+* @example
+* tiltAmount(0, 0); // 0
+* tiltAmount(90, 0); // 1
+*/
+var tiltAmount = (tiltX = 0, tiltY = 0) => clamp01(Math.hypot(tiltX, tiltY) / 90);
+/**
+* The direction the pen leans, in degrees (0 = towards +X, 90 = towards +Y).
+*
+* @example
+* tiltDirection(0, 45); // 90
+*/
+var tiltDirection = (tiltX = 0, tiltY = 0) => Math.atan2(tiltY, tiltX) * 180 / Math.PI;
+/**
+* Combine a parameter's randomise, pressure and tilt factors into one factor (they multiply). Returns 1 when nothing is enabled.
+* Pressure and tilt only apply to pens; for other devices they count as full (`maxPressure`/`maxTilt`).
+*
+* @example
+* variationFactor({ useRandomise: true, minRandomise: 0.5, maxRandomise: 1 }, { isPen: false }, () => 0); // 0.5
+*/
+var variationFactor = (config, input, random = Math.random) => {
+	if (!config) return 1;
+	let factor = 1;
+	if (config.useRandomise) factor *= lerp(config.minRandomise ?? 1, config.maxRandomise ?? 1, random());
+	if (config.usePressure) {
+		const pressure = input.isPen ? clamp01(input.pressure ?? 1) : 1;
+		factor *= lerp(config.minPressure ?? 0, config.maxPressure ?? 1, pressure);
+	}
+	if (config.useTilt) {
+		const tilt = input.isPen ? tiltAmount(input.tiltX, input.tiltY) : 1;
+		factor *= lerp(config.minTilt ?? 0, config.maxTilt ?? 1, tilt);
+	}
+	return factor;
+};
+/**
+* Work out one stamp's size, rotation, offset and alpha from the preset, the user's chosen size and the input at that point.
+*
+* - Size and alpha are scaled by their factor.
+* - Rotation adds `factor × 360°`; with `useTilt`, it follows the pen's lean direction instead.
+* - Offsets scatter up to `factor × size` in a random direction.
+*
+* @example
+* stampParams(preset, { width: 20, height: 20 }, { isPen: true, pressure: 0.5 });
+*/
+var stampParams = (preset, size, input, random = Math.random) => {
+	const width = Math.max(0, size.width * variationFactor(preset.widthConfig, input, random));
+	const height = preset.constrainProportions ? width * size.height / size.width : Math.max(0, size.height * variationFactor(preset.heightConfig, input, random));
+	let rotation = preset.rotation ?? 0;
+	const rotationConfig = preset.rotationConfig;
+	if (rotationConfig?.useTilt && input.isPen && tiltAmount(input.tiltX, input.tiltY) > 0) rotation += tiltDirection(input.tiltX, input.tiltY);
+	else if (rotationConfig?.useRandomise || rotationConfig?.usePressure) rotation += variationFactor({
+		...rotationConfig,
+		useTilt: false
+	}, input, random) * 360;
+	/** Base offset plus a scatter of up to `factor × extent` in a random direction */
+	const scatter = (base, config, extent) => {
+		if (!config?.useRandomise && !config?.usePressure && !config?.useTilt) return base ?? 0;
+		const direction = random() < .5 ? -1 : 1;
+		return (base ?? 0) + direction * variationFactor(config, input, random) * extent;
+	};
+	return {
+		width,
+		height,
+		rotation,
+		offsetX: scatter(preset.offsetX, preset.offsetXConfig, width),
+		offsetY: scatter(preset.offsetY, preset.offsetYConfig, height),
+		alpha: clamp01((preset.alpha ?? 1) * variationFactor(preset.alphaConfig, input, random))
+	};
+};
+/**
+* Round a size to whole pixels: at least 1 pixel unless it is 0 or less (nothing is drawn).
+*/
+var wholePixels = (size) => size > 0 ? Math.max(1, Math.round(size)) : 0;
+/**
+* Move an area centred on a point onto whole pixels. The size is rounded to whole pixels and the top-left corner is
+* rounded down, so the pixel under the point is always covered.
+*
+* @example
+* snapToPixelGrid(10.7, 4.2, 1, 1); // { x: 10.5, y: 4.5, width: 1, height: 1 }: the pixel at (10, 4)
+* snapToPixelGrid(10.7, 4.2, 2, 2); // { x: 10, y: 4, width: 2, height: 2 }: pixels 9–10 and 3–4
+*/
+var snapToPixelGrid = (x, y, width, height) => {
+	const snappedWidth = wholePixels(width);
+	const snappedHeight = wholePixels(height);
+	const left = Math.floor(x) - Math.floor(snappedWidth / 2);
+	const top = Math.floor(y) - Math.floor(snappedHeight / 2);
+	return {
+		x: left + snappedWidth / 2,
+		y: top + snappedHeight / 2,
+		width: snappedWidth,
+		height: snappedHeight
+	};
+};
+/**
+* Move a stamp onto whole pixels (see {@link snapToPixelGrid}). Its offset is included in the returned point, so the
+* returned params have no offset.
+*
+* @example
+* snapStamp(10.7, 4.2, { width: 1, height: 1, rotation: 0, offsetX: 2, offsetY: 0, alpha: 1 });
+* // { x: 12.5, y: 4.5, params: { width: 1, height: 1, rotation: 0, offsetX: 0, offsetY: 0, alpha: 1 } }
+*/
+var snapStamp = (x, y, params) => {
+	const area = snapToPixelGrid(x + params.offsetX, y + params.offsetY, params.width, params.height);
+	return {
+		x: area.x,
+		y: area.y,
+		params: {
+			...params,
+			width: area.width,
+			height: area.height,
+			offsetX: 0,
+			offsetY: 0
+		}
+	};
+};
+/**
+* Describe a stroke point's input for parameter variation.
+*/
+var pointInput = (point, isPen) => ({
+	pressure: point.pressure,
+	tiltX: point.tiltX,
+	tiltY: point.tiltY,
+	isPen
+});
+export { lerp, pointInput, snapStamp, snapToPixelGrid, stampParams, tiltAmount, tiltDirection, variationFactor };

package/dist/lib/brushes/presetFile/index.d.ts

@@ -0,0 +1,32 @@
+import type { BrushConfig } from "../types";
+/** Messages shown when importing or exporting presets fails */
+export declare const PRESET_FILE_ERRORS: {
+    readonly incompatible: "Brush preset JSON file not compatible";
+    readonly read: "Failed to read brush preset JSON file";
+    readonly export: "Error exporting brush preset JSON file";
+    readonly empty: "No brush presets to export";
+};
+/** Importing or exporting presets failed, with a message for the user */
+export declare class PresetFileError extends Error {
+}
+/**
+ * The file name presets are exported to on a day, starting with a prefix (see `PaintCanvasNames.filePrefix`).
+ *
+ * @example
+ * presetFileName(new Date(2026, 9, 24)); // "paintcanvas-brush-presets-2026-10-24.json"
+ * presetFileName(new Date(2026, 9, 24), "myapp"); // "myapp-brush-presets-2026-10-24.json"
+ */
+export declare const presetFileName: (date?: Date, prefix?: string) => string;
+/**
+ * Write presets to a brush preset file (JSON) of a format (see `PaintCanvasNames.presetFileFormat`). Throws a
+ * `PresetFileError` if there are none, or one can't be exported (e.g. its shape isn't a PNG data URL).
+ *
+ * @example
+ * exportPresetFile([myPreset]); // '{ "format": "paintcanvas-brush-presets", "version": 1, "presets": [...] }'
+ */
+export declare const exportPresetFile: (presets: BrushConfig[], format?: string) => string;
+/**
+ * Read the presets in a brush preset file of one of the given formats (PaintCanvas's by default).
+ * Throws a `PresetFileError` if it isn't valid JSON or a compatible file.
+ */
+export declare const parsePresetFile: (text: string, formats?: readonly string[]) => BrushConfig[];