fabricjs-document-engine 0.3.0 → 0.4.0

package/README.md

@@ -11,6 +11,7 @@ Fabric already draws objects, handles interaction and serializes to JSON. This p
 - **Safe saving.** It tracks unsaved changes and can autosave. Only one save runs at a time, so a slow older save can never overwrite newer work. Revision checks catch another tab or device saving the same document, and failed saves are retried with backoff.
 - **Your storage.** Plug in any backend with two functions, or use the built-in memory and localStorage adapters. No hosted service is needed.
 - **Assets and fonts.** Documents record the images and fonts they need. When a document is opened, every image and font is checked first. You get the exact list of what is missing, can offer replacements, and tab-only images are uploaded when you save.
+- **Recovery.** Unsaved work is copied to IndexedDB while the user edits, and again at the moment the tab is closed or refreshed. After a crash or refresh you can offer to restore it, including images that only existed in the old tab.
 - **Reliable undo and redo.** One user action is one undo step. Transactions group several code changes into one labelled step, and ids survive undo and redo.
 - **Fabric 6 and 7.** Every release is tested against both.
 
@@ -175,6 +176,34 @@ await engine.replaceImage('/old-logo.png', '/new-logo.png');
 
 `replaceImage` swaps every image that uses a URL. Each image keeps its size on the page, and the change is one undo step. `engine.getAssetManifest()` returns the manifest for the current canvas.
 
+## Recovery
+
+```ts
+import { createIndexedDbRecovery } from 'fabricjs-document-engine/recovery';
+
+const engine = createDocumentEngine({
+  canvas,
+  storage,
+  recovery: { store: createIndexedDbRecovery(), interval: 2000 },
+});
+
+const [latest] = await engine.getRecoverableDocuments();
+if (latest && confirm(`Restore unsaved work from ${new Date(latest.savedAt).toLocaleString()}?`)) {
+  await engine.restoreRecovery(latest.documentId);
+} else if (latest) {
+  await engine.discardRecovery(latest.documentId);
+}
+```
+
+- **Checkpoints.** While there are unsaved changes, a copy is written at most once every `interval` ms (default 2000). Nothing is written while the document is saved.
+- **Closing or refreshing.** Browsers do not let IndexedDB finish writing while a page unloads. So when the tab is hidden or closed, the engine also writes an immediate copy to localStorage. The newest copy wins when you read it back.
+- **Tab-only images.** Images with `blob:` URLs vanish on refresh. Checkpoints keep the image data, and restoring creates fresh URLs for it.
+- **After a save.** When a save covers every change, the copy is removed. If the tab closes during a save, the copy stays, so work is never lost between the edit and the server.
+- **Restoring.** The restored document is marked as unsaved and keeps the revision it was based on. If the server moved on meanwhile, the next save reports `SAVE_CONFLICT` instead of overwriting newer work.
+- **Interrupted loads.** A marker is kept while a document loads. If the tab crashes during loading, `engine.getInterruptedLoad()` returns `{ documentId, startedAt }` on the next start, so you can skip or discard that document instead of crashing again.
+- `engine.flushRecovery()` writes a copy right now. `engine.getRecovery(id?)` reads one.
+- `createMemoryRecovery()` keeps copies in memory, which is useful for tests. To use your own storage, implement `{ get, set, delete, keys }`, plus an optional synchronous `setNow` for the moment the page closes.
+
 ## Custom objects
 
 ```ts
@@ -282,6 +311,10 @@ Keep project data such as titles, owners and tags in `metadata` with `engine.upd
 | `engine.getAssetManifest()` | Lists the images and fonts used on the canvas. |
 | `engine.checkAssets()` | Resolves to `{ manifest, missingImages, unavailableFonts, warnings }` for the current canvas. |
 | `engine.replaceImage(oldUrl, newUrl)` | Replaces every image with that URL as one undo step. Resolves to the number of images replaced. |
+| `engine.getRecoverableDocuments()` | Lists recovery copies, newest first. |
+| `engine.restoreRecovery(id?)` / `engine.discardRecovery(id?)` | Loads or deletes a recovery copy. The default is the current document. |
+| `engine.getRecovery(id?)` / `engine.flushRecovery()` | Reads a copy, or writes one now. |
+| `engine.getInterruptedLoad()` | Returns the load that was running when the tab last crashed, if any. |
 | `engine.transaction(label, work)` | Runs `work` and records everything it changed as one undo step. Returns what `work` returns. |
 | `engine.commit(label?)` | Records changes made since the last step. Returns `false` when nothing changed. |
 | `engine.undo()` / `engine.redo()` | Resolves to `true` when a step was applied. Calls run one after another. |
@@ -289,7 +322,7 @@ Keep project data such as titles, owners and tags in `metadata` with `engine.upd
 | `engine.getHistory()` | Returns `{ undo, redo }` label lists, newest first. |
 | `engine.clearHistory()` | Forgets all steps. Loading a document or starting a new one also does this. |
 | `bindKeyboardShortcuts(engine, { target? })` | Adds the undo and redo shortcuts. Returns an unbind function. |
-| `engine.on(event, handler)` | Listens to `load:start`, `load:success`, `load:error`, `save:start`, `save:success`, `save:error`, `save:retry`, `save:status`, `assets:warning`, `history:change` or `history:error`. Returns an unsubscribe function. |
+| `engine.on(event, handler)` | Listens to `load:start`, `load:success`, `load:error`, `save:start`, `save:success`, `save:error`, `save:retry`, `save:status`, `assets:warning`, `recovery:checkpoint`, `recovery:restored`, `recovery:error`, `history:change` or `history:error`. Returns an unsubscribe function. |
 | `engine.destroy()` | Stops listening to the canvas and cancels a running load. |
 | `validateDocument(value)` | Returns a list of issues with the exact path of each problem. |
 
@@ -312,6 +345,9 @@ Every failure is a `DocumentEngineError` with a `code` you can switch on:
 | `SAVE_CANCELLED` | A queued save was dropped because another document was opened. |
 | `DOCUMENT_NOT_FOUND` | The built-in adapters have no document with that id. |
 | `HISTORY_FAILED` | Undo or redo could not rebuild an object, for example because an image is gone. The step is kept and the canvas is unchanged. |
+| `RECOVERY_MISSING` | A recovery method was called without `recovery: { store }`. |
+| `RECOVERY_NOT_FOUND` | There is no recovery copy for that document. |
+| `RECOVERY_FAILED` | Writing a recovery copy failed, for example because storage is full. It is delivered as a `recovery:error` event and never interrupts editing. |
 | `STORAGE_MISSING` | `load` or `save` was called without a storage adapter. |
 | `INVALID_CUSTOM_OBJECT` | A registered class has no static `type`, or it does not extend a Fabric class. |
 | `ENGINE_DESTROYED` | The engine was used after `destroy()`. |
@@ -326,7 +362,7 @@ A failed load never clears or half-fills your canvas.
 | 2 | Undo and redo with transactions | 0.1.0 |
 | 3 | Safe saving: dirty state, autosave, stale-response protection | 0.2.0 |
 | 4 | Assets and fonts | 0.3.0 |
-| 5 | Recovery after a refresh or crash | |
+| 5 | Recovery after a refresh or crash | 0.4.0 |
 | 6 | PNG, JPEG, SVG and JSON export with preflight checks | |
 | 7 | Named versions and schema migrations | |
 | 8 | React adapter and examples | |

package/dist/assets/asset-pipeline.cjs

@@ -172,3 +172,4 @@ async function prepareAssetsForSave(document, options, uploadedUrls) {
 exports.inspectAssets = inspectAssets;
 exports.prepareAssetsForLoad = prepareAssetsForLoad;
 exports.prepareAssetsForSave = prepareAssetsForSave;
+exports.rewriteUrls = rewriteUrls;

package/dist/assets/asset-pipeline.js

@@ -169,4 +169,4 @@ async function prepareAssetsForSave(document, options, uploadedUrls) {
 	};
 }
 //#endregion
-export { inspectAssets, prepareAssetsForLoad, prepareAssetsForSave };
+export { inspectAssets, prepareAssetsForLoad, prepareAssetsForSave, rewriteUrls };

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

@@ -11,6 +11,7 @@ const require_fabric_adapter = require("../fabric/fabric-adapter.cjs");
 const require_object_ids = require("../fabric/object-ids.cjs");
 const require_object_registry = require("../fabric/object-registry.cjs");
 const require_create_history = require("../history/create-history.cjs");
+const require_recovery_controller = require("../recovery/recovery-controller.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
@@ -70,7 +71,7 @@ function createDocumentEngine(options) {
 			return require_fabric_adapter.serializeCanvas(canvas, registry.propertiesToInclude()).objects;
 		},
 		onChange: (state) => events.emit("history:change", state),
-		onContentChange: () => saving.noteContentChange()
+		onContentChange: () => noteContentChange()
 	});
 	const saving = require_save_controller.createSaveController({
 		getStorage: () => requireStorage(),
@@ -83,10 +84,30 @@ function createDocumentEngine(options) {
 		autosave: options.autosave === true ? {} : options.autosave ?? false,
 		onStateChange: (state) => events.emit("save:status", state),
 		onStart: (document) => events.emit("save:start", { document }),
-		onSuccess: (document) => events.emit("save:success", { document }),
+		onSuccess: (document) => {
+			if (recovery && !saving.state().isDirty) recovery.remove(document.id);
+			events.emit("save:success", { document });
+		},
 		onError: (error) => events.emit("save:error", { error }),
 		onRetry: (event) => events.emit("save:retry", event)
 	});
+	const recovery = options.recovery ? require_recovery_controller.createRecoveryController({
+		...options.recovery,
+		createDocument: () => toDocument(),
+		shouldWrite: () => !destroyed && saving.state().isDirty,
+		onCheckpoint: (record) => events.emit("recovery:checkpoint", {
+			documentId: record.documentId,
+			savedAt: record.savedAt
+		}),
+		onError: (error) => {
+			const reason = error instanceof Error ? error.message : String(error);
+			events.emit("recovery:error", { error: new require_errors.DocumentEngineError("RECOVERY_FAILED", `Could not write the recovery copy: ${reason}`, { cause: error }) });
+		}
+	}) : void 0;
+	function noteContentChange() {
+		saving.noteContentChange();
+		recovery?.schedule();
+	}
 	function toDocument() {
 		ensureUsable();
 		rebuildIndex();
@@ -135,8 +156,11 @@ function createDocumentEngine(options) {
 		activeLoad?.abort();
 		const controller = new AbortController();
 		activeLoad = controller;
-		events.emit("load:start", { documentId: describeDocumentId(input) });
+		const documentId = describeDocumentId(input);
+		events.emit("load:start", { documentId });
 		try {
+			await recovery?.markLoadStarted(documentId);
+			if (controller.signal.aborted) throw new Error("aborted");
 			const checked = checkDocument(input);
 			const { document, warnings } = await require_asset_pipeline.prepareAssetsForLoad(checked, assetOptions, controller.signal);
 			if (controller.signal.aborted) throw new Error("aborted");
@@ -158,6 +182,7 @@ function createDocumentEngine(options) {
 			};
 			rebuildIndex();
 			history.reset();
+			recovery?.cancel();
 			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
 			if (warnings.length > 0) events.emit("assets:warning", { warnings });
@@ -171,7 +196,10 @@ function createDocumentEngine(options) {
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		} finally {
-			if (activeLoad === controller) activeLoad = null;
+			if (activeLoad === controller) {
+				activeLoad = null;
+				await recovery?.markLoadFinished();
+			}
 		}
 	}
 	function requireStorage() {
@@ -208,6 +236,7 @@ function createDocumentEngine(options) {
 		documentInfo = require_create_document.createDocumentInfo(newOptions);
 		uploadedUrls.clear();
 		history.reset();
+		recovery?.cancel();
 		saving.startSession(0);
 	}
 	function getObjectById(id) {
@@ -241,6 +270,21 @@ function createDocumentEngine(options) {
 		canvas.requestRenderAll();
 		return images.length;
 	}
+	function requireRecovery() {
+		ensureUsable();
+		if (!recovery) throw new require_errors.DocumentEngineError("RECOVERY_MISSING", "Pass recovery: { store } to createDocumentEngine to use recovery");
+		return recovery;
+	}
+	async function restoreRecovery(documentId, loadOptions) {
+		const source = requireRecovery();
+		const id = documentId ?? documentInfo.id;
+		const record = await source.read(id);
+		if (!record) throw new 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);
+		noteContentChange();
+		events.emit("recovery:restored", { document: loaded });
+		return loaded;
+	}
 	async function travelThroughHistory(direction) {
 		ensureUsable();
 		try {
@@ -258,6 +302,7 @@ function createDocumentEngine(options) {
 		activeLoad?.abort();
 		history.destroy();
 		saving.destroy();
+		recovery?.destroy();
 		canvas.off("object:added", handleObjectAdded);
 		canvas.off("object:removed", handleObjectRemoved);
 		objectsById.clear();
@@ -278,7 +323,7 @@ function createDocumentEngine(options) {
 					...changes
 				}
 			};
-			saving.noteContentChange();
+			noteContentChange();
 		},
 		newDocument,
 		toDocument,
@@ -298,6 +343,12 @@ function createDocumentEngine(options) {
 		},
 		checkAssets,
 		replaceImage,
+		flushRecovery: async () => requireRecovery().flush(),
+		getRecoverableDocuments: async () => requireRecovery().list(),
+		getRecovery: async (documentId) => requireRecovery().read(documentId ?? documentInfo.id),
+		restoreRecovery,
+		discardRecovery: async (documentId) => requireRecovery().remove(documentId ?? documentInfo.id),
+		getInterruptedLoad: async () => requireRecovery().interruptedLoad(),
 		transaction(label, work) {
 			ensureUsable();
 			return history.transaction(label, work);

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

@@ -4,6 +4,7 @@ import { AssetOptions, AssetReport, AssetWarning } from "../assets/asset-pipelin
 import { NewDocumentOptions } from "../document/create-document.cjs";
 import { CustomObjectDefinition } from "../fabric/object-registry.cjs";
 import { HistoryOptions, HistoryState } from "../history/create-history.cjs";
+import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "../recovery/recovery-controller.cjs";
 import { AutosaveOptions } from "../save/autosave-scheduler.cjs";
 import { RetryOptions } from "../save/retry.cjs";
 import { DocumentEngineError } from "./errors.cjs";
@@ -21,6 +22,7 @@ export interface DocumentEngineOptions {
   autosave?: boolean | AutosaveOptions;
   saveRetry?: RetryOptions;
   assets?: AssetOptions;
+  recovery?: RecoveryOptions;
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
@@ -54,6 +56,16 @@ export interface DocumentEngineEvents {
   "history:error": {
     error: DocumentEngineError;
   };
+  "recovery:checkpoint": {
+    documentId: string;
+    savedAt: string;
+  };
+  "recovery:restored": {
+    document: FabricDocument;
+  };
+  "recovery:error": {
+    error: DocumentEngineError;
+  };
 }
 export interface DocumentEngine {
   readonly canvas: StaticCanvas;
@@ -82,6 +94,12 @@ export interface DocumentEngine {
   getAssetManifest(): AssetManifest;
   checkAssets(): Promise<AssetReport>;
   replaceImage(oldUrl: string, newUrl: string): Promise<number>;
+  flushRecovery(): Promise<void>;
+  getRecoverableDocuments(): Promise<RecoveryRecord[]>;
+  getRecovery(documentId?: string): Promise<RecoveryRecord | undefined>;
+  restoreRecovery(documentId?: string, options?: LoadOptions): Promise<FabricDocument>;
+  discardRecovery(documentId?: 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

@@ -4,6 +4,7 @@ import { AssetOptions, AssetReport, AssetWarning } from "../assets/asset-pipelin
 import { NewDocumentOptions } from "../document/create-document.js";
 import { CustomObjectDefinition } from "../fabric/object-registry.js";
 import { HistoryOptions, HistoryState } from "../history/create-history.js";
+import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "../recovery/recovery-controller.js";
 import { AutosaveOptions } from "../save/autosave-scheduler.js";
 import { RetryOptions } from "../save/retry.js";
 import { DocumentEngineError } from "./errors.js";
@@ -21,6 +22,7 @@ export interface DocumentEngineOptions {
   autosave?: boolean | AutosaveOptions;
   saveRetry?: RetryOptions;
   assets?: AssetOptions;
+  recovery?: RecoveryOptions;
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
@@ -54,6 +56,16 @@ export interface DocumentEngineEvents {
   "history:error": {
     error: DocumentEngineError;
   };
+  "recovery:checkpoint": {
+    documentId: string;
+    savedAt: string;
+  };
+  "recovery:restored": {
+    document: FabricDocument;
+  };
+  "recovery:error": {
+    error: DocumentEngineError;
+  };
 }
 export interface DocumentEngine {
   readonly canvas: StaticCanvas;
@@ -82,6 +94,12 @@ export interface DocumentEngine {
   getAssetManifest(): AssetManifest;
   checkAssets(): Promise<AssetReport>;
   replaceImage(oldUrl: string, newUrl: string): Promise<number>;
+  flushRecovery(): Promise<void>;
+  getRecoverableDocuments(): Promise<RecoveryRecord[]>;
+  getRecovery(documentId?: string): Promise<RecoveryRecord | undefined>;
+  restoreRecovery(documentId?: string, options?: LoadOptions): Promise<FabricDocument>;
+  discardRecovery(documentId?: 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.js

@@ -11,6 +11,7 @@ import { loadIntoCanvas, serializeCanvas } from "../fabric/fabric-adapter.js";
 import { readObjectId, writeObjectId } from "../fabric/object-ids.js";
 import { createObjectRegistry } from "../fabric/object-registry.js";
 import { createHistory } from "../history/create-history.js";
+import { createRecoveryController, restoreRecordedFiles } from "../recovery/recovery-controller.js";
 import { createSaveController } from "../save/save-controller.js";
 import { createEventEmitter } from "./event-emitter.js";
 //#region src/engine/create-document-engine.ts
@@ -70,7 +71,7 @@ function createDocumentEngine(options) {
 			return serializeCanvas(canvas, registry.propertiesToInclude()).objects;
 		},
 		onChange: (state) => events.emit("history:change", state),
-		onContentChange: () => saving.noteContentChange()
+		onContentChange: () => noteContentChange()
 	});
 	const saving = createSaveController({
 		getStorage: () => requireStorage(),
@@ -83,10 +84,30 @@ function createDocumentEngine(options) {
 		autosave: options.autosave === true ? {} : options.autosave ?? false,
 		onStateChange: (state) => events.emit("save:status", state),
 		onStart: (document) => events.emit("save:start", { document }),
-		onSuccess: (document) => events.emit("save:success", { document }),
+		onSuccess: (document) => {
+			if (recovery && !saving.state().isDirty) recovery.remove(document.id);
+			events.emit("save:success", { document });
+		},
 		onError: (error) => events.emit("save:error", { error }),
 		onRetry: (event) => events.emit("save:retry", event)
 	});
+	const recovery = options.recovery ? createRecoveryController({
+		...options.recovery,
+		createDocument: () => toDocument(),
+		shouldWrite: () => !destroyed && saving.state().isDirty,
+		onCheckpoint: (record) => events.emit("recovery:checkpoint", {
+			documentId: record.documentId,
+			savedAt: record.savedAt
+		}),
+		onError: (error) => {
+			const reason = error instanceof Error ? error.message : String(error);
+			events.emit("recovery:error", { error: new DocumentEngineError("RECOVERY_FAILED", `Could not write the recovery copy: ${reason}`, { cause: error }) });
+		}
+	}) : void 0;
+	function noteContentChange() {
+		saving.noteContentChange();
+		recovery?.schedule();
+	}
 	function toDocument() {
 		ensureUsable();
 		rebuildIndex();
@@ -135,8 +156,11 @@ function createDocumentEngine(options) {
 		activeLoad?.abort();
 		const controller = new AbortController();
 		activeLoad = controller;
-		events.emit("load:start", { documentId: describeDocumentId(input) });
+		const documentId = describeDocumentId(input);
+		events.emit("load:start", { documentId });
 		try {
+			await recovery?.markLoadStarted(documentId);
+			if (controller.signal.aborted) throw new Error("aborted");
 			const checked = checkDocument(input);
 			const { document, warnings } = await prepareAssetsForLoad(checked, assetOptions, controller.signal);
 			if (controller.signal.aborted) throw new Error("aborted");
@@ -158,6 +182,7 @@ function createDocumentEngine(options) {
 			};
 			rebuildIndex();
 			history.reset();
+			recovery?.cancel();
 			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
 			if (warnings.length > 0) events.emit("assets:warning", { warnings });
@@ -171,7 +196,10 @@ function createDocumentEngine(options) {
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		} finally {
-			if (activeLoad === controller) activeLoad = null;
+			if (activeLoad === controller) {
+				activeLoad = null;
+				await recovery?.markLoadFinished();
+			}
 		}
 	}
 	function requireStorage() {
@@ -208,6 +236,7 @@ function createDocumentEngine(options) {
 		documentInfo = createDocumentInfo(newOptions);
 		uploadedUrls.clear();
 		history.reset();
+		recovery?.cancel();
 		saving.startSession(0);
 	}
 	function getObjectById(id) {
@@ -241,6 +270,21 @@ function createDocumentEngine(options) {
 		canvas.requestRenderAll();
 		return images.length;
 	}
+	function requireRecovery() {
+		ensureUsable();
+		if (!recovery) throw new DocumentEngineError("RECOVERY_MISSING", "Pass recovery: { store } to createDocumentEngine to use recovery");
+		return recovery;
+	}
+	async function restoreRecovery(documentId, loadOptions) {
+		const source = requireRecovery();
+		const id = documentId ?? documentInfo.id;
+		const record = await source.read(id);
+		if (!record) throw new DocumentEngineError("RECOVERY_NOT_FOUND", `There is no recovery copy for document "${id}"`);
+		const loaded = await loadDocument(await restoreRecordedFiles(record), loadOptions);
+		noteContentChange();
+		events.emit("recovery:restored", { document: loaded });
+		return loaded;
+	}
 	async function travelThroughHistory(direction) {
 		ensureUsable();
 		try {
@@ -258,6 +302,7 @@ function createDocumentEngine(options) {
 		activeLoad?.abort();
 		history.destroy();
 		saving.destroy();
+		recovery?.destroy();
 		canvas.off("object:added", handleObjectAdded);
 		canvas.off("object:removed", handleObjectRemoved);
 		objectsById.clear();
@@ -278,7 +323,7 @@ function createDocumentEngine(options) {
 					...changes
 				}
 			};
-			saving.noteContentChange();
+			noteContentChange();
 		},
 		newDocument,
 		toDocument,
@@ -298,6 +343,12 @@ function createDocumentEngine(options) {
 		},
 		checkAssets,
 		replaceImage,
+		flushRecovery: async () => requireRecovery().flush(),
+		getRecoverableDocuments: async () => requireRecovery().list(),
+		getRecovery: async (documentId) => requireRecovery().read(documentId ?? documentInfo.id),
+		restoreRecovery,
+		discardRecovery: async (documentId) => requireRecovery().remove(documentId ?? documentInfo.id),
+		getInterruptedLoad: async () => requireRecovery().interruptedLoad(),
 		transaction(label, work) {
 			ensureUsable();
 			return history.transaction(label, work);

package/dist/engine/errors.d.cts

@@ -1,6 +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" | "MISSING_ASSETS" | "MISSING_FONTS" | "ASSET_UPLOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "SAVE_CONFLICT" | "SAVE_CANCELLED" | "DOCUMENT_NOT_FOUND" | "HISTORY_FAILED" | "ENGINE_DESTROYED";
+export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "MISSING_ASSETS" | "MISSING_FONTS" | "ASSET_UPLOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "SAVE_CONFLICT" | "SAVE_CANCELLED" | "DOCUMENT_NOT_FOUND" | "HISTORY_FAILED" | "RECOVERY_MISSING" | "RECOVERY_NOT_FOUND" | "RECOVERY_FAILED" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;

package/dist/engine/errors.d.ts

@@ -1,6 +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" | "MISSING_ASSETS" | "MISSING_FONTS" | "ASSET_UPLOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "SAVE_CONFLICT" | "SAVE_CANCELLED" | "DOCUMENT_NOT_FOUND" | "HISTORY_FAILED" | "ENGINE_DESTROYED";
+export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "MISSING_ASSETS" | "MISSING_FONTS" | "ASSET_UPLOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "SAVE_CONFLICT" | "SAVE_CANCELLED" | "DOCUMENT_NOT_FOUND" | "HISTORY_FAILED" | "RECOVERY_MISSING" | "RECOVERY_NOT_FOUND" | "RECOVERY_FAILED" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;

package/dist/index.d.cts

@@ -5,6 +5,8 @@ import { AssetOptions, AssetReport, AssetWarning, AssetWarningCode, UploadReques
 import { NewDocumentOptions } from "./document/create-document.cjs";
 import { CustomObjectDefinition } from "./fabric/object-registry.cjs";
 import { HistoryOptions, HistoryState } from "./history/create-history.cjs";
+import { RecoveryStore } from "./recovery/recovery-store.cjs";
+import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "./recovery/recovery-controller.cjs";
 import { AutosaveOptions } from "./save/autosave-scheduler.cjs";
 import { RetryOptions } from "./save/retry.cjs";
 import { DocumentEngineError, DocumentEngineErrorDetails, DocumentErrorCode, DocumentIssue, createConflictError, isDocumentEngineError } from "./engine/errors.cjs";
@@ -15,4 +17,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 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 };
+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 InterruptedLoad, type KeyboardShortcutOptions, type LoadOptions, type NewDocumentOptions, type RecoveryOptions, type RecoveryRecord, type RecoveryStore, 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

@@ -5,6 +5,8 @@ import { AssetOptions, AssetReport, AssetWarning, AssetWarningCode, UploadReques
 import { NewDocumentOptions } from "./document/create-document.js";
 import { CustomObjectDefinition } from "./fabric/object-registry.js";
 import { HistoryOptions, HistoryState } from "./history/create-history.js";
+import { RecoveryStore } from "./recovery/recovery-store.js";
+import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "./recovery/recovery-controller.js";
 import { AutosaveOptions } from "./save/autosave-scheduler.js";
 import { RetryOptions } from "./save/retry.js";
 import { DocumentEngineError, DocumentEngineErrorDetails, DocumentErrorCode, DocumentIssue, createConflictError, isDocumentEngineError } from "./engine/errors.js";
@@ -15,4 +17,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 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 };
+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 InterruptedLoad, type KeyboardShortcutOptions, type LoadOptions, type NewDocumentOptions, type RecoveryOptions, type RecoveryRecord, type RecoveryStore, 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/recovery/indexed-db-recovery.cjs

@@ -0,0 +1,80 @@
+//#region src/recovery/indexed-db-recovery.ts
+function requestToPromise(request) {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+	});
+}
+function browserStorage() {
+	try {
+		return globalThis.localStorage;
+	} catch {
+		return;
+	}
+}
+function createIndexedDbRecovery(options = {}) {
+	const databaseName = options.databaseName ?? "fabricjs-document-engine";
+	const storeName = options.storeName ?? "recovery";
+	let opening;
+	let database;
+	const emergencyPrefix = `${databaseName}/${storeName}:`;
+	const emergencyStorage = browserStorage();
+	function readEmergency(key) {
+		const json = emergencyStorage?.getItem(`${emergencyPrefix}${key}`);
+		return json === null || json === void 0 ? void 0 : JSON.parse(json);
+	}
+	function emergencyKeys() {
+		if (!emergencyStorage) return [];
+		return Array.from({ length: emergencyStorage.length }, (_, index) => emergencyStorage.key(index) ?? "").filter((key) => key.startsWith(emergencyPrefix)).map((key) => key.slice(emergencyPrefix.length));
+	}
+	function openDatabase() {
+		opening ?? (opening = new Promise((resolve, reject) => {
+			const request = indexedDB.open(databaseName, 1);
+			request.onupgradeneeded = () => {
+				if (!request.result.objectStoreNames.contains(storeName)) request.result.createObjectStore(storeName);
+			};
+			request.onsuccess = () => {
+				database = request.result;
+				resolve(request.result);
+			};
+			request.onerror = () => {
+				opening = void 0;
+				reject(request.error);
+			};
+		}));
+		return opening;
+	}
+	async function run(mode, work) {
+		const transaction = (database ?? await openDatabase()).transaction(storeName, mode);
+		const result = requestToPromise(work(transaction.objectStore(storeName)));
+		await new Promise((resolve, reject) => {
+			transaction.oncomplete = () => resolve();
+			transaction.onerror = () => reject(transaction.error);
+			transaction.onabort = () => reject(transaction.error);
+		});
+		return result;
+	}
+	return {
+		get: async (key) => await run("readonly", (store) => store.get(key)) ?? readEmergency(key),
+		set: async (key, value) => {
+			await run("readwrite", (store) => store.put(value, key));
+		},
+		setNow(key, value) {
+			try {
+				emergencyStorage?.setItem(`${emergencyPrefix}${key}`, JSON.stringify(value));
+			} catch {
+				return;
+			}
+		},
+		delete: async (key) => {
+			emergencyStorage?.removeItem(`${emergencyPrefix}${key}`);
+			await run("readwrite", (store) => store.delete(key));
+		},
+		keys: async () => {
+			const stored = (await run("readonly", (store) => store.getAllKeys())).map(String);
+			return [.../* @__PURE__ */ new Set([...stored, ...emergencyKeys()])];
+		}
+	};
+}
+//#endregion
+exports.createIndexedDbRecovery = createIndexedDbRecovery;

package/dist/recovery/indexed-db-recovery.d.cts

@@ -0,0 +1,8 @@
+import { RecoveryStore } from "./recovery-store.cjs";
+//#region src/recovery/indexed-db-recovery.d.ts
+export interface IndexedDbRecoveryOptions {
+  databaseName?: string;
+  storeName?: string;
+}
+export declare function createIndexedDbRecovery(options?: IndexedDbRecoveryOptions): RecoveryStore;
+//#endregion

package/dist/recovery/indexed-db-recovery.d.ts

@@ -0,0 +1,8 @@
+import { RecoveryStore } from "./recovery-store.js";
+//#region src/recovery/indexed-db-recovery.d.ts
+export interface IndexedDbRecoveryOptions {
+  databaseName?: string;
+  storeName?: string;
+}
+export declare function createIndexedDbRecovery(options?: IndexedDbRecoveryOptions): RecoveryStore;
+//#endregion

package/dist/recovery/indexed-db-recovery.js

@@ -0,0 +1,80 @@
+//#region src/recovery/indexed-db-recovery.ts
+function requestToPromise(request) {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+	});
+}
+function browserStorage() {
+	try {
+		return globalThis.localStorage;
+	} catch {
+		return;
+	}
+}
+function createIndexedDbRecovery(options = {}) {
+	const databaseName = options.databaseName ?? "fabricjs-document-engine";
+	const storeName = options.storeName ?? "recovery";
+	let opening;
+	let database;
+	const emergencyPrefix = `${databaseName}/${storeName}:`;
+	const emergencyStorage = browserStorage();
+	function readEmergency(key) {
+		const json = emergencyStorage?.getItem(`${emergencyPrefix}${key}`);
+		return json === null || json === void 0 ? void 0 : JSON.parse(json);
+	}
+	function emergencyKeys() {
+		if (!emergencyStorage) return [];
+		return Array.from({ length: emergencyStorage.length }, (_, index) => emergencyStorage.key(index) ?? "").filter((key) => key.startsWith(emergencyPrefix)).map((key) => key.slice(emergencyPrefix.length));
+	}
+	function openDatabase() {
+		opening ?? (opening = new Promise((resolve, reject) => {
+			const request = indexedDB.open(databaseName, 1);
+			request.onupgradeneeded = () => {
+				if (!request.result.objectStoreNames.contains(storeName)) request.result.createObjectStore(storeName);
+			};
+			request.onsuccess = () => {
+				database = request.result;
+				resolve(request.result);
+			};
+			request.onerror = () => {
+				opening = void 0;
+				reject(request.error);
+			};
+		}));
+		return opening;
+	}
+	async function run(mode, work) {
+		const transaction = (database ?? await openDatabase()).transaction(storeName, mode);
+		const result = requestToPromise(work(transaction.objectStore(storeName)));
+		await new Promise((resolve, reject) => {
+			transaction.oncomplete = () => resolve();
+			transaction.onerror = () => reject(transaction.error);
+			transaction.onabort = () => reject(transaction.error);
+		});
+		return result;
+	}
+	return {
+		get: async (key) => await run("readonly", (store) => store.get(key)) ?? readEmergency(key),
+		set: async (key, value) => {
+			await run("readwrite", (store) => store.put(value, key));
+		},
+		setNow(key, value) {
+			try {
+				emergencyStorage?.setItem(`${emergencyPrefix}${key}`, JSON.stringify(value));
+			} catch {
+				return;
+			}
+		},
+		delete: async (key) => {
+			emergencyStorage?.removeItem(`${emergencyPrefix}${key}`);
+			await run("readwrite", (store) => store.delete(key));
+		},
+		keys: async () => {
+			const stored = (await run("readonly", (store) => store.getAllKeys())).map(String);
+			return [.../* @__PURE__ */ new Set([...stored, ...emergencyKeys()])];
+		}
+	};
+}
+//#endregion
+export { createIndexedDbRecovery };

package/dist/recovery/recovery-controller.cjs

@@ -0,0 +1,159 @@
+const require_asset_pipeline = require("../assets/asset-pipeline.cjs");
+//#region src/recovery/recovery-controller.ts
+const documentKeyPrefix = "document:";
+const unloadKeyPrefix = "unload:";
+const loadingKey = "loading";
+function documentKey(documentId) {
+	return `${documentKeyPrefix}${documentId}`;
+}
+function unloadKey(documentId) {
+	return `${unloadKeyPrefix}${documentId}`;
+}
+function newerRecord(checkpoint, unloadCopy) {
+	if (!unloadCopy) return checkpoint;
+	if (!checkpoint || unloadCopy.savedAt > checkpoint.savedAt) return {
+		...unloadCopy,
+		files: {
+			...checkpoint?.files,
+			...unloadCopy.files
+		}
+	};
+	return checkpoint;
+}
+function isRecoveryRecord(value) {
+	const record = value;
+	return typeof record?.documentId === "string" && typeof record.document === "object" && record.document !== null;
+}
+async function restoreRecordedFiles(record) {
+	const document = JSON.parse(JSON.stringify(record.document));
+	const recreatedUrls = /* @__PURE__ */ new Map();
+	await require_asset_pipeline.rewriteUrls(document, async (url) => {
+		const blob = record.files[url];
+		if (!blob) return url;
+		const recreated = recreatedUrls.get(url) ?? URL.createObjectURL(blob);
+		recreatedUrls.set(url, recreated);
+		return recreated;
+	});
+	return document;
+}
+function createRecoveryController(options) {
+	const { store } = options;
+	const interval = options.interval ?? 2e3;
+	const capturedFiles = /* @__PURE__ */ new Map();
+	const readyFiles = /* @__PURE__ */ new Map();
+	let timer;
+	let queue = Promise.resolve();
+	let checkpointWaiting;
+	function enqueue(task) {
+		const run = queue.then(task).catch(options.onError);
+		queue = run;
+		return run;
+	}
+	async function captureTabOnlyFiles(document) {
+		const files = {};
+		await require_asset_pipeline.rewriteUrls(document, async (url) => {
+			if (!url.startsWith("blob:")) return url;
+			let capturing = capturedFiles.get(url);
+			if (!capturing) {
+				capturing = fetch(url).then((response) => response.blob());
+				capturedFiles.set(url, capturing);
+				capturing.then((blob) => readyFiles.set(url, blob), () => void 0);
+				capturing.catch(() => capturedFiles.delete(url));
+			}
+			files[url] = await capturing;
+			return url;
+		});
+		return files;
+	}
+	function createRecord(document, files) {
+		return {
+			documentId: document.id,
+			savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			baseRevision: document.revision ?? 0,
+			document,
+			files
+		};
+	}
+	async function writeCheckpoint() {
+		checkpointWaiting = void 0;
+		if (!options.shouldWrite()) return;
+		const document = options.createDocument();
+		const record = createRecord(document, await captureTabOnlyFiles(document));
+		await store.set(documentKey(document.id), record);
+		options.onCheckpoint(record);
+	}
+	function writeCheckpointBeforeThePageCloses() {
+		cancel();
+		if (!options.shouldWrite()) return;
+		const document = options.createDocument();
+		if (store.setNow) {
+			store.setNow(unloadKey(document.id), createRecord(document, {}));
+			return;
+		}
+		const record = createRecord(document, Object.fromEntries(readyFiles));
+		store.set(documentKey(document.id), record).then(() => options.onCheckpoint(record), options.onError);
+	}
+	async function read(documentId) {
+		await queue;
+		const [checkpoint, unloadCopy] = await Promise.all([store.get(documentKey(documentId)), store.get(unloadKey(documentId))]);
+		return newerRecord(isRecoveryRecord(checkpoint) ? checkpoint : void 0, isRecoveryRecord(unloadCopy) ? unloadCopy : void 0);
+	}
+	function cancel() {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = void 0;
+	}
+	function flush() {
+		cancel();
+		checkpointWaiting ?? (checkpointWaiting = enqueue(writeCheckpoint));
+		return checkpointWaiting;
+	}
+	const handlePageHidden = () => writeCheckpointBeforeThePageCloses();
+	const handleVisibilityChange = () => {
+		if (document.visibilityState === "hidden") writeCheckpointBeforeThePageCloses();
+	};
+	const pageEvents = typeof window === "undefined" ? void 0 : window;
+	pageEvents?.addEventListener("pagehide", handlePageHidden);
+	pageEvents?.document.addEventListener("visibilitychange", handleVisibilityChange);
+	return {
+		schedule() {
+			if (timer !== void 0) return;
+			timer = setTimeout(() => {
+				timer = void 0;
+				flush();
+			}, interval);
+		},
+		flush,
+		cancel,
+		remove: (documentId) => enqueue(async () => {
+			await store.delete(unloadKey(documentId));
+			await store.delete(documentKey(documentId));
+		}),
+		read,
+		async list() {
+			await queue;
+			const documentIds = /* @__PURE__ */ new Set();
+			for (const key of await store.keys()) {
+				if (key.startsWith(documentKeyPrefix)) documentIds.add(key.slice(9));
+				if (key.startsWith(unloadKeyPrefix)) documentIds.add(key.slice(7));
+			}
+			return (await Promise.all([...documentIds].map(read))).filter((record) => record !== void 0).sort((first, second) => second.savedAt.localeCompare(first.savedAt));
+		},
+		markLoadStarted: (documentId) => store.set(loadingKey, {
+			documentId,
+			startedAt: (/* @__PURE__ */ new Date()).toISOString()
+		}).catch(options.onError),
+		markLoadFinished: () => store.delete(loadingKey).catch(options.onError),
+		async interruptedLoad() {
+			const marker = await store.get(loadingKey);
+			return marker && typeof marker.startedAt === "string" ? marker : void 0;
+		},
+		destroy() {
+			cancel();
+			pageEvents?.removeEventListener("pagehide", handlePageHidden);
+			pageEvents?.document.removeEventListener("visibilitychange", handleVisibilityChange);
+		}
+	};
+}
+//#endregion
+exports.createRecoveryController = createRecoveryController;
+exports.restoreRecordedFiles = restoreRecordedFiles;

package/dist/recovery/recovery-controller.d.cts

@@ -0,0 +1,19 @@
+import { FabricDocument } from "../document/document-format.cjs";
+import { RecoveryStore } from "./recovery-store.cjs";
+//#region src/recovery/recovery-controller.d.ts
+export interface RecoveryOptions {
+  store: RecoveryStore;
+  interval?: number;
+}
+export interface RecoveryRecord {
+  documentId: string;
+  savedAt: string;
+  baseRevision: number;
+  document: FabricDocument;
+  files: Record<string, Blob>;
+}
+export interface InterruptedLoad {
+  documentId: string | undefined;
+  startedAt: string;
+}
+//#endregion

package/dist/recovery/recovery-controller.d.ts

@@ -0,0 +1,19 @@
+import { FabricDocument } from "../document/document-format.js";
+import { RecoveryStore } from "./recovery-store.js";
+//#region src/recovery/recovery-controller.d.ts
+export interface RecoveryOptions {
+  store: RecoveryStore;
+  interval?: number;
+}
+export interface RecoveryRecord {
+  documentId: string;
+  savedAt: string;
+  baseRevision: number;
+  document: FabricDocument;
+  files: Record<string, Blob>;
+}
+export interface InterruptedLoad {
+  documentId: string | undefined;
+  startedAt: string;
+}
+//#endregion

package/dist/recovery/recovery-controller.js

@@ -0,0 +1,158 @@
+import { rewriteUrls } from "../assets/asset-pipeline.js";
+//#region src/recovery/recovery-controller.ts
+const documentKeyPrefix = "document:";
+const unloadKeyPrefix = "unload:";
+const loadingKey = "loading";
+function documentKey(documentId) {
+	return `${documentKeyPrefix}${documentId}`;
+}
+function unloadKey(documentId) {
+	return `${unloadKeyPrefix}${documentId}`;
+}
+function newerRecord(checkpoint, unloadCopy) {
+	if (!unloadCopy) return checkpoint;
+	if (!checkpoint || unloadCopy.savedAt > checkpoint.savedAt) return {
+		...unloadCopy,
+		files: {
+			...checkpoint?.files,
+			...unloadCopy.files
+		}
+	};
+	return checkpoint;
+}
+function isRecoveryRecord(value) {
+	const record = value;
+	return typeof record?.documentId === "string" && typeof record.document === "object" && record.document !== null;
+}
+async function restoreRecordedFiles(record) {
+	const document = JSON.parse(JSON.stringify(record.document));
+	const recreatedUrls = /* @__PURE__ */ new Map();
+	await rewriteUrls(document, async (url) => {
+		const blob = record.files[url];
+		if (!blob) return url;
+		const recreated = recreatedUrls.get(url) ?? URL.createObjectURL(blob);
+		recreatedUrls.set(url, recreated);
+		return recreated;
+	});
+	return document;
+}
+function createRecoveryController(options) {
+	const { store } = options;
+	const interval = options.interval ?? 2e3;
+	const capturedFiles = /* @__PURE__ */ new Map();
+	const readyFiles = /* @__PURE__ */ new Map();
+	let timer;
+	let queue = Promise.resolve();
+	let checkpointWaiting;
+	function enqueue(task) {
+		const run = queue.then(task).catch(options.onError);
+		queue = run;
+		return run;
+	}
+	async function captureTabOnlyFiles(document) {
+		const files = {};
+		await rewriteUrls(document, async (url) => {
+			if (!url.startsWith("blob:")) return url;
+			let capturing = capturedFiles.get(url);
+			if (!capturing) {
+				capturing = fetch(url).then((response) => response.blob());
+				capturedFiles.set(url, capturing);
+				capturing.then((blob) => readyFiles.set(url, blob), () => void 0);
+				capturing.catch(() => capturedFiles.delete(url));
+			}
+			files[url] = await capturing;
+			return url;
+		});
+		return files;
+	}
+	function createRecord(document, files) {
+		return {
+			documentId: document.id,
+			savedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			baseRevision: document.revision ?? 0,
+			document,
+			files
+		};
+	}
+	async function writeCheckpoint() {
+		checkpointWaiting = void 0;
+		if (!options.shouldWrite()) return;
+		const document = options.createDocument();
+		const record = createRecord(document, await captureTabOnlyFiles(document));
+		await store.set(documentKey(document.id), record);
+		options.onCheckpoint(record);
+	}
+	function writeCheckpointBeforeThePageCloses() {
+		cancel();
+		if (!options.shouldWrite()) return;
+		const document = options.createDocument();
+		if (store.setNow) {
+			store.setNow(unloadKey(document.id), createRecord(document, {}));
+			return;
+		}
+		const record = createRecord(document, Object.fromEntries(readyFiles));
+		store.set(documentKey(document.id), record).then(() => options.onCheckpoint(record), options.onError);
+	}
+	async function read(documentId) {
+		await queue;
+		const [checkpoint, unloadCopy] = await Promise.all([store.get(documentKey(documentId)), store.get(unloadKey(documentId))]);
+		return newerRecord(isRecoveryRecord(checkpoint) ? checkpoint : void 0, isRecoveryRecord(unloadCopy) ? unloadCopy : void 0);
+	}
+	function cancel() {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = void 0;
+	}
+	function flush() {
+		cancel();
+		checkpointWaiting ?? (checkpointWaiting = enqueue(writeCheckpoint));
+		return checkpointWaiting;
+	}
+	const handlePageHidden = () => writeCheckpointBeforeThePageCloses();
+	const handleVisibilityChange = () => {
+		if (document.visibilityState === "hidden") writeCheckpointBeforeThePageCloses();
+	};
+	const pageEvents = typeof window === "undefined" ? void 0 : window;
+	pageEvents?.addEventListener("pagehide", handlePageHidden);
+	pageEvents?.document.addEventListener("visibilitychange", handleVisibilityChange);
+	return {
+		schedule() {
+			if (timer !== void 0) return;
+			timer = setTimeout(() => {
+				timer = void 0;
+				flush();
+			}, interval);
+		},
+		flush,
+		cancel,
+		remove: (documentId) => enqueue(async () => {
+			await store.delete(unloadKey(documentId));
+			await store.delete(documentKey(documentId));
+		}),
+		read,
+		async list() {
+			await queue;
+			const documentIds = /* @__PURE__ */ new Set();
+			for (const key of await store.keys()) {
+				if (key.startsWith(documentKeyPrefix)) documentIds.add(key.slice(9));
+				if (key.startsWith(unloadKeyPrefix)) documentIds.add(key.slice(7));
+			}
+			return (await Promise.all([...documentIds].map(read))).filter((record) => record !== void 0).sort((first, second) => second.savedAt.localeCompare(first.savedAt));
+		},
+		markLoadStarted: (documentId) => store.set(loadingKey, {
+			documentId,
+			startedAt: (/* @__PURE__ */ new Date()).toISOString()
+		}).catch(options.onError),
+		markLoadFinished: () => store.delete(loadingKey).catch(options.onError),
+		async interruptedLoad() {
+			const marker = await store.get(loadingKey);
+			return marker && typeof marker.startedAt === "string" ? marker : void 0;
+		},
+		destroy() {
+			cancel();
+			pageEvents?.removeEventListener("pagehide", handlePageHidden);
+			pageEvents?.document.removeEventListener("visibilitychange", handleVisibilityChange);
+		}
+	};
+}
+//#endregion
+export { createRecoveryController, restoreRecordedFiles };

package/dist/recovery/recovery-store.cjs

@@ -0,0 +1,19 @@
+//#region src/recovery/recovery-store.ts
+function createMemoryRecovery() {
+	const values = /* @__PURE__ */ new Map();
+	return {
+		get: async (key) => values.get(key),
+		set: async (key, value) => {
+			values.set(key, value);
+		},
+		setNow: (key, value) => {
+			values.set(key, value);
+		},
+		delete: async (key) => {
+			values.delete(key);
+		},
+		keys: async () => [...values.keys()]
+	};
+}
+//#endregion
+exports.createMemoryRecovery = createMemoryRecovery;

package/dist/recovery/recovery-store.d.cts

@@ -0,0 +1,10 @@
+//#region src/recovery/recovery-store.d.ts
+export interface RecoveryStore {
+  get(key: string): Promise<unknown>;
+  set(key: string, value: unknown): Promise<void>;
+  setNow?(key: string, value: unknown): void;
+  delete(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+}
+export declare function createMemoryRecovery(): RecoveryStore;
+//#endregion

package/dist/recovery/recovery-store.d.ts

@@ -0,0 +1,10 @@
+//#region src/recovery/recovery-store.d.ts
+export interface RecoveryStore {
+  get(key: string): Promise<unknown>;
+  set(key: string, value: unknown): Promise<void>;
+  setNow?(key: string, value: unknown): void;
+  delete(key: string): Promise<void>;
+  keys(): Promise<string[]>;
+}
+export declare function createMemoryRecovery(): RecoveryStore;
+//#endregion

package/dist/recovery/recovery-store.js

@@ -0,0 +1,19 @@
+//#region src/recovery/recovery-store.ts
+function createMemoryRecovery() {
+	const values = /* @__PURE__ */ new Map();
+	return {
+		get: async (key) => values.get(key),
+		set: async (key, value) => {
+			values.set(key, value);
+		},
+		setNow: (key, value) => {
+			values.set(key, value);
+		},
+		delete: async (key) => {
+			values.delete(key);
+		},
+		keys: async () => [...values.keys()]
+	};
+}
+//#endregion
+export { createMemoryRecovery };

package/dist/recovery.cjs

@@ -0,0 +1,5 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_indexed_db_recovery = require("./recovery/indexed-db-recovery.cjs");
+const require_recovery_store = require("./recovery/recovery-store.cjs");
+exports.createIndexedDbRecovery = require_indexed_db_recovery.createIndexedDbRecovery;
+exports.createMemoryRecovery = require_recovery_store.createMemoryRecovery;

package/dist/recovery.d.cts

@@ -0,0 +1,4 @@
+import { RecoveryStore, createMemoryRecovery } from "./recovery/recovery-store.cjs";
+import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "./recovery/recovery-controller.cjs";
+import { IndexedDbRecoveryOptions, createIndexedDbRecovery } from "./recovery/indexed-db-recovery.cjs";
+export { type IndexedDbRecoveryOptions, type InterruptedLoad, type RecoveryOptions, type RecoveryRecord, type RecoveryStore, createIndexedDbRecovery, createMemoryRecovery };

package/dist/recovery.d.ts

@@ -0,0 +1,4 @@
+import { RecoveryStore, createMemoryRecovery } from "./recovery/recovery-store.js";
+import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "./recovery/recovery-controller.js";
+import { IndexedDbRecoveryOptions, createIndexedDbRecovery } from "./recovery/indexed-db-recovery.js";
+export { type IndexedDbRecoveryOptions, type InterruptedLoad, type RecoveryOptions, type RecoveryRecord, type RecoveryStore, createIndexedDbRecovery, createMemoryRecovery };

package/dist/recovery.js

@@ -0,0 +1,3 @@
+import { createIndexedDbRecovery } from "./recovery/indexed-db-recovery.js";
+import { createMemoryRecovery } from "./recovery/recovery-store.js";
+export { createIndexedDbRecovery, createMemoryRecovery };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fabricjs-document-engine",
-  "version": "0.3.0",
+  "version": "0.4.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",
@@ -18,7 +18,8 @@
     "autosave",
     "editor",
     "typescript",
-    "storage"
+    "storage",
+    "recovery"
   ],
   "license": "MIT",
   "author": "Sohail Khan (https://me.jscrate.dev)",
@@ -53,6 +54,16 @@
         "default": "./dist/storage.cjs"
       }
     },
+    "./recovery": {
+      "import": {
+        "types": "./dist/recovery.d.ts",
+        "default": "./dist/recovery.js"
+      },
+      "require": {
+        "types": "./dist/recovery.d.cts",
+        "default": "./dist/recovery.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "scripts": {