fabricjs-document-engine 0.0.0 → 0.2.0

package/README.md

@@ -8,7 +8,9 @@ Fabric already draws objects, handles interaction and serializes to JSON. This p
 - **A versioned document format.** It records the schema version, canvas size, background, object order and your own metadata.
 - **Safe loading.** Documents are validated first. Unknown object types are refused before the canvas is touched. A missing image fails the load instead of silently disappearing. When loads overlap, the newest one wins.
 - **Custom objects.** Register your own Fabric classes and the extra properties they need to keep.
-- **Your storage.** Plug in any backend with two functions. No hosted service is needed.
+- **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.
+- **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.
 
 ## Install
@@ -36,20 +38,89 @@ await engine.loadDocument(JSON.parse(localStorage.getItem(document.id)!));
 
 ## Saving and loading through storage
 
+The built-in adapters are the quickest way to start:
+
 ```ts
+import { createLocalStorage, createMemoryStorage } from 'fabricjs-document-engine/storage';
+
 const engine = createDocumentEngine({
   canvas,
-  storage: {
-    loadDocument: (id) => fetch(`/api/documents/${id}`).then((response) => response.json()),
-    saveDocument: (document) =>
-      fetch(`/api/documents/${document.id}`, { method: 'PUT', body: JSON.stringify(document) }).then(() => {}),
-  },
+  storage: createLocalStorage({ prefix: 'my-app:' }),
+  autosave: true,
 });
 
 await engine.load('project-42');
 await engine.save();
 ```
 
+Both adapters also have `listDocuments()` and `deleteDocument(id)`. To build on another key-value store, use `createKeyValueStorage({ read, write, remove, keys }, prefix)`.
+
+### Your own backend
+
+A storage adapter is two functions:
+
+```ts
+import { createDocumentEngine, createConflictError } from 'fabricjs-document-engine';
+import type { DocumentStorage } from 'fabricjs-document-engine';
+
+const storage: DocumentStorage = {
+  async loadDocument(id) {
+    const response = await fetch(`/api/documents/${id}`);
+    return response.json();
+  },
+  async saveDocument(document, { expectedRevision, signal }) {
+    const response = await fetch(`/api/documents/${document.id}`, {
+      method: 'PUT',
+      headers: { 'If-Match': String(expectedRevision ?? '*') },
+      body: JSON.stringify(document),
+      signal,
+    });
+    if (response.status === 409) throw Object.assign(new Error('Saved elsewhere'), { code: 'SAVE_CONFLICT' });
+    if (response.status === 403) throw Object.assign(new Error('Not allowed'), { retryable: false });
+    if (!response.ok) throw new Error(`Save failed with ${response.status}`);
+    return { revision: document.revision };
+  },
+};
+```
+
+- `expectedRevision` is the revision this editor last saved or loaded. Reject the save when the stored document has a different revision. It is `null` when the user chose to overwrite.
+- `document.revision` is the next revision. If your backend assigns its own number, return `{ revision }`.
+- Throw an error with `code: 'SAVE_CONFLICT'`, or use `createConflictError(id, expected, actual)`, to report a conflict. Conflicts are never retried.
+- Throw an error with `retryable: false` for failures that retrying cannot fix. Every other error is retried.
+- Pass `signal` to `fetch`. The engine aborts it when another document is opened.
+
+## Safe saving
+
+```ts
+const engine = createDocumentEngine({
+  canvas,
+  storage,
+  autosave: { delay: 1000, maxWait: 10000 },
+  saveRetry: { attempts: 3, baseDelay: 500, maxDelay: 8000 },
+});
+
+engine.on('save:status', ({ status, isDirty, revision, lastSavedAt, error }) => {
+  statusLabel.textContent = status;
+});
+```
+
+`status` is one of `saved`, `unsaved`, `saving`, `error` or `conflict`.
+
+- **Unsaved changes.** Every recorded history step, undo, redo and metadata change marks the document as changed. `engine.isDirty()` tells you whether anything is unsaved. Edits made while a save is running stay unsaved until the next save.
+- **Autosave.** It saves after `delay` ms without edits, and at the latest `maxWait` ms after the first unsaved edit, even while the user keeps editing. `autosave: true` uses the defaults shown above.
+- **One save at a time.** Calling `save()` while a save is running queues exactly one follow-up save of the latest content. Responses can never arrive out of order.
+- **Stale responses.** If another document is loaded while a save is running, that save's response is ignored and any queued save is cancelled with `SAVE_CANCELLED`.
+- **Conflicts.** When another tab or device saved first, the save fails with `SAVE_CONFLICT` and the status becomes `conflict`. Either reload the document with `engine.load(id)`, or keep your version with `engine.save({ overwrite: true })`.
+- **Retries.** Temporary failures are retried with exponential backoff and jitter. Each retry emits `save:retry` with `{ attempt, delay, error }`.
+
+### Warn before leaving
+
+```ts
+import { bindUnsavedChangesWarning } from 'fabricjs-document-engine';
+
+const unbind = bindUnsavedChangesWarning(engine);
+```
+
 ## Custom objects
 
 ```ts
@@ -68,6 +139,54 @@ const engine = createDocumentEngine({
 
 If a document contains a type that has not been registered, loading fails with `UNKNOWN_OBJECT_TYPE` and lists the missing types. Your object is never turned into something else.
 
+## Undo and redo
+
+History is on by default. The engine records these automatically:
+
+- adding and deleting objects, where several changes in the same tick become one step
+- pointer moves, resizes and rotations (Fabric's `object:modified`)
+- finished text editing
+
+Fabric fires no events for changes your code makes directly, such as `object.set('fill', 'red')` or `canvas.bringObjectForward(object)`. Wrap them in a transaction or call `commit`:
+
+```ts
+engine.transaction('Arrange furniture', () => {
+  chair.set({ left: 120, top: 80 });
+  table.set('fill', 'oak');
+  canvas.bringObjectToFront(table);
+});
+
+canvas.sendObjectBackwards(rug);
+engine.commit('Send rug backwards');
+
+await engine.undo();
+await engine.redo();
+```
+
+- Transactions can be nested, and the outermost label is used. They can also be async: `await engine.transaction('Import', async () => { ... })`.
+- Grouping and ungrouping are ordinary changes to the object list. Do the remove and the add inside one transaction and they take one undo step.
+- Undo and redo rebuild the changed objects from their saved state, so they come back as new instances with the same ids. Look them up again with `engine.getObjectById(id)` rather than keeping old references.
+- Keep the last 50 steps with `createDocumentEngine({ canvas, history: { limit: 50 } })`. The default is 100.
+
+### Keyboard shortcuts
+
+```ts
+import { bindKeyboardShortcuts } from 'fabricjs-document-engine';
+
+const unbind = bindKeyboardShortcuts(engine);
+```
+
+Ctrl/Cmd + Z undoes. Ctrl/Cmd + Shift + Z and Ctrl + Y redo. Shortcuts are ignored while the user is typing in an input, a textarea, a contenteditable element or Fabric text, so native text undo keeps working there. Pass `{ target: element }` to listen somewhere other than `window`.
+
+### Toolbar state
+
+```ts
+engine.on('history:change', ({ canUndo, canRedo, undoLabel, redoLabel }) => {
+  undoButton.disabled = !canUndo;
+  undoButton.title = undoLabel ? `Undo ${undoLabel}` : 'Undo';
+});
+```
+
 ## Document format
 
 ```ts
@@ -76,6 +195,7 @@ interface FabricDocument {
   id: string;
   createdAt: string;
   updatedAt: string;
+  revision?: number;
   fabricVersion?: string;
   canvas: { width: number; height: number; background?: unknown };
   objects: SerializedFabricObject[];
@@ -92,13 +212,23 @@ Keep project data such as titles, owners and tags in `metadata` with `engine.upd
 | `createDocumentEngine({ canvas, storage?, customObjects?, document? })` | Connects the engine to your canvas. |
 | `engine.toDocument()` | Serializes the canvas into the versioned document format. |
 | `engine.loadDocument(document, { restoreCanvasSize? })` | Validates and loads a document. Resolves when the objects are on the canvas. |
-| `engine.load(id)` / `engine.save()` | Reads from or writes to your storage adapter. |
+| `engine.load(id)` / `engine.save({ overwrite? })` | Reads from or writes to your storage adapter. |
+| `engine.isDirty()` | Tells you whether there are unsaved changes. |
+| `engine.getSaveState()` | Returns `{ status, isDirty, isSaving, revision, lastSavedAt, error }`. |
+| `bindUnsavedChangesWarning(engine)` | Asks the browser to confirm before closing a page with unsaved changes. Returns an unbind function. |
 | `engine.newDocument({ id?, metadata? })` | Clears the canvas and starts a fresh document. |
 | `engine.getDocumentInfo()` | Returns the current document's id, dates and metadata. |
 | `engine.updateMetadata(changes)` | Merges changes into the document metadata. |
 | `engine.getObjectById(id)` | Finds any object by id, including objects inside groups. |
 | `engine.registerObject({ fabricClass, properties })` | Registers a custom class after the engine is created. |
-| `engine.on(event, handler)` | Listens to `load:start`, `load:success`, `load:error`, `save:start`, `save:success` or `save:error`. Returns an unsubscribe function. |
+| `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. |
+| `engine.canUndo()` / `engine.canRedo()` | Tells you whether a step is available. |
+| `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`, `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. |
 
@@ -113,7 +243,11 @@ Every failure is a `DocumentEngineError` with a `code` you can switch on:
 | `UNKNOWN_OBJECT_TYPE` | A type is not registered. `error.unknownTypes` lists them. |
 | `LOAD_FAILED` | Fabric or your storage could not load the document, for example because an image is missing. `error.cause` holds the original error. |
 | `LOAD_ABORTED` | A newer load started before this one finished. |
-| `SAVE_FAILED` | Your storage adapter rejected the save. |
+| `SAVE_FAILED` | Your storage adapter rejected the save after all retries. `error.retryable` tells you whether trying again could help. |
+| `SAVE_CONFLICT` | Another tab or device saved this document first. |
+| `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. |
 | `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()`. |
@@ -124,9 +258,9 @@ A failed load never clears or half-fills your canvas.
 
 | Version | Focus |
 | --- | --- |
-| 0.1 | Document foundation: ids, save and load, validation, custom objects |
-| 0.2 | Undo and redo with transactions |
-| 0.3 | Safe saving: dirty state, autosave, stale-response protection |
+| 0.1 ✓ | Document foundation: ids, save and load, validation, custom objects |
+| 0.2 ✓ | Undo and redo with transactions |
+| 0.3 ✓ | Safe saving: dirty state, autosave, stale-response protection |
 | 0.4 | Assets and fonts |
 | 0.5 | Recovery after a refresh or crash |
 | 0.6 | PNG, JPEG, SVG and JSON export with preflight checks |

package/dist/document/document-format.d.cts

@@ -17,6 +17,7 @@ export interface FabricDocument {
   id: string;
   createdAt: string;
   updatedAt: string;
+  revision?: number;
   fabricVersion?: string;
   canvas: DocumentCanvas;
   objects: SerializedFabricObject[];

package/dist/document/document-format.d.ts

@@ -17,6 +17,7 @@ export interface FabricDocument {
   id: string;
   createdAt: string;
   updatedAt: string;
+  revision?: number;
   fabricVersion?: string;
   canvas: DocumentCanvas;
   objects: SerializedFabricObject[];

package/dist/document/validate-document.cjs

@@ -57,6 +57,7 @@ function validateDocument(value) {
 	if (typeof value.id !== "string" || value.id.length === 0) issues.push(invalid("id", "must be a non-empty string"));
 	if (typeof value.createdAt !== "string") issues.push(invalid("createdAt", "must be an ISO date string"));
 	if (typeof value.updatedAt !== "string") issues.push(invalid("updatedAt", "must be an ISO date string"));
+	if (value.revision !== void 0 && !(Number.isInteger(value.revision) && value.revision >= 0)) issues.push(invalid("revision", "must be a whole number of zero or more when present"));
 	if (!isPlainObject(value.metadata)) issues.push(invalid("metadata", "must be an object"));
 	if (!isPlainObject(value.canvas)) issues.push(invalid("canvas", "must be an object"));
 	else {

package/dist/document/validate-document.js

@@ -57,6 +57,7 @@ function validateDocument(value) {
 	if (typeof value.id !== "string" || value.id.length === 0) issues.push(invalid("id", "must be a non-empty string"));
 	if (typeof value.createdAt !== "string") issues.push(invalid("createdAt", "must be an ISO date string"));
 	if (typeof value.updatedAt !== "string") issues.push(invalid("updatedAt", "must be an ISO date string"));
+	if (value.revision !== void 0 && !(Number.isInteger(value.revision) && value.revision >= 0)) issues.push(invalid("revision", "must be a whole number of zero or more when present"));
 	if (!isPlainObject(value.metadata)) issues.push(invalid("metadata", "must be an object"));
 	if (!isPlainObject(value.canvas)) issues.push(invalid("canvas", "must be an object"));
 	else {

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

@@ -7,6 +7,8 @@ const require_fabric_adapter = require("../fabric/fabric-adapter.cjs");
 const require_object_ids = require("../fabric/object-ids.cjs");
 const require_errors = require("./errors.cjs");
 const require_object_registry = require("../fabric/object-registry.cjs");
+const require_create_history = require("../history/create-history.cjs");
+const require_save_controller = require("../save/save-controller.cjs");
 const require_event_emitter = require("./event-emitter.cjs");
 //#region src/engine/create-document-engine.ts
 function describeDocumentId(value) {
@@ -15,6 +17,7 @@ function describeDocumentId(value) {
 }
 function createDocumentEngine(options) {
 	const { canvas, storage } = options;
+	if (options.autosave && !storage) throw new require_errors.DocumentEngineError("STORAGE_MISSING", "Autosave needs a storage adapter passed to createDocumentEngine");
 	const registry = require_object_registry.createObjectRegistry(options.customObjects);
 	const events = require_event_emitter.createEventEmitter();
 	const objectsById = /* @__PURE__ */ new Map();
@@ -50,6 +53,27 @@ function createDocumentEngine(options) {
 	canvas.on("object:added", handleObjectAdded);
 	canvas.on("object:removed", handleObjectRemoved);
 	rebuildIndex();
+	const history = require_create_history.createHistory({
+		canvas,
+		limit: options.history?.limit,
+		serializeObjects: () => {
+			rebuildIndex();
+			return require_fabric_adapter.serializeCanvas(canvas, registry.propertiesToInclude()).objects;
+		},
+		onChange: (state) => events.emit("history:change", state),
+		onContentChange: () => saving.noteContentChange()
+	});
+	const saving = require_save_controller.createSaveController({
+		getStorage: () => requireStorage(),
+		createDocument: () => toDocument(),
+		retry: options.saveRetry,
+		autosave: options.autosave === true ? {} : options.autosave ?? false,
+		onStateChange: (state) => events.emit("save:status", state),
+		onStart: (document) => events.emit("save:start", { document }),
+		onSuccess: (document) => events.emit("save:success", { document }),
+		onError: (error) => events.emit("save:error", { error }),
+		onRetry: (event) => events.emit("save:retry", event)
+	});
 	function toDocument() {
 		ensureUsable();
 		rebuildIndex();
@@ -63,6 +87,7 @@ function createDocumentEngine(options) {
 			id: documentInfo.id,
 			createdAt: documentInfo.createdAt,
 			updatedAt: documentInfo.updatedAt,
+			revision: saving.state().revision,
 			canvas: {
 				width: canvas.getWidth(),
 				height: canvas.getHeight()
@@ -99,11 +124,11 @@ function createDocumentEngine(options) {
 		events.emit("load:start", { documentId: describeDocumentId(input) });
 		try {
 			const document = checkDocument(input);
-			await require_fabric_adapter.loadIntoCanvas(canvas, {
+			await history.withoutRecording(() => require_fabric_adapter.loadIntoCanvas(canvas, {
 				version: document.fabricVersion,
 				background: document.canvas.background,
 				objects: document.objects
-			}, controller.signal);
+			}, controller.signal));
 			if (controller.signal.aborted) throw new Error("aborted");
 			if (loadOptions.restoreCanvasSize ?? true) canvas.setDimensions({
 				width: document.canvas.width,
@@ -116,6 +141,8 @@ function createDocumentEngine(options) {
 				metadata: { ...document.metadata }
 			};
 			rebuildIndex();
+			history.reset();
+			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
 			events.emit("load:success", { document });
 			return document;
@@ -139,34 +166,28 @@ function createDocumentEngine(options) {
 			stored = await source.loadDocument(documentId);
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
-			const engineError = new require_errors.DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
+			const engineError = require_errors.isDocumentEngineError(error) ? error : new require_errors.DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
 		return loadDocument(stored, loadOptions);
 	}
-	async function save() {
-		ensureUsable();
-		const target = requireStorage();
-		const document = toDocument();
-		events.emit("save:start", { document });
+	function save(saveOptions) {
 		try {
-			await target.saveDocument(document);
+			ensureUsable();
 		} catch (error) {
-			const reason = error instanceof Error ? error.message : String(error);
-			const engineError = new require_errors.DocumentEngineError("SAVE_FAILED", `Storage could not save the document: ${reason}`, { cause: error });
-			events.emit("save:error", { error: engineError });
-			throw engineError;
+			return Promise.reject(error);
 		}
-		events.emit("save:success", { document });
-		return document;
+		return saving.save(saveOptions);
 	}
 	function newDocument(newOptions) {
 		ensureUsable();
 		activeLoad?.abort();
-		canvas.clear();
+		history.withoutRecording(() => canvas.clear());
 		objectsById.clear();
 		documentInfo = require_create_document.createDocumentInfo(newOptions);
+		history.reset();
+		saving.startSession(0);
 	}
 	function getObjectById(id) {
 		ensureUsable();
@@ -175,10 +196,23 @@ function createDocumentEngine(options) {
 		rebuildIndex();
 		return objectsById.get(id);
 	}
+	async function travelThroughHistory(direction) {
+		ensureUsable();
+		try {
+			return await history[direction]();
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			const engineError = new require_errors.DocumentEngineError("HISTORY_FAILED", `Could not ${direction}: ${reason}`, { cause: error });
+			events.emit("history:error", { error: engineError });
+			throw engineError;
+		}
+	}
 	function destroy() {
 		if (destroyed) return;
 		destroyed = true;
 		activeLoad?.abort();
+		history.destroy();
+		saving.destroy();
 		canvas.off("object:added", handleObjectAdded);
 		canvas.off("object:removed", handleObjectRemoved);
 		objectsById.clear();
@@ -199,17 +233,37 @@ function createDocumentEngine(options) {
 					...changes
 				}
 			};
+			saving.noteContentChange();
 		},
 		newDocument,
 		toDocument,
 		loadDocument,
 		load,
 		save,
+		isDirty: () => saving.state().isDirty,
+		getSaveState: () => saving.state(),
 		registerObject(definition) {
 			ensureUsable();
 			registry.register(definition);
 		},
 		getObjectById,
+		transaction(label, work) {
+			ensureUsable();
+			return history.transaction(label, work);
+		},
+		commit(label = "Edit") {
+			ensureUsable();
+			return history.commit(label);
+		},
+		undo: () => travelThroughHistory("undo"),
+		redo: () => travelThroughHistory("redo"),
+		canUndo: () => history.state().canUndo,
+		canRedo: () => history.state().canRedo,
+		getHistory: () => history.labels(),
+		clearHistory() {
+			ensureUsable();
+			history.reset();
+		},
 		on: (name, handler) => events.on(name, handler),
 		destroy
 	};

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

@@ -1,19 +1,23 @@
 import { DocumentInfo, FabricDocument } from "../document/document-format.cjs";
 import { NewDocumentOptions } from "../document/create-document.cjs";
 import { CustomObjectDefinition } from "../fabric/object-registry.cjs";
+import { HistoryOptions, HistoryState } from "../history/create-history.cjs";
+import { AutosaveOptions } from "../save/autosave-scheduler.cjs";
+import { RetryOptions } from "../save/retry.cjs";
 import { DocumentEngineError } from "./errors.cjs";
+import { DocumentStorage } from "../storage/storage-contract.cjs";
+import { SaveOptions, SaveRetryEvent, SaveState } from "../save/save-controller.cjs";
 import { Unsubscribe } from "./event-emitter.cjs";
 import { FabricObject, StaticCanvas } from "fabric";
 //#region src/engine/create-document-engine.d.ts
-export interface DocumentStorage {
-  loadDocument(id: string): Promise<unknown>;
-  saveDocument(document: FabricDocument): Promise<void>;
-}
 export interface DocumentEngineOptions {
   canvas: StaticCanvas;
   storage?: DocumentStorage;
   customObjects?: CustomObjectDefinition[];
   document?: NewDocumentOptions;
+  history?: HistoryOptions;
+  autosave?: boolean | AutosaveOptions;
+  saveRetry?: RetryOptions;
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
@@ -37,6 +41,12 @@ export interface DocumentEngineEvents {
   "save:error": {
     error: DocumentEngineError;
   };
+  "save:retry": SaveRetryEvent;
+  "save:status": SaveState;
+  "history:change": HistoryState;
+  "history:error": {
+    error: DocumentEngineError;
+  };
 }
 export interface DocumentEngine {
   readonly canvas: StaticCanvas;
@@ -46,8 +56,21 @@ export interface DocumentEngine {
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
-  save(): Promise<FabricDocument>;
+  save(options?: SaveOptions): Promise<FabricDocument>;
+  isDirty(): boolean;
+  getSaveState(): SaveState;
   registerObject(definition: CustomObjectDefinition): void;
+  transaction<Result>(label: string, work: () => Result): Result;
+  commit(label?: string): boolean;
+  undo(): Promise<boolean>;
+  redo(): Promise<boolean>;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  getHistory(): {
+    undo: string[];
+    redo: string[];
+  };
+  clearHistory(): void;
   getObjectById(id: string): FabricObject | undefined;
   on<Name extends keyof DocumentEngineEvents>(name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): Unsubscribe;
   destroy(): void;

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

@@ -1,19 +1,23 @@
 import { DocumentInfo, FabricDocument } from "../document/document-format.js";
 import { NewDocumentOptions } from "../document/create-document.js";
 import { CustomObjectDefinition } from "../fabric/object-registry.js";
+import { HistoryOptions, HistoryState } from "../history/create-history.js";
+import { AutosaveOptions } from "../save/autosave-scheduler.js";
+import { RetryOptions } from "../save/retry.js";
 import { DocumentEngineError } from "./errors.js";
+import { DocumentStorage } from "../storage/storage-contract.js";
+import { SaveOptions, SaveRetryEvent, SaveState } from "../save/save-controller.js";
 import { Unsubscribe } from "./event-emitter.js";
 import { FabricObject, StaticCanvas } from "fabric";
 //#region src/engine/create-document-engine.d.ts
-export interface DocumentStorage {
-  loadDocument(id: string): Promise<unknown>;
-  saveDocument(document: FabricDocument): Promise<void>;
-}
 export interface DocumentEngineOptions {
   canvas: StaticCanvas;
   storage?: DocumentStorage;
   customObjects?: CustomObjectDefinition[];
   document?: NewDocumentOptions;
+  history?: HistoryOptions;
+  autosave?: boolean | AutosaveOptions;
+  saveRetry?: RetryOptions;
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
@@ -37,6 +41,12 @@ export interface DocumentEngineEvents {
   "save:error": {
     error: DocumentEngineError;
   };
+  "save:retry": SaveRetryEvent;
+  "save:status": SaveState;
+  "history:change": HistoryState;
+  "history:error": {
+    error: DocumentEngineError;
+  };
 }
 export interface DocumentEngine {
   readonly canvas: StaticCanvas;
@@ -46,8 +56,21 @@ export interface DocumentEngine {
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
-  save(): Promise<FabricDocument>;
+  save(options?: SaveOptions): Promise<FabricDocument>;
+  isDirty(): boolean;
+  getSaveState(): SaveState;
   registerObject(definition: CustomObjectDefinition): void;
+  transaction<Result>(label: string, work: () => Result): Result;
+  commit(label?: string): boolean;
+  undo(): Promise<boolean>;
+  redo(): Promise<boolean>;
+  canUndo(): boolean;
+  canRedo(): boolean;
+  getHistory(): {
+    undo: string[];
+    redo: string[];
+  };
+  clearHistory(): void;
   getObjectById(id: string): FabricObject | undefined;
   on<Name extends keyof DocumentEngineEvents>(name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): Unsubscribe;
   destroy(): void;