fabricjs-document-engine 1.0.2 → 1.2.0

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

@@ -1,4 +1,5 @@
 const require_asset_manifest = require("../assets/asset-manifest.cjs");
+const require_page_state = require("../fabric/page-state.cjs");
 const require_errors = require("./errors.cjs");
 const require_content_limits = require("../security/content-limits.cjs");
 const require_image_check = require("../assets/image-check.cjs");
@@ -9,6 +10,8 @@ const require_object_ids = require("../fabric/object-ids.cjs");
 const require_walk_objects = require("../fabric/walk-objects.cjs");
 const require_preflight_export = require("../export/preflight-export.cjs");
 const require_render_export = require("../export/render-export.cjs");
+const require_embed_assets = require("../export/svg/embed-assets.cjs");
+const require_svg_import = require("../import/svg-import.cjs");
 require("../document/document-format.cjs");
 const require_ids = require("../document/ids.cjs");
 const require_create_document = require("../document/create-document.cjs");
@@ -36,11 +39,21 @@ function createDocumentEngine(options) {
 	const registry = require_object_registry.createObjectRegistry(options.customObjects);
 	const events = require_event_emitter.createEventEmitter();
 	const objectsById = /* @__PURE__ */ new Map();
-	const assetOptions = options.assets ?? {};
+	const assetOptions = {
+		...options.assets,
+		maxImagePixels: options.limits?.maxImagePixels ?? 67108864
+	};
 	const uploadedUrls = /* @__PURE__ */ new Map();
 	let documentInfo = require_create_document.createDocumentInfo(options.document);
 	let activeLoad = null;
 	let destroyed = false;
+	let mutations = 0;
+	let session = 0;
+	/** Throws when async work started under `startedIn` would now change another document. */
+	function ensureSameSession(startedIn, what) {
+		ensureUsable();
+		if (session !== startedIn) throw new require_errors.DocumentEngineError("DOCUMENT_CHANGED", `${what} was dropped because another document was opened while it ran`);
+	}
 	function ensureUsable() {
 		if (destroyed) throw new require_errors.DocumentEngineError("ENGINE_DESTROYED", "This document engine was destroyed");
 	}
@@ -65,21 +78,41 @@ function createDocumentEngine(options) {
 		objectsById.clear();
 		canvas.getObjects().forEach(indexObjectTree);
 	}
-	const handleObjectAdded = ({ target }) => indexObjectTree(target);
-	const handleObjectRemoved = ({ target }) => removeObjectTreeFromIndex(target);
+	const handleObjectAdded = ({ target }) => {
+		mutations += 1;
+		indexObjectTree(target);
+	};
+	const handleObjectRemoved = ({ target }) => {
+		mutations += 1;
+		removeObjectTreeFromIndex(target);
+	};
+	const countMutation = () => {
+		mutations += 1;
+	};
 	canvas.on("object:added", handleObjectAdded);
 	canvas.on("object:removed", handleObjectRemoved);
+	canvas.on("object:modified", countMutation);
+	canvas.on("text:changed", countMutation);
 	rebuildIndex();
 	const history = require_create_history.createHistory({
 		canvas,
 		limit: options.history?.limit,
 		maxBytes: options.history?.maxBytes,
-		serializeObjects: () => {
+		serializeState: () => {
 			rebuildIndex();
-			return require_fabric_adapter.serializeCanvas(canvas, registry.propertiesToInclude()).objects;
+			const serialized = require_fabric_adapter.serializeCanvas(canvas, registry.propertiesToInclude());
+			return {
+				objects: serialized.objects,
+				page: {
+					width: canvas.getWidth(),
+					height: canvas.getHeight(),
+					...require_page_state.pickPageFields(serialized)
+				}
+			};
 		},
 		onChange: (state) => events.emit("history:change", state),
-		onContentChange: () => noteContentChange()
+		onContentChange: () => noteContentChange(),
+		onLiveChange: () => noteContentChange()
 	});
 	const saving = require_save_controller.createSaveController({
 		getStorage: () => requireStorage(),
@@ -114,6 +147,7 @@ function createDocumentEngine(options) {
 		}
 	}) : void 0;
 	function noteContentChange() {
+		mutations += 1;
 		saving.noteContentChange();
 		recovery?.schedule();
 	}
@@ -136,15 +170,21 @@ function createDocumentEngine(options) {
 				height: canvas.getHeight()
 			},
 			objects: serialized.objects,
-			assets: require_asset_manifest.buildAssetManifest(serialized.objects),
+			assets: require_asset_manifest.buildAssetManifest(require_page_state.documentObjects({
+				objects: serialized.objects,
+				canvas: serialized
+			})),
 			metadata: { ...documentInfo.metadata }
 		};
 		if (serialized.version !== void 0) document.fabricVersion = serialized.version;
-		if (serialized.background !== void 0) document.canvas.background = serialized.background;
+		Object.assign(document.canvas, require_page_state.pickPageFields(serialized));
 		return document;
 	}
-	function toLoadError(error, signal) {
-		if (signal.aborted) return new require_errors.DocumentEngineError("LOAD_ABORTED", "Loading stopped because a newer load started", { cause: error });
+	function toLoadError(error, controller) {
+		if (controller.signal.aborted) {
+			const reason = cancelledByCaller.has(controller) ? "Loading was cancelled" : destroyed ? "Loading stopped because the engine was destroyed" : "Loading stopped because a newer load started";
+			return new require_errors.DocumentEngineError("LOAD_ABORTED", reason, { cause: error });
+		}
 		if (require_errors.isDocumentEngineError(error)) return error;
 		const reason = error instanceof Error ? error.message : String(error);
 		return new require_errors.DocumentEngineError("LOAD_FAILED", `Fabric could not load the document: ${reason}`, { cause: error });
@@ -156,7 +196,7 @@ function createDocumentEngine(options) {
 			throw new require_errors.DocumentEngineError(issues[0].code, `The document is not valid: ${summary}`, { issues });
 		}
 		const document = input;
-		const unknownTypes = registry.findUnknownTypes(require_walk_objects.collectSerializedTypes(document.objects));
+		const unknownTypes = registry.findUnknownTypes(require_walk_objects.collectSerializedTypes(require_page_state.documentObjects(document)));
 		if (unknownTypes.length > 0) throw new require_errors.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;
 	}
@@ -167,19 +207,50 @@ function createDocumentEngine(options) {
 		if (!storage || discardUnsavedChanges || !saving.state().isDirty) return;
 		throw new require_errors.DocumentEngineError("UNSAVED_CHANGES", "The current document has unsaved changes. Save first, or pass { discardUnsavedChanges: true } to replace it anyway.");
 	}
-	function startLoad() {
+	const cancelledByCaller = /* @__PURE__ */ new WeakSet();
+	const unlinkCallerSignal = /* @__PURE__ */ new WeakMap();
+	function startLoad(callerSignal) {
 		activeLoad?.abort();
 		const controller = new AbortController();
 		activeLoad = controller;
+		if (callerSignal) {
+			const cancel = () => {
+				cancelledByCaller.add(controller);
+				controller.abort();
+			};
+			if (callerSignal.aborted) cancel();
+			else {
+				callerSignal.addEventListener("abort", cancel, { once: true });
+				unlinkCallerSignal.set(controller, () => callerSignal.removeEventListener("abort", cancel));
+			}
+		}
 		return controller;
 	}
+	function finishLoad(controller) {
+		unlinkCallerSignal.get(controller)?.();
+		unlinkCallerSignal.delete(controller);
+	}
 	async function loadMigratedDocument(input, loadOptions, importDetails, startedLoad) {
 		ensureUsable();
 		protectUnsavedChanges(loadOptions.discardUnsavedChanges);
-		const controller = startedLoad ?? startLoad();
+		const controller = startedLoad ?? startLoad(loadOptions.signal);
+		const mutationsAtStart = mutations;
 		const documentId = describeDocumentId(input);
+		const report = (stage, done, total) => {
+			if (controller.signal.aborted) return;
+			const progress = {
+				documentId,
+				stage,
+				done,
+				total
+			};
+			loadOptions.onProgress?.(progress);
+			events.emit("load:progress", progress);
+		};
 		events.emit("load:start", { documentId });
 		try {
+			if (controller.signal.aborted) throw new Error("aborted");
+			report("prepare", 0, 1);
 			await recovery?.markLoadStarted(documentId);
 			if (controller.signal.aborted) throw new Error("aborted");
 			const { document: migrated, migratedFrom } = require_migrate_document.migrateDocument(require_content_limits.secureDocument(input, options.limits), {
@@ -188,13 +259,21 @@ function createDocumentEngine(options) {
 				...importDetails
 			});
 			const checked = checkDocument(migrated);
-			const { document, warnings } = await require_asset_pipeline.prepareAssetsForLoad(checked, assetOptions, controller.signal, options.limits?.isAllowedUrl);
+			report("prepare", 1, 1);
+			const { document, warnings } = await require_asset_pipeline.prepareAssetsForLoad(checked, assetOptions, controller.signal, options.limits?.isAllowedUrl, (done, total) => report("images", done, total));
 			if (controller.signal.aborted) throw new Error("aborted");
 			await history.withoutRecording(() => require_fabric_adapter.loadIntoCanvas(canvas, {
 				version: document.fabricVersion,
-				background: document.canvas.background,
+				...require_page_state.pickPageFields(document.canvas),
 				objects: document.objects
-			}, controller.signal));
+			}, {
+				signal: controller.signal,
+				onObjects: (done, total) => report("objects", done, total),
+				beforeSwap: () => {
+					if (mutations !== mutationsAtStart && !loadOptions.discardUnsavedChanges) throw new require_errors.DocumentEngineError("LOAD_CONFLICT", "The canvas was edited while the document loaded, so the load was stopped to keep the edits. Pass { discardUnsavedChanges: true } to replace them.");
+					session += 1;
+				}
+			}));
 			if (controller.signal.aborted) throw new Error("aborted");
 			if (loadOptions.restoreCanvasSize ?? true) canvas.setDimensions({
 				width: document.canvas.width,
@@ -211,6 +290,7 @@ function createDocumentEngine(options) {
 			recovery?.cancel();
 			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
+			report("done", 1, 1);
 			if (warnings.length > 0) events.emit("assets:warning", { warnings });
 			events.emit("document:change", { documentId: document.id });
 			events.emit("load:success", {
@@ -220,10 +300,11 @@ function createDocumentEngine(options) {
 			});
 			return document;
 		} catch (error) {
-			const engineError = toLoadError(error, controller.signal);
+			const engineError = toLoadError(error, controller);
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		} finally {
+			finishLoad(controller);
 			if (activeLoad === controller) {
 				activeLoad = null;
 				await recovery?.markLoadFinished();
@@ -244,6 +325,43 @@ function createDocumentEngine(options) {
 			metadata
 		});
 	}
+	function setPage(changes, label = "Change page") {
+		ensureUsable();
+		const problem = require_content_limits.canvasSizeProblem(changes.width ?? canvas.getWidth(), changes.height ?? canvas.getHeight(), options.limits);
+		if (problem) throw new require_errors.DocumentEngineError("UNSAFE_DOCUMENT", `The page was not resized: it would be ${problem}`);
+		history.transaction(label, () => {
+			const width = changes.width ?? canvas.getWidth();
+			const height = changes.height ?? canvas.getHeight();
+			if (width !== canvas.getWidth() || height !== canvas.getHeight()) canvas.setDimensions({
+				width,
+				height
+			});
+			const live = {};
+			if (changes.background !== void 0) live.backgroundColor = changes.background ?? "";
+			if (changes.backgroundImage !== void 0) live.backgroundImage = changes.backgroundImage ?? void 0;
+			if (changes.overlay !== void 0) live.overlayColor = changes.overlay ?? "";
+			if (changes.overlayImage !== void 0) live.overlayImage = changes.overlayImage ?? void 0;
+			if (changes.clipPath !== void 0) live.clipPath = changes.clipPath ?? void 0;
+			canvas.set(live);
+		});
+		canvas.requestRenderAll();
+	}
+	async function importSvg(svg, importOptions = {}) {
+		ensureUsable();
+		const startedIn = session;
+		const result = await require_svg_import.readSvg(svg, importOptions, options.limits);
+		try {
+			ensureSameSession(startedIn, "The SVG import");
+		} catch (error) {
+			result.objects.forEach((object) => object.dispose?.());
+			throw error;
+		}
+		if (result.objects.length > 0) {
+			history.transaction("Import SVG", () => canvas.add(...result.objects));
+			canvas.requestRenderAll();
+		}
+		return result;
+	}
 	let savesSinceAutomaticVersion = 0;
 	let lastVersionTime = 0;
 	function nextVersionTimestamp() {
@@ -322,15 +440,17 @@ function createDocumentEngine(options) {
 		ensureUsable();
 		const source = requireStorage();
 		protectUnsavedChanges(loadOptions?.discardUnsavedChanges);
-		const controller = startLoad();
+		const controller = startLoad(loadOptions?.signal);
 		let stored;
 		try {
+			if (controller.signal.aborted) throw new Error("aborted");
 			stored = await source.loadDocument(documentId);
 			if (controller.signal.aborted) throw new Error("aborted");
 		} catch (error) {
+			finishLoad(controller);
 			if (activeLoad === controller) activeLoad = null;
 			if (controller.signal.aborted) {
-				const aborted = toLoadError(error, controller.signal);
+				const aborted = toLoadError(error, controller);
 				events.emit("load:error", { error: aborted });
 				throw aborted;
 			}
@@ -355,6 +475,7 @@ function createDocumentEngine(options) {
 		protectUnsavedChanges(newOptions.discardUnsavedChanges);
 		activeLoad?.abort();
 		history.withoutRecording(() => canvas.clear());
+		session += 1;
 		objectsById.clear();
 		documentInfo = require_create_document.createDocumentInfo(newOptions);
 		uploadedUrls.clear();
@@ -381,10 +502,12 @@ function createDocumentEngine(options) {
 			if (isReplaceableImage(object) && require_image_check.isSameUrl(object.getSrc(), oldUrl)) images.push(object);
 		});
 		if (images.length === 0) return 0;
+		const startedIn = session;
 		await history.transaction("Replace image", () => Promise.all(images.map(async (image) => {
 			const displayedWidth = image.width * image.scaleX;
 			const displayedHeight = image.height * image.scaleY;
 			await image.setSrc(newUrl, { crossOrigin: image.crossOrigin ?? null });
+			ensureSameSession(startedIn, "Replacing the image");
 			image.set({
 				scaleX: displayedWidth / image.width,
 				scaleY: displayedHeight / image.height
@@ -400,8 +523,8 @@ function createDocumentEngine(options) {
 	}
 	async function checkBeforeExport(exportOptions) {
 		ensureUsable();
-		const { format } = require_export_options.normalizeExportOptions(exportOptions);
-		return require_preflight_export.preflightExport(canvas, format, format === "json" ? [] : fontsOnCanvas(), assetOptions);
+		const { format, svg } = require_export_options.normalizeExportOptions(exportOptions);
+		return require_preflight_export.preflightExport(canvas, format, format === "json" ? [] : fontsOnCanvas(), assetOptions, svg);
 	}
 	function describeProblems(check) {
 		return check.problems.map((problem) => problem.message).join("; ");
@@ -430,24 +553,58 @@ function createDocumentEngine(options) {
 		if (!check.ok) throw new require_errors.DocumentEngineError("EXPORT_BLOCKED", `The export cannot run: ${describeProblems(check)}`, { problems: check.problems });
 		const format = settings.format;
 		try {
+			const warnings = [...check.warnings];
 			const rendered = require_render_export.withExportView(canvas, settings.background, format, () => {
 				const area = require_export_area.resolveExportArea(canvas, settings.area, settings.padding);
+				if (format !== "svg") {
+					const problem = require_content_limits.canvasSizeProblem(area.width * settings.scale, area.height * settings.scale, options.limits);
+					if (problem) {
+						const message = `The export would be ${problem}. Lower the scale or export a smaller area.`;
+						throw new require_errors.DocumentEngineError("EXPORT_BLOCKED", message, { problems: [{
+							code: "TOO_LARGE",
+							message,
+							objectIds: []
+						}] });
+					}
+				}
 				return {
 					area,
-					content: format === "svg" ? Promise.resolve(new Blob([require_render_export.renderSvg(canvas, area, settings.scale)], { type: require_render_export.mimeTypes.svg })) : require_render_export.renderRaster(canvas, area, format, settings.scale, settings.quality)
+					content: format === "svg" ? Promise.resolve(require_render_export.renderSvg(canvas, area, settings.scale, settings.svg, options.limits)) : require_render_export.renderRaster(canvas, area, format, settings.scale, settings.quality)
 				};
 			});
-			const blob = await rendered.content;
+			let blob;
+			if (format === "svg") {
+				const { svg, rasterizedObjectIds } = await rendered.content;
+				if (rasterizedObjectIds.length > 0) warnings.push({
+					code: "CLIP_PATH_RASTERIZED",
+					message: "Objects whose clip path has a clip path of its own were drawn as pictures: Fabric cannot write nested clip paths as SVG.",
+					objectIds: rasterizedObjectIds
+				});
+				const embedded = await require_embed_assets.embedSvgAssets(svg, canvas, settings.svg, settings.signal, options.limits?.isAllowedUrl ?? require_content_limits.isSafeImageUrl);
+				stopIfCancelled();
+				if (settings.svg.embedImages === "require" && embedded.problems.length > 0) {
+					const problems = embedded.warnings.filter((warning) => warning.code === "IMAGE_NOT_EMBEDDED").map((warning) => ({
+						code: "IMAGE_NOT_EMBEDDED",
+						message: warning.message,
+						url: warning.url,
+						objectIds: warning.objectIds
+					}));
+					throw new require_errors.DocumentEngineError("EXPORT_BLOCKED", `The export cannot run: ${embedded.problems.join("; ")}`, { problems });
+				}
+				warnings.push(...embedded.warnings);
+				blob = new Blob([embedded.svg], { type: require_render_export.mimeTypes.svg });
+			} else blob = await rendered.content;
 			return {
 				format,
 				mimeType: blob.type || require_render_export.mimeTypes[format],
 				blob,
 				width: Math.round(rendered.area.width * settings.scale),
 				height: Math.round(rendered.area.height * settings.scale),
-				warnings: check.warnings
+				warnings
 			};
 		} catch (error) {
 			if (require_errors.isDocumentEngineError(error)) throw error;
+			if (settings.signal?.aborted) throw new require_errors.DocumentEngineError("EXPORT_ABORTED", "The export was cancelled", { cause: error });
 			if (error?.name === "SecurityError") {
 				const problem = {
 					code: "CROSS_ORIGIN_IMAGE",
@@ -485,12 +642,14 @@ function createDocumentEngine(options) {
 		if (!recovery) throw new require_errors.DocumentEngineError("RECOVERY_MISSING", "Pass recovery: { store } to createDocumentEngine to use recovery");
 		return recovery;
 	}
-	async function restoreRecovery(documentId, loadOptions) {
+	async function restoreRecovery(documentId, restoreOptions = {}) {
 		const source = requireRecovery();
 		const id = documentId ?? documentInfo.id;
-		const record = await source.read(id);
+		const { sessionId: branch, ...loadOptions } = restoreOptions;
+		const record = await source.read(id, branch);
 		if (!record) throw new require_errors.DocumentEngineError("RECOVERY_NOT_FOUND", `There is no recovery copy for document "${id}"`);
 		const loaded = await loadDocument(await require_recovery_controller.restoreRecordedFiles(record), loadOptions);
+		source.adopt(loaded.id, record.sessionId);
 		noteContentChange();
 		events.emit("recovery:restored", { document: loaded });
 		return loaded;
@@ -511,12 +670,15 @@ function createDocumentEngine(options) {
 		const { disposed } = canvas;
 		if (recovery && saving.state().isDirty && !disposed) recovery.writeNow();
 		destroyed = true;
+		session += 1;
 		activeLoad?.abort();
 		history.destroy();
 		saving.destroy();
 		recovery?.destroy();
 		canvas.off("object:added", handleObjectAdded);
 		canvas.off("object:removed", handleObjectRemoved);
+		canvas.off("object:modified", countMutation);
+		canvas.off("text:changed", countMutation);
 		objectsById.clear();
 		events.clear();
 	}
@@ -524,7 +686,8 @@ function createDocumentEngine(options) {
 		canvas,
 		getDocumentInfo: () => ({
 			...documentInfo,
-			metadata: { ...documentInfo.metadata }
+			metadata: { ...documentInfo.metadata },
+			session
 		}),
 		updateMetadata(changes) {
 			ensureUsable();
@@ -542,6 +705,7 @@ function createDocumentEngine(options) {
 		loadDocument,
 		load,
 		importFabricJson,
+		importSvg,
 		createVersion: (name) => storeVersion(name ?? `Version ${(/* @__PURE__ */ new Date()).toLocaleString()}`, "named"),
 		listVersions: async (documentId) => requireVersions().listVersions(documentId ?? documentInfo.id),
 		restoreVersion,
@@ -564,14 +728,15 @@ function createDocumentEngine(options) {
 		preflightExport: checkBeforeExport,
 		flushRecovery: async () => requireRecovery().flush(),
 		getRecoverableDocuments: async () => requireRecovery().list(),
-		getRecovery: async (documentId) => requireRecovery().read(documentId ?? documentInfo.id),
+		getRecovery: async (documentId, sessionId) => requireRecovery().read(documentId ?? documentInfo.id, sessionId),
 		restoreRecovery,
-		discardRecovery: async (documentId) => requireRecovery().remove(documentId ?? documentInfo.id),
+		discardRecovery: async (documentId, sessionId) => requireRecovery().discard(documentId ?? documentInfo.id, sessionId),
 		getInterruptedLoad: async () => requireRecovery().interruptedLoad(),
-		transaction(label, work) {
+		transaction(label, work, transactionOptions) {
 			ensureUsable();
-			return history.transaction(label, work);
+			return history.transaction(label, work, transactionOptions);
 		},
+		setPage,
 		commit(label = "Edit") {
 			ensureUsable();
 			return history.commit(label);

package/dist/engine/create-document-engine.d.cts

@@ -3,10 +3,11 @@ import { AssetManifest } from "../assets/asset-manifest.cjs";
 import { AssetOptions, AssetReport, AssetWarning } from "../assets/asset-pipeline.cjs";
 import { ExportFormat, ExportOptions } from "../export/export-options.cjs";
 import { ExportPreflight } from "../export/preflight-export.cjs";
+import { ContentLimits } from "../security/content-limits.cjs";
+import { SvgImportOptions, SvgImportResult } from "../import/svg-import.cjs";
 import { NewDocumentOptions } from "../document/create-document.cjs";
 import { CustomObjectDefinition } from "../fabric/object-registry.cjs";
-import { HistoryOptions, HistoryState } from "../history/create-history.cjs";
-import { ContentLimits } from "../security/content-limits.cjs";
+import { HistoryOptions, HistoryState, TransactionOptions } from "../history/create-history.cjs";
 import { VersionOptions, VersionSummary } from "../versions/document-version.cjs";
 import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "../recovery/recovery-controller.cjs";
 import { AutosaveOptions } from "../save/autosave-scheduler.cjs";
@@ -15,7 +16,7 @@ import { DocumentEngineError } from "./errors.cjs";
 import { DocumentStorage } from "../storage/storage-contract.cjs";
 import { SaveOptions, SaveRetryEvent, SaveState } from "../save/save-controller.cjs";
 import { Unsubscribe } from "./event-emitter.cjs";
-import { FabricObject, StaticCanvas } from "fabric";
+import { FabricObject, StaticCanvas, TFiller } from "fabric";
 //#region src/engine/create-document-engine.d.ts
 export interface DocumentEngineOptions {
   canvas: StaticCanvas;
@@ -33,6 +34,39 @@ export interface DocumentEngineOptions {
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
   discardUnsavedChanges?: boolean;
+  /** Cancels the load. The canvas keeps its current content and the load rejects with `LOAD_ABORTED`. */
+  signal?: AbortSignal;
+  /** Called as the load moves through its stages. The `load:progress` event carries the same values. */
+  onProgress?: (progress: LoadProgress) => void;
+}
+/**
+ * Where a load is. `prepare` covers validation and migration, `images` counts
+ * images checked, `objects` counts top-level objects created, and `done` comes
+ * once the canvas shows the document.
+ */
+export type LoadStage = "prepare" | "images" | "objects" | "done";
+export interface LoadProgress {
+  documentId: string | undefined;
+  stage: LoadStage;
+  done: number;
+  total: number;
+}
+/**
+ * Page settings for `setPage`. Images and the mask are live Fabric objects;
+ * `null` removes one.
+ */
+export interface PageChanges {
+  width?: number;
+  height?: number;
+  background?: string | TFiller | null;
+  backgroundImage?: FabricObject | null;
+  overlay?: string | TFiller | null;
+  overlayImage?: FabricObject | null;
+  clipPath?: FabricObject | null;
+}
+export interface RestoreRecoveryOptions extends LoadOptions {
+  /** Restore the copy one session wrote. By default the newest copy of the document is used. */
+  sessionId?: string;
 }
 export interface NewDocumentRequest extends NewDocumentOptions {
   discardUnsavedChanges?: boolean;
@@ -54,6 +88,7 @@ export interface DocumentEngineEvents {
   "load:start": {
     documentId: string | undefined;
   };
+  "load:progress": LoadProgress;
   "document:change": {
     documentId: string;
   };
@@ -120,6 +155,7 @@ export interface DocumentEngine {
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
   importFabricJson(json: string | Record<string, unknown>, options?: ImportOptions): Promise<FabricDocument>;
+  importSvg(svg: string, options?: SvgImportOptions): Promise<SvgImportResult>;
   createVersion(name?: string): Promise<VersionSummary>;
   listVersions(documentId?: string): Promise<VersionSummary[]>;
   restoreVersion(versionId: string): Promise<FabricDocument>;
@@ -128,7 +164,8 @@ export interface DocumentEngine {
   isDirty(): boolean;
   getSaveState(): SaveState;
   registerObject(definition: CustomObjectDefinition): void;
-  transaction<Result>(label: string, work: () => Result): Result;
+  transaction<Result>(label: string, work: () => Result, options?: TransactionOptions): Result;
+  setPage(changes: PageChanges, label?: string): void;
   commit(label?: string): boolean;
   undo(): Promise<boolean>;
   redo(): Promise<boolean>;
@@ -147,9 +184,9 @@ export interface DocumentEngine {
   preflightExport(options: ExportOptions): Promise<ExportPreflight>;
   flushRecovery(): Promise<void>;
   getRecoverableDocuments(): Promise<RecoveryRecord[]>;
-  getRecovery(documentId?: string): Promise<RecoveryRecord | undefined>;
-  restoreRecovery(documentId?: string, options?: LoadOptions): Promise<FabricDocument>;
-  discardRecovery(documentId?: string): Promise<void>;
+  getRecovery(documentId?: string, sessionId?: string): Promise<RecoveryRecord | undefined>;
+  restoreRecovery(documentId?: string, options?: RestoreRecoveryOptions): Promise<FabricDocument>;
+  discardRecovery(documentId?: string, sessionId?: string): Promise<void>;
   getInterruptedLoad(): Promise<InterruptedLoad | undefined>;
   on<Name extends keyof DocumentEngineEvents>(name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): Unsubscribe;
   destroy(): void;

package/dist/engine/create-document-engine.d.ts

@@ -3,10 +3,11 @@ import { AssetManifest } from "../assets/asset-manifest.js";
 import { AssetOptions, AssetReport, AssetWarning } from "../assets/asset-pipeline.js";
 import { ExportFormat, ExportOptions } from "../export/export-options.js";
 import { ExportPreflight } from "../export/preflight-export.js";
+import { ContentLimits } from "../security/content-limits.js";
+import { SvgImportOptions, SvgImportResult } from "../import/svg-import.js";
 import { NewDocumentOptions } from "../document/create-document.js";
 import { CustomObjectDefinition } from "../fabric/object-registry.js";
-import { HistoryOptions, HistoryState } from "../history/create-history.js";
-import { ContentLimits } from "../security/content-limits.js";
+import { HistoryOptions, HistoryState, TransactionOptions } from "../history/create-history.js";
 import { VersionOptions, VersionSummary } from "../versions/document-version.js";
 import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "../recovery/recovery-controller.js";
 import { AutosaveOptions } from "../save/autosave-scheduler.js";
@@ -15,7 +16,7 @@ import { DocumentEngineError } from "./errors.js";
 import { DocumentStorage } from "../storage/storage-contract.js";
 import { SaveOptions, SaveRetryEvent, SaveState } from "../save/save-controller.js";
 import { Unsubscribe } from "./event-emitter.js";
-import { FabricObject, StaticCanvas } from "fabric";
+import { FabricObject, StaticCanvas, TFiller } from "fabric";
 //#region src/engine/create-document-engine.d.ts
 export interface DocumentEngineOptions {
   canvas: StaticCanvas;
@@ -33,6 +34,39 @@ export interface DocumentEngineOptions {
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
   discardUnsavedChanges?: boolean;
+  /** Cancels the load. The canvas keeps its current content and the load rejects with `LOAD_ABORTED`. */
+  signal?: AbortSignal;
+  /** Called as the load moves through its stages. The `load:progress` event carries the same values. */
+  onProgress?: (progress: LoadProgress) => void;
+}
+/**
+ * Where a load is. `prepare` covers validation and migration, `images` counts
+ * images checked, `objects` counts top-level objects created, and `done` comes
+ * once the canvas shows the document.
+ */
+export type LoadStage = "prepare" | "images" | "objects" | "done";
+export interface LoadProgress {
+  documentId: string | undefined;
+  stage: LoadStage;
+  done: number;
+  total: number;
+}
+/**
+ * Page settings for `setPage`. Images and the mask are live Fabric objects;
+ * `null` removes one.
+ */
+export interface PageChanges {
+  width?: number;
+  height?: number;
+  background?: string | TFiller | null;
+  backgroundImage?: FabricObject | null;
+  overlay?: string | TFiller | null;
+  overlayImage?: FabricObject | null;
+  clipPath?: FabricObject | null;
+}
+export interface RestoreRecoveryOptions extends LoadOptions {
+  /** Restore the copy one session wrote. By default the newest copy of the document is used. */
+  sessionId?: string;
 }
 export interface NewDocumentRequest extends NewDocumentOptions {
   discardUnsavedChanges?: boolean;
@@ -54,6 +88,7 @@ export interface DocumentEngineEvents {
   "load:start": {
     documentId: string | undefined;
   };
+  "load:progress": LoadProgress;
   "document:change": {
     documentId: string;
   };
@@ -120,6 +155,7 @@ export interface DocumentEngine {
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
   importFabricJson(json: string | Record<string, unknown>, options?: ImportOptions): Promise<FabricDocument>;
+  importSvg(svg: string, options?: SvgImportOptions): Promise<SvgImportResult>;
   createVersion(name?: string): Promise<VersionSummary>;
   listVersions(documentId?: string): Promise<VersionSummary[]>;
   restoreVersion(versionId: string): Promise<FabricDocument>;
@@ -128,7 +164,8 @@ export interface DocumentEngine {
   isDirty(): boolean;
   getSaveState(): SaveState;
   registerObject(definition: CustomObjectDefinition): void;
-  transaction<Result>(label: string, work: () => Result): Result;
+  transaction<Result>(label: string, work: () => Result, options?: TransactionOptions): Result;
+  setPage(changes: PageChanges, label?: string): void;
   commit(label?: string): boolean;
   undo(): Promise<boolean>;
   redo(): Promise<boolean>;
@@ -147,9 +184,9 @@ export interface DocumentEngine {
   preflightExport(options: ExportOptions): Promise<ExportPreflight>;
   flushRecovery(): Promise<void>;
   getRecoverableDocuments(): Promise<RecoveryRecord[]>;
-  getRecovery(documentId?: string): Promise<RecoveryRecord | undefined>;
-  restoreRecovery(documentId?: string, options?: LoadOptions): Promise<FabricDocument>;
-  discardRecovery(documentId?: string): Promise<void>;
+  getRecovery(documentId?: string, sessionId?: string): Promise<RecoveryRecord | undefined>;
+  restoreRecovery(documentId?: string, options?: RestoreRecoveryOptions): Promise<FabricDocument>;
+  discardRecovery(documentId?: string, sessionId?: string): Promise<void>;
   getInterruptedLoad(): Promise<InterruptedLoad | undefined>;
   on<Name extends keyof DocumentEngineEvents>(name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): Unsubscribe;
   destroy(): void;