fabricjs-document-engine 0.2.0 → 0.3.0

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,12 +9,15 @@ 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;
@@ -21,6 +28,8 @@ function createDocumentEngine(options) {
 	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;
@@ -65,7 +74,11 @@ function createDocumentEngine(options) {
 	});
 	const saving = createSaveController({
 		getStorage: () => requireStorage(),
-		createDocument: () => toDocument(),
+		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),
@@ -93,6 +106,7 @@ function createDocumentEngine(options) {
 				height: canvas.getHeight()
 			},
 			objects: serialized.objects,
+			assets: buildAssetManifest(serialized.objects),
 			metadata: { ...documentInfo.metadata }
 		};
 		if (serialized.version !== void 0) document.fabricVersion = serialized.version;
@@ -100,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 });
 	}
@@ -123,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,
@@ -144,7 +160,11 @@ function createDocumentEngine(options) {
 			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);
@@ -186,6 +206,7 @@ function createDocumentEngine(options) {
 		history.withoutRecording(() => canvas.clear());
 		objectsById.clear();
 		documentInfo = createDocumentInfo(newOptions);
+		uploadedUrls.clear();
 		history.reset();
 		saving.startSession(0);
 	}
@@ -196,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 {
@@ -247,6 +292,12 @@ function createDocumentEngine(options) {
 			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,6 +6,8 @@ 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;
 	}

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" | "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" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -8,6 +9,8 @@ export interface DocumentIssue {
 export interface DocumentEngineErrorDetails {
   issues?: DocumentIssue[];
   unknownTypes?: string[];
+  missingAssets?: ImageAsset[];
+  missingFonts?: FontAsset[];
   cause?: unknown;
   retryable?: boolean;
 }
@@ -15,6 +18,8 @@ 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);

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" | "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" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -8,6 +9,8 @@ export interface DocumentIssue {
 export interface DocumentEngineErrorDetails {
   issues?: DocumentIssue[];
   unknownTypes?: string[];
+  missingAssets?: ImageAsset[];
+  missingFonts?: FontAsset[];
   cause?: unknown;
   retryable?: boolean;
 }
@@ -15,6 +18,8 @@ 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);

package/dist/engine/errors.js

@@ -6,6 +6,8 @@ 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;
 	}

package/dist/index.cjs

@@ -1,7 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("./engine/errors.cjs");
 const require_document_format = require("./document/document-format.cjs");
 const require_validate_document = require("./document/validate-document.cjs");
-const require_errors = require("./engine/errors.cjs");
 const require_create_document_engine = require("./engine/create-document-engine.cjs");
 const require_keyboard_shortcuts = require("./history/keyboard-shortcuts.cjs");
 const require_unsaved_changes_warning = require("./save/unsaved-changes-warning.cjs");

package/dist/index.d.cts

@@ -1,4 +1,7 @@
 import { CURRENT_SCHEMA_VERSION, DocumentCanvas, DocumentInfo, FabricDocument, SerializedFabricObject } from "./document/document-format.cjs";
+import { AssetManifest, FontAsset, ImageAsset } from "./assets/asset-manifest.cjs";
+import { FontLoader } from "./assets/font-check.cjs";
+import { AssetOptions, AssetReport, AssetWarning, AssetWarningCode, UploadRequest } 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";
@@ -12,4 +15,4 @@ import { DocumentEngine, DocumentEngineEvents, DocumentEngineOptions, LoadOption
 import { validateDocument } from "./document/validate-document.cjs";
 import { KeyboardShortcutOptions, UndoRedoTarget, bindKeyboardShortcuts } from "./history/keyboard-shortcuts.cjs";
 import { UnsavedChangesSource, bindUnsavedChangesWarning } from "./save/unsaved-changes-warning.cjs";
-export { type AutosaveOptions, CURRENT_SCHEMA_VERSION, type CustomObjectDefinition, type DocumentCanvas, type DocumentEngine, DocumentEngineError, type DocumentEngineErrorDetails, type DocumentEngineEvents, type DocumentEngineOptions, type DocumentErrorCode, type DocumentInfo, type DocumentIssue, type DocumentStorage, type FabricDocument, type HistoryOptions, type HistoryState, type KeyboardShortcutOptions, type LoadOptions, type NewDocumentOptions, type RetryOptions, type SaveContext, type SaveOptions, type SaveResult, type SaveRetryEvent, type SaveState, type SaveStatus, type SerializedFabricObject, type UndoRedoTarget, type UnsavedChangesSource, type Unsubscribe, bindKeyboardShortcuts, bindUnsavedChangesWarning, createConflictError, createDocumentEngine, isDocumentEngineError, validateDocument };
+export { type AssetManifest, type AssetOptions, type AssetReport, type AssetWarning, type AssetWarningCode, type AutosaveOptions, CURRENT_SCHEMA_VERSION, type CustomObjectDefinition, type DocumentCanvas, type DocumentEngine, DocumentEngineError, type DocumentEngineErrorDetails, type DocumentEngineEvents, type DocumentEngineOptions, type DocumentErrorCode, type DocumentInfo, type DocumentIssue, type DocumentStorage, type FabricDocument, type FontAsset, type FontLoader, type HistoryOptions, type HistoryState, type ImageAsset, type KeyboardShortcutOptions, type LoadOptions, type NewDocumentOptions, type RetryOptions, type SaveContext, type SaveOptions, type SaveResult, type SaveRetryEvent, type SaveState, type SaveStatus, type SerializedFabricObject, type UndoRedoTarget, type UnsavedChangesSource, type Unsubscribe, type UploadRequest, bindKeyboardShortcuts, bindUnsavedChangesWarning, createConflictError, createDocumentEngine, isDocumentEngineError, validateDocument };

package/dist/index.d.ts

@@ -1,4 +1,7 @@
 import { CURRENT_SCHEMA_VERSION, DocumentCanvas, DocumentInfo, FabricDocument, SerializedFabricObject } from "./document/document-format.js";
+import { AssetManifest, FontAsset, ImageAsset } from "./assets/asset-manifest.js";
+import { FontLoader } from "./assets/font-check.js";
+import { AssetOptions, AssetReport, AssetWarning, AssetWarningCode, UploadRequest } 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";
@@ -12,4 +15,4 @@ import { DocumentEngine, DocumentEngineEvents, DocumentEngineOptions, LoadOption
 import { validateDocument } from "./document/validate-document.js";
 import { KeyboardShortcutOptions, UndoRedoTarget, bindKeyboardShortcuts } from "./history/keyboard-shortcuts.js";
 import { UnsavedChangesSource, bindUnsavedChangesWarning } from "./save/unsaved-changes-warning.js";
-export { type AutosaveOptions, CURRENT_SCHEMA_VERSION, type CustomObjectDefinition, type DocumentCanvas, type DocumentEngine, DocumentEngineError, type DocumentEngineErrorDetails, type DocumentEngineEvents, type DocumentEngineOptions, type DocumentErrorCode, type DocumentInfo, type DocumentIssue, type DocumentStorage, type FabricDocument, type HistoryOptions, type HistoryState, type KeyboardShortcutOptions, type LoadOptions, type NewDocumentOptions, type RetryOptions, type SaveContext, type SaveOptions, type SaveResult, type SaveRetryEvent, type SaveState, type SaveStatus, type SerializedFabricObject, type UndoRedoTarget, type UnsavedChangesSource, type Unsubscribe, bindKeyboardShortcuts, bindUnsavedChangesWarning, createConflictError, createDocumentEngine, isDocumentEngineError, validateDocument };
+export { type AssetManifest, type AssetOptions, type AssetReport, type AssetWarning, type AssetWarningCode, type AutosaveOptions, CURRENT_SCHEMA_VERSION, type CustomObjectDefinition, type DocumentCanvas, type DocumentEngine, DocumentEngineError, type DocumentEngineErrorDetails, type DocumentEngineEvents, type DocumentEngineOptions, type DocumentErrorCode, type DocumentInfo, type DocumentIssue, type DocumentStorage, type FabricDocument, type FontAsset, type FontLoader, type HistoryOptions, type HistoryState, type ImageAsset, type KeyboardShortcutOptions, type LoadOptions, type NewDocumentOptions, type RetryOptions, type SaveContext, type SaveOptions, type SaveResult, type SaveRetryEvent, type SaveState, type SaveStatus, type SerializedFabricObject, type UndoRedoTarget, type UnsavedChangesSource, type Unsubscribe, type UploadRequest, bindKeyboardShortcuts, bindUnsavedChangesWarning, createConflictError, createDocumentEngine, isDocumentEngineError, validateDocument };

package/dist/index.js

@@ -1,6 +1,6 @@
+import { DocumentEngineError, createConflictError, isDocumentEngineError } from "./engine/errors.js";
 import { CURRENT_SCHEMA_VERSION } from "./document/document-format.js";
 import { validateDocument } from "./document/validate-document.js";
-import { DocumentEngineError, createConflictError, isDocumentEngineError } from "./engine/errors.js";
 import { createDocumentEngine } from "./engine/create-document-engine.js";
 import { bindKeyboardShortcuts } from "./history/keyboard-shortcuts.js";
 import { bindUnsavedChangesWarning } from "./save/unsaved-changes-warning.js";

package/dist/save/save-controller.cjs

@@ -68,16 +68,17 @@ function createSaveController(options) {
 		const sessionAtStart = session;
 		const { signal } = sessionAbort;
 		const versionAtSnapshot = contentVersion;
-		const document = {
-			...options.createDocument(),
-			revision: revision + 1
-		};
 		const expectedRevision = saveOptions.overwrite === true ? null : revision;
+		const creating = options.createDocument();
 		saving = true;
 		lastError = void 0;
 		publish();
-		options.onStart(document);
 		try {
+			const document = {
+				...await creating,
+				revision: revision + 1
+			};
+			options.onStart(document);
 			const result = await sendWithRetries(storage, document, expectedRevision, signal);
 			if (sessionAtStart !== session) return document;
 			revision = result?.revision ?? document.revision;

package/dist/save/save-controller.js

@@ -68,16 +68,17 @@ function createSaveController(options) {
 		const sessionAtStart = session;
 		const { signal } = sessionAbort;
 		const versionAtSnapshot = contentVersion;
-		const document = {
-			...options.createDocument(),
-			revision: revision + 1
-		};
 		const expectedRevision = saveOptions.overwrite === true ? null : revision;
+		const creating = options.createDocument();
 		saving = true;
 		lastError = void 0;
 		publish();
-		options.onStart(document);
 		try {
+			const document = {
+				...await creating,
+				revision: revision + 1
+			};
+			options.onStart(document);
 			const result = await sendWithRetries(storage, document, expectedRevision, signal);
 			if (sessionAtStart !== session) return document;
 			revision = result?.revision ?? document.revision;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fabricjs-document-engine",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Turn an existing Fabric.js canvas into a dependable editable document: stable object ids, versioned save and load, undo and redo, safe autosave with conflict protection, custom objects and clear errors.",
   "keywords": [
     "fabric",