fabricjs-document-engine 0.1.0 → 0.3.0

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

@@ -1,3 +1,7 @@
+const require_asset_manifest = require("../assets/asset-manifest.cjs");
+const require_errors = require("./errors.cjs");
+const require_image_check = require("../assets/image-check.cjs");
+const require_asset_pipeline = require("../assets/asset-pipeline.cjs");
 require("../document/document-format.cjs");
 const require_ids = require("../document/ids.cjs");
 const require_create_document = require("../document/create-document.cjs");
@@ -5,20 +9,27 @@ const require_validate_document = require("../document/validate-document.cjs");
 const require_walk_objects = require("../fabric/walk-objects.cjs");
 const require_fabric_adapter = require("../fabric/fabric-adapter.cjs");
 const require_object_ids = require("../fabric/object-ids.cjs");
-const require_errors = require("./errors.cjs");
 const require_object_registry = require("../fabric/object-registry.cjs");
 const require_create_history = require("../history/create-history.cjs");
+const require_save_controller = require("../save/save-controller.cjs");
 const require_event_emitter = require("./event-emitter.cjs");
 //#region src/engine/create-document-engine.ts
+function isReplaceableImage(object) {
+	const candidate = object;
+	return typeof candidate.getSrc === "function" && typeof candidate.setSrc === "function";
+}
 function describeDocumentId(value) {
 	const id = value?.id;
 	return typeof id === "string" ? id : void 0;
 }
 function createDocumentEngine(options) {
 	const { canvas, storage } = options;
+	if (options.autosave && !storage) throw new require_errors.DocumentEngineError("STORAGE_MISSING", "Autosave needs a storage adapter passed to createDocumentEngine");
 	const registry = require_object_registry.createObjectRegistry(options.customObjects);
 	const events = require_event_emitter.createEventEmitter();
 	const objectsById = /* @__PURE__ */ new Map();
+	const assetOptions = options.assets ?? {};
+	const uploadedUrls = /* @__PURE__ */ new Map();
 	let documentInfo = require_create_document.createDocumentInfo(options.document);
 	let activeLoad = null;
 	let destroyed = false;
@@ -58,7 +69,23 @@ function createDocumentEngine(options) {
 			rebuildIndex();
 			return require_fabric_adapter.serializeCanvas(canvas, registry.propertiesToInclude()).objects;
 		},
-		onChange: (state) => events.emit("history:change", state)
+		onChange: (state) => events.emit("history:change", state),
+		onContentChange: () => saving.noteContentChange()
+	});
+	const saving = require_save_controller.createSaveController({
+		getStorage: () => requireStorage(),
+		createDocument: async () => {
+			const prepared = await require_asset_pipeline.prepareAssetsForSave(toDocument(), assetOptions, uploadedUrls);
+			if (prepared.warnings.length > 0) events.emit("assets:warning", { warnings: prepared.warnings });
+			return prepared.document;
+		},
+		retry: options.saveRetry,
+		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 }),
+		onError: (error) => events.emit("save:error", { error }),
+		onRetry: (event) => events.emit("save:retry", event)
 	});
 	function toDocument() {
 		ensureUsable();
@@ -73,11 +100,13 @@ function createDocumentEngine(options) {
 			id: documentInfo.id,
 			createdAt: documentInfo.createdAt,
 			updatedAt: documentInfo.updatedAt,
+			revision: saving.state().revision,
 			canvas: {
 				width: canvas.getWidth(),
 				height: canvas.getHeight()
 			},
 			objects: serialized.objects,
+			assets: require_asset_manifest.buildAssetManifest(serialized.objects),
 			metadata: { ...documentInfo.metadata }
 		};
 		if (serialized.version !== void 0) document.fabricVersion = serialized.version;
@@ -85,8 +114,8 @@ function createDocumentEngine(options) {
 		return document;
 	}
 	function toLoadError(error, signal) {
-		if (require_errors.isDocumentEngineError(error)) return error;
 		if (signal.aborted) return new require_errors.DocumentEngineError("LOAD_ABORTED", "Loading stopped because a newer load started", { 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 });
 	}
@@ -108,7 +137,9 @@ function createDocumentEngine(options) {
 		activeLoad = controller;
 		events.emit("load:start", { documentId: describeDocumentId(input) });
 		try {
-			const document = checkDocument(input);
+			const checked = checkDocument(input);
+			const { document, warnings } = await require_asset_pipeline.prepareAssetsForLoad(checked, assetOptions, controller.signal);
+			if (controller.signal.aborted) throw new Error("aborted");
 			await history.withoutRecording(() => require_fabric_adapter.loadIntoCanvas(canvas, {
 				version: document.fabricVersion,
 				background: document.canvas.background,
@@ -127,8 +158,13 @@ function createDocumentEngine(options) {
 			};
 			rebuildIndex();
 			history.reset();
+			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
-			events.emit("load:success", { document });
+			if (warnings.length > 0) events.emit("assets:warning", { warnings });
+			events.emit("load:success", {
+				document,
+				warnings
+			});
 			return document;
 		} catch (error) {
 			const engineError = toLoadError(error, controller.signal);
@@ -150,27 +186,19 @@ function createDocumentEngine(options) {
 			stored = await source.loadDocument(documentId);
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
-			const engineError = new require_errors.DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
+			const engineError = require_errors.isDocumentEngineError(error) ? error : new require_errors.DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
 		return loadDocument(stored, loadOptions);
 	}
-	async function save() {
-		ensureUsable();
-		const target = requireStorage();
-		const document = toDocument();
-		events.emit("save:start", { document });
+	function save(saveOptions) {
 		try {
-			await target.saveDocument(document);
+			ensureUsable();
 		} catch (error) {
-			const reason = error instanceof Error ? error.message : String(error);
-			const engineError = new require_errors.DocumentEngineError("SAVE_FAILED", `Storage could not save the document: ${reason}`, { cause: error });
-			events.emit("save:error", { error: engineError });
-			throw engineError;
+			return Promise.reject(error);
 		}
-		events.emit("save:success", { document });
-		return document;
+		return saving.save(saveOptions);
 	}
 	function newDocument(newOptions) {
 		ensureUsable();
@@ -178,7 +206,9 @@ function createDocumentEngine(options) {
 		history.withoutRecording(() => canvas.clear());
 		objectsById.clear();
 		documentInfo = require_create_document.createDocumentInfo(newOptions);
+		uploadedUrls.clear();
 		history.reset();
+		saving.startSession(0);
 	}
 	function getObjectById(id) {
 		ensureUsable();
@@ -187,6 +217,30 @@ function createDocumentEngine(options) {
 		rebuildIndex();
 		return objectsById.get(id);
 	}
+	function checkAssets() {
+		ensureUsable();
+		return require_asset_pipeline.inspectAssets(toDocument(), assetOptions, new AbortController().signal);
+	}
+	async function replaceImage(oldUrl, newUrl) {
+		ensureUsable();
+		const images = [];
+		require_walk_objects.walkObjects(canvas.getObjects(), (object) => {
+			if (isReplaceableImage(object) && require_image_check.isSameUrl(object.getSrc(), oldUrl)) images.push(object);
+		});
+		if (images.length === 0) return 0;
+		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 });
+			image.set({
+				scaleX: displayedWidth / image.width,
+				scaleY: displayedHeight / image.height
+			});
+			image.setCoords();
+		})));
+		canvas.requestRenderAll();
+		return images.length;
+	}
 	async function travelThroughHistory(direction) {
 		ensureUsable();
 		try {
@@ -203,6 +257,7 @@ function createDocumentEngine(options) {
 		destroyed = true;
 		activeLoad?.abort();
 		history.destroy();
+		saving.destroy();
 		canvas.off("object:added", handleObjectAdded);
 		canvas.off("object:removed", handleObjectRemoved);
 		objectsById.clear();
@@ -223,17 +278,26 @@ function createDocumentEngine(options) {
 					...changes
 				}
 			};
+			saving.noteContentChange();
 		},
 		newDocument,
 		toDocument,
 		loadDocument,
 		load,
 		save,
+		isDirty: () => saving.state().isDirty,
+		getSaveState: () => saving.state(),
 		registerObject(definition) {
 			ensureUsable();
 			registry.register(definition);
 		},
 		getObjectById,
+		getAssetManifest: () => toDocument().assets ?? {
+			images: [],
+			fonts: []
+		},
+		checkAssets,
+		replaceImage,
 		transaction(label, work) {
 			ensureUsable();
 			return history.transaction(label, work);

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

@@ -1,21 +1,26 @@
 import { DocumentInfo, FabricDocument } from "../document/document-format.cjs";
+import { AssetManifest } from "../assets/asset-manifest.cjs";
+import { AssetOptions, AssetReport, AssetWarning } from "../assets/asset-pipeline.cjs";
 import { NewDocumentOptions } from "../document/create-document.cjs";
 import { CustomObjectDefinition } from "../fabric/object-registry.cjs";
 import { HistoryOptions, HistoryState } from "../history/create-history.cjs";
+import { AutosaveOptions } from "../save/autosave-scheduler.cjs";
+import { RetryOptions } from "../save/retry.cjs";
 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";
 //#region src/engine/create-document-engine.d.ts
-export interface DocumentStorage {
-  loadDocument(id: string): Promise<unknown>;
-  saveDocument(document: FabricDocument): Promise<void>;
-}
 export interface DocumentEngineOptions {
   canvas: StaticCanvas;
   storage?: DocumentStorage;
   customObjects?: CustomObjectDefinition[];
   document?: NewDocumentOptions;
   history?: HistoryOptions;
+  autosave?: boolean | AutosaveOptions;
+  saveRetry?: RetryOptions;
+  assets?: AssetOptions;
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
@@ -26,6 +31,10 @@ export interface DocumentEngineEvents {
   };
   "load:success": {
     document: FabricDocument;
+    warnings: AssetWarning[];
+  };
+  "assets:warning": {
+    warnings: AssetWarning[];
   };
   "load:error": {
     error: DocumentEngineError;
@@ -39,6 +48,8 @@ export interface DocumentEngineEvents {
   "save:error": {
     error: DocumentEngineError;
   };
+  "save:retry": SaveRetryEvent;
+  "save:status": SaveState;
   "history:change": HistoryState;
   "history:error": {
     error: DocumentEngineError;
@@ -52,7 +63,9 @@ export interface DocumentEngine {
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
-  save(): Promise<FabricDocument>;
+  save(options?: SaveOptions): Promise<FabricDocument>;
+  isDirty(): boolean;
+  getSaveState(): SaveState;
   registerObject(definition: CustomObjectDefinition): void;
   transaction<Result>(label: string, work: () => Result): Result;
   commit(label?: string): boolean;
@@ -66,6 +79,9 @@ export interface DocumentEngine {
   };
   clearHistory(): void;
   getObjectById(id: string): FabricObject | undefined;
+  getAssetManifest(): AssetManifest;
+  checkAssets(): Promise<AssetReport>;
+  replaceImage(oldUrl: string, newUrl: string): Promise<number>;
   on<Name extends keyof DocumentEngineEvents>(name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): Unsubscribe;
   destroy(): void;
 }

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

@@ -1,21 +1,26 @@
 import { DocumentInfo, FabricDocument } from "../document/document-format.js";
+import { AssetManifest } from "../assets/asset-manifest.js";
+import { AssetOptions, AssetReport, AssetWarning } from "../assets/asset-pipeline.js";
 import { NewDocumentOptions } from "../document/create-document.js";
 import { CustomObjectDefinition } from "../fabric/object-registry.js";
 import { HistoryOptions, HistoryState } from "../history/create-history.js";
+import { AutosaveOptions } from "../save/autosave-scheduler.js";
+import { RetryOptions } from "../save/retry.js";
 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";
 //#region src/engine/create-document-engine.d.ts
-export interface DocumentStorage {
-  loadDocument(id: string): Promise<unknown>;
-  saveDocument(document: FabricDocument): Promise<void>;
-}
 export interface DocumentEngineOptions {
   canvas: StaticCanvas;
   storage?: DocumentStorage;
   customObjects?: CustomObjectDefinition[];
   document?: NewDocumentOptions;
   history?: HistoryOptions;
+  autosave?: boolean | AutosaveOptions;
+  saveRetry?: RetryOptions;
+  assets?: AssetOptions;
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
@@ -26,6 +31,10 @@ export interface DocumentEngineEvents {
   };
   "load:success": {
     document: FabricDocument;
+    warnings: AssetWarning[];
+  };
+  "assets:warning": {
+    warnings: AssetWarning[];
   };
   "load:error": {
     error: DocumentEngineError;
@@ -39,6 +48,8 @@ export interface DocumentEngineEvents {
   "save:error": {
     error: DocumentEngineError;
   };
+  "save:retry": SaveRetryEvent;
+  "save:status": SaveState;
   "history:change": HistoryState;
   "history:error": {
     error: DocumentEngineError;
@@ -52,7 +63,9 @@ export interface DocumentEngine {
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
-  save(): Promise<FabricDocument>;
+  save(options?: SaveOptions): Promise<FabricDocument>;
+  isDirty(): boolean;
+  getSaveState(): SaveState;
   registerObject(definition: CustomObjectDefinition): void;
   transaction<Result>(label: string, work: () => Result): Result;
   commit(label?: string): boolean;
@@ -66,6 +79,9 @@ export interface DocumentEngine {
   };
   clearHistory(): void;
   getObjectById(id: string): FabricObject | undefined;
+  getAssetManifest(): AssetManifest;
+  checkAssets(): Promise<AssetReport>;
+  replaceImage(oldUrl: string, newUrl: string): Promise<number>;
   on<Name extends keyof DocumentEngineEvents>(name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): Unsubscribe;
   destroy(): void;
 }

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

@@ -1,3 +1,7 @@
+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 "../document/document-format.js";
 import { createId } from "../document/ids.js";
 import { createDocumentInfo } from "../document/create-document.js";
@@ -5,20 +9,27 @@ 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 { DocumentEngineError, isDocumentEngineError } from "./errors.js";
 import { createObjectRegistry } from "../fabric/object-registry.js";
 import { createHistory } from "../history/create-history.js";
+import { createSaveController } from "../save/save-controller.js";
 import { createEventEmitter } from "./event-emitter.js";
 //#region src/engine/create-document-engine.ts
+function isReplaceableImage(object) {
+	const candidate = object;
+	return typeof candidate.getSrc === "function" && typeof candidate.setSrc === "function";
+}
 function describeDocumentId(value) {
 	const id = value?.id;
 	return typeof id === "string" ? id : void 0;
 }
 function createDocumentEngine(options) {
 	const { canvas, storage } = options;
+	if (options.autosave && !storage) throw new DocumentEngineError("STORAGE_MISSING", "Autosave needs a storage adapter passed to createDocumentEngine");
 	const registry = createObjectRegistry(options.customObjects);
 	const events = createEventEmitter();
 	const objectsById = /* @__PURE__ */ new Map();
+	const assetOptions = options.assets ?? {};
+	const uploadedUrls = /* @__PURE__ */ new Map();
 	let documentInfo = createDocumentInfo(options.document);
 	let activeLoad = null;
 	let destroyed = false;
@@ -58,7 +69,23 @@ function createDocumentEngine(options) {
 			rebuildIndex();
 			return serializeCanvas(canvas, registry.propertiesToInclude()).objects;
 		},
-		onChange: (state) => events.emit("history:change", state)
+		onChange: (state) => events.emit("history:change", state),
+		onContentChange: () => saving.noteContentChange()
+	});
+	const saving = createSaveController({
+		getStorage: () => requireStorage(),
+		createDocument: async () => {
+			const prepared = await prepareAssetsForSave(toDocument(), assetOptions, uploadedUrls);
+			if (prepared.warnings.length > 0) events.emit("assets:warning", { warnings: prepared.warnings });
+			return prepared.document;
+		},
+		retry: options.saveRetry,
+		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 }),
+		onError: (error) => events.emit("save:error", { error }),
+		onRetry: (event) => events.emit("save:retry", event)
 	});
 	function toDocument() {
 		ensureUsable();
@@ -73,11 +100,13 @@ function createDocumentEngine(options) {
 			id: documentInfo.id,
 			createdAt: documentInfo.createdAt,
 			updatedAt: documentInfo.updatedAt,
+			revision: saving.state().revision,
 			canvas: {
 				width: canvas.getWidth(),
 				height: canvas.getHeight()
 			},
 			objects: serialized.objects,
+			assets: buildAssetManifest(serialized.objects),
 			metadata: { ...documentInfo.metadata }
 		};
 		if (serialized.version !== void 0) document.fabricVersion = serialized.version;
@@ -85,8 +114,8 @@ function createDocumentEngine(options) {
 		return document;
 	}
 	function toLoadError(error, signal) {
-		if (isDocumentEngineError(error)) return error;
 		if (signal.aborted) return new DocumentEngineError("LOAD_ABORTED", "Loading stopped because a newer load started", { cause: error });
+		if (isDocumentEngineError(error)) return error;
 		const reason = error instanceof Error ? error.message : String(error);
 		return new DocumentEngineError("LOAD_FAILED", `Fabric could not load the document: ${reason}`, { cause: error });
 	}
@@ -108,7 +137,9 @@ function createDocumentEngine(options) {
 		activeLoad = controller;
 		events.emit("load:start", { documentId: describeDocumentId(input) });
 		try {
-			const document = checkDocument(input);
+			const checked = checkDocument(input);
+			const { document, warnings } = await prepareAssetsForLoad(checked, assetOptions, controller.signal);
+			if (controller.signal.aborted) throw new Error("aborted");
 			await history.withoutRecording(() => loadIntoCanvas(canvas, {
 				version: document.fabricVersion,
 				background: document.canvas.background,
@@ -127,8 +158,13 @@ function createDocumentEngine(options) {
 			};
 			rebuildIndex();
 			history.reset();
+			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
-			events.emit("load:success", { document });
+			if (warnings.length > 0) events.emit("assets:warning", { warnings });
+			events.emit("load:success", {
+				document,
+				warnings
+			});
 			return document;
 		} catch (error) {
 			const engineError = toLoadError(error, controller.signal);
@@ -150,27 +186,19 @@ function createDocumentEngine(options) {
 			stored = await source.loadDocument(documentId);
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
-			const engineError = new DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
+			const engineError = isDocumentEngineError(error) ? error : new DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
 		return loadDocument(stored, loadOptions);
 	}
-	async function save() {
-		ensureUsable();
-		const target = requireStorage();
-		const document = toDocument();
-		events.emit("save:start", { document });
+	function save(saveOptions) {
 		try {
-			await target.saveDocument(document);
+			ensureUsable();
 		} catch (error) {
-			const reason = error instanceof Error ? error.message : String(error);
-			const engineError = new DocumentEngineError("SAVE_FAILED", `Storage could not save the document: ${reason}`, { cause: error });
-			events.emit("save:error", { error: engineError });
-			throw engineError;
+			return Promise.reject(error);
 		}
-		events.emit("save:success", { document });
-		return document;
+		return saving.save(saveOptions);
 	}
 	function newDocument(newOptions) {
 		ensureUsable();
@@ -178,7 +206,9 @@ function createDocumentEngine(options) {
 		history.withoutRecording(() => canvas.clear());
 		objectsById.clear();
 		documentInfo = createDocumentInfo(newOptions);
+		uploadedUrls.clear();
 		history.reset();
+		saving.startSession(0);
 	}
 	function getObjectById(id) {
 		ensureUsable();
@@ -187,6 +217,30 @@ function createDocumentEngine(options) {
 		rebuildIndex();
 		return objectsById.get(id);
 	}
+	function checkAssets() {
+		ensureUsable();
+		return inspectAssets(toDocument(), assetOptions, new AbortController().signal);
+	}
+	async function replaceImage(oldUrl, newUrl) {
+		ensureUsable();
+		const images = [];
+		walkObjects(canvas.getObjects(), (object) => {
+			if (isReplaceableImage(object) && isSameUrl(object.getSrc(), oldUrl)) images.push(object);
+		});
+		if (images.length === 0) return 0;
+		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 });
+			image.set({
+				scaleX: displayedWidth / image.width,
+				scaleY: displayedHeight / image.height
+			});
+			image.setCoords();
+		})));
+		canvas.requestRenderAll();
+		return images.length;
+	}
 	async function travelThroughHistory(direction) {
 		ensureUsable();
 		try {
@@ -203,6 +257,7 @@ function createDocumentEngine(options) {
 		destroyed = true;
 		activeLoad?.abort();
 		history.destroy();
+		saving.destroy();
 		canvas.off("object:added", handleObjectAdded);
 		canvas.off("object:removed", handleObjectRemoved);
 		objectsById.clear();
@@ -223,17 +278,26 @@ function createDocumentEngine(options) {
 					...changes
 				}
 			};
+			saving.noteContentChange();
 		},
 		newDocument,
 		toDocument,
 		loadDocument,
 		load,
 		save,
+		isDirty: () => saving.state().isDirty,
+		getSaveState: () => saving.state(),
 		registerObject(definition) {
 			ensureUsable();
 			registry.register(definition);
 		},
 		getObjectById,
+		getAssetManifest: () => toDocument().assets ?? {
+			images: [],
+			fonts: []
+		},
+		checkAssets,
+		replaceImage,
 		transaction(label, work) {
 			ensureUsable();
 			return history.transaction(label, work);

package/dist/engine/errors.cjs

@@ -6,12 +6,19 @@ var DocumentEngineError = class extends Error {
 		this.code = code;
 		this.issues = details.issues ?? [];
 		this.unknownTypes = details.unknownTypes ?? [];
+		this.missingAssets = details.missingAssets ?? [];
+		this.missingFonts = details.missingFonts ?? [];
 		this.cause = details.cause;
+		this.retryable = details.retryable ?? false;
 	}
 };
 function isDocumentEngineError(value) {
 	return value instanceof DocumentEngineError;
 }
+function createConflictError(documentId, expectedRevision, actualRevision) {
+	return new DocumentEngineError("SAVE_CONFLICT", `Document "${documentId}" was saved somewhere else: expected revision ${expectedRevision} but storage has ${actualRevision}`);
+}
 //#endregion
 exports.DocumentEngineError = DocumentEngineError;
+exports.createConflictError = createConflictError;
 exports.isDocumentEngineError = isDocumentEngineError;

package/dist/engine/errors.d.cts

@@ -1,5 +1,6 @@
+import { FontAsset, ImageAsset } from "../assets/asset-manifest.cjs";
 //#region src/engine/errors.d.ts
-export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "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" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -8,14 +9,21 @@ export interface DocumentIssue {
 export interface DocumentEngineErrorDetails {
   issues?: DocumentIssue[];
   unknownTypes?: string[];
+  missingAssets?: ImageAsset[];
+  missingFonts?: FontAsset[];
   cause?: unknown;
+  retryable?: boolean;
 }
 export declare class DocumentEngineError extends Error {
   readonly code: DocumentErrorCode;
   readonly issues: DocumentIssue[];
   readonly unknownTypes: string[];
+  readonly missingAssets: ImageAsset[];
+  readonly missingFonts: FontAsset[];
   readonly cause: unknown;
+  readonly retryable: boolean;
   constructor(code: DocumentErrorCode, message: string, details?: DocumentEngineErrorDetails);
 }
 export declare function isDocumentEngineError(value: unknown): value is DocumentEngineError;
+export declare function createConflictError(documentId: string, expectedRevision: number, actualRevision: number): DocumentEngineError;
 //#endregion

package/dist/engine/errors.d.ts

@@ -1,5 +1,6 @@
+import { FontAsset, ImageAsset } from "../assets/asset-manifest.js";
 //#region src/engine/errors.d.ts
-export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "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" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -8,14 +9,21 @@ export interface DocumentIssue {
 export interface DocumentEngineErrorDetails {
   issues?: DocumentIssue[];
   unknownTypes?: string[];
+  missingAssets?: ImageAsset[];
+  missingFonts?: FontAsset[];
   cause?: unknown;
+  retryable?: boolean;
 }
 export declare class DocumentEngineError extends Error {
   readonly code: DocumentErrorCode;
   readonly issues: DocumentIssue[];
   readonly unknownTypes: string[];
+  readonly missingAssets: ImageAsset[];
+  readonly missingFonts: FontAsset[];
   readonly cause: unknown;
+  readonly retryable: boolean;
   constructor(code: DocumentErrorCode, message: string, details?: DocumentEngineErrorDetails);
 }
 export declare function isDocumentEngineError(value: unknown): value is DocumentEngineError;
+export declare function createConflictError(documentId: string, expectedRevision: number, actualRevision: number): DocumentEngineError;
 //#endregion

package/dist/engine/errors.js

@@ -6,11 +6,17 @@ var DocumentEngineError = class extends Error {
 		this.code = code;
 		this.issues = details.issues ?? [];
 		this.unknownTypes = details.unknownTypes ?? [];
+		this.missingAssets = details.missingAssets ?? [];
+		this.missingFonts = details.missingFonts ?? [];
 		this.cause = details.cause;
+		this.retryable = details.retryable ?? false;
 	}
 };
 function isDocumentEngineError(value) {
 	return value instanceof DocumentEngineError;
 }
+function createConflictError(documentId, expectedRevision, actualRevision) {
+	return new DocumentEngineError("SAVE_CONFLICT", `Document "${documentId}" was saved somewhere else: expected revision ${expectedRevision} but storage has ${actualRevision}`);
+}
 //#endregion
-export { DocumentEngineError, isDocumentEngineError };
+export { DocumentEngineError, createConflictError, isDocumentEngineError };