fabricjs-document-engine 0.3.0 → 0.5.0

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

@@ -2,15 +2,20 @@ 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 { createRecoveryController, restoreRecordedFiles } from "../recovery/recovery-controller.js";
 import { createSaveController } from "../save/save-controller.js";
 import { createEventEmitter } from "./event-emitter.js";
 //#region src/engine/create-document-engine.ts
@@ -70,7 +75,7 @@ function createDocumentEngine(options) {
 			return serializeCanvas(canvas, registry.propertiesToInclude()).objects;
 		},
 		onChange: (state) => events.emit("history:change", state),
-		onContentChange: () => saving.noteContentChange()
+		onContentChange: () => noteContentChange()
 	});
 	const saving = createSaveController({
 		getStorage: () => requireStorage(),
@@ -83,10 +88,30 @@ function createDocumentEngine(options) {
 		autosave: options.autosave === true ? {} : options.autosave ?? false,
 		onStateChange: (state) => events.emit("save:status", state),
 		onStart: (document) => events.emit("save:start", { document }),
-		onSuccess: (document) => events.emit("save:success", { document }),
+		onSuccess: (document) => {
+			if (recovery && !saving.state().isDirty) recovery.remove(document.id);
+			events.emit("save:success", { document });
+		},
 		onError: (error) => events.emit("save:error", { error }),
 		onRetry: (event) => events.emit("save:retry", event)
 	});
+	const recovery = options.recovery ? createRecoveryController({
+		...options.recovery,
+		createDocument: () => toDocument(),
+		shouldWrite: () => !destroyed && saving.state().isDirty,
+		onCheckpoint: (record) => events.emit("recovery:checkpoint", {
+			documentId: record.documentId,
+			savedAt: record.savedAt
+		}),
+		onError: (error) => {
+			const reason = error instanceof Error ? error.message : String(error);
+			events.emit("recovery:error", { error: new DocumentEngineError("RECOVERY_FAILED", `Could not write the recovery copy: ${reason}`, { cause: error }) });
+		}
+	}) : void 0;
+	function noteContentChange() {
+		saving.noteContentChange();
+		recovery?.schedule();
+	}
 	function toDocument() {
 		ensureUsable();
 		rebuildIndex();
@@ -135,8 +160,11 @@ function createDocumentEngine(options) {
 		activeLoad?.abort();
 		const controller = new AbortController();
 		activeLoad = controller;
-		events.emit("load:start", { documentId: describeDocumentId(input) });
+		const documentId = describeDocumentId(input);
+		events.emit("load:start", { documentId });
 		try {
+			await recovery?.markLoadStarted(documentId);
+			if (controller.signal.aborted) throw new Error("aborted");
 			const checked = checkDocument(input);
 			const { document, warnings } = await prepareAssetsForLoad(checked, assetOptions, controller.signal);
 			if (controller.signal.aborted) throw new Error("aborted");
@@ -158,6 +186,7 @@ function createDocumentEngine(options) {
 			};
 			rebuildIndex();
 			history.reset();
+			recovery?.cancel();
 			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
 			if (warnings.length > 0) events.emit("assets:warning", { warnings });
@@ -171,7 +200,10 @@ function createDocumentEngine(options) {
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		} finally {
-			if (activeLoad === controller) activeLoad = null;
+			if (activeLoad === controller) {
+				activeLoad = null;
+				await recovery?.markLoadFinished();
+			}
 		}
 	}
 	function requireStorage() {
@@ -208,6 +240,7 @@ function createDocumentEngine(options) {
 		documentInfo = createDocumentInfo(newOptions);
 		uploadedUrls.clear();
 		history.reset();
+		recovery?.cancel();
 		saving.startSession(0);
 	}
 	function getObjectById(id) {
@@ -241,6 +274,107 @@ 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");
+		return recovery;
+	}
+	async function restoreRecovery(documentId, loadOptions) {
+		const source = requireRecovery();
+		const id = documentId ?? documentInfo.id;
+		const record = await source.read(id);
+		if (!record) throw new DocumentEngineError("RECOVERY_NOT_FOUND", `There is no recovery copy for document "${id}"`);
+		const loaded = await loadDocument(await restoreRecordedFiles(record), loadOptions);
+		noteContentChange();
+		events.emit("recovery:restored", { document: loaded });
+		return loaded;
+	}
 	async function travelThroughHistory(direction) {
 		ensureUsable();
 		try {
@@ -258,6 +392,7 @@ function createDocumentEngine(options) {
 		activeLoad?.abort();
 		history.destroy();
 		saving.destroy();
+		recovery?.destroy();
 		canvas.off("object:added", handleObjectAdded);
 		canvas.off("object:removed", handleObjectRemoved);
 		objectsById.clear();
@@ -278,7 +413,7 @@ function createDocumentEngine(options) {
 					...changes
 				}
 			};
-			saving.noteContentChange();
+			noteContentChange();
 		},
 		newDocument,
 		toDocument,
@@ -298,6 +433,14 @@ 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),
+		restoreRecovery,
+		discardRecovery: async (documentId) => requireRecovery().remove(documentId ?? documentInfo.id),
+		getInterruptedLoad: async () => requireRecovery().interruptedLoad(),
 		transaction(label, work) {
 			ensureUsable();
 			return history.transaction(label, work);

package/dist/engine/errors.cjs

@@ -8,6 +8,7 @@ var DocumentEngineError = class extends Error {
 		this.unknownTypes = details.unknownTypes ?? [];
 		this.missingAssets = details.missingAssets ?? [];
 		this.missingFonts = details.missingFonts ?? [];
+		this.problems = details.problems ?? [];
 		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" | "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" | "INVALID_EXPORT_OPTIONS" | "EXPORT_BLOCKED" | "EXPORT_FAILED" | "EXPORT_ABORTED" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -11,6 +12,7 @@ export interface DocumentEngineErrorDetails {
   unknownTypes?: string[];
   missingAssets?: ImageAsset[];
   missingFonts?: FontAsset[];
+  problems?: ExportProblem[];
   cause?: unknown;
   retryable?: boolean;
 }
@@ -20,6 +22,7 @@ export declare class DocumentEngineError extends Error {
   readonly unknownTypes: string[];
   readonly missingAssets: ImageAsset[];
   readonly missingFonts: FontAsset[];
+  readonly problems: ExportProblem[];
   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" | "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" | "INVALID_EXPORT_OPTIONS" | "EXPORT_BLOCKED" | "EXPORT_FAILED" | "EXPORT_ABORTED" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -11,6 +12,7 @@ export interface DocumentEngineErrorDetails {
   unknownTypes?: string[];
   missingAssets?: ImageAsset[];
   missingFonts?: FontAsset[];
+  problems?: ExportProblem[];
   cause?: unknown;
   retryable?: boolean;
 }
@@ -20,6 +22,7 @@ export declare class DocumentEngineError extends Error {
   readonly unknownTypes: string[];
   readonly missingAssets: ImageAsset[];
   readonly missingFonts: FontAsset[];
+  readonly problems: ExportProblem[];
   readonly cause: unknown;
   readonly retryable: boolean;
   constructor(code: DocumentErrorCode, message: string, details?: DocumentEngineErrorDetails);

package/dist/engine/errors.js

@@ -8,6 +8,7 @@ var DocumentEngineError = class extends Error {
 		this.unknownTypes = details.unknownTypes ?? [];
 		this.missingAssets = details.missingAssets ?? [];
 		this.missingFonts = details.missingFonts ?? [];
+		this.problems = details.problems ?? [];
 		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 };