fabricjs-document-engine 0.4.0 → 0.6.0

package/dist/engine/create-document-engine.js

@@ -2,16 +2,22 @@ import { buildAssetManifest } from "../assets/asset-manifest.js";
 import { DocumentEngineError, isDocumentEngineError } from "./errors.js";
 import { isSameUrl } from "../assets/image-check.js";
 import { inspectAssets, prepareAssetsForLoad, prepareAssetsForSave } from "../assets/asset-pipeline.js";
+import { resolveExportArea } from "../export/export-area.js";
+import { normalizeExportOptions } from "../export/export-options.js";
+import { readObjectId, writeObjectId } from "../fabric/object-ids.js";
+import { collectSerializedTypes, walkObjects } from "../fabric/walk-objects.js";
+import { preflightExport } from "../export/preflight-export.js";
+import { dataUrlToBlob, mimeTypes, renderRaster, renderSvg, withExportView } from "../export/render-export.js";
 import "../document/document-format.js";
 import { createId } from "../document/ids.js";
 import { createDocumentInfo } from "../document/create-document.js";
 import { validateDocument } from "../document/validate-document.js";
-import { collectSerializedTypes, walkObjects } from "../fabric/walk-objects.js";
 import { loadIntoCanvas, serializeCanvas } from "../fabric/fabric-adapter.js";
-import { readObjectId, writeObjectId } from "../fabric/object-ids.js";
 import { createObjectRegistry } from "../fabric/object-registry.js";
 import { createHistory } from "../history/create-history.js";
+import { migrateDocument } from "../migrations/migrate-document.js";
 import { createRecoveryController, restoreRecordedFiles } from "../recovery/recovery-controller.js";
+import { summarize, supportsVersions, versionsToPrune } from "../versions/document-version.js";
 import { createSaveController } from "../save/save-controller.js";
 import { createEventEmitter } from "./event-emitter.js";
 //#region src/engine/create-document-engine.ts
@@ -87,6 +93,7 @@ function createDocumentEngine(options) {
 		onSuccess: (document) => {
 			if (recovery && !saving.state().isDirty) recovery.remove(document.id);
 			events.emit("save:success", { document });
+			createAutomaticVersionAfterSave(document);
 		},
 		onError: (error) => events.emit("save:error", { error }),
 		onRetry: (event) => events.emit("save:retry", event)
@@ -151,7 +158,10 @@ function createDocumentEngine(options) {
 		if (unknownTypes.length > 0) throw new DocumentEngineError("UNKNOWN_OBJECT_TYPE", `The document uses object types that are not registered: ${unknownTypes.join(", ")}. Register them with customObjects or engine.registerObject before loading.`, { unknownTypes });
 		return document;
 	}
-	async function loadDocument(input, loadOptions = {}) {
+	function loadDocument(input, loadOptions = {}) {
+		return loadMigratedDocument(input, loadOptions, {});
+	}
+	async function loadMigratedDocument(input, loadOptions, importDetails) {
 		ensureUsable();
 		activeLoad?.abort();
 		const controller = new AbortController();
@@ -161,7 +171,12 @@ function createDocumentEngine(options) {
 		try {
 			await recovery?.markLoadStarted(documentId);
 			if (controller.signal.aborted) throw new Error("aborted");
-			const checked = checkDocument(input);
+			const { document: migrated, migratedFrom } = migrateDocument(input, {
+				canvasWidth: canvas.getWidth(),
+				canvasHeight: canvas.getHeight(),
+				...importDetails
+			});
+			const checked = checkDocument(migrated);
 			const { document, warnings } = await prepareAssetsForLoad(checked, assetOptions, controller.signal);
 			if (controller.signal.aborted) throw new Error("aborted");
 			await history.withoutRecording(() => loadIntoCanvas(canvas, {
@@ -188,7 +203,8 @@ function createDocumentEngine(options) {
 			if (warnings.length > 0) events.emit("assets:warning", { warnings });
 			events.emit("load:success", {
 				document,
-				warnings
+				warnings,
+				migratedFrom
 			});
 			return document;
 		} catch (error) {
@@ -202,6 +218,90 @@ function createDocumentEngine(options) {
 			}
 		}
 	}
+	function importFabricJson(json, importOptions = {}) {
+		let parsed = json;
+		if (typeof json === "string") try {
+			parsed = JSON.parse(json);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			return Promise.reject(new DocumentEngineError("INVALID_DOCUMENT", `The text is not valid JSON: ${reason}`, { cause: error }));
+		}
+		const { id, metadata, ...loadOptions } = importOptions;
+		return loadMigratedDocument(parsed, loadOptions, {
+			id,
+			metadata
+		});
+	}
+	let savesSinceAutomaticVersion = 0;
+	let lastVersionTime = 0;
+	function nextVersionTimestamp() {
+		lastVersionTime = Math.max(Date.now(), lastVersionTime + 1);
+		return new Date(lastVersionTime).toISOString();
+	}
+	function requireVersions() {
+		ensureUsable();
+		if (!supportsVersions(storage)) throw new DocumentEngineError("VERSIONS_UNSUPPORTED", "The storage adapter needs saveVersion, listVersions, loadVersion and deleteVersion to keep versions");
+		return storage;
+	}
+	async function pruneAutomaticVersions(versionStorage, documentId) {
+		const keepAuto = options.versions?.keepAuto ?? 20;
+		const existing = await versionStorage.listVersions(documentId);
+		await Promise.all(versionsToPrune(existing, keepAuto).map((version) => versionStorage.deleteVersion(documentId, version.id)));
+	}
+	async function storeVersion(name, kind, document) {
+		const versionStorage = requireVersions();
+		const content = document ?? (await prepareAssetsForSave(toDocument(), assetOptions, uploadedUrls)).document;
+		const version = {
+			id: createId(),
+			documentId: content.id,
+			name,
+			kind,
+			createdAt: nextVersionTimestamp(),
+			revision: content.revision ?? saving.state().revision,
+			document: content
+		};
+		await versionStorage.saveVersion(version);
+		await pruneAutomaticVersions(versionStorage, content.id);
+		const summary = summarize(version);
+		events.emit("version:created", summary);
+		return summary;
+	}
+	function reportVersionError(error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		const engineError = isDocumentEngineError(error) ? error : new DocumentEngineError("VERSION_FAILED", `Could not keep an automatic version: ${reason}`, { cause: error });
+		events.emit("version:error", { error: engineError });
+	}
+	function createAutomaticVersionAfterSave(document) {
+		const every = options.versions?.autoEvery ?? 0;
+		if (every <= 0 || !supportsVersions(storage)) return;
+		savesSinceAutomaticVersion += 1;
+		if (savesSinceAutomaticVersion < every) return;
+		savesSinceAutomaticVersion = 0;
+		storeVersion(`Autosave ${(/* @__PURE__ */ new Date()).toLocaleString()}`, "auto", document).catch(reportVersionError);
+	}
+	async function restoreVersion(versionId) {
+		const versionStorage = requireVersions();
+		const current = documentInfo;
+		const version = await versionStorage.loadVersion(current.id, versionId);
+		await storeVersion(`Before restoring "${version.name}"`, "auto");
+		const { document: migrated } = migrateDocument(version.document, {
+			canvasWidth: canvas.getWidth(),
+			canvasHeight: canvas.getHeight()
+		});
+		const baseRevision = saving.state().revision;
+		const loaded = await loadDocument({
+			...migrated,
+			id: current.id,
+			createdAt: current.createdAt,
+			revision: baseRevision
+		});
+		noteContentChange();
+		events.emit("version:restored", {
+			version: summarize(version),
+			document: loaded
+		});
+		return loaded;
+	}
 	function requireStorage() {
 		if (!storage) throw new DocumentEngineError("STORAGE_MISSING", "Pass a storage adapter to createDocumentEngine to use load and save");
 		return storage;
@@ -218,7 +318,7 @@ function createDocumentEngine(options) {
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
-		return loadDocument(stored, loadOptions);
+		return loadMigratedDocument(stored, loadOptions ?? {}, { id: documentId });
 	}
 	function save(saveOptions) {
 		try {
@@ -270,6 +370,92 @@ function createDocumentEngine(options) {
 		canvas.requestRenderAll();
 		return images.length;
 	}
+	function fontsOnCanvas() {
+		rebuildIndex();
+		return buildAssetManifest(serializeCanvas(canvas, registry.propertiesToInclude()).objects).fonts;
+	}
+	async function checkBeforeExport(exportOptions) {
+		ensureUsable();
+		const { format } = normalizeExportOptions(exportOptions);
+		return preflightExport(canvas, format, format === "json" ? [] : fontsOnCanvas(), assetOptions);
+	}
+	function describeProblems(check) {
+		return check.problems.map((problem) => problem.message).join("; ");
+	}
+	async function exportContent(exportOptions) {
+		const settings = normalizeExportOptions(exportOptions);
+		const stopIfCancelled = () => {
+			if (settings.signal?.aborted) throw new DocumentEngineError("EXPORT_ABORTED", "The export was cancelled");
+		};
+		stopIfCancelled();
+		if (settings.format === "json") {
+			const prepared = await prepareAssetsForSave(toDocument(), assetOptions, uploadedUrls);
+			stopIfCancelled();
+			return {
+				format: "json",
+				mimeType: mimeTypes.json,
+				blob: new Blob([JSON.stringify(prepared.document)], { type: mimeTypes.json }),
+				width: prepared.document.canvas.width,
+				height: prepared.document.canvas.height,
+				warnings: prepared.warnings,
+				document: prepared.document
+			};
+		}
+		const check = await checkBeforeExport(settings);
+		stopIfCancelled();
+		if (!check.ok) throw new DocumentEngineError("EXPORT_BLOCKED", `The export cannot run: ${describeProblems(check)}`, { problems: check.problems });
+		const format = settings.format;
+		try {
+			const rendered = withExportView(canvas, settings.background, format, () => {
+				const area = resolveExportArea(canvas, settings.area, settings.padding);
+				return {
+					area,
+					content: format === "svg" ? renderSvg(canvas, area, settings.scale) : renderRaster(canvas, area, format, settings.scale, settings.quality)
+				};
+			});
+			const blob = format === "svg" ? new Blob([rendered.content], { type: mimeTypes.svg }) : dataUrlToBlob(rendered.content);
+			return {
+				format,
+				mimeType: blob.type || mimeTypes[format],
+				blob,
+				width: Math.round(rendered.area.width * settings.scale),
+				height: Math.round(rendered.area.height * settings.scale),
+				warnings: check.warnings
+			};
+		} catch (error) {
+			if (isDocumentEngineError(error)) throw error;
+			if (error?.name === "SecurityError") {
+				const problem = {
+					code: "CROSS_ORIGIN_IMAGE",
+					message: "The browser blocked the export because the canvas shows an image from another site without CORS",
+					objectIds: []
+				};
+				throw new DocumentEngineError("EXPORT_BLOCKED", problem.message, {
+					problems: [problem],
+					cause: error
+				});
+			}
+			const reason = error instanceof Error ? error.message : String(error);
+			throw new DocumentEngineError("EXPORT_FAILED", `Fabric could not export the canvas: ${reason}`, { cause: error });
+		}
+	}
+	async function exportDocument(exportOptions) {
+		ensureUsable();
+		try {
+			const result = await exportContent(exportOptions);
+			events.emit("export:success", {
+				format: result.format,
+				width: result.width,
+				height: result.height,
+				warnings: result.warnings
+			});
+			return result;
+		} catch (error) {
+			const engineError = isDocumentEngineError(error) ? error : new DocumentEngineError("EXPORT_FAILED", String(error), { cause: error });
+			events.emit("export:error", { error: engineError });
+			throw engineError;
+		}
+	}
 	function requireRecovery() {
 		ensureUsable();
 		if (!recovery) throw new DocumentEngineError("RECOVERY_MISSING", "Pass recovery: { store } to createDocumentEngine to use recovery");
@@ -329,6 +515,11 @@ function createDocumentEngine(options) {
 		toDocument,
 		loadDocument,
 		load,
+		importFabricJson,
+		createVersion: (name) => storeVersion(name ?? `Version ${(/* @__PURE__ */ new Date()).toLocaleString()}`, "named"),
+		listVersions: async (documentId) => requireVersions().listVersions(documentId ?? documentInfo.id),
+		restoreVersion,
+		deleteVersion: async (versionId) => requireVersions().deleteVersion(documentInfo.id, versionId),
 		save,
 		isDirty: () => saving.state().isDirty,
 		getSaveState: () => saving.state(),
@@ -343,6 +534,8 @@ function createDocumentEngine(options) {
 		},
 		checkAssets,
 		replaceImage,
+		export: exportDocument,
+		preflightExport: checkBeforeExport,
 		flushRecovery: async () => requireRecovery().flush(),
 		getRecoverableDocuments: async () => requireRecovery().list(),
 		getRecovery: async (documentId) => requireRecovery().read(documentId ?? documentInfo.id),

package/dist/engine/errors.cjs

@@ -8,6 +8,8 @@ var DocumentEngineError = class extends Error {
 		this.unknownTypes = details.unknownTypes ?? [];
 		this.missingAssets = details.missingAssets ?? [];
 		this.missingFonts = details.missingFonts ?? [];
+		this.problems = details.problems ?? [];
+		this.migrationFrom = details.migrationFrom;
 		this.cause = details.cause;
 		this.retryable = details.retryable ?? false;
 	}

package/dist/engine/errors.d.cts

@@ -1,6 +1,7 @@
 import { FontAsset, ImageAsset } from "../assets/asset-manifest.cjs";
+import { ExportProblem } from "../export/preflight-export.cjs";
 //#region src/engine/errors.d.ts
-export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "MISSING_ASSETS" | "MISSING_FONTS" | "ASSET_UPLOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "SAVE_CONFLICT" | "SAVE_CANCELLED" | "DOCUMENT_NOT_FOUND" | "HISTORY_FAILED" | "RECOVERY_MISSING" | "RECOVERY_NOT_FOUND" | "RECOVERY_FAILED" | "ENGINE_DESTROYED";
+export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "MISSING_ASSETS" | "MISSING_FONTS" | "ASSET_UPLOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "SAVE_CONFLICT" | "SAVE_CANCELLED" | "DOCUMENT_NOT_FOUND" | "HISTORY_FAILED" | "RECOVERY_MISSING" | "RECOVERY_NOT_FOUND" | "RECOVERY_FAILED" | "MIGRATION_FAILED" | "VERSIONS_UNSUPPORTED" | "VERSION_NOT_FOUND" | "VERSION_FAILED" | "INVALID_EXPORT_OPTIONS" | "EXPORT_BLOCKED" | "EXPORT_FAILED" | "EXPORT_ABORTED" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -11,6 +12,8 @@ export interface DocumentEngineErrorDetails {
   unknownTypes?: string[];
   missingAssets?: ImageAsset[];
   missingFonts?: FontAsset[];
+  problems?: ExportProblem[];
+  migrationFrom?: number;
   cause?: unknown;
   retryable?: boolean;
 }
@@ -20,6 +23,8 @@ export declare class DocumentEngineError extends Error {
   readonly unknownTypes: string[];
   readonly missingAssets: ImageAsset[];
   readonly missingFonts: FontAsset[];
+  readonly problems: ExportProblem[];
+  readonly migrationFrom: number | undefined;
   readonly cause: unknown;
   readonly retryable: boolean;
   constructor(code: DocumentErrorCode, message: string, details?: DocumentEngineErrorDetails);

package/dist/engine/errors.d.ts

@@ -1,6 +1,7 @@
 import { FontAsset, ImageAsset } from "../assets/asset-manifest.js";
+import { ExportProblem } from "../export/preflight-export.js";
 //#region src/engine/errors.d.ts
-export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "MISSING_ASSETS" | "MISSING_FONTS" | "ASSET_UPLOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "SAVE_CONFLICT" | "SAVE_CANCELLED" | "DOCUMENT_NOT_FOUND" | "HISTORY_FAILED" | "RECOVERY_MISSING" | "RECOVERY_NOT_FOUND" | "RECOVERY_FAILED" | "ENGINE_DESTROYED";
+export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "MISSING_ASSETS" | "MISSING_FONTS" | "ASSET_UPLOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "SAVE_CONFLICT" | "SAVE_CANCELLED" | "DOCUMENT_NOT_FOUND" | "HISTORY_FAILED" | "RECOVERY_MISSING" | "RECOVERY_NOT_FOUND" | "RECOVERY_FAILED" | "MIGRATION_FAILED" | "VERSIONS_UNSUPPORTED" | "VERSION_NOT_FOUND" | "VERSION_FAILED" | "INVALID_EXPORT_OPTIONS" | "EXPORT_BLOCKED" | "EXPORT_FAILED" | "EXPORT_ABORTED" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -11,6 +12,8 @@ export interface DocumentEngineErrorDetails {
   unknownTypes?: string[];
   missingAssets?: ImageAsset[];
   missingFonts?: FontAsset[];
+  problems?: ExportProblem[];
+  migrationFrom?: number;
   cause?: unknown;
   retryable?: boolean;
 }
@@ -20,6 +23,8 @@ export declare class DocumentEngineError extends Error {
   readonly unknownTypes: string[];
   readonly missingAssets: ImageAsset[];
   readonly missingFonts: FontAsset[];
+  readonly problems: ExportProblem[];
+  readonly migrationFrom: number | undefined;
   readonly cause: unknown;
   readonly retryable: boolean;
   constructor(code: DocumentErrorCode, message: string, details?: DocumentEngineErrorDetails);

package/dist/engine/errors.js

@@ -8,6 +8,8 @@ var DocumentEngineError = class extends Error {
 		this.unknownTypes = details.unknownTypes ?? [];
 		this.missingAssets = details.missingAssets ?? [];
 		this.missingFonts = details.missingFonts ?? [];
+		this.problems = details.problems ?? [];
+		this.migrationFrom = details.migrationFrom;
 		this.cause = details.cause;
 		this.retryable = details.retryable ?? false;
 	}

package/dist/export/download-export.cjs

@@ -0,0 +1,14 @@
+//#region src/export/download-export.ts
+function downloadExport(result, fileName = `document.${result.format === "jpeg" ? "jpg" : result.format}`) {
+	const url = URL.createObjectURL(result.blob);
+	const link = document.createElement("a");
+	link.href = url;
+	link.download = fileName;
+	link.style.display = "none";
+	document.body.append(link);
+	link.click();
+	link.remove();
+	setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+//#endregion
+exports.downloadExport = downloadExport;

package/dist/export/download-export.d.cts

@@ -0,0 +1,7 @@
+//#region src/export/download-export.d.ts
+export interface DownloadableExport {
+  blob: Blob;
+  format: string;
+}
+export declare function downloadExport(result: DownloadableExport, fileName?: string): void;
+//#endregion

package/dist/export/download-export.d.ts

@@ -0,0 +1,7 @@
+//#region src/export/download-export.d.ts
+export interface DownloadableExport {
+  blob: Blob;
+  format: string;
+}
+export declare function downloadExport(result: DownloadableExport, fileName?: string): void;
+//#endregion

package/dist/export/download-export.js

@@ -0,0 +1,14 @@
+//#region src/export/download-export.ts
+function downloadExport(result, fileName = `document.${result.format === "jpeg" ? "jpg" : result.format}`) {
+	const url = URL.createObjectURL(result.blob);
+	const link = document.createElement("a");
+	link.href = url;
+	link.download = fileName;
+	link.style.display = "none";
+	document.body.append(link);
+	link.click();
+	link.remove();
+	setTimeout(() => URL.revokeObjectURL(url), 0);
+}
+//#endregion
+export { downloadExport };

package/dist/export/export-area.cjs

@@ -0,0 +1,46 @@
+const require_errors = require("../engine/errors.cjs");
+//#region src/export/export-area.ts
+function boundsOf(objects) {
+	if (objects.length === 0) return null;
+	let left = Infinity;
+	let top = Infinity;
+	let right = -Infinity;
+	let bottom = -Infinity;
+	for (const object of objects) {
+		const box = object.getBoundingRect();
+		left = Math.min(left, box.left);
+		top = Math.min(top, box.top);
+		right = Math.max(right, box.left + box.width);
+		bottom = Math.max(bottom, box.top + box.height);
+	}
+	return {
+		left,
+		top,
+		width: right - left,
+		height: bottom - top
+	};
+}
+function padAndRound(rect, padding) {
+	const left = Math.floor(rect.left - padding);
+	const top = Math.floor(rect.top - padding);
+	return {
+		left,
+		top,
+		width: Math.max(1, Math.ceil(rect.left + rect.width + padding) - left),
+		height: Math.max(1, Math.ceil(rect.top + rect.height + padding) - top)
+	};
+}
+function resolveExportArea(canvas, area, padding) {
+	if (typeof area === "object") return padAndRound(area, padding);
+	if (area === "canvas") return {
+		left: 0,
+		top: 0,
+		width: canvas.getWidth(),
+		height: canvas.getHeight()
+	};
+	const bounds = boundsOf(area === "selection" ? canvas.getActiveObjects?.() ?? [] : canvas.getObjects());
+	if (bounds === null) throw new require_errors.DocumentEngineError("INVALID_EXPORT_OPTIONS", `Cannot export the ${area} because ${area === "selection" ? "nothing is selected" : "the canvas is empty"}`);
+	return padAndRound(bounds, padding);
+}
+//#endregion
+exports.resolveExportArea = resolveExportArea;

package/dist/export/export-area.js

@@ -0,0 +1,46 @@
+import { DocumentEngineError } from "../engine/errors.js";
+//#region src/export/export-area.ts
+function boundsOf(objects) {
+	if (objects.length === 0) return null;
+	let left = Infinity;
+	let top = Infinity;
+	let right = -Infinity;
+	let bottom = -Infinity;
+	for (const object of objects) {
+		const box = object.getBoundingRect();
+		left = Math.min(left, box.left);
+		top = Math.min(top, box.top);
+		right = Math.max(right, box.left + box.width);
+		bottom = Math.max(bottom, box.top + box.height);
+	}
+	return {
+		left,
+		top,
+		width: right - left,
+		height: bottom - top
+	};
+}
+function padAndRound(rect, padding) {
+	const left = Math.floor(rect.left - padding);
+	const top = Math.floor(rect.top - padding);
+	return {
+		left,
+		top,
+		width: Math.max(1, Math.ceil(rect.left + rect.width + padding) - left),
+		height: Math.max(1, Math.ceil(rect.top + rect.height + padding) - top)
+	};
+}
+function resolveExportArea(canvas, area, padding) {
+	if (typeof area === "object") return padAndRound(area, padding);
+	if (area === "canvas") return {
+		left: 0,
+		top: 0,
+		width: canvas.getWidth(),
+		height: canvas.getHeight()
+	};
+	const bounds = boundsOf(area === "selection" ? canvas.getActiveObjects?.() ?? [] : canvas.getObjects());
+	if (bounds === null) throw new DocumentEngineError("INVALID_EXPORT_OPTIONS", `Cannot export the ${area} because ${area === "selection" ? "nothing is selected" : "the canvas is empty"}`);
+	return padAndRound(bounds, padding);
+}
+//#endregion
+export { resolveExportArea };

package/dist/export/export-options.cjs

@@ -0,0 +1,47 @@
+const require_errors = require("../engine/errors.cjs");
+//#region src/export/export-options.ts
+const formats = /* @__PURE__ */ new Set([
+	"png",
+	"jpeg",
+	"webp",
+	"svg",
+	"json"
+]);
+function invalid(message) {
+	return new require_errors.DocumentEngineError("INVALID_EXPORT_OPTIONS", message);
+}
+function isPositive(value) {
+	return Number.isFinite(value) && value > 0;
+}
+function isRasterFormat(format) {
+	return format === "png" || format === "jpeg" || format === "webp";
+}
+function normalizeExportOptions(options) {
+	if (!formats.has(options.format)) throw invalid(`Unknown export format "${String(options.format)}", use png, jpeg, webp, svg or json`);
+	const scale = options.scale ?? 1;
+	if (!isPositive(scale)) throw invalid("scale must be a number greater than zero");
+	const quality = options.quality ?? .92;
+	if (!(quality >= 0 && quality <= 1)) throw invalid("quality must be between 0 and 1");
+	const padding = options.padding ?? 0;
+	if (!(Number.isFinite(padding) && padding >= 0)) throw invalid("padding must be zero or more");
+	const area = options.area ?? "canvas";
+	if (typeof area === "object") {
+		if (![area.left, area.top].every(Number.isFinite) || !isPositive(area.width) || !isPositive(area.height)) throw invalid("area needs finite left and top and a positive width and height");
+	} else if (![
+		"canvas",
+		"content",
+		"selection"
+	].includes(area)) throw invalid(`Unknown export area "${String(area)}", use canvas, content, selection or a rectangle`);
+	return {
+		format: options.format,
+		scale,
+		quality,
+		area,
+		padding,
+		background: options.background ?? "keep",
+		signal: options.signal
+	};
+}
+//#endregion
+exports.isRasterFormat = isRasterFormat;
+exports.normalizeExportOptions = normalizeExportOptions;

package/dist/export/export-options.d.cts

@@ -0,0 +1,20 @@
+//#region src/export/export-options.d.ts
+export type ExportFormat = "png" | "jpeg" | "webp" | "svg" | "json";
+export interface ExportRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+export type ExportArea = "canvas" | "content" | "selection" | ExportRect;
+export type ExportBackground = "keep" | "transparent" | (string & {});
+export interface ExportOptions {
+  format: ExportFormat;
+  scale?: number;
+  quality?: number;
+  area?: ExportArea;
+  padding?: number;
+  background?: ExportBackground;
+  signal?: AbortSignal;
+}
+//#endregion

package/dist/export/export-options.d.ts

@@ -0,0 +1,20 @@
+//#region src/export/export-options.d.ts
+export type ExportFormat = "png" | "jpeg" | "webp" | "svg" | "json";
+export interface ExportRect {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+export type ExportArea = "canvas" | "content" | "selection" | ExportRect;
+export type ExportBackground = "keep" | "transparent" | (string & {});
+export interface ExportOptions {
+  format: ExportFormat;
+  scale?: number;
+  quality?: number;
+  area?: ExportArea;
+  padding?: number;
+  background?: ExportBackground;
+  signal?: AbortSignal;
+}
+//#endregion

package/dist/export/export-options.js

@@ -0,0 +1,46 @@
+import { DocumentEngineError } from "../engine/errors.js";
+//#region src/export/export-options.ts
+const formats = /* @__PURE__ */ new Set([
+	"png",
+	"jpeg",
+	"webp",
+	"svg",
+	"json"
+]);
+function invalid(message) {
+	return new DocumentEngineError("INVALID_EXPORT_OPTIONS", message);
+}
+function isPositive(value) {
+	return Number.isFinite(value) && value > 0;
+}
+function isRasterFormat(format) {
+	return format === "png" || format === "jpeg" || format === "webp";
+}
+function normalizeExportOptions(options) {
+	if (!formats.has(options.format)) throw invalid(`Unknown export format "${String(options.format)}", use png, jpeg, webp, svg or json`);
+	const scale = options.scale ?? 1;
+	if (!isPositive(scale)) throw invalid("scale must be a number greater than zero");
+	const quality = options.quality ?? .92;
+	if (!(quality >= 0 && quality <= 1)) throw invalid("quality must be between 0 and 1");
+	const padding = options.padding ?? 0;
+	if (!(Number.isFinite(padding) && padding >= 0)) throw invalid("padding must be zero or more");
+	const area = options.area ?? "canvas";
+	if (typeof area === "object") {
+		if (![area.left, area.top].every(Number.isFinite) || !isPositive(area.width) || !isPositive(area.height)) throw invalid("area needs finite left and top and a positive width and height");
+	} else if (![
+		"canvas",
+		"content",
+		"selection"
+	].includes(area)) throw invalid(`Unknown export area "${String(area)}", use canvas, content, selection or a rectangle`);
+	return {
+		format: options.format,
+		scale,
+		quality,
+		area,
+		padding,
+		background: options.background ?? "keep",
+		signal: options.signal
+	};
+}
+//#endregion
+export { isRasterFormat, normalizeExportOptions };