fabricjs-document-engine 0.8.0 → 1.0.1

package/README.md

@@ -156,6 +156,7 @@ engine.on('save:status', ({ status, isDirty, revision, lastSavedAt, error }) =>
 - **Stale responses.** If another document is loaded while a save is running, that save's response is ignored and any queued save is cancelled with `SAVE_CANCELLED`.
 - **Conflicts.** When another tab or device saved first, the save fails with `SAVE_CONFLICT` and the status becomes `conflict`. Either reload the document with `engine.load(id)`, or keep your version with `engine.save({ overwrite: true })`.
 - **Retries.** Temporary failures are retried with exponential backoff and jitter. Each retry emits `save:retry` with `{ attempt, delay, error }`.
+- **Unsaved work is never replaced silently.** With a storage adapter, `load`, `loadDocument`, `importFabricJson` and `newDocument` refuse with `UNSAVED_CHANGES` while there are unsaved changes. Save first, or pass `{ discardUnsavedChanges: true }` when the user chose to throw the changes away.
 
 ### Warn before leaving
 
@@ -402,99 +403,25 @@ interface FabricDocument {
 
 Keep project data such as titles, owners and tags in `metadata` with `engine.updateMetadata()`, rather than on Fabric objects.
 
-## API
-
-| Member | What it does |
-| --- | --- |
-| `createDocumentEngine({ canvas, storage?, customObjects?, document? })` | Connects the engine to your canvas. |
-| `engine.toDocument()` | Serializes the canvas into the versioned document format. |
-| `engine.loadDocument(document, { restoreCanvasSize? })` | Validates and loads a document. Resolves when the objects are on the canvas. |
-| `engine.load(id)` / `engine.save({ 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. |
-| `engine.newDocument({ id?, metadata? })` | Clears the canvas and starts a fresh document. |
-| `engine.getDocumentInfo()` | Returns the current document's id, dates and metadata. |
-| `engine.updateMetadata(changes)` | Merges changes into the document metadata. |
-| `engine.getObjectById(id)` | Finds any object by id, including objects inside groups. |
-| `engine.registerObject({ fabricClass, properties })` | Registers a custom class after the engine is created. |
-| `engine.getAssetManifest()` | Lists the images and fonts used on the canvas. |
-| `engine.checkAssets()` | Resolves to `{ manifest, missingImages, unavailableFonts, warnings }` for the current canvas. |
-| `engine.replaceImage(oldUrl, newUrl)` | Replaces every image with that URL as one undo step. Resolves to the number of images replaced. |
-| `engine.export(options)` | Exports PNG, JPEG, WebP, SVG or JSON. See [Export](#export). |
-| `engine.preflightExport(options)` | Resolves to `{ ok, problems, warnings }` without exporting. |
-| `downloadExport(result, fileName?)` | Starts a browser download of an export result. |
-| `engine.getRecoverableDocuments()` | Lists recovery copies, newest first. |
-| `engine.restoreRecovery(id?)` / `engine.discardRecovery(id?)` | Loads or deletes a recovery copy. The default is the current document. |
-| `engine.getRecovery(id?)` / `engine.flushRecovery()` | Reads a copy, or writes one now. |
-| `engine.getInterruptedLoad()` | Returns the load that was running when the tab last crashed, if any. |
-| `engine.transaction(label, work)` | Runs `work` and records everything it changed as one undo step. Returns what `work` returns. |
-| `engine.commit(label?)` | Records changes made since the last step. Returns `false` when nothing changed. |
-| `engine.undo()` / `engine.redo()` | Resolves to `true` when a step was applied. Calls run one after another. |
-| `engine.canUndo()` / `engine.canRedo()` | Tells you whether a step is available. |
-| `engine.getHistory()` | Returns `{ undo, redo }` label lists, newest first. |
-| `engine.clearHistory()` | Forgets all steps. Loading a document or starting a new one also does this. |
-| `bindKeyboardShortcuts(engine, { target? })` | Adds the undo and redo shortcuts. Returns an unbind function. |
-| `engine.on(event, handler)` | Listens to `load:start`, `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. |
-| `secureDocument(value, limits?)` / `refuseUnsafeImageUrls(objects, isAllowed?)` / `isSafeImageUrl(url)` | The safety checks, exported for server-side validation. |
-| `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
-
-Every failure is a `DocumentEngineError` with a `code` you can switch on:
-
-| Code | Meaning |
-| --- | --- |
-| `UNSAFE_DOCUMENT` | The document broke a safety rule: an unsafe image address, too many objects, or nesting too deep. `error.issues` lists each one. |
-| `INVALID_DOCUMENT` | The document shape is wrong. `error.issues` lists each path, such as `objects[3].objects[1].type`. |
-| `UNSUPPORTED_SCHEMA` | The document was written by a newer version of this package. |
-| `UNKNOWN_OBJECT_TYPE` | A type is not registered. `error.unknownTypes` lists them. |
-| `LOAD_FAILED` | Fabric or your storage could not load the document, for example because an image is missing. `error.cause` holds the original error. |
-| `LOAD_ABORTED` | A newer load started before this one finished. |
-| `MISSING_ASSETS` | Images could not be loaded and had no replacement. `error.missingAssets` lists each `{ url, objectIds }`. |
-| `MISSING_FONTS` | Fonts are not available and `requireFonts` is on. `error.missingFonts` lists them. |
-| `ASSET_UPLOAD_FAILED` | Your `upload` handler failed while saving. |
-| `SAVE_FAILED` | Your storage adapter rejected the save after all retries. `error.retryable` tells you whether trying again could help. |
-| `SAVE_CONFLICT` | Another tab or device saved this document first. |
-| `SAVE_CANCELLED` | A queued save was dropped because another document was opened. |
-| `DOCUMENT_NOT_FOUND` | The built-in adapters have no document with that id. |
-| `HISTORY_FAILED` | Undo or redo could not rebuild an object, for example because an image is gone. The step is kept and the canvas is unchanged. |
-| `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`. |
-| `EXPORT_FAILED` | Fabric could not render the export. `error.cause` holds the original error. |
-| `RECOVERY_MISSING` | A recovery method was called without `recovery: { store }`. |
-| `RECOVERY_NOT_FOUND` | There is no recovery copy for that document. |
-| `RECOVERY_FAILED` | Writing a recovery copy failed, for example because storage is full. It is delivered as a `recovery:error` event and never interrupts editing. |
-| `STORAGE_MISSING` | `load` or `save` was called without a storage adapter. |
-| `INVALID_CUSTOM_OBJECT` | A registered class has no static `type`, or it does not extend a Fabric class. |
-| `ENGINE_DESTROYED` | The engine was used after `destroy()`. |
-
-A failed load never clears or half-fills your canvas.
-
-## Roadmap
-
-| Stage | Focus | Released in |
-| --- | --- | --- |
-| 1 | Document foundation: ids, save and load, validation, custom objects | 0.0.0 |
-| 2 | Undo and redo with transactions | 0.1.0 |
-| 3 | Safe saving: dirty state, autosave, stale-response protection | 0.2.0 |
-| 4 | Assets and fonts | 0.3.0 |
-| 5 | Recovery after a refresh or crash | 0.4.0 |
-| 6 | PNG, JPEG, SVG and JSON export with preflight checks | 0.5.0 |
-| 7 | Named versions and schema migrations | 0.6.0 |
-| 8 | React adapter and examples | 0.7.0 |
-| 9 | Hardening and benchmarks | 0.8.0 |
-| 10 | Stable API | 1.0.0 |
+The format is described by a JSON Schema that ships with the package:
+
+```ts
+import schema from 'fabricjs-document-engine/schema/document-v1.json';
+```
+
+## API reference
+
+Every function, option, event and error code is listed in [docs/api.md](https://github.com/re-sohail/fabricjs-document-engine/blob/main/docs/api.md). Every failure is a `DocumentEngineError` with a stable `code` you can switch on, such as `SAVE_CONFLICT`, `MISSING_ASSETS` or `UNSAVED_CHANGES`. A failed load never clears or half-fills your canvas.
+
+## Stability
+
+Version 1.0 freezes the document format and the adapter contracts:
+
+- Documents are validated by the published JSON Schema at `fabricjs-document-engine/schema/document-v1.json`. Every 1.x release reads every document written by earlier releases, as well as plain Fabric JSON from Fabric 5, 6 and 7.
+- Public API names, options, events and error codes do not change within 1.x. New ones may be added.
+- Storage, version and recovery adapters written for 1.0 keep working. `verifyStorageAdapter(storage)` from `fabricjs-document-engine/storage` checks that your adapter follows the save rules.
+
+The full promise is in the [compatibility policy](https://github.com/re-sohail/fabricjs-document-engine/blob/main/docs/compatibility-policy.md). Tested browsers, Fabric versions and performance results are in [docs/compatibility.md](https://github.com/re-sohail/fabricjs-document-engine/blob/main/docs/compatibility.md), and a complete setup is in the [production guide](https://github.com/re-sohail/fabricjs-document-engine/blob/main/docs/production.md).
 
 ## Imported content and limits
 

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

@@ -163,11 +163,20 @@ function createDocumentEngine(options) {
 	function loadDocument(input, loadOptions = {}) {
 		return loadMigratedDocument(input, loadOptions, {});
 	}
-	async function loadMigratedDocument(input, loadOptions, importDetails) {
-		ensureUsable();
+	function protectUnsavedChanges(discardUnsavedChanges) {
+		if (!storage || discardUnsavedChanges || !saving.state().isDirty) return;
+		throw new require_errors.DocumentEngineError("UNSAVED_CHANGES", "The current document has unsaved changes. Save first, or pass { discardUnsavedChanges: true } to replace it anyway.");
+	}
+	function startLoad() {
 		activeLoad?.abort();
 		const controller = new AbortController();
 		activeLoad = controller;
+		return controller;
+	}
+	async function loadMigratedDocument(input, loadOptions, importDetails, startedLoad) {
+		ensureUsable();
+		protectUnsavedChanges(loadOptions.discardUnsavedChanges);
+		const controller = startedLoad ?? startLoad();
 		const documentId = describeDocumentId(input);
 		events.emit("load:start", { documentId });
 		try {
@@ -297,7 +306,7 @@ function createDocumentEngine(options) {
 			id: current.id,
 			createdAt: current.createdAt,
 			revision: baseRevision
-		});
+		}, { discardUnsavedChanges: true });
 		noteContentChange();
 		events.emit("version:restored", {
 			version: require_document_version.summarize(version),
@@ -312,16 +321,25 @@ function createDocumentEngine(options) {
 	async function load(documentId, loadOptions) {
 		ensureUsable();
 		const source = requireStorage();
+		protectUnsavedChanges(loadOptions?.discardUnsavedChanges);
+		const controller = startLoad();
 		let stored;
 		try {
 			stored = await source.loadDocument(documentId);
+			if (controller.signal.aborted) throw new Error("aborted");
 		} catch (error) {
+			if (activeLoad === controller) activeLoad = null;
+			if (controller.signal.aborted) {
+				const aborted = toLoadError(error, controller.signal);
+				events.emit("load:error", { error: aborted });
+				throw aborted;
+			}
 			const reason = error instanceof Error ? error.message : String(error);
 			const engineError = require_errors.isDocumentEngineError(error) ? error : new require_errors.DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
-		return loadMigratedDocument(stored, loadOptions ?? {}, { id: documentId });
+		return loadMigratedDocument(stored, loadOptions ?? {}, { id: documentId }, controller);
 	}
 	function save(saveOptions) {
 		try {
@@ -329,10 +347,12 @@ function createDocumentEngine(options) {
 		} catch (error) {
 			return Promise.reject(error);
 		}
+		history.flush();
 		return saving.save(saveOptions);
 	}
-	function newDocument(newOptions) {
+	function newDocument(newOptions = {}) {
 		ensureUsable();
+		protectUnsavedChanges(newOptions.discardUnsavedChanges);
 		activeLoad?.abort();
 		history.withoutRecording(() => canvas.clear());
 		objectsById.clear();
@@ -488,6 +508,8 @@ function createDocumentEngine(options) {
 	}
 	function destroy() {
 		if (destroyed) return;
+		const { disposed } = canvas;
+		if (recovery && saving.state().isDirty && !disposed) recovery.writeNow();
 		destroyed = true;
 		activeLoad?.abort();
 		history.destroy();
@@ -561,6 +583,7 @@ function createDocumentEngine(options) {
 		getHistory: () => history.labels(),
 		clearHistory() {
 			ensureUsable();
+			history.flush();
 			history.reset();
 		},
 		on: (name, handler) => events.on(name, handler),

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

@@ -32,6 +32,10 @@ export interface DocumentEngineOptions {
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
+  discardUnsavedChanges?: boolean;
+}
+export interface NewDocumentRequest extends NewDocumentOptions {
+  discardUnsavedChanges?: boolean;
 }
 export interface ImportOptions extends LoadOptions {
   id?: string;
@@ -111,7 +115,7 @@ export interface DocumentEngine {
   readonly canvas: StaticCanvas;
   getDocumentInfo(): DocumentInfo;
   updateMetadata(changes: Record<string, unknown>): void;
-  newDocument(options?: NewDocumentOptions): void;
+  newDocument(options?: NewDocumentRequest): void;
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;

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

@@ -32,6 +32,10 @@ export interface DocumentEngineOptions {
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
+  discardUnsavedChanges?: boolean;
+}
+export interface NewDocumentRequest extends NewDocumentOptions {
+  discardUnsavedChanges?: boolean;
 }
 export interface ImportOptions extends LoadOptions {
   id?: string;
@@ -111,7 +115,7 @@ export interface DocumentEngine {
   readonly canvas: StaticCanvas;
   getDocumentInfo(): DocumentInfo;
   updateMetadata(changes: Record<string, unknown>): void;
-  newDocument(options?: NewDocumentOptions): void;
+  newDocument(options?: NewDocumentRequest): void;
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;

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

@@ -163,11 +163,20 @@ function createDocumentEngine(options) {
 	function loadDocument(input, loadOptions = {}) {
 		return loadMigratedDocument(input, loadOptions, {});
 	}
-	async function loadMigratedDocument(input, loadOptions, importDetails) {
-		ensureUsable();
+	function protectUnsavedChanges(discardUnsavedChanges) {
+		if (!storage || discardUnsavedChanges || !saving.state().isDirty) return;
+		throw new DocumentEngineError("UNSAVED_CHANGES", "The current document has unsaved changes. Save first, or pass { discardUnsavedChanges: true } to replace it anyway.");
+	}
+	function startLoad() {
 		activeLoad?.abort();
 		const controller = new AbortController();
 		activeLoad = controller;
+		return controller;
+	}
+	async function loadMigratedDocument(input, loadOptions, importDetails, startedLoad) {
+		ensureUsable();
+		protectUnsavedChanges(loadOptions.discardUnsavedChanges);
+		const controller = startedLoad ?? startLoad();
 		const documentId = describeDocumentId(input);
 		events.emit("load:start", { documentId });
 		try {
@@ -297,7 +306,7 @@ function createDocumentEngine(options) {
 			id: current.id,
 			createdAt: current.createdAt,
 			revision: baseRevision
-		});
+		}, { discardUnsavedChanges: true });
 		noteContentChange();
 		events.emit("version:restored", {
 			version: summarize(version),
@@ -312,16 +321,25 @@ function createDocumentEngine(options) {
 	async function load(documentId, loadOptions) {
 		ensureUsable();
 		const source = requireStorage();
+		protectUnsavedChanges(loadOptions?.discardUnsavedChanges);
+		const controller = startLoad();
 		let stored;
 		try {
 			stored = await source.loadDocument(documentId);
+			if (controller.signal.aborted) throw new Error("aborted");
 		} catch (error) {
+			if (activeLoad === controller) activeLoad = null;
+			if (controller.signal.aborted) {
+				const aborted = toLoadError(error, controller.signal);
+				events.emit("load:error", { error: aborted });
+				throw aborted;
+			}
 			const reason = error instanceof Error ? error.message : String(error);
 			const engineError = isDocumentEngineError(error) ? error : new DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
-		return loadMigratedDocument(stored, loadOptions ?? {}, { id: documentId });
+		return loadMigratedDocument(stored, loadOptions ?? {}, { id: documentId }, controller);
 	}
 	function save(saveOptions) {
 		try {
@@ -329,10 +347,12 @@ function createDocumentEngine(options) {
 		} catch (error) {
 			return Promise.reject(error);
 		}
+		history.flush();
 		return saving.save(saveOptions);
 	}
-	function newDocument(newOptions) {
+	function newDocument(newOptions = {}) {
 		ensureUsable();
+		protectUnsavedChanges(newOptions.discardUnsavedChanges);
 		activeLoad?.abort();
 		history.withoutRecording(() => canvas.clear());
 		objectsById.clear();
@@ -488,6 +508,8 @@ function createDocumentEngine(options) {
 	}
 	function destroy() {
 		if (destroyed) return;
+		const { disposed } = canvas;
+		if (recovery && saving.state().isDirty && !disposed) recovery.writeNow();
 		destroyed = true;
 		activeLoad?.abort();
 		history.destroy();
@@ -561,6 +583,7 @@ function createDocumentEngine(options) {
 		getHistory: () => history.labels(),
 		clearHistory() {
 			ensureUsable();
+			history.flush();
 			history.reset();
 		},
 		on: (name, handler) => events.on(name, handler),

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" | "UNSAFE_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 type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSAFE_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "MISSING_ASSETS" | "MISSING_FONTS" | "ASSET_UPLOAD_FAILED" | "STORAGE_MISSING" | "UNSAVED_CHANGES" | "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;

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" | "UNSAFE_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 type DocumentErrorCode = "INVALID_DOCUMENT" | "UNSAFE_DOCUMENT" | "UNSUPPORTED_SCHEMA" | "UNKNOWN_OBJECT_TYPE" | "INVALID_CUSTOM_OBJECT" | "LOAD_ABORTED" | "LOAD_FAILED" | "MISSING_ASSETS" | "MISSING_FONTS" | "ASSET_UPLOAD_FAILED" | "STORAGE_MISSING" | "UNSAVED_CHANGES" | "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;

package/dist/history/create-history.cjs

@@ -178,6 +178,7 @@ function createHistory(options) {
 			redo: stack.redoLabels()
 		}),
 		withoutRecording,
+		flush: commitPendingChanges,
 		reset() {
 			pendingChanges = [];
 			stack.clear();

package/dist/history/create-history.js

@@ -178,6 +178,7 @@ function createHistory(options) {
 			redo: stack.redoLabels()
 		}),
 		withoutRecording,
+		flush: commitPendingChanges,
 		reset() {
 			pendingChanges = [];
 			stack.clear();

package/dist/index.d.cts

@@ -17,11 +17,11 @@ 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, ImportOptions, LoadOptions, createDocumentEngine } from "./engine/create-document-engine.cjs";
+import { DocumentEngine, DocumentEngineEvents, DocumentEngineOptions, ExportResult, ImportOptions, LoadOptions, NewDocumentRequest, 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";
 import { Migration, MigrationContext, MigrationResult, detectSchemaVersion, migrateDocument } from "./migrations/migrate-document.cjs";
 import { DocumentState, DocumentStateStore, createDocumentStateStore } from "./state/document-state-store.cjs";
-export { type AssetManifest, type AssetOptions, type AssetReport, type AssetWarning, type AssetWarningCode, type AutosaveOptions, CURRENT_SCHEMA_VERSION, type ContentLimits, type CustomObjectDefinition, type DocumentCanvas, type DocumentEngine, DocumentEngineError, type DocumentEngineErrorDetails, type DocumentEngineEvents, type DocumentEngineOptions, type DocumentErrorCode, type DocumentInfo, type DocumentIssue, type DocumentState, type DocumentStateStore, 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, createDocumentStateStore, detectSchemaVersion, downloadExport, isDocumentEngineError, isSafeImageUrl, migrateDocument, refuseUnsafeImageUrls, secureDocument, validateDocument };
+export { type AssetManifest, type AssetOptions, type AssetReport, type AssetWarning, type AssetWarningCode, type AutosaveOptions, CURRENT_SCHEMA_VERSION, type ContentLimits, type CustomObjectDefinition, type DocumentCanvas, type DocumentEngine, DocumentEngineError, type DocumentEngineErrorDetails, type DocumentEngineEvents, type DocumentEngineOptions, type DocumentErrorCode, type DocumentInfo, type DocumentIssue, type DocumentState, type DocumentStateStore, 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 NewDocumentRequest, 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, createDocumentStateStore, detectSchemaVersion, downloadExport, isDocumentEngineError, isSafeImageUrl, migrateDocument, refuseUnsafeImageUrls, secureDocument, validateDocument };

package/dist/index.d.ts

@@ -17,11 +17,11 @@ 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, ImportOptions, LoadOptions, createDocumentEngine } from "./engine/create-document-engine.js";
+import { DocumentEngine, DocumentEngineEvents, DocumentEngineOptions, ExportResult, ImportOptions, LoadOptions, NewDocumentRequest, 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";
 import { Migration, MigrationContext, MigrationResult, detectSchemaVersion, migrateDocument } from "./migrations/migrate-document.js";
 import { DocumentState, DocumentStateStore, createDocumentStateStore } from "./state/document-state-store.js";
-export { type AssetManifest, type AssetOptions, type AssetReport, type AssetWarning, type AssetWarningCode, type AutosaveOptions, CURRENT_SCHEMA_VERSION, type ContentLimits, type CustomObjectDefinition, type DocumentCanvas, type DocumentEngine, DocumentEngineError, type DocumentEngineErrorDetails, type DocumentEngineEvents, type DocumentEngineOptions, type DocumentErrorCode, type DocumentInfo, type DocumentIssue, type DocumentState, type DocumentStateStore, 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, createDocumentStateStore, detectSchemaVersion, downloadExport, isDocumentEngineError, isSafeImageUrl, migrateDocument, refuseUnsafeImageUrls, secureDocument, validateDocument };
+export { type AssetManifest, type AssetOptions, type AssetReport, type AssetWarning, type AssetWarningCode, type AutosaveOptions, CURRENT_SCHEMA_VERSION, type ContentLimits, type CustomObjectDefinition, type DocumentCanvas, type DocumentEngine, DocumentEngineError, type DocumentEngineErrorDetails, type DocumentEngineEvents, type DocumentEngineOptions, type DocumentErrorCode, type DocumentInfo, type DocumentIssue, type DocumentState, type DocumentStateStore, 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 NewDocumentRequest, 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, createDocumentStateStore, detectSchemaVersion, downloadExport, isDocumentEngineError, isSafeImageUrl, migrateDocument, refuseUnsafeImageUrls, secureDocument, validateDocument };

package/dist/recovery/recovery-controller.cjs

@@ -149,6 +149,7 @@ function createRecoveryController(options) {
 			}, interval);
 		},
 		flush,
+		writeNow: writeCheckpointBeforeThePageCloses,
 		cancel,
 		remove: (documentId) => enqueue(async () => {
 			await store.delete(unloadKey(documentId));

package/dist/recovery/recovery-controller.js

@@ -149,6 +149,7 @@ function createRecoveryController(options) {
 			}, interval);
 		},
 		flush,
+		writeNow: writeCheckpointBeforeThePageCloses,
 		cancel,
 		remove: (documentId) => enqueue(async () => {
 			await store.delete(unloadKey(documentId));

package/dist/storage/verify-storage-adapter.cjs

@@ -0,0 +1,125 @@
+require("../document/document-format.cjs");
+const require_ids = require("../document/ids.cjs");
+const require_document_version = require("../versions/document-version.cjs");
+//#region src/storage/verify-storage-adapter.ts
+function sampleDocument(id, revision, label) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		schemaVersion: 1,
+		id,
+		createdAt: now,
+		updatedAt: now,
+		revision,
+		canvas: {
+			width: 100,
+			height: 100
+		},
+		objects: [{
+			type: "Rect",
+			id: `${id}-shape`,
+			width: 10,
+			height: 10,
+			fill: label
+		}],
+		metadata: { label }
+	};
+}
+function codeOf(error) {
+	return error?.code;
+}
+async function verifyStorageAdapter(storage) {
+	const checks = [];
+	const documentId = `adapter-check-${require_ids.createId()}`;
+	const signal = new AbortController().signal;
+	let revision = 0;
+	async function check(name, work) {
+		try {
+			const problem = await work();
+			checks.push(problem === void 0 ? {
+				name,
+				passed: true
+			} : {
+				name,
+				passed: false,
+				message: problem
+			});
+			return problem === void 0;
+		} catch (error) {
+			checks.push({
+				name,
+				passed: false,
+				message: error instanceof Error ? error.message : String(error)
+			});
+			return false;
+		}
+	}
+	async function saveAt(expectedRevision, label) {
+		return (await storage.saveDocument(sampleDocument(documentId, (expectedRevision ?? revision) + 1, label), {
+			expectedRevision,
+			signal
+		}))?.revision ?? (expectedRevision ?? revision) + 1;
+	}
+	if (await check("saves a new document when expectedRevision is 0", async () => {
+		revision = await saveAt(0, "first");
+		return revision > 0 ? void 0 : `returned revision ${revision}, expected a number above 0`;
+	})) {
+		await check("loads the document it saved", async () => {
+			const loaded = await storage.loadDocument(documentId);
+			if (loaded?.id !== documentId) return `loaded id ${String(loaded?.id)}, expected ${documentId}`;
+			if (loaded.metadata?.label !== "first") return "loaded content differs from what was saved";
+		});
+		await check("refuses a save based on an old revision with code SAVE_CONFLICT", async () => {
+			try {
+				await saveAt(revision - 1, "stale");
+			} catch (error) {
+				return codeOf(error) === "SAVE_CONFLICT" ? void 0 : `rejected with code ${String(codeOf(error))} instead of SAVE_CONFLICT`;
+			}
+			return "the stale save was accepted, so an older tab could overwrite newer work";
+		});
+		await check("accepts a save based on the current revision", async () => {
+			const next = await saveAt(revision, "second");
+			if (next <= revision) return `revision went from ${revision} to ${next}, it must increase`;
+			revision = next;
+			return (await storage.loadDocument(documentId))?.metadata?.label === "second" ? void 0 : "the newer content was not stored";
+		});
+		await check("overwrites when expectedRevision is null", async () => {
+			revision = await saveAt(null, "overwritten");
+			return (await storage.loadDocument(documentId))?.metadata?.label === "overwritten" ? void 0 : "the overwrite was not stored";
+		});
+	}
+	await check("rejects loading a document that does not exist", async () => {
+		try {
+			const missing = await storage.loadDocument(`adapter-check-missing-${require_ids.createId()}`);
+			return missing === void 0 || missing === null ? "resolved with nothing instead of rejecting, which hides a missing document" : "returned a document for an id that was never saved";
+		} catch {
+			return;
+		}
+	});
+	if (require_document_version.supportsVersions(storage)) {
+		const version = {
+			id: `version-${require_ids.createId()}`,
+			documentId,
+			name: "Adapter check",
+			kind: "named",
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			revision,
+			document: sampleDocument(documentId, revision, "versioned")
+		};
+		await check("keeps, lists, loads and deletes versions", async () => {
+			await storage.saveVersion(version);
+			const listed = await storage.listVersions(documentId);
+			if (!listed.some((summary) => summary.id === version.id)) return "listVersions did not include the saved version";
+			if (listed.some((summary) => "document" in summary)) return "listVersions should return summaries without the document";
+			if ((await storage.loadVersion(documentId, version.id)).document.metadata.label !== "versioned") return "loadVersion returned different content";
+			await storage.deleteVersion(documentId, version.id);
+			return (await storage.listVersions(documentId)).some((summary) => summary.id === version.id) ? "deleteVersion did not remove the version" : void 0;
+		});
+	}
+	await storage.deleteDocument?.(documentId).catch(() => void 0);
+	return {
+		ok: checks.every((result) => result.passed),
+		checks
+	};
+}
+//#endregion
+exports.verifyStorageAdapter = verifyStorageAdapter;

package/dist/storage/verify-storage-adapter.d.cts

@@ -0,0 +1,13 @@
+import { DocumentStorage } from "./storage-contract.cjs";
+//#region src/storage/verify-storage-adapter.d.ts
+export interface AdapterCheck {
+  name: string;
+  passed: boolean;
+  message?: string;
+}
+export interface AdapterReport {
+  ok: boolean;
+  checks: AdapterCheck[];
+}
+export declare function verifyStorageAdapter(storage: DocumentStorage): Promise<AdapterReport>;
+//#endregion

package/dist/storage/verify-storage-adapter.d.ts

@@ -0,0 +1,13 @@
+import { DocumentStorage } from "./storage-contract.js";
+//#region src/storage/verify-storage-adapter.d.ts
+export interface AdapterCheck {
+  name: string;
+  passed: boolean;
+  message?: string;
+}
+export interface AdapterReport {
+  ok: boolean;
+  checks: AdapterCheck[];
+}
+export declare function verifyStorageAdapter(storage: DocumentStorage): Promise<AdapterReport>;
+//#endregion

package/dist/storage/verify-storage-adapter.js

@@ -0,0 +1,125 @@
+import "../document/document-format.js";
+import { createId } from "../document/ids.js";
+import { supportsVersions } from "../versions/document-version.js";
+//#region src/storage/verify-storage-adapter.ts
+function sampleDocument(id, revision, label) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		schemaVersion: 1,
+		id,
+		createdAt: now,
+		updatedAt: now,
+		revision,
+		canvas: {
+			width: 100,
+			height: 100
+		},
+		objects: [{
+			type: "Rect",
+			id: `${id}-shape`,
+			width: 10,
+			height: 10,
+			fill: label
+		}],
+		metadata: { label }
+	};
+}
+function codeOf(error) {
+	return error?.code;
+}
+async function verifyStorageAdapter(storage) {
+	const checks = [];
+	const documentId = `adapter-check-${createId()}`;
+	const signal = new AbortController().signal;
+	let revision = 0;
+	async function check(name, work) {
+		try {
+			const problem = await work();
+			checks.push(problem === void 0 ? {
+				name,
+				passed: true
+			} : {
+				name,
+				passed: false,
+				message: problem
+			});
+			return problem === void 0;
+		} catch (error) {
+			checks.push({
+				name,
+				passed: false,
+				message: error instanceof Error ? error.message : String(error)
+			});
+			return false;
+		}
+	}
+	async function saveAt(expectedRevision, label) {
+		return (await storage.saveDocument(sampleDocument(documentId, (expectedRevision ?? revision) + 1, label), {
+			expectedRevision,
+			signal
+		}))?.revision ?? (expectedRevision ?? revision) + 1;
+	}
+	if (await check("saves a new document when expectedRevision is 0", async () => {
+		revision = await saveAt(0, "first");
+		return revision > 0 ? void 0 : `returned revision ${revision}, expected a number above 0`;
+	})) {
+		await check("loads the document it saved", async () => {
+			const loaded = await storage.loadDocument(documentId);
+			if (loaded?.id !== documentId) return `loaded id ${String(loaded?.id)}, expected ${documentId}`;
+			if (loaded.metadata?.label !== "first") return "loaded content differs from what was saved";
+		});
+		await check("refuses a save based on an old revision with code SAVE_CONFLICT", async () => {
+			try {
+				await saveAt(revision - 1, "stale");
+			} catch (error) {
+				return codeOf(error) === "SAVE_CONFLICT" ? void 0 : `rejected with code ${String(codeOf(error))} instead of SAVE_CONFLICT`;
+			}
+			return "the stale save was accepted, so an older tab could overwrite newer work";
+		});
+		await check("accepts a save based on the current revision", async () => {
+			const next = await saveAt(revision, "second");
+			if (next <= revision) return `revision went from ${revision} to ${next}, it must increase`;
+			revision = next;
+			return (await storage.loadDocument(documentId))?.metadata?.label === "second" ? void 0 : "the newer content was not stored";
+		});
+		await check("overwrites when expectedRevision is null", async () => {
+			revision = await saveAt(null, "overwritten");
+			return (await storage.loadDocument(documentId))?.metadata?.label === "overwritten" ? void 0 : "the overwrite was not stored";
+		});
+	}
+	await check("rejects loading a document that does not exist", async () => {
+		try {
+			const missing = await storage.loadDocument(`adapter-check-missing-${createId()}`);
+			return missing === void 0 || missing === null ? "resolved with nothing instead of rejecting, which hides a missing document" : "returned a document for an id that was never saved";
+		} catch {
+			return;
+		}
+	});
+	if (supportsVersions(storage)) {
+		const version = {
+			id: `version-${createId()}`,
+			documentId,
+			name: "Adapter check",
+			kind: "named",
+			createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+			revision,
+			document: sampleDocument(documentId, revision, "versioned")
+		};
+		await check("keeps, lists, loads and deletes versions", async () => {
+			await storage.saveVersion(version);
+			const listed = await storage.listVersions(documentId);
+			if (!listed.some((summary) => summary.id === version.id)) return "listVersions did not include the saved version";
+			if (listed.some((summary) => "document" in summary)) return "listVersions should return summaries without the document";
+			if ((await storage.loadVersion(documentId, version.id)).document.metadata.label !== "versioned") return "loadVersion returned different content";
+			await storage.deleteVersion(documentId, version.id);
+			return (await storage.listVersions(documentId)).some((summary) => summary.id === version.id) ? "deleteVersion did not remove the version" : void 0;
+		});
+	}
+	await storage.deleteDocument?.(documentId).catch(() => void 0);
+	return {
+		ok: checks.every((result) => result.passed),
+		checks
+	};
+}
+//#endregion
+export { verifyStorageAdapter };

package/dist/storage.cjs

@@ -2,6 +2,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_key_value_storage = require("./storage/key-value-storage.cjs");
 const require_memory_storage = require("./storage/memory-storage.cjs");
 const require_local_storage = require("./storage/local-storage.cjs");
+const require_verify_storage_adapter = require("./storage/verify-storage-adapter.cjs");
 exports.createKeyValueStorage = require_key_value_storage.createKeyValueStorage;
 exports.createLocalStorage = require_local_storage.createLocalStorage;
 exports.createMemoryStorage = require_memory_storage.createMemoryStorage;
+exports.verifyStorageAdapter = require_verify_storage_adapter.verifyStorageAdapter;

package/dist/storage.d.cts

@@ -3,4 +3,5 @@ import { DocumentStorage, SaveContext, SaveResult } from "./storage/storage-cont
 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 DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage };
+import { AdapterCheck, AdapterReport, verifyStorageAdapter } from "./storage/verify-storage-adapter.cjs";
+export { type AdapterCheck, type AdapterReport, type DocumentStorage, type DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage, verifyStorageAdapter };

package/dist/storage.d.ts

@@ -3,4 +3,5 @@ import { DocumentStorage, SaveContext, SaveResult } from "./storage/storage-cont
 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 DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage };
+import { AdapterCheck, AdapterReport, verifyStorageAdapter } from "./storage/verify-storage-adapter.js";
+export { type AdapterCheck, type AdapterReport, type DocumentStorage, type DocumentVersion, type KeyValueStore, type LocalStorageOptions, type ManagedDocumentStorage, type SaveContext, type SaveResult, type VersionStorage, type VersionSummary, createKeyValueStorage, createLocalStorage, createMemoryStorage, verifyStorageAdapter };

package/dist/storage.js

@@ -1,4 +1,5 @@
 import { createKeyValueStorage } from "./storage/key-value-storage.js";
 import { createMemoryStorage } from "./storage/memory-storage.js";
 import { createLocalStorage } from "./storage/local-storage.js";
-export { createKeyValueStorage, createLocalStorage, createMemoryStorage };
+import { verifyStorageAdapter } from "./storage/verify-storage-adapter.js";
+export { createKeyValueStorage, createLocalStorage, createMemoryStorage, verifyStorageAdapter };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fabricjs-document-engine",
-  "version": "0.8.0",
+  "version": "1.0.1",
   "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",
@@ -29,6 +29,7 @@
   "sideEffects": false,
   "files": [
     "dist",
+    "schema",
     "README.md",
     "LICENSE"
   ],
@@ -76,6 +77,7 @@
         "default": "./dist/react.cjs"
       }
     },
+    "./schema/document-v1.json": "./schema/document-v1.schema.json",
     "./package.json": "./package.json"
   },
   "scripts": {
@@ -117,6 +119,7 @@
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vitest/browser-playwright": "^5.0.2",
+    "ajv": "^8.20.0",
     "fabric": "^7.4.0",
     "fabric6": "npm:fabric@^6.9.1",
     "playwright": "^1.63.0",

package/schema/document-v1.schema.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://unpkg.com/fabricjs-document-engine/schema/document-v1.schema.json",
+  "title": "Fabric document, schema version 1",
+  "description": "The document format written by fabricjs-document-engine 1.x. Fabric object properties are kept as Fabric serializes them.",
+  "type": "object",
+  "required": ["schemaVersion", "id", "createdAt", "updatedAt", "canvas", "objects", "metadata"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "createdAt": { "type": "string" },
+    "updatedAt": { "type": "string" },
+    "revision": { "type": "integer", "minimum": 0 },
+    "fabricVersion": { "type": "string" },
+    "canvas": {
+      "type": "object",
+      "required": ["width", "height"],
+      "properties": {
+        "width": { "type": "number", "exclusiveMinimum": 0 },
+        "height": { "type": "number", "exclusiveMinimum": 0 },
+        "background": {}
+      }
+    },
+    "objects": { "type": "array", "items": { "$ref": "#/$defs/fabricObject" } },
+    "assets": {
+      "type": "object",
+      "required": ["images", "fonts"],
+      "properties": {
+        "images": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["url", "objectIds"],
+            "properties": {
+              "url": { "type": "string" },
+              "objectIds": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        },
+        "fonts": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["family", "weight", "style", "objectIds"],
+            "properties": {
+              "family": { "type": "string" },
+              "weight": { "type": "string" },
+              "style": { "type": "string" },
+              "objectIds": { "type": "array", "items": { "type": "string" } }
+            }
+          }
+        }
+      }
+    },
+    "metadata": { "type": "object" }
+  },
+  "$defs": {
+    "fabricObject": {
+      "type": "object",
+      "required": ["type"],
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "id": { "type": "string" },
+        "objects": { "type": "array", "items": { "$ref": "#/$defs/fabricObject" } },
+        "clipPath": { "$ref": "#/$defs/fabricObject" }
+      }
+    }
+  }
+}