fabricjs-document-engine 0.5.0 → 0.7.0

package/README.md

@@ -13,7 +13,9 @@ 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.
+- **React ready, framework free.** Hooks for React, and a small state store for any other framework. Your toolbar and UI stay yours.
 - **Fabric 6 and 7.** Every release is tested against both.
 
 ## Install
@@ -39,6 +41,42 @@ localStorage.setItem(document.id, JSON.stringify(document));
 await engine.loadDocument(JSON.parse(localStorage.getItem(document.id)!));
 ```
 
+## React
+
+```tsx
+import { useDocumentEngine, useDocumentState, DocumentEngineProvider, useEngine } from 'fabricjs-document-engine/react';
+
+function Editor({ canvas }: { canvas: Canvas | null }) {
+  const engine = useDocumentEngine(canvas, { storage, autosave: true });
+  return (
+    <DocumentEngineProvider engine={engine}>
+      <YourToolbar />
+    </DocumentEngineProvider>
+  );
+}
+
+function YourToolbar() {
+  const engine = useEngine();
+  const state = useDocumentState(engine);
+  if (!engine || !state) return null;
+  return (
+    <>
+      <button disabled={!state.canUndo} onClick={() => engine.undo()}>Undo {state.undoLabel}</button>
+      <button disabled={!state.isDirty} onClick={() => engine.save()}>Save</button>
+      <span>{state.saveStatus}</span>
+    </>
+  );
+}
+```
+
+- `useDocumentEngine(canvas, options)` creates the engine once your Fabric canvas exists and destroys it on unmount. It returns `null` until then. Options are read when the engine is created.
+- `useDocumentState(engine)` returns `{ documentId, isLoading, loadError, saveStatus, isDirty, isSaving, revision, lastSavedAt, saveError, canUndo, canRedo, undoLabel, redoLabel, assetWarnings }` and re-renders when any of them change.
+- `useDocumentEvent(engine, 'save:error', handler)` subscribes to any event with the latest handler.
+- `DocumentEngineProvider` and `useEngine()` pass the engine to deeply nested toolbars.
+- The React entry is marked `'use client'` for Next.js. React is an optional peer dependency, so the core never imports it.
+
+For other frameworks, `createDocumentStateStore(engine)` gives the same state as `{ getSnapshot, subscribe }`, which fits Svelte stores, Vue's `shallowRef` and similar tools.
+
 ## Saving and loading through storage
 
 The built-in adapters are the quickest way to start:
@@ -58,6 +96,8 @@ 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)`.
 
+More adapters, including a REST API with revision checks and image uploads, are in [docs/storage-examples.md](https://github.com/re-sohail/fabricjs-document-engine/blob/main/docs/storage-examples.md).
+
 ### Your own backend
 
 A storage adapter is two functions:
@@ -218,6 +258,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 +409,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,8 +437,9 @@ 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`, `document:change`, `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. |
+| `createDocumentStateStore(engine)` | Framework-free `{ getSnapshot, subscribe, destroy }` state for toolbars. |
 | `validateDocument(value)` | Returns a list of issues with the exact path of each problem. |
 
 ## Errors
@@ -390,6 +461,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,11 +488,15 @@ 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 | |
-| 8 | React adapter and examples | |
+| 7 | Named versions and schema migrations | 0.6.0 |
+| 8 | React adapter and examples | 0.7.0 |
 | 9 | Hardening and benchmarks | |
 | 10 | Stable API | 1.0.0 |
 
+## Troubleshooting
+
+Common problems and fixes are in [docs/troubleshooting.md](https://github.com/re-sohail/fabricjs-document-engine/blob/main/docs/troubleshooting.md).
+
 ## License
 
 MIT

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, {
@@ -190,9 +201,11 @@ function createDocumentEngine(options) {
 			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
 			if (warnings.length > 0) events.emit("assets:warning", { warnings });
+			events.emit("document:change", { documentId: document.id });
 			events.emit("load:success", {
 				document,
-				warnings
+				warnings,
+				migratedFrom
 			});
 			return document;
 		} catch (error) {
@@ -206,6 +219,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 +319,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 {
@@ -242,6 +339,7 @@ function createDocumentEngine(options) {
 		history.reset();
 		recovery?.cancel();
 		saving.startSession(0);
+		events.emit("document:change", { documentId: documentInfo.id });
 	}
 	function getObjectById(id) {
 		ensureUsable();
@@ -419,6 +517,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;
@@ -42,9 +48,13 @@ export interface DocumentEngineEvents {
   "load:start": {
     documentId: string | undefined;
   };
+  "document:change": {
+    documentId: string;
+  };
   "load:success": {
     document: FabricDocument;
     warnings: AssetWarning[];
+    migratedFrom: number | undefined;
   };
   "assets:warning": {
     warnings: AssetWarning[];
@@ -86,6 +96,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 +113,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;
@@ -42,9 +48,13 @@ export interface DocumentEngineEvents {
   "load:start": {
     documentId: string | undefined;
   };
+  "document:change": {
+    documentId: string;
+  };
   "load:success": {
     document: FabricDocument;
     warnings: AssetWarning[];
+    migratedFrom: number | undefined;
   };
   "assets:warning": {
     warnings: AssetWarning[];
@@ -86,6 +96,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 +113,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, {
@@ -190,9 +201,11 @@ function createDocumentEngine(options) {
 			saving.startSession(document.revision ?? 0);
 			canvas.requestRenderAll();
 			if (warnings.length > 0) events.emit("assets:warning", { warnings });
+			events.emit("document:change", { documentId: document.id });
 			events.emit("load:success", {
 				document,
-				warnings
+				warnings,
+				migratedFrom
 			});
 			return document;
 		} catch (error) {
@@ -206,6 +219,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 +319,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 {
@@ -242,6 +339,7 @@ function createDocumentEngine(options) {
 		history.reset();
 		recovery?.cancel();
 		saving.startSession(0);
+		events.emit("document:change", { documentId: documentInfo.id });
 	}
 	function getObjectById(id) {
 		ensureUsable();
@@ -419,6 +517,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);