fabricjs-document-engine 0.1.0 → 0.2.0

package/README.md

@@ -8,7 +8,8 @@ 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.
 
@@ -37,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
@@ -125,6 +195,7 @@ interface FabricDocument {
   id: string;
   createdAt: string;
   updatedAt: string;
+  revision?: number;
   fabricVersion?: string;
   canvas: { width: number; height: number; background?: unknown };
   objects: SerializedFabricObject[];
@@ -141,7 +212,10 @@ 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. |
@@ -154,7 +228,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`, `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`, `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. |
 
@@ -169,7 +243,10 @@ 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. |
@@ -183,7 +260,7 @@ A failed load never clears or half-fills your canvas.
 | --- | --- |
 | 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.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

@@ -8,6 +8,7 @@ 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) {
@@ -16,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();
@@ -58,7 +60,19 @@ function createDocumentEngine(options) {
 			rebuildIndex();
 			return require_fabric_adapter.serializeCanvas(canvas, registry.propertiesToInclude()).objects;
 		},
-		onChange: (state) => events.emit("history:change", state)
+		onChange: (state) => events.emit("history:change", state),
+		onContentChange: () => saving.noteContentChange()
+	});
+	const saving = require_save_controller.createSaveController({
+		getStorage: () => requireStorage(),
+		createDocument: () => 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();
@@ -73,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()
@@ -127,6 +142,7 @@ function createDocumentEngine(options) {
 			};
 			rebuildIndex();
 			history.reset();
+			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
 			events.emit("load:success", { document });
 			return document;
@@ -150,27 +166,19 @@ function createDocumentEngine(options) {
 			stored = await source.loadDocument(documentId);
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
-			const engineError = new require_errors.DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
+			const engineError = require_errors.isDocumentEngineError(error) ? error : new require_errors.DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
 		return loadDocument(stored, loadOptions);
 	}
-	async function save() {
-		ensureUsable();
-		const target = requireStorage();
-		const document = toDocument();
-		events.emit("save:start", { document });
+	function save(saveOptions) {
 		try {
-			await target.saveDocument(document);
+			ensureUsable();
 		} catch (error) {
-			const reason = error instanceof Error ? error.message : String(error);
-			const engineError = new require_errors.DocumentEngineError("SAVE_FAILED", `Storage could not save the document: ${reason}`, { cause: error });
-			events.emit("save:error", { error: engineError });
-			throw engineError;
+			return Promise.reject(error);
 		}
-		events.emit("save:success", { document });
-		return document;
+		return saving.save(saveOptions);
 	}
 	function newDocument(newOptions) {
 		ensureUsable();
@@ -179,6 +187,7 @@ function createDocumentEngine(options) {
 		objectsById.clear();
 		documentInfo = require_create_document.createDocumentInfo(newOptions);
 		history.reset();
+		saving.startSession(0);
 	}
 	function getObjectById(id) {
 		ensureUsable();
@@ -203,6 +212,7 @@ function createDocumentEngine(options) {
 		destroyed = true;
 		activeLoad?.abort();
 		history.destroy();
+		saving.destroy();
 		canvas.off("object:added", handleObjectAdded);
 		canvas.off("object:removed", handleObjectRemoved);
 		objectsById.clear();
@@ -223,12 +233,15 @@ function createDocumentEngine(options) {
 					...changes
 				}
 			};
+			saving.noteContentChange();
 		},
 		newDocument,
 		toDocument,
 		loadDocument,
 		load,
 		save,
+		isDirty: () => saving.state().isDirty,
+		getSaveState: () => saving.state(),
 		registerObject(definition) {
 			ensureUsable();
 			registry.register(definition);

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

@@ -2,20 +2,22 @@ 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;
@@ -39,6 +41,8 @@ export interface DocumentEngineEvents {
   "save:error": {
     error: DocumentEngineError;
   };
+  "save:retry": SaveRetryEvent;
+  "save:status": SaveState;
   "history:change": HistoryState;
   "history:error": {
     error: DocumentEngineError;
@@ -52,7 +56,9 @@ export interface DocumentEngine {
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
-  save(): Promise<FabricDocument>;
+  save(options?: SaveOptions): Promise<FabricDocument>;
+  isDirty(): boolean;
+  getSaveState(): SaveState;
   registerObject(definition: CustomObjectDefinition): void;
   transaction<Result>(label: string, work: () => Result): Result;
   commit(label?: string): boolean;

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

@@ -2,20 +2,22 @@ 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;
@@ -39,6 +41,8 @@ export interface DocumentEngineEvents {
   "save:error": {
     error: DocumentEngineError;
   };
+  "save:retry": SaveRetryEvent;
+  "save:status": SaveState;
   "history:change": HistoryState;
   "history:error": {
     error: DocumentEngineError;
@@ -52,7 +56,9 @@ export interface DocumentEngine {
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
-  save(): Promise<FabricDocument>;
+  save(options?: SaveOptions): Promise<FabricDocument>;
+  isDirty(): boolean;
+  getSaveState(): SaveState;
   registerObject(definition: CustomObjectDefinition): void;
   transaction<Result>(label: string, work: () => Result): Result;
   commit(label?: string): boolean;

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

@@ -8,6 +8,7 @@ import { readObjectId, writeObjectId } from "../fabric/object-ids.js";
 import { DocumentEngineError, isDocumentEngineError } from "./errors.js";
 import { createObjectRegistry } from "../fabric/object-registry.js";
 import { createHistory } from "../history/create-history.js";
+import { createSaveController } from "../save/save-controller.js";
 import { createEventEmitter } from "./event-emitter.js";
 //#region src/engine/create-document-engine.ts
 function describeDocumentId(value) {
@@ -16,6 +17,7 @@ function describeDocumentId(value) {
 }
 function createDocumentEngine(options) {
 	const { canvas, storage } = options;
+	if (options.autosave && !storage) throw new DocumentEngineError("STORAGE_MISSING", "Autosave needs a storage adapter passed to createDocumentEngine");
 	const registry = createObjectRegistry(options.customObjects);
 	const events = createEventEmitter();
 	const objectsById = /* @__PURE__ */ new Map();
@@ -58,7 +60,19 @@ function createDocumentEngine(options) {
 			rebuildIndex();
 			return serializeCanvas(canvas, registry.propertiesToInclude()).objects;
 		},
-		onChange: (state) => events.emit("history:change", state)
+		onChange: (state) => events.emit("history:change", state),
+		onContentChange: () => saving.noteContentChange()
+	});
+	const saving = createSaveController({
+		getStorage: () => requireStorage(),
+		createDocument: () => 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();
@@ -73,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()
@@ -127,6 +142,7 @@ function createDocumentEngine(options) {
 			};
 			rebuildIndex();
 			history.reset();
+			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
 			events.emit("load:success", { document });
 			return document;
@@ -150,27 +166,19 @@ function createDocumentEngine(options) {
 			stored = await source.loadDocument(documentId);
 		} catch (error) {
 			const reason = error instanceof Error ? error.message : String(error);
-			const engineError = new DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
+			const engineError = isDocumentEngineError(error) ? error : new DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
 		return loadDocument(stored, loadOptions);
 	}
-	async function save() {
-		ensureUsable();
-		const target = requireStorage();
-		const document = toDocument();
-		events.emit("save:start", { document });
+	function save(saveOptions) {
 		try {
-			await target.saveDocument(document);
+			ensureUsable();
 		} catch (error) {
-			const reason = error instanceof Error ? error.message : String(error);
-			const engineError = new DocumentEngineError("SAVE_FAILED", `Storage could not save the document: ${reason}`, { cause: error });
-			events.emit("save:error", { error: engineError });
-			throw engineError;
+			return Promise.reject(error);
 		}
-		events.emit("save:success", { document });
-		return document;
+		return saving.save(saveOptions);
 	}
 	function newDocument(newOptions) {
 		ensureUsable();
@@ -179,6 +187,7 @@ function createDocumentEngine(options) {
 		objectsById.clear();
 		documentInfo = createDocumentInfo(newOptions);
 		history.reset();
+		saving.startSession(0);
 	}
 	function getObjectById(id) {
 		ensureUsable();
@@ -203,6 +212,7 @@ function createDocumentEngine(options) {
 		destroyed = true;
 		activeLoad?.abort();
 		history.destroy();
+		saving.destroy();
 		canvas.off("object:added", handleObjectAdded);
 		canvas.off("object:removed", handleObjectRemoved);
 		objectsById.clear();
@@ -223,12 +233,15 @@ function createDocumentEngine(options) {
 					...changes
 				}
 			};
+			saving.noteContentChange();
 		},
 		newDocument,
 		toDocument,
 		loadDocument,
 		load,
 		save,
+		isDirty: () => saving.state().isDirty,
+		getSaveState: () => saving.state(),
 		registerObject(definition) {
 			ensureUsable();
 			registry.register(definition);

package/dist/engine/errors.cjs

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

package/dist/engine/errors.d.cts

@@ -1,5 +1,5 @@
 //#region src/engine/errors.d.ts
-export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "HISTORY_FAILED" | "ENGINE_DESTROYED";
+export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "SAVE_CONFLICT" | "SAVE_CANCELLED" | "DOCUMENT_NOT_FOUND" | "HISTORY_FAILED" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -9,13 +9,16 @@ export interface DocumentEngineErrorDetails {
   issues?: DocumentIssue[];
   unknownTypes?: string[];
   cause?: unknown;
+  retryable?: boolean;
 }
 export declare class DocumentEngineError extends Error {
   readonly code: DocumentErrorCode;
   readonly issues: DocumentIssue[];
   readonly unknownTypes: string[];
   readonly cause: unknown;
+  readonly retryable: boolean;
   constructor(code: DocumentErrorCode, message: string, details?: DocumentEngineErrorDetails);
 }
 export declare function isDocumentEngineError(value: unknown): value is DocumentEngineError;
+export declare function createConflictError(documentId: string, expectedRevision: number, actualRevision: number): DocumentEngineError;
 //#endregion

package/dist/engine/errors.d.ts

@@ -1,5 +1,5 @@
 //#region src/engine/errors.d.ts
-export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "HISTORY_FAILED" | "ENGINE_DESTROYED";
+export type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "STORAGE_MISSING" | "SAVE_FAILED" | "SAVE_CONFLICT" | "SAVE_CANCELLED" | "DOCUMENT_NOT_FOUND" | "HISTORY_FAILED" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -9,13 +9,16 @@ export interface DocumentEngineErrorDetails {
   issues?: DocumentIssue[];
   unknownTypes?: string[];
   cause?: unknown;
+  retryable?: boolean;
 }
 export declare class DocumentEngineError extends Error {
   readonly code: DocumentErrorCode;
   readonly issues: DocumentIssue[];
   readonly unknownTypes: string[];
   readonly cause: unknown;
+  readonly retryable: boolean;
   constructor(code: DocumentErrorCode, message: string, details?: DocumentEngineErrorDetails);
 }
 export declare function isDocumentEngineError(value: unknown): value is DocumentEngineError;
+export declare function createConflictError(documentId: string, expectedRevision: number, actualRevision: number): DocumentEngineError;
 //#endregion

package/dist/engine/errors.js

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

package/dist/history/create-history.cjs

@@ -24,7 +24,7 @@ function describePendingChanges(changes) {
 	return changes.length === 1 ? `${verb} ${changes[0].noun}` : `${verb} ${changes.length} objects`;
 }
 function createHistory(options) {
-	const { canvas, serializeObjects, onChange } = options;
+	const { canvas, serializeObjects, onChange, onContentChange } = options;
 	const stack = require_history_stack.createHistoryStack(Math.max(1, options.limit ?? 100));
 	let snapshot = require_snapshot.createSnapshot(serializeObjects());
 	let pendingChanges = [];
@@ -53,6 +53,7 @@ function createHistory(options) {
 			label,
 			...difference
 		});
+		onContentChange();
 		onChange(state());
 		return true;
 	}
@@ -155,6 +156,7 @@ function createHistory(options) {
 			}
 			snapshot = require_snapshot.createSnapshot(serializeObjects());
 			moveTo(step);
+			onContentChange();
 			onChange(state());
 			return true;
 		});

package/dist/history/create-history.js

@@ -24,7 +24,7 @@ function describePendingChanges(changes) {
 	return changes.length === 1 ? `${verb} ${changes[0].noun}` : `${verb} ${changes.length} objects`;
 }
 function createHistory(options) {
-	const { canvas, serializeObjects, onChange } = options;
+	const { canvas, serializeObjects, onChange, onContentChange } = options;
 	const stack = createHistoryStack(Math.max(1, options.limit ?? 100));
 	let snapshot = createSnapshot(serializeObjects());
 	let pendingChanges = [];
@@ -53,6 +53,7 @@ function createHistory(options) {
 			label,
 			...difference
 		});
+		onContentChange();
 		onChange(state());
 		return true;
 	}
@@ -155,6 +156,7 @@ function createHistory(options) {
 			}
 			snapshot = createSnapshot(serializeObjects());
 			moveTo(step);
+			onContentChange();
 			onChange(state());
 			return true;
 		});