fabricjs-document-engine 1.1.0 → 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");
@@ -38,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");
 	}
@@ -67,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(),
@@ -116,6 +147,7 @@ function createDocumentEngine(options) {
 		}
 	}) : void 0;
 	function noteContentChange() {
+		mutations += 1;
 		saving.noteContentChange();
 		recovery?.schedule();
 	}
@@ -138,11 +170,14 @@ 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, controller) {
@@ -161,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;
 	}
@@ -199,6 +234,7 @@ function createDocumentEngine(options) {
 		ensureUsable();
 		protectUnsavedChanges(loadOptions.discardUnsavedChanges);
 		const controller = startedLoad ?? startLoad(loadOptions.signal);
+		const mutationsAtStart = mutations;
 		const documentId = describeDocumentId(input);
 		const report = (stage, done, total) => {
 			if (controller.signal.aborted) return;
@@ -228,11 +264,15 @@ function createDocumentEngine(options) {
 			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
 			}, {
 				signal: controller.signal,
-				onObjects: (done, total) => report("objects", done, total)
+				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({
@@ -285,10 +325,37 @@ 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);
-		ensureUsable();
+		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();
@@ -408,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();
@@ -434,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
@@ -486,14 +556,31 @@ function createDocumentEngine(options) {
 			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(require_render_export.renderSvg(canvas, area, settings.scale, settings.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)
 				};
 			});
 			let blob;
 			if (format === "svg") {
-				const embedded = await require_embed_assets.embedSvgAssets(await rendered.content, canvas, settings.svg, settings.signal, options.limits?.isAllowedUrl ?? require_content_limits.isSafeImageUrl);
+				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) => ({
@@ -555,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;
@@ -581,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();
 	}
@@ -594,7 +686,8 @@ function createDocumentEngine(options) {
 		canvas,
 		getDocumentInfo: () => ({
 			...documentInfo,
-			metadata: { ...documentInfo.metadata }
+			metadata: { ...documentInfo.metadata },
+			session
 		}),
 		updateMetadata(changes) {
 			ensureUsable();
@@ -635,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

@@ -7,7 +7,7 @@ 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 { 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";
@@ -16,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;
@@ -51,6 +51,23 @@ export interface LoadProgress {
   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;
 }
@@ -147,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>;
@@ -166,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

@@ -7,7 +7,7 @@ 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 { 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";
@@ -16,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;
@@ -51,6 +51,23 @@ export interface LoadProgress {
   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;
 }
@@ -147,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>;
@@ -166,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;