fabricjs-document-engine 0.5.0 → 0.6.0

package/README.md

@@ -13,6 +13,7 @@ Fabric already draws objects, handles interaction and serializes to JSON. This p
 - **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.
 - **Dependable export.** PNG, JPEG, WebP, SVG and editable JSON. You choose the area, scale and background. A preflight check means an export either succeeds or tells you exactly which image or font prevents it.
+- **Versions and migration.** Keep named versions, restore any of them as a new revision, and open plain Fabric JSON or documents saved by older versions of this package.
 - **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.
 
@@ -218,6 +219,33 @@ const check = await engine.preflightExport({ format: 'png' });
 if (!check.ok) showProblems(check.problems);
 ```
 
+## Versions
+
+```ts
+const version = await engine.createVersion('Sent to client');
+const versions = await engine.listVersions();
+await engine.restoreVersion(version.id);
+await engine.deleteVersion(version.id);
+```
+
+- Versions are full copies of the document, kept in your storage adapter. The built-in adapters support them. A custom adapter adds four methods: `saveVersion(version)`, `listVersions(documentId)`, `loadVersion(documentId, versionId)` and `deleteVersion(documentId, versionId)`.
+- `listVersions` returns summaries, newest first: `{ id, documentId, name, kind, createdAt, revision }`. `kind` is `named` or `auto`.
+- **Restoring never loses work.** The engine first keeps an automatic version named `Before restoring "..."`. It then loads the old content as a new, unsaved revision of the same document. The next save stores it as the newest revision, and history stays linear. To undo a restore, restore the automatic version.
+- **Automatic versions.** Use `versions: { autoEvery: 10, keepAuto: 20 }` to keep a version after every 10 successful saves. Named versions are never pruned. Only the newest `keepAuto` automatic versions are kept, 20 by default.
+- Undo and redo cover recent edits in this session. Versions preserve chosen states for later.
+
+## Migration and importing Fabric JSON
+
+Plain Fabric JSON, such as the output of `canvas.toJSON()` from Fabric 5, 6 or 7, opens directly:
+
+```ts
+await engine.importFabricJson(savedJsonText, { id: 'plan-42', metadata: { source: 'old editor' } });
+```
+
+`loadDocument` and `load(id)` also recognise plain Fabric JSON, so projects stored by an existing Fabric app open without a separate import step. A document loaded with `load(id)` keeps that id, and its next save stores it in the current format.
+
+Every document records its `schemaVersion`. When the package format changes, older documents are upgraded step by step when they are opened. `load:success` reports `migratedFrom` when that happened. A failed step rejects with `MIGRATION_FAILED`, and `error.migrationFrom` names the version it started from. A document from a newer version of the package is refused with `UNSUPPORTED_SCHEMA` rather than being misread. `migrateDocument(value, context)` and `detectSchemaVersion(value)` are exported for tooling such as server-side batch upgrades.
+
 ## Recovery
 
 ```ts
@@ -342,6 +370,9 @@ Keep project data such as titles, owners and tags in `metadata` with `engine.upd
 | `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({ overwrite? })` | Reads from or writes to your storage adapter. |
+| `engine.importFabricJson(json, { id?, metadata? })` | Opens plain Fabric JSON, as text or an object. |
+| `engine.createVersion(name?)` / `engine.listVersions()` | Keeps a named version, or lists versions newest first. |
+| `engine.restoreVersion(id)` / `engine.deleteVersion(id)` | Restores a version as a new unsaved revision, or deletes it. |
 | `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. |
@@ -367,7 +398,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`, `recovery:checkpoint`, `recovery:restored`, `recovery:error`, `export:success`, `export: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`, `assets:warning`, `recovery:checkpoint`, `recovery:restored`, `recovery:error`, `export:success`, `export:error`, `version:created`, `version:restored`, `version: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. |
 
@@ -390,6 +421,10 @@ 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. |
+| `MIGRATION_FAILED` | An older document could not be upgraded. `error.migrationFrom` is the schema version it started from. |
+| `VERSIONS_UNSUPPORTED` | The storage adapter has no version methods. |
+| `VERSION_NOT_FOUND` | There is no version with that id. |
+| `VERSION_FAILED` | An automatic version could not be kept. It is delivered as a `version:error` event. |
 | `EXPORT_BLOCKED` | The preflight found problems. `error.problems` lists each one with the objects involved. |
 | `INVALID_EXPORT_OPTIONS` | The format, scale, quality, area or padding is not valid, or the area is empty. |
 | `EXPORT_ABORTED` | The export was cancelled with its `signal`. |
@@ -413,7 +448,7 @@ A failed load never clears or half-fills your canvas.
 | 4 | Assets and fonts | 0.3.0 |
 | 5 | Recovery after a refresh or crash | 0.4.0 |
 | 6 | PNG, JPEG, SVG and JSON export with preflight checks | 0.5.0 |
-| 7 | Named versions and schema migrations | |
+| 7 | Named versions and schema migrations | 0.6.0 |
 | 8 | React adapter and examples | |
 | 9 | Hardening and benchmarks | |
 | 10 | Stable API | 1.0.0 |

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

@@ -15,7 +15,9 @@ const require_validate_document = require("../document/validate-document.cjs");
 const require_fabric_adapter = require("../fabric/fabric-adapter.cjs");
 const require_object_registry = require("../fabric/object-registry.cjs");
 const require_create_history = require("../history/create-history.cjs");
+const require_migrate_document = require("../migrations/migrate-document.cjs");
 const require_recovery_controller = require("../recovery/recovery-controller.cjs");
+const require_document_version = require("../versions/document-version.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
@@ -91,6 +93,7 @@ function createDocumentEngine(options) {
 		onSuccess: (document) => {
 			if (recovery && !saving.state().isDirty) recovery.remove(document.id);
 			events.emit("save:success", { document });
+			createAutomaticVersionAfterSave(document);
 		},
 		onError: (error) => events.emit("save:error", { error }),
 		onRetry: (event) => events.emit("save:retry", event)
@@ -155,7 +158,10 @@ function createDocumentEngine(options) {
 		if (unknownTypes.length > 0) throw new require_errors.DocumentEngineError("UNKNOWN_OBJECT_TYPE", `The document uses object types that are not registered: ${unknownTypes.join(", ")}. Register them with customObjects or engine.registerObject before loading.`, { unknownTypes });
 		return document;
 	}
-	async function loadDocument(input, loadOptions = {}) {
+	function loadDocument(input, loadOptions = {}) {
+		return loadMigratedDocument(input, loadOptions, {});
+	}
+	async function loadMigratedDocument(input, loadOptions, importDetails) {
 		ensureUsable();
 		activeLoad?.abort();
 		const controller = new AbortController();
@@ -165,7 +171,12 @@ function createDocumentEngine(options) {
 		try {
 			await recovery?.markLoadStarted(documentId);
 			if (controller.signal.aborted) throw new Error("aborted");
-			const checked = checkDocument(input);
+			const { document: migrated, migratedFrom } = require_migrate_document.migrateDocument(input, {
+				canvasWidth: canvas.getWidth(),
+				canvasHeight: canvas.getHeight(),
+				...importDetails
+			});
+			const checked = checkDocument(migrated);
 			const { document, warnings } = await require_asset_pipeline.prepareAssetsForLoad(checked, assetOptions, controller.signal);
 			if (controller.signal.aborted) throw new Error("aborted");
 			await history.withoutRecording(() => require_fabric_adapter.loadIntoCanvas(canvas, {
@@ -192,7 +203,8 @@ function createDocumentEngine(options) {
 			if (warnings.length > 0) events.emit("assets:warning", { warnings });
 			events.emit("load:success", {
 				document,
-				warnings
+				warnings,
+				migratedFrom
 			});
 			return document;
 		} catch (error) {
@@ -206,6 +218,90 @@ function createDocumentEngine(options) {
 			}
 		}
 	}
+	function importFabricJson(json, importOptions = {}) {
+		let parsed = json;
+		if (typeof json === "string") try {
+			parsed = JSON.parse(json);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			return Promise.reject(new require_errors.DocumentEngineError("INVALID_DOCUMENT", `The text is not valid JSON: ${reason}`, { cause: error }));
+		}
+		const { id, metadata, ...loadOptions } = importOptions;
+		return loadMigratedDocument(parsed, loadOptions, {
+			id,
+			metadata
+		});
+	}
+	let savesSinceAutomaticVersion = 0;
+	let lastVersionTime = 0;
+	function nextVersionTimestamp() {
+		lastVersionTime = Math.max(Date.now(), lastVersionTime + 1);
+		return new Date(lastVersionTime).toISOString();
+	}
+	function requireVersions() {
+		ensureUsable();
+		if (!require_document_version.supportsVersions(storage)) throw new require_errors.DocumentEngineError("VERSIONS_UNSUPPORTED", "The storage adapter needs saveVersion, listVersions, loadVersion and deleteVersion to keep versions");
+		return storage;
+	}
+	async function pruneAutomaticVersions(versionStorage, documentId) {
+		const keepAuto = options.versions?.keepAuto ?? 20;
+		const existing = await versionStorage.listVersions(documentId);
+		await Promise.all(require_document_version.versionsToPrune(existing, keepAuto).map((version) => versionStorage.deleteVersion(documentId, version.id)));
+	}
+	async function storeVersion(name, kind, document) {
+		const versionStorage = requireVersions();
+		const content = document ?? (await require_asset_pipeline.prepareAssetsForSave(toDocument(), assetOptions, uploadedUrls)).document;
+		const version = {
+			id: require_ids.createId(),
+			documentId: content.id,
+			name,
+			kind,
+			createdAt: nextVersionTimestamp(),
+			revision: content.revision ?? saving.state().revision,
+			document: content
+		};
+		await versionStorage.saveVersion(version);
+		await pruneAutomaticVersions(versionStorage, content.id);
+		const summary = require_document_version.summarize(version);
+		events.emit("version:created", summary);
+		return summary;
+	}
+	function reportVersionError(error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		const engineError = require_errors.isDocumentEngineError(error) ? error : new require_errors.DocumentEngineError("VERSION_FAILED", `Could not keep an automatic version: ${reason}`, { cause: error });
+		events.emit("version:error", { error: engineError });
+	}
+	function createAutomaticVersionAfterSave(document) {
+		const every = options.versions?.autoEvery ?? 0;
+		if (every <= 0 || !require_document_version.supportsVersions(storage)) return;
+		savesSinceAutomaticVersion += 1;
+		if (savesSinceAutomaticVersion < every) return;
+		savesSinceAutomaticVersion = 0;
+		storeVersion(`Autosave ${(/* @__PURE__ */ new Date()).toLocaleString()}`, "auto", document).catch(reportVersionError);
+	}
+	async function restoreVersion(versionId) {
+		const versionStorage = requireVersions();
+		const current = documentInfo;
+		const version = await versionStorage.loadVersion(current.id, versionId);
+		await storeVersion(`Before restoring "${version.name}"`, "auto");
+		const { document: migrated } = require_migrate_document.migrateDocument(version.document, {
+			canvasWidth: canvas.getWidth(),
+			canvasHeight: canvas.getHeight()
+		});
+		const baseRevision = saving.state().revision;
+		const loaded = await loadDocument({
+			...migrated,
+			id: current.id,
+			createdAt: current.createdAt,
+			revision: baseRevision
+		});
+		noteContentChange();
+		events.emit("version:restored", {
+			version: require_document_version.summarize(version),
+			document: loaded
+		});
+		return loaded;
+	}
 	function requireStorage() {
 		if (!storage) throw new require_errors.DocumentEngineError("STORAGE_MISSING", "Pass a storage adapter to createDocumentEngine to use load and save");
 		return storage;
@@ -222,7 +318,7 @@ function createDocumentEngine(options) {
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
-		return loadDocument(stored, loadOptions);
+		return loadMigratedDocument(stored, loadOptions ?? {}, { id: documentId });
 	}
 	function save(saveOptions) {
 		try {
@@ -419,6 +515,11 @@ function createDocumentEngine(options) {
 		toDocument,
 		loadDocument,
 		load,
+		importFabricJson,
+		createVersion: (name) => storeVersion(name ?? `Version ${(/* @__PURE__ */ new Date()).toLocaleString()}`, "named"),
+		listVersions: async (documentId) => requireVersions().listVersions(documentId ?? documentInfo.id),
+		restoreVersion,
+		deleteVersion: async (versionId) => requireVersions().deleteVersion(documentInfo.id, versionId),
 		save,
 		isDirty: () => saving.state().isDirty,
 		getSaveState: () => saving.state(),

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

@@ -6,6 +6,7 @@ import { ExportPreflight } from "../export/preflight-export.cjs";
 import { NewDocumentOptions } from "../document/create-document.cjs";
 import { CustomObjectDefinition } from "../fabric/object-registry.cjs";
 import { HistoryOptions, HistoryState } from "../history/create-history.cjs";
+import { VersionOptions, VersionSummary } from "../versions/document-version.cjs";
 import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "../recovery/recovery-controller.cjs";
 import { AutosaveOptions } from "../save/autosave-scheduler.cjs";
 import { RetryOptions } from "../save/retry.cjs";
@@ -25,10 +26,15 @@ export interface DocumentEngineOptions {
   saveRetry?: RetryOptions;
   assets?: AssetOptions;
   recovery?: RecoveryOptions;
+  versions?: VersionOptions;
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
 }
+export interface ImportOptions extends LoadOptions {
+  id?: string;
+  metadata?: Record<string, unknown>;
+}
 export interface ExportResult {
   format: ExportFormat;
   mimeType: string;
@@ -45,6 +51,7 @@ export interface DocumentEngineEvents {
   "load:success": {
     document: FabricDocument;
     warnings: AssetWarning[];
+    migratedFrom: number | undefined;
   };
   "assets:warning": {
     warnings: AssetWarning[];
@@ -86,6 +93,14 @@ export interface DocumentEngineEvents {
   "export:error": {
     error: DocumentEngineError;
   };
+  "version:created": VersionSummary;
+  "version:restored": {
+    version: VersionSummary;
+    document: FabricDocument;
+  };
+  "version:error": {
+    error: DocumentEngineError;
+  };
 }
 export interface DocumentEngine {
   readonly canvas: StaticCanvas;
@@ -95,6 +110,11 @@ export interface DocumentEngine {
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
+  importFabricJson(json: string | Record<string, unknown>, options?: ImportOptions): Promise<FabricDocument>;
+  createVersion(name?: string): Promise<VersionSummary>;
+  listVersions(documentId?: string): Promise<VersionSummary[]>;
+  restoreVersion(versionId: string): Promise<FabricDocument>;
+  deleteVersion(versionId: string): Promise<void>;
   save(options?: SaveOptions): Promise<FabricDocument>;
   isDirty(): boolean;
   getSaveState(): SaveState;

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

@@ -6,6 +6,7 @@ import { ExportPreflight } from "../export/preflight-export.js";
 import { NewDocumentOptions } from "../document/create-document.js";
 import { CustomObjectDefinition } from "../fabric/object-registry.js";
 import { HistoryOptions, HistoryState } from "../history/create-history.js";
+import { VersionOptions, VersionSummary } from "../versions/document-version.js";
 import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "../recovery/recovery-controller.js";
 import { AutosaveOptions } from "../save/autosave-scheduler.js";
 import { RetryOptions } from "../save/retry.js";
@@ -25,10 +26,15 @@ export interface DocumentEngineOptions {
   saveRetry?: RetryOptions;
   assets?: AssetOptions;
   recovery?: RecoveryOptions;
+  versions?: VersionOptions;
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
 }
+export interface ImportOptions extends LoadOptions {
+  id?: string;
+  metadata?: Record<string, unknown>;
+}
 export interface ExportResult {
   format: ExportFormat;
   mimeType: string;
@@ -45,6 +51,7 @@ export interface DocumentEngineEvents {
   "load:success": {
     document: FabricDocument;
     warnings: AssetWarning[];
+    migratedFrom: number | undefined;
   };
   "assets:warning": {
     warnings: AssetWarning[];
@@ -86,6 +93,14 @@ export interface DocumentEngineEvents {
   "export:error": {
     error: DocumentEngineError;
   };
+  "version:created": VersionSummary;
+  "version:restored": {
+    version: VersionSummary;
+    document: FabricDocument;
+  };
+  "version:error": {
+    error: DocumentEngineError;
+  };
 }
 export interface DocumentEngine {
   readonly canvas: StaticCanvas;
@@ -95,6 +110,11 @@ export interface DocumentEngine {
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
+  importFabricJson(json: string | Record<string, unknown>, options?: ImportOptions): Promise<FabricDocument>;
+  createVersion(name?: string): Promise<VersionSummary>;
+  listVersions(documentId?: string): Promise<VersionSummary[]>;
+  restoreVersion(versionId: string): Promise<FabricDocument>;
+  deleteVersion(versionId: string): Promise<void>;
   save(options?: SaveOptions): Promise<FabricDocument>;
   isDirty(): boolean;
   getSaveState(): SaveState;

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

@@ -15,7 +15,9 @@ import { validateDocument } from "../document/validate-document.js";
 import { loadIntoCanvas, serializeCanvas } from "../fabric/fabric-adapter.js";
 import { createObjectRegistry } from "../fabric/object-registry.js";
 import { createHistory } from "../history/create-history.js";
+import { migrateDocument } from "../migrations/migrate-document.js";
 import { createRecoveryController, restoreRecordedFiles } from "../recovery/recovery-controller.js";
+import { summarize, supportsVersions, versionsToPrune } from "../versions/document-version.js";
 import { createSaveController } from "../save/save-controller.js";
 import { createEventEmitter } from "./event-emitter.js";
 //#region src/engine/create-document-engine.ts
@@ -91,6 +93,7 @@ function createDocumentEngine(options) {
 		onSuccess: (document) => {
 			if (recovery && !saving.state().isDirty) recovery.remove(document.id);
 			events.emit("save:success", { document });
+			createAutomaticVersionAfterSave(document);
 		},
 		onError: (error) => events.emit("save:error", { error }),
 		onRetry: (event) => events.emit("save:retry", event)
@@ -155,7 +158,10 @@ function createDocumentEngine(options) {
 		if (unknownTypes.length > 0) throw new DocumentEngineError("UNKNOWN_OBJECT_TYPE", `The document uses object types that are not registered: ${unknownTypes.join(", ")}. Register them with customObjects or engine.registerObject before loading.`, { unknownTypes });
 		return document;
 	}
-	async function loadDocument(input, loadOptions = {}) {
+	function loadDocument(input, loadOptions = {}) {
+		return loadMigratedDocument(input, loadOptions, {});
+	}
+	async function loadMigratedDocument(input, loadOptions, importDetails) {
 		ensureUsable();
 		activeLoad?.abort();
 		const controller = new AbortController();
@@ -165,7 +171,12 @@ function createDocumentEngine(options) {
 		try {
 			await recovery?.markLoadStarted(documentId);
 			if (controller.signal.aborted) throw new Error("aborted");
-			const checked = checkDocument(input);
+			const { document: migrated, migratedFrom } = migrateDocument(input, {
+				canvasWidth: canvas.getWidth(),
+				canvasHeight: canvas.getHeight(),
+				...importDetails
+			});
+			const checked = checkDocument(migrated);
 			const { document, warnings } = await prepareAssetsForLoad(checked, assetOptions, controller.signal);
 			if (controller.signal.aborted) throw new Error("aborted");
 			await history.withoutRecording(() => loadIntoCanvas(canvas, {
@@ -192,7 +203,8 @@ function createDocumentEngine(options) {
 			if (warnings.length > 0) events.emit("assets:warning", { warnings });
 			events.emit("load:success", {
 				document,
-				warnings
+				warnings,
+				migratedFrom
 			});
 			return document;
 		} catch (error) {
@@ -206,6 +218,90 @@ function createDocumentEngine(options) {
 			}
 		}
 	}
+	function importFabricJson(json, importOptions = {}) {
+		let parsed = json;
+		if (typeof json === "string") try {
+			parsed = JSON.parse(json);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			return Promise.reject(new DocumentEngineError("INVALID_DOCUMENT", `The text is not valid JSON: ${reason}`, { cause: error }));
+		}
+		const { id, metadata, ...loadOptions } = importOptions;
+		return loadMigratedDocument(parsed, loadOptions, {
+			id,
+			metadata
+		});
+	}
+	let savesSinceAutomaticVersion = 0;
+	let lastVersionTime = 0;
+	function nextVersionTimestamp() {
+		lastVersionTime = Math.max(Date.now(), lastVersionTime + 1);
+		return new Date(lastVersionTime).toISOString();
+	}
+	function requireVersions() {
+		ensureUsable();
+		if (!supportsVersions(storage)) throw new DocumentEngineError("VERSIONS_UNSUPPORTED", "The storage adapter needs saveVersion, listVersions, loadVersion and deleteVersion to keep versions");
+		return storage;
+	}
+	async function pruneAutomaticVersions(versionStorage, documentId) {
+		const keepAuto = options.versions?.keepAuto ?? 20;
+		const existing = await versionStorage.listVersions(documentId);
+		await Promise.all(versionsToPrune(existing, keepAuto).map((version) => versionStorage.deleteVersion(documentId, version.id)));
+	}
+	async function storeVersion(name, kind, document) {
+		const versionStorage = requireVersions();
+		const content = document ?? (await prepareAssetsForSave(toDocument(), assetOptions, uploadedUrls)).document;
+		const version = {
+			id: createId(),
+			documentId: content.id,
+			name,
+			kind,
+			createdAt: nextVersionTimestamp(),
+			revision: content.revision ?? saving.state().revision,
+			document: content
+		};
+		await versionStorage.saveVersion(version);
+		await pruneAutomaticVersions(versionStorage, content.id);
+		const summary = summarize(version);
+		events.emit("version:created", summary);
+		return summary;
+	}
+	function reportVersionError(error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		const engineError = isDocumentEngineError(error) ? error : new DocumentEngineError("VERSION_FAILED", `Could not keep an automatic version: ${reason}`, { cause: error });
+		events.emit("version:error", { error: engineError });
+	}
+	function createAutomaticVersionAfterSave(document) {
+		const every = options.versions?.autoEvery ?? 0;
+		if (every <= 0 || !supportsVersions(storage)) return;
+		savesSinceAutomaticVersion += 1;
+		if (savesSinceAutomaticVersion < every) return;
+		savesSinceAutomaticVersion = 0;
+		storeVersion(`Autosave ${(/* @__PURE__ */ new Date()).toLocaleString()}`, "auto", document).catch(reportVersionError);
+	}
+	async function restoreVersion(versionId) {
+		const versionStorage = requireVersions();
+		const current = documentInfo;
+		const version = await versionStorage.loadVersion(current.id, versionId);
+		await storeVersion(`Before restoring "${version.name}"`, "auto");
+		const { document: migrated } = migrateDocument(version.document, {
+			canvasWidth: canvas.getWidth(),
+			canvasHeight: canvas.getHeight()
+		});
+		const baseRevision = saving.state().revision;
+		const loaded = await loadDocument({
+			...migrated,
+			id: current.id,
+			createdAt: current.createdAt,
+			revision: baseRevision
+		});
+		noteContentChange();
+		events.emit("version:restored", {
+			version: summarize(version),
+			document: loaded
+		});
+		return loaded;
+	}
 	function requireStorage() {
 		if (!storage) throw new DocumentEngineError("STORAGE_MISSING", "Pass a storage adapter to createDocumentEngine to use load and save");
 		return storage;
@@ -222,7 +318,7 @@ function createDocumentEngine(options) {
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
-		return loadDocument(stored, loadOptions);
+		return loadMigratedDocument(stored, loadOptions ?? {}, { id: documentId });
 	}
 	function save(saveOptions) {
 		try {
@@ -419,6 +515,11 @@ function createDocumentEngine(options) {
 		toDocument,
 		loadDocument,
 		load,
+		importFabricJson,
+		createVersion: (name) => storeVersion(name ?? `Version ${(/* @__PURE__ */ new Date()).toLocaleString()}`, "named"),
+		listVersions: async (documentId) => requireVersions().listVersions(documentId ?? documentInfo.id),
+		restoreVersion,
+		deleteVersion: async (versionId) => requireVersions().deleteVersion(documentInfo.id, versionId),
 		save,
 		isDirty: () => saving.state().isDirty,
 		getSaveState: () => saving.state(),

package/dist/engine/errors.cjs

@@ -9,6 +9,7 @@ var DocumentEngineError = class extends Error {
 		this.missingAssets = details.missingAssets ?? [];
 		this.missingFonts = details.missingFonts ?? [];
 		this.problems = details.problems ?? [];
+		this.migrationFrom = details.migrationFrom;
 		this.cause = details.cause;
 		this.retryable = details.retryable ?? false;
 	}

package/dist/engine/errors.d.cts

@@ -1,7 +1,7 @@
 import { FontAsset, ImageAsset } from "../assets/asset-manifest.cjs";
 import { ExportProblem } from "../export/preflight-export.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" | "RECOVERY_MISSING" | "RECOVERY_NOT_FOUND" | "RECOVERY_FAILED" | "INVALID_EXPORT_OPTIONS" | "EXPORT_BLOCKED" | "EXPORT_FAILED" | "EXPORT_ABORTED" | "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" | "MIGRATION_FAILED" | "VERSIONS_UNSUPPORTED" | "VERSION_NOT_FOUND" | "VERSION_FAILED" | "INVALID_EXPORT_OPTIONS" | "EXPORT_BLOCKED" | "EXPORT_FAILED" | "EXPORT_ABORTED" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -13,6 +13,7 @@ export interface DocumentEngineErrorDetails {
   missingAssets?: ImageAsset[];
   missingFonts?: FontAsset[];
   problems?: ExportProblem[];
+  migrationFrom?: number;
   cause?: unknown;
   retryable?: boolean;
 }
@@ -23,6 +24,7 @@ export declare class DocumentEngineError extends Error {
   readonly missingAssets: ImageAsset[];
   readonly missingFonts: FontAsset[];
   readonly problems: ExportProblem[];
+  readonly migrationFrom: number | undefined;
   readonly cause: unknown;
   readonly retryable: boolean;
   constructor(code: DocumentErrorCode, message: string, details?: DocumentEngineErrorDetails);

package/dist/engine/errors.d.ts

@@ -1,7 +1,7 @@
 import { FontAsset, ImageAsset } from "../assets/asset-manifest.js";
 import { ExportProblem } from "../export/preflight-export.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" | "RECOVERY_MISSING" | "RECOVERY_NOT_FOUND" | "RECOVERY_FAILED" | "INVALID_EXPORT_OPTIONS" | "EXPORT_BLOCKED" | "EXPORT_FAILED" | "EXPORT_ABORTED" | "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" | "MIGRATION_FAILED" | "VERSIONS_UNSUPPORTED" | "VERSION_NOT_FOUND" | "VERSION_FAILED" | "INVALID_EXPORT_OPTIONS" | "EXPORT_BLOCKED" | "EXPORT_FAILED" | "EXPORT_ABORTED" | "ENGINE_DESTROYED";
 export interface DocumentIssue {
   code: DocumentErrorCode;
   path: string;
@@ -13,6 +13,7 @@ export interface DocumentEngineErrorDetails {
   missingAssets?: ImageAsset[];
   missingFonts?: FontAsset[];
   problems?: ExportProblem[];
+  migrationFrom?: number;
   cause?: unknown;
   retryable?: boolean;
 }
@@ -23,6 +24,7 @@ export declare class DocumentEngineError extends Error {
   readonly missingAssets: ImageAsset[];
   readonly missingFonts: FontAsset[];
   readonly problems: ExportProblem[];
+  readonly migrationFrom: number | undefined;
   readonly cause: unknown;
   readonly retryable: boolean;
   constructor(code: DocumentErrorCode, message: string, details?: DocumentEngineErrorDetails);

package/dist/engine/errors.js

@@ -9,6 +9,7 @@ var DocumentEngineError = class extends Error {
 		this.missingAssets = details.missingAssets ?? [];
 		this.missingFonts = details.missingFonts ?? [];
 		this.problems = details.problems ?? [];
+		this.migrationFrom = details.migrationFrom;
 		this.cause = details.cause;
 		this.retryable = details.retryable ?? false;
 	}

package/dist/index.cjs

@@ -2,6 +2,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_errors = require("./engine/errors.cjs");
 const require_document_format = require("./document/document-format.cjs");
 const require_validate_document = require("./document/validate-document.cjs");
+const require_migrate_document = require("./migrations/migrate-document.cjs");
 const require_create_document_engine = require("./engine/create-document-engine.cjs");
 const require_keyboard_shortcuts = require("./history/keyboard-shortcuts.cjs");
 const require_unsaved_changes_warning = require("./save/unsaved-changes-warning.cjs");
@@ -12,6 +13,8 @@ exports.bindKeyboardShortcuts = require_keyboard_shortcuts.bindKeyboardShortcuts
 exports.bindUnsavedChangesWarning = require_unsaved_changes_warning.bindUnsavedChangesWarning;
 exports.createConflictError = require_errors.createConflictError;
 exports.createDocumentEngine = require_create_document_engine.createDocumentEngine;
+exports.detectSchemaVersion = require_migrate_document.detectSchemaVersion;
 exports.downloadExport = require_download_export.downloadExport;
 exports.isDocumentEngineError = require_errors.isDocumentEngineError;
+exports.migrateDocument = require_migrate_document.migrateDocument;
 exports.validateDocument = require_validate_document.validateDocument;

package/dist/index.d.cts

@@ -7,6 +7,7 @@ import { ExportPreflight, ExportProblem, ExportProblemCode } from "./export/pref
 import { NewDocumentOptions } from "./document/create-document.cjs";
 import { CustomObjectDefinition } from "./fabric/object-registry.cjs";
 import { HistoryOptions, HistoryState } from "./history/create-history.cjs";
+import { DocumentVersion, VersionKind, VersionOptions, VersionStorage, VersionSummary } from "./versions/document-version.cjs";
 import { RecoveryStore } from "./recovery/recovery-store.cjs";
 import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "./recovery/recovery-controller.cjs";
 import { AutosaveOptions } from "./save/autosave-scheduler.cjs";
@@ -15,9 +16,10 @@ import { DocumentEngineError, DocumentEngineErrorDetails, DocumentErrorCode, Doc
 import { DocumentStorage, SaveContext, SaveResult } from "./storage/storage-contract.cjs";
 import { SaveOptions, SaveRetryEvent, SaveState, SaveStatus } from "./save/save-controller.cjs";
 import { Unsubscribe } from "./engine/event-emitter.cjs";
-import { DocumentEngine, DocumentEngineEvents, DocumentEngineOptions, ExportResult, LoadOptions, createDocumentEngine } from "./engine/create-document-engine.cjs";
+import { DocumentEngine, DocumentEngineEvents, DocumentEngineOptions, ExportResult, ImportOptions, LoadOptions, createDocumentEngine } from "./engine/create-document-engine.cjs";
 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";
 import { DownloadableExport, downloadExport } from "./export/download-export.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 DownloadableExport, type ExportArea, type ExportBackground, type ExportFormat, type ExportOptions, type ExportPreflight, type ExportProblem, type ExportProblemCode, type ExportRect, type ExportResult, 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, downloadExport, isDocumentEngineError, validateDocument };
+import { Migration, MigrationContext, MigrationResult, detectSchemaVersion, migrateDocument } from "./migrations/migrate-document.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 DocumentVersion, type DownloadableExport, type ExportArea, type ExportBackground, type ExportFormat, type ExportOptions, type ExportPreflight, type ExportProblem, type ExportProblemCode, type ExportRect, type ExportResult, type FabricDocument, type FontAsset, type FontLoader, type HistoryOptions, type HistoryState, type ImageAsset, type ImportOptions, type InterruptedLoad, type KeyboardShortcutOptions, type LoadOptions, type Migration, type MigrationContext, type MigrationResult, 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, type VersionKind, type VersionOptions, type VersionStorage, type VersionSummary, bindKeyboardShortcuts, bindUnsavedChangesWarning, createConflictError, createDocumentEngine, detectSchemaVersion, downloadExport, isDocumentEngineError, migrateDocument, validateDocument };

package/dist/index.d.ts

@@ -7,6 +7,7 @@ import { ExportPreflight, ExportProblem, ExportProblemCode } from "./export/pref
 import { NewDocumentOptions } from "./document/create-document.js";
 import { CustomObjectDefinition } from "./fabric/object-registry.js";
 import { HistoryOptions, HistoryState } from "./history/create-history.js";
+import { DocumentVersion, VersionKind, VersionOptions, VersionStorage, VersionSummary } from "./versions/document-version.js";
 import { RecoveryStore } from "./recovery/recovery-store.js";
 import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "./recovery/recovery-controller.js";
 import { AutosaveOptions } from "./save/autosave-scheduler.js";
@@ -15,9 +16,10 @@ import { DocumentEngineError, DocumentEngineErrorDetails, DocumentErrorCode, Doc
 import { DocumentStorage, SaveContext, SaveResult } from "./storage/storage-contract.js";
 import { SaveOptions, SaveRetryEvent, SaveState, SaveStatus } from "./save/save-controller.js";
 import { Unsubscribe } from "./engine/event-emitter.js";
-import { DocumentEngine, DocumentEngineEvents, DocumentEngineOptions, ExportResult, LoadOptions, createDocumentEngine } from "./engine/create-document-engine.js";
+import { DocumentEngine, DocumentEngineEvents, DocumentEngineOptions, ExportResult, ImportOptions, LoadOptions, createDocumentEngine } from "./engine/create-document-engine.js";
 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";
 import { DownloadableExport, downloadExport } from "./export/download-export.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 DownloadableExport, type ExportArea, type ExportBackground, type ExportFormat, type ExportOptions, type ExportPreflight, type ExportProblem, type ExportProblemCode, type ExportRect, type ExportResult, 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, downloadExport, isDocumentEngineError, validateDocument };
+import { Migration, MigrationContext, MigrationResult, detectSchemaVersion, migrateDocument } from "./migrations/migrate-document.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 DocumentVersion, type DownloadableExport, type ExportArea, type ExportBackground, type ExportFormat, type ExportOptions, type ExportPreflight, type ExportProblem, type ExportProblemCode, type ExportRect, type ExportResult, type FabricDocument, type FontAsset, type FontLoader, type HistoryOptions, type HistoryState, type ImageAsset, type ImportOptions, type InterruptedLoad, type KeyboardShortcutOptions, type LoadOptions, type Migration, type MigrationContext, type MigrationResult, 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, type VersionKind, type VersionOptions, type VersionStorage, type VersionSummary, bindKeyboardShortcuts, bindUnsavedChangesWarning, createConflictError, createDocumentEngine, detectSchemaVersion, downloadExport, isDocumentEngineError, migrateDocument, validateDocument };

package/dist/index.js

@@ -1,8 +1,9 @@
 import { DocumentEngineError, createConflictError, isDocumentEngineError } from "./engine/errors.js";
 import { CURRENT_SCHEMA_VERSION } from "./document/document-format.js";
 import { validateDocument } from "./document/validate-document.js";
+import { detectSchemaVersion, migrateDocument } from "./migrations/migrate-document.js";
 import { createDocumentEngine } from "./engine/create-document-engine.js";
 import { bindKeyboardShortcuts } from "./history/keyboard-shortcuts.js";
 import { bindUnsavedChangesWarning } from "./save/unsaved-changes-warning.js";
 import { downloadExport } from "./export/download-export.js";
-export { CURRENT_SCHEMA_VERSION, DocumentEngineError, bindKeyboardShortcuts, bindUnsavedChangesWarning, createConflictError, createDocumentEngine, downloadExport, isDocumentEngineError, validateDocument };
+export { CURRENT_SCHEMA_VERSION, DocumentEngineError, bindKeyboardShortcuts, bindUnsavedChangesWarning, createConflictError, createDocumentEngine, detectSchemaVersion, downloadExport, isDocumentEngineError, migrateDocument, validateDocument };

package/dist/migrations/migrate-document.cjs

@@ -0,0 +1,65 @@
+const require_errors = require("../engine/errors.cjs");
+require("../document/document-format.cjs");
+const require_ids = require("../document/ids.cjs");
+//#region src/migrations/migrate-document.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function positiveNumberOr(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function fromFabricJson(json, context) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const document = {
+		schemaVersion: 1,
+		id: context.id ?? (typeof json.id === "string" && json.id.length > 0 ? json.id : require_ids.createId()),
+		createdAt: now,
+		updatedAt: now,
+		revision: 0,
+		canvas: {
+			width: positiveNumberOr(json.width, context.canvasWidth),
+			height: positiveNumberOr(json.height, context.canvasHeight),
+			...json.background === void 0 ? {} : { background: json.background }
+		},
+		objects: json.objects,
+		metadata: { ...context.metadata }
+	};
+	if (typeof json.version === "string") document.fabricVersion = json.version;
+	return document;
+}
+const migrations = { 0: fromFabricJson };
+function detectSchemaVersion(value) {
+	if (!isPlainObject(value)) return void 0;
+	if (typeof value.schemaVersion === "number" && Number.isInteger(value.schemaVersion)) return value.schemaVersion;
+	if (value.schemaVersion === void 0 && Array.isArray(value.objects)) return 0;
+}
+function migrateDocument(value, context, steps = migrations, targetVersion = 1) {
+	const startVersion = detectSchemaVersion(value);
+	if (startVersion === void 0 || startVersion >= targetVersion || startVersion < 0) return {
+		document: value,
+		migratedFrom: void 0
+	};
+	let document = JSON.parse(JSON.stringify(value));
+	for (let version = startVersion; version < targetVersion; version += 1) {
+		const step = steps[version];
+		if (!step) throw new require_errors.DocumentEngineError("MIGRATION_FAILED", `There is no migration from schema version ${version}`, { migrationFrom: version });
+		try {
+			document = step(document, context);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			throw new require_errors.DocumentEngineError("MIGRATION_FAILED", `Could not migrate the document from schema version ${version} to ${version + 1}: ${reason}`, {
+				cause: error,
+				migrationFrom: version
+			});
+		}
+		if (document.schemaVersion !== version + 1) throw new require_errors.DocumentEngineError("MIGRATION_FAILED", `The migration from schema version ${version} produced version ${String(document.schemaVersion)} instead of ${version + 1}`, { migrationFrom: version });
+	}
+	return {
+		document,
+		migratedFrom: startVersion
+	};
+}
+//#endregion
+exports.detectSchemaVersion = detectSchemaVersion;
+exports.migrateDocument = migrateDocument;
+exports.migrations = migrations;

package/dist/migrations/migrate-document.d.cts

@@ -0,0 +1,15 @@
+//#region src/migrations/migrate-document.d.ts
+export interface MigrationContext {
+  canvasWidth: number;
+  canvasHeight: number;
+  id?: string;
+  metadata?: Record<string, unknown>;
+}
+export type Migration = (document: Record<string, unknown>, context: MigrationContext) => Record<string, unknown>;
+export interface MigrationResult {
+  document: unknown;
+  migratedFrom: number | undefined;
+}
+export declare function detectSchemaVersion(value: unknown): number | undefined;
+export declare function migrateDocument(value: unknown, context: MigrationContext, steps?: Readonly<Record<number, Migration>>, targetVersion?: number): MigrationResult;
+//#endregion

package/dist/migrations/migrate-document.d.ts

@@ -0,0 +1,15 @@
+//#region src/migrations/migrate-document.d.ts
+export interface MigrationContext {
+  canvasWidth: number;
+  canvasHeight: number;
+  id?: string;
+  metadata?: Record<string, unknown>;
+}
+export type Migration = (document: Record<string, unknown>, context: MigrationContext) => Record<string, unknown>;
+export interface MigrationResult {
+  document: unknown;
+  migratedFrom: number | undefined;
+}
+export declare function detectSchemaVersion(value: unknown): number | undefined;
+export declare function migrateDocument(value: unknown, context: MigrationContext, steps?: Readonly<Record<number, Migration>>, targetVersion?: number): MigrationResult;
+//#endregion

package/dist/migrations/migrate-document.js

@@ -0,0 +1,63 @@
+import { DocumentEngineError } from "../engine/errors.js";
+import "../document/document-format.js";
+import { createId } from "../document/ids.js";
+//#region src/migrations/migrate-document.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function positiveNumberOr(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+function fromFabricJson(json, context) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const document = {
+		schemaVersion: 1,
+		id: context.id ?? (typeof json.id === "string" && json.id.length > 0 ? json.id : createId()),
+		createdAt: now,
+		updatedAt: now,
+		revision: 0,
+		canvas: {
+			width: positiveNumberOr(json.width, context.canvasWidth),
+			height: positiveNumberOr(json.height, context.canvasHeight),
+			...json.background === void 0 ? {} : { background: json.background }
+		},
+		objects: json.objects,
+		metadata: { ...context.metadata }
+	};
+	if (typeof json.version === "string") document.fabricVersion = json.version;
+	return document;
+}
+const migrations = { 0: fromFabricJson };
+function detectSchemaVersion(value) {
+	if (!isPlainObject(value)) return void 0;
+	if (typeof value.schemaVersion === "number" && Number.isInteger(value.schemaVersion)) return value.schemaVersion;
+	if (value.schemaVersion === void 0 && Array.isArray(value.objects)) return 0;
+}
+function migrateDocument(value, context, steps = migrations, targetVersion = 1) {
+	const startVersion = detectSchemaVersion(value);
+	if (startVersion === void 0 || startVersion >= targetVersion || startVersion < 0) return {
+		document: value,
+		migratedFrom: void 0
+	};
+	let document = JSON.parse(JSON.stringify(value));
+	for (let version = startVersion; version < targetVersion; version += 1) {
+		const step = steps[version];
+		if (!step) throw new DocumentEngineError("MIGRATION_FAILED", `There is no migration from schema version ${version}`, { migrationFrom: version });
+		try {
+			document = step(document, context);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			throw new DocumentEngineError("MIGRATION_FAILED", `Could not migrate the document from schema version ${version} to ${version + 1}: ${reason}`, {
+				cause: error,
+				migrationFrom: version
+			});
+		}
+		if (document.schemaVersion !== version + 1) throw new DocumentEngineError("MIGRATION_FAILED", `The migration from schema version ${version} produced version ${String(document.schemaVersion)} instead of ${version + 1}`, { migrationFrom: version });
+	}
+	return {
+		document,
+		migratedFrom: startVersion
+	};
+}
+//#endregion
+export { detectSchemaVersion, migrateDocument, migrations };

package/dist/storage/key-value-storage.cjs

@@ -1,4 +1,5 @@
 const require_errors = require("../engine/errors.cjs");
+const require_document_version = require("../versions/document-version.cjs");
 //#region src/storage/key-value-storage.ts
 function readRevision(json) {
 	if (json === null) return 0;
@@ -6,7 +7,19 @@ function readRevision(json) {
 	return typeof revision === "number" ? revision : 0;
 }
 function createKeyValueStorage(store, prefix) {
+	const versionMarker = "::version::";
 	const keyFor = (id) => `${prefix}${id}`;
+	const versionPrefixFor = (documentId) => `${keyFor(documentId)}${versionMarker}`;
+	const versionKeyFor = (documentId, versionId) => `${versionPrefixFor(documentId)}${versionId}`;
+	function readVersion(documentId, versionId) {
+		const json = store.read(versionKeyFor(documentId, versionId));
+		if (json === null) throw new require_errors.DocumentEngineError("VERSION_NOT_FOUND", `Document "${documentId}" has no version "${versionId}"`);
+		return JSON.parse(json);
+	}
+	function versionKeysOf(documentId) {
+		const versionPrefix = versionPrefixFor(documentId);
+		return store.keys().filter((key) => key.startsWith(versionPrefix));
+	}
 	return {
 		async loadDocument(id) {
 			const json = store.read(keyFor(id));
@@ -24,10 +37,23 @@ function createKeyValueStorage(store, prefix) {
 			return { revision };
 		},
 		async listDocuments() {
-			return store.keys().filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+			return store.keys().filter((key) => key.startsWith(prefix) && !key.includes(versionMarker)).map((key) => key.slice(prefix.length));
 		},
 		async deleteDocument(id) {
+			versionKeysOf(id).forEach((key) => store.remove(key));
 			store.remove(keyFor(id));
+		},
+		async saveVersion(version) {
+			store.write(versionKeyFor(version.documentId, version.id), JSON.stringify(version));
+		},
+		async listVersions(documentId) {
+			return versionKeysOf(documentId).map((key) => require_document_version.summarize(JSON.parse(store.read(key) ?? "null"))).sort(require_document_version.newestFirst);
+		},
+		async loadVersion(documentId, versionId) {
+			return readVersion(documentId, versionId);
+		},
+		async deleteVersion(documentId, versionId) {
+			store.remove(versionKeyFor(documentId, versionId));
 		}
 	};
 }

package/dist/storage/key-value-storage.d.cts

@@ -1,3 +1,4 @@
+import { VersionStorage } from "../versions/document-version.cjs";
 import { DocumentStorage } from "./storage-contract.cjs";
 //#region src/storage/key-value-storage.d.ts
 export interface KeyValueStore {
@@ -6,7 +7,7 @@ export interface KeyValueStore {
   remove(key: string): void;
   keys(): string[];
 }
-export interface ManagedDocumentStorage extends DocumentStorage {
+export interface ManagedDocumentStorage extends DocumentStorage, VersionStorage {
   listDocuments(): Promise<string[]>;
   deleteDocument(id: string): Promise<void>;
 }

package/dist/storage/key-value-storage.d.ts

@@ -1,3 +1,4 @@
+import { VersionStorage } from "../versions/document-version.js";
 import { DocumentStorage } from "./storage-contract.js";
 //#region src/storage/key-value-storage.d.ts
 export interface KeyValueStore {
@@ -6,7 +7,7 @@ export interface KeyValueStore {
   remove(key: string): void;
   keys(): string[];
 }
-export interface ManagedDocumentStorage extends DocumentStorage {
+export interface ManagedDocumentStorage extends DocumentStorage, VersionStorage {
   listDocuments(): Promise<string[]>;
   deleteDocument(id: string): Promise<void>;
 }

package/dist/storage/key-value-storage.js

@@ -1,4 +1,5 @@
 import { DocumentEngineError, createConflictError } from "../engine/errors.js";
+import { newestFirst, summarize } from "../versions/document-version.js";
 //#region src/storage/key-value-storage.ts
 function readRevision(json) {
 	if (json === null) return 0;
@@ -6,7 +7,19 @@ function readRevision(json) {
 	return typeof revision === "number" ? revision : 0;
 }
 function createKeyValueStorage(store, prefix) {
+	const versionMarker = "::version::";
 	const keyFor = (id) => `${prefix}${id}`;
+	const versionPrefixFor = (documentId) => `${keyFor(documentId)}${versionMarker}`;
+	const versionKeyFor = (documentId, versionId) => `${versionPrefixFor(documentId)}${versionId}`;
+	function readVersion(documentId, versionId) {
+		const json = store.read(versionKeyFor(documentId, versionId));
+		if (json === null) throw new DocumentEngineError("VERSION_NOT_FOUND", `Document "${documentId}" has no version "${versionId}"`);
+		return JSON.parse(json);
+	}
+	function versionKeysOf(documentId) {
+		const versionPrefix = versionPrefixFor(documentId);
+		return store.keys().filter((key) => key.startsWith(versionPrefix));
+	}
 	return {
 		async loadDocument(id) {
 			const json = store.read(keyFor(id));
@@ -24,10 +37,23 @@ function createKeyValueStorage(store, prefix) {
 			return { revision };
 		},
 		async listDocuments() {
-			return store.keys().filter((key) => key.startsWith(prefix)).map((key) => key.slice(prefix.length));
+			return store.keys().filter((key) => key.startsWith(prefix) && !key.includes(versionMarker)).map((key) => key.slice(prefix.length));
 		},
 		async deleteDocument(id) {
+			versionKeysOf(id).forEach((key) => store.remove(key));
 			store.remove(keyFor(id));
+		},
+		async saveVersion(version) {
+			store.write(versionKeyFor(version.documentId, version.id), JSON.stringify(version));
+		},
+		async listVersions(documentId) {
+			return versionKeysOf(documentId).map((key) => summarize(JSON.parse(store.read(key) ?? "null"))).sort(newestFirst);
+		},
+		async loadVersion(documentId, versionId) {
+			return readVersion(documentId, versionId);
+		},
+		async deleteVersion(documentId, versionId) {
+			store.remove(versionKeyFor(documentId, versionId));
 		}
 	};
 }

package/dist/storage.d.cts

@@ -1,5 +1,6 @@
+import { DocumentVersion, VersionStorage, VersionSummary } from "./versions/document-version.cjs";
 import { DocumentStorage, SaveContext, SaveResult } from "./storage/storage-contract.cjs";
 import { KeyValueStore, ManagedDocumentStorage, createKeyValueStorage } from "./storage/key-value-storage.cjs";
 import { createMemoryStorage } from "./storage/memory-storage.cjs";
 import { LocalStorageOptions, createLocalStorage } from "./storage/local-storage.cjs";
-export { type DocumentStorage, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, createKeyValueStorage, createLocalStorage, createMemoryStorage };
+export { type DocumentStorage, type DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage };

package/dist/storage.d.ts

@@ -1,5 +1,6 @@
+import { DocumentVersion, VersionStorage, VersionSummary } from "./versions/document-version.js";
 import { DocumentStorage, SaveContext, SaveResult } from "./storage/storage-contract.js";
 import { KeyValueStore, ManagedDocumentStorage, createKeyValueStorage } from "./storage/key-value-storage.js";
 import { createMemoryStorage } from "./storage/memory-storage.js";
 import { LocalStorageOptions, createLocalStorage } from "./storage/local-storage.js";
-export { type DocumentStorage, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, createKeyValueStorage, createLocalStorage, createMemoryStorage };
+export { type DocumentStorage, type DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage };

package/dist/versions/document-version.cjs

@@ -0,0 +1,20 @@
+//#region src/versions/document-version.ts
+function summarize(version) {
+	const { document: _document, ...summary } = version;
+	return summary;
+}
+function newestFirst(first, second) {
+	return second.createdAt.localeCompare(first.createdAt);
+}
+function versionsToPrune(versions, keepAuto) {
+	return versions.filter((version) => version.kind === "auto").sort(newestFirst).slice(Math.max(0, keepAuto));
+}
+function supportsVersions(storage) {
+	const candidate = storage;
+	return typeof candidate?.saveVersion === "function" && typeof candidate.listVersions === "function" && typeof candidate.loadVersion === "function" && typeof candidate.deleteVersion === "function";
+}
+//#endregion
+exports.newestFirst = newestFirst;
+exports.summarize = summarize;
+exports.supportsVersions = supportsVersions;
+exports.versionsToPrune = versionsToPrune;

package/dist/versions/document-version.d.cts

@@ -0,0 +1,25 @@
+import { FabricDocument } from "../document/document-format.cjs";
+//#region src/versions/document-version.d.ts
+export type VersionKind = "named" | "auto";
+export interface VersionSummary {
+  id: string;
+  documentId: string;
+  name: string;
+  kind: VersionKind;
+  createdAt: string;
+  revision: number;
+}
+export interface DocumentVersion extends VersionSummary {
+  document: FabricDocument;
+}
+export interface VersionStorage {
+  saveVersion(version: DocumentVersion): Promise<void>;
+  listVersions(documentId: string): Promise<VersionSummary[]>;
+  loadVersion(documentId: string, versionId: string): Promise<DocumentVersion>;
+  deleteVersion(documentId: string, versionId: string): Promise<void>;
+}
+export interface VersionOptions {
+  keepAuto?: number;
+  autoEvery?: number;
+}
+//#endregion

package/dist/versions/document-version.d.ts

@@ -0,0 +1,25 @@
+import { FabricDocument } from "../document/document-format.js";
+//#region src/versions/document-version.d.ts
+export type VersionKind = "named" | "auto";
+export interface VersionSummary {
+  id: string;
+  documentId: string;
+  name: string;
+  kind: VersionKind;
+  createdAt: string;
+  revision: number;
+}
+export interface DocumentVersion extends VersionSummary {
+  document: FabricDocument;
+}
+export interface VersionStorage {
+  saveVersion(version: DocumentVersion): Promise<void>;
+  listVersions(documentId: string): Promise<VersionSummary[]>;
+  loadVersion(documentId: string, versionId: string): Promise<DocumentVersion>;
+  deleteVersion(documentId: string, versionId: string): Promise<void>;
+}
+export interface VersionOptions {
+  keepAuto?: number;
+  autoEvery?: number;
+}
+//#endregion

package/dist/versions/document-version.js

@@ -0,0 +1,17 @@
+//#region src/versions/document-version.ts
+function summarize(version) {
+	const { document: _document, ...summary } = version;
+	return summary;
+}
+function newestFirst(first, second) {
+	return second.createdAt.localeCompare(first.createdAt);
+}
+function versionsToPrune(versions, keepAuto) {
+	return versions.filter((version) => version.kind === "auto").sort(newestFirst).slice(Math.max(0, keepAuto));
+}
+function supportsVersions(storage) {
+	const candidate = storage;
+	return typeof candidate?.saveVersion === "function" && typeof candidate.listVersions === "function" && typeof candidate.loadVersion === "function" && typeof candidate.deleteVersion === "function";
+}
+//#endregion
+export { newestFirst, summarize, supportsVersions, versionsToPrune };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fabricjs-document-engine",
-  "version": "0.5.0",
+  "version": "0.6.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",