fabricjs-document-engine 0.6.0 → 0.7.0

package/README.md

@@ -15,6 +15,7 @@ Fabric already draws objects, handles interaction and serializes to JSON. This p
 - **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
@@ -40,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:
@@ -59,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:
@@ -398,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`, `version:created`, `version:restored`, `version: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
@@ -449,10 +489,14 @@ A failed load never clears or half-fills your canvas.
 | 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 | |
+| 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

@@ -201,6 +201,7 @@ 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,
@@ -338,6 +339,7 @@ function createDocumentEngine(options) {
 		history.reset();
 		recovery?.cancel();
 		saving.startSession(0);
+		events.emit("document:change", { documentId: documentInfo.id });
 	}
 	function getObjectById(id) {
 		ensureUsable();

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

@@ -48,6 +48,9 @@ export interface DocumentEngineEvents {
   "load:start": {
     documentId: string | undefined;
   };
+  "document:change": {
+    documentId: string;
+  };
   "load:success": {
     document: FabricDocument;
     warnings: AssetWarning[];

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

@@ -48,6 +48,9 @@ export interface DocumentEngineEvents {
   "load:start": {
     documentId: string | undefined;
   };
+  "document:change": {
+    documentId: string;
+  };
   "load:success": {
     document: FabricDocument;
     warnings: AssetWarning[];

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

@@ -201,6 +201,7 @@ 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,
@@ -338,6 +339,7 @@ function createDocumentEngine(options) {
 		history.reset();
 		recovery?.cancel();
 		saving.startSession(0);
+		events.emit("document:change", { documentId: documentInfo.id });
 	}
 	function getObjectById(id) {
 		ensureUsable();

package/dist/index.cjs

@@ -7,12 +7,14 @@ const require_create_document_engine = require("./engine/create-document-engine.
 const require_keyboard_shortcuts = require("./history/keyboard-shortcuts.cjs");
 const require_unsaved_changes_warning = require("./save/unsaved-changes-warning.cjs");
 const require_download_export = require("./export/download-export.cjs");
+const require_document_state_store = require("./state/document-state-store.cjs");
 exports.CURRENT_SCHEMA_VERSION = require_document_format.CURRENT_SCHEMA_VERSION;
 exports.DocumentEngineError = require_errors.DocumentEngineError;
 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.createDocumentStateStore = require_document_state_store.createDocumentStateStore;
 exports.detectSchemaVersion = require_migrate_document.detectSchemaVersion;
 exports.downloadExport = require_download_export.downloadExport;
 exports.isDocumentEngineError = require_errors.isDocumentEngineError;

package/dist/index.d.cts

@@ -22,4 +22,5 @@ import { KeyboardShortcutOptions, UndoRedoTarget, bindKeyboardShortcuts } from "
 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";
-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 };
+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 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, migrateDocument, validateDocument };

package/dist/index.d.ts

@@ -22,4 +22,5 @@ import { KeyboardShortcutOptions, UndoRedoTarget, bindKeyboardShortcuts } from "
 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";
-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 };
+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 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, migrateDocument, validateDocument };

package/dist/index.js

@@ -6,4 +6,5 @@ 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, detectSchemaVersion, downloadExport, isDocumentEngineError, migrateDocument, validateDocument };
+import { createDocumentStateStore } from "./state/document-state-store.js";
+export { CURRENT_SCHEMA_VERSION, DocumentEngineError, bindKeyboardShortcuts, bindUnsavedChangesWarning, createConflictError, createDocumentEngine, createDocumentStateStore, detectSchemaVersion, downloadExport, isDocumentEngineError, migrateDocument, validateDocument };

package/dist/react/engine-context.cjs

@@ -0,0 +1,12 @@
+let react = require("react");
+//#region src/react/engine-context.ts
+const EngineContext = (0, react.createContext)(null);
+function DocumentEngineProvider({ engine, children }) {
+	return (0, react.createElement)(EngineContext.Provider, { value: engine }, children);
+}
+function useEngine() {
+	return (0, react.useContext)(EngineContext);
+}
+//#endregion
+exports.DocumentEngineProvider = DocumentEngineProvider;
+exports.useEngine = useEngine;

package/dist/react/engine-context.d.cts

@@ -0,0 +1,10 @@
+import { DocumentEngine } from "../engine/create-document-engine.cjs";
+import { ReactNode } from "react";
+//#region src/react/engine-context.d.ts
+export interface DocumentEngineProviderProps {
+  engine: DocumentEngine | null;
+  children?: ReactNode;
+}
+export declare function DocumentEngineProvider({ engine, children }: DocumentEngineProviderProps): ReactNode;
+export declare function useEngine(): DocumentEngine | null;
+//#endregion

package/dist/react/engine-context.d.ts

@@ -0,0 +1,10 @@
+import { DocumentEngine } from "../engine/create-document-engine.js";
+import { ReactNode } from "react";
+//#region src/react/engine-context.d.ts
+export interface DocumentEngineProviderProps {
+  engine: DocumentEngine | null;
+  children?: ReactNode;
+}
+export declare function DocumentEngineProvider({ engine, children }: DocumentEngineProviderProps): ReactNode;
+export declare function useEngine(): DocumentEngine | null;
+//#endregion

package/dist/react/engine-context.js

@@ -0,0 +1,11 @@
+import { createContext, createElement, useContext } from "react";
+//#region src/react/engine-context.ts
+const EngineContext = createContext(null);
+function DocumentEngineProvider({ engine, children }) {
+	return createElement(EngineContext.Provider, { value: engine }, children);
+}
+function useEngine() {
+	return useContext(EngineContext);
+}
+//#endregion
+export { DocumentEngineProvider, useEngine };

package/dist/react/use-document-engine.cjs

@@ -0,0 +1,23 @@
+const require_create_document_engine = require("../engine/create-document-engine.cjs");
+let react = require("react");
+//#region src/react/use-document-engine.ts
+function useDocumentEngine(canvas, options = {}) {
+	const latestOptions = (0, react.useRef)(options);
+	latestOptions.current = options;
+	const [engine, setEngine] = (0, react.useState)(null);
+	(0, react.useEffect)(() => {
+		if (!canvas) return void 0;
+		const created = require_create_document_engine.createDocumentEngine({
+			...latestOptions.current,
+			canvas
+		});
+		setEngine(created);
+		return () => {
+			created.destroy();
+			setEngine((current) => current === created ? null : current);
+		};
+	}, [canvas]);
+	return engine;
+}
+//#endregion
+exports.useDocumentEngine = useDocumentEngine;

package/dist/react/use-document-engine.d.cts

@@ -0,0 +1,6 @@
+import { DocumentEngine, DocumentEngineOptions } from "../engine/create-document-engine.cjs";
+import { StaticCanvas } from "fabric";
+//#region src/react/use-document-engine.d.ts
+export type ReactEngineOptions = Omit<DocumentEngineOptions, "canvas">;
+export declare function useDocumentEngine(canvas: StaticCanvas | null | undefined, options?: ReactEngineOptions): DocumentEngine | null;
+//#endregion

package/dist/react/use-document-engine.d.ts

@@ -0,0 +1,6 @@
+import { DocumentEngine, DocumentEngineOptions } from "../engine/create-document-engine.js";
+import { StaticCanvas } from "fabric";
+//#region src/react/use-document-engine.d.ts
+export type ReactEngineOptions = Omit<DocumentEngineOptions, "canvas">;
+export declare function useDocumentEngine(canvas: StaticCanvas | null | undefined, options?: ReactEngineOptions): DocumentEngine | null;
+//#endregion

package/dist/react/use-document-engine.js

@@ -0,0 +1,23 @@
+import { createDocumentEngine } from "../engine/create-document-engine.js";
+import { useEffect, useRef, useState } from "react";
+//#region src/react/use-document-engine.ts
+function useDocumentEngine(canvas, options = {}) {
+	const latestOptions = useRef(options);
+	latestOptions.current = options;
+	const [engine, setEngine] = useState(null);
+	useEffect(() => {
+		if (!canvas) return void 0;
+		const created = createDocumentEngine({
+			...latestOptions.current,
+			canvas
+		});
+		setEngine(created);
+		return () => {
+			created.destroy();
+			setEngine((current) => current === created ? null : current);
+		};
+	}, [canvas]);
+	return engine;
+}
+//#endregion
+export { useDocumentEngine };

package/dist/react/use-document-event.cjs

@@ -0,0 +1,12 @@
+let react = require("react");
+//#region src/react/use-document-event.ts
+function useDocumentEvent(engine, name, handler) {
+	const latestHandler = (0, react.useRef)(handler);
+	latestHandler.current = handler;
+	(0, react.useEffect)(() => {
+		if (!engine) return void 0;
+		return engine.on(name, (payload) => latestHandler.current(payload));
+	}, [engine, name]);
+}
+//#endregion
+exports.useDocumentEvent = useDocumentEvent;

package/dist/react/use-document-event.d.cts

@@ -0,0 +1,4 @@
+import { DocumentEngine, DocumentEngineEvents } from "../engine/create-document-engine.cjs";
+//#region src/react/use-document-event.d.ts
+export declare function useDocumentEvent<Name extends keyof DocumentEngineEvents>(engine: DocumentEngine | null | undefined, name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): void;
+//#endregion

package/dist/react/use-document-event.d.ts

@@ -0,0 +1,4 @@
+import { DocumentEngine, DocumentEngineEvents } from "../engine/create-document-engine.js";
+//#region src/react/use-document-event.d.ts
+export declare function useDocumentEvent<Name extends keyof DocumentEngineEvents>(engine: DocumentEngine | null | undefined, name: Name, handler: (payload: DocumentEngineEvents[Name]) => void): void;
+//#endregion

package/dist/react/use-document-event.js

@@ -0,0 +1,12 @@
+import { useEffect, useRef } from "react";
+//#region src/react/use-document-event.ts
+function useDocumentEvent(engine, name, handler) {
+	const latestHandler = useRef(handler);
+	latestHandler.current = handler;
+	useEffect(() => {
+		if (!engine) return void 0;
+		return engine.on(name, (payload) => latestHandler.current(payload));
+	}, [engine, name]);
+}
+//#endregion
+export { useDocumentEvent };

package/dist/react/use-document-state.cjs

@@ -0,0 +1,11 @@
+const require_document_state_store = require("../state/document-state-store.cjs");
+let react = require("react");
+//#region src/react/use-document-state.ts
+const subscribeToNothing = () => () => void 0;
+const nothing = () => null;
+function useDocumentState(engine) {
+	const store = (0, react.useMemo)(() => engine ? require_document_state_store.createDocumentStateStore(engine) : null, [engine]);
+	return (0, react.useSyncExternalStore)(store ? store.subscribe : subscribeToNothing, store ? store.getSnapshot : nothing, nothing);
+}
+//#endregion
+exports.useDocumentState = useDocumentState;

package/dist/react/use-document-state.d.cts

@@ -0,0 +1,5 @@
+import { DocumentEngine } from "../engine/create-document-engine.cjs";
+import { DocumentState } from "../state/document-state-store.cjs";
+//#region src/react/use-document-state.d.ts
+export declare function useDocumentState(engine: DocumentEngine | null | undefined): DocumentState | null;
+//#endregion

package/dist/react/use-document-state.d.ts

@@ -0,0 +1,5 @@
+import { DocumentEngine } from "../engine/create-document-engine.js";
+import { DocumentState } from "../state/document-state-store.js";
+//#region src/react/use-document-state.d.ts
+export declare function useDocumentState(engine: DocumentEngine | null | undefined): DocumentState | null;
+//#endregion

package/dist/react/use-document-state.js

@@ -0,0 +1,11 @@
+import { createDocumentStateStore } from "../state/document-state-store.js";
+import { useMemo, useSyncExternalStore } from "react";
+//#region src/react/use-document-state.ts
+const subscribeToNothing = () => () => void 0;
+const nothing = () => null;
+function useDocumentState(engine) {
+	const store = useMemo(() => engine ? createDocumentStateStore(engine) : null, [engine]);
+	return useSyncExternalStore(store ? store.subscribe : subscribeToNothing, store ? store.getSnapshot : nothing, nothing);
+}
+//#endregion
+export { useDocumentState };

package/dist/react.cjs

@@ -0,0 +1,11 @@
+"use client";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_use_document_engine = require("./react/use-document-engine.cjs");
+const require_use_document_state = require("./react/use-document-state.cjs");
+const require_use_document_event = require("./react/use-document-event.cjs");
+const require_engine_context = require("./react/engine-context.cjs");
+exports.DocumentEngineProvider = require_engine_context.DocumentEngineProvider;
+exports.useDocumentEngine = require_use_document_engine.useDocumentEngine;
+exports.useDocumentEvent = require_use_document_event.useDocumentEvent;
+exports.useDocumentState = require_use_document_state.useDocumentState;
+exports.useEngine = require_engine_context.useEngine;

package/dist/react.d.cts

@@ -0,0 +1,6 @@
+import { DocumentState } from "./state/document-state-store.cjs";
+import { ReactEngineOptions, useDocumentEngine } from "./react/use-document-engine.cjs";
+import { useDocumentState } from "./react/use-document-state.cjs";
+import { useDocumentEvent } from "./react/use-document-event.cjs";
+import { DocumentEngineProvider, DocumentEngineProviderProps, useEngine } from "./react/engine-context.cjs";
+export { DocumentEngineProvider, type DocumentEngineProviderProps, type DocumentState, type ReactEngineOptions, useDocumentEngine, useDocumentEvent, useDocumentState, useEngine };

package/dist/react.d.ts

@@ -0,0 +1,6 @@
+import { DocumentState } from "./state/document-state-store.js";
+import { ReactEngineOptions, useDocumentEngine } from "./react/use-document-engine.js";
+import { useDocumentState } from "./react/use-document-state.js";
+import { useDocumentEvent } from "./react/use-document-event.js";
+import { DocumentEngineProvider, DocumentEngineProviderProps, useEngine } from "./react/engine-context.js";
+export { DocumentEngineProvider, type DocumentEngineProviderProps, type DocumentState, type ReactEngineOptions, useDocumentEngine, useDocumentEvent, useDocumentState, useEngine };

package/dist/react.js

@@ -0,0 +1,6 @@
+"use client";
+import { useDocumentEngine } from "./react/use-document-engine.js";
+import { useDocumentState } from "./react/use-document-state.js";
+import { useDocumentEvent } from "./react/use-document-event.js";
+import { DocumentEngineProvider, useEngine } from "./react/engine-context.js";
+export { DocumentEngineProvider, useDocumentEngine, useDocumentEvent, useDocumentState, useEngine };

package/dist/state/document-state-store.cjs

@@ -0,0 +1,114 @@
+//#region src/state/document-state-store.ts
+function initialState(engine) {
+	const saveState = engine.getSaveState();
+	const history = engine.getHistory();
+	return {
+		documentId: engine.getDocumentInfo().id,
+		isLoading: false,
+		loadError: void 0,
+		saveStatus: saveState.status,
+		isDirty: saveState.isDirty,
+		isSaving: saveState.isSaving,
+		revision: saveState.revision,
+		lastSavedAt: saveState.lastSavedAt,
+		saveError: saveState.error,
+		canUndo: history.undo.length > 0,
+		canRedo: history.redo.length > 0,
+		undoLabel: history.undo[0],
+		redoLabel: history.redo[0],
+		assetWarnings: []
+	};
+}
+function withLiveEngineValues(engine, previous) {
+	return {
+		...previous,
+		...initialState(engine),
+		isLoading: previous.isLoading,
+		loadError: previous.loadError,
+		assetWarnings: previous.assetWarnings
+	};
+}
+function isSameState(first, second) {
+	return Object.keys(first).every((key) => first[key] === second[key]);
+}
+function createDocumentStateStore(engine) {
+	let state = initialState(engine);
+	const listeners = /* @__PURE__ */ new Set();
+	let detachFromEngine;
+	function update(changes) {
+		const next = {
+			...state,
+			...changes
+		};
+		if (isSameState(state, next)) return;
+		state = next;
+		for (const listener of [...listeners]) listener();
+	}
+	function attachToEngine() {
+		const unsubscribers = [
+			engine.on("load:start", () => update({
+				isLoading: true,
+				loadError: void 0
+			})),
+			engine.on("load:success", ({ warnings }) => update({
+				isLoading: false,
+				assetWarnings: warnings
+			})),
+			engine.on("load:error", ({ error }) => {
+				if (error.code !== "LOAD_ABORTED") update({
+					isLoading: false,
+					loadError: error
+				});
+			}),
+			engine.on("document:change", ({ documentId }) => update({
+				documentId,
+				loadError: void 0
+			})),
+			engine.on("assets:warning", ({ warnings }) => update({ assetWarnings: warnings })),
+			engine.on("save:status", (saveState) => update({
+				saveStatus: saveState.status,
+				isDirty: saveState.isDirty,
+				isSaving: saveState.isSaving,
+				revision: saveState.revision,
+				lastSavedAt: saveState.lastSavedAt,
+				saveError: saveState.error
+			})),
+			engine.on("history:change", (history) => update({
+				canUndo: history.canUndo,
+				canRedo: history.canRedo,
+				undoLabel: history.undoLabel,
+				redoLabel: history.redoLabel
+			}))
+		];
+		return () => unsubscribers.forEach((unsubscribe) => unsubscribe());
+	}
+	function refreshWhileDetached() {
+		if (detachFromEngine) return;
+		const fresh = withLiveEngineValues(engine, state);
+		if (!isSameState(state, fresh)) state = fresh;
+	}
+	return {
+		getSnapshot() {
+			refreshWhileDetached();
+			return state;
+		},
+		subscribe(listener) {
+			refreshWhileDetached();
+			listeners.add(listener);
+			detachFromEngine ?? (detachFromEngine = attachToEngine());
+			return () => {
+				listeners.delete(listener);
+				if (listeners.size > 0) return;
+				detachFromEngine?.();
+				detachFromEngine = void 0;
+			};
+		},
+		destroy() {
+			listeners.clear();
+			detachFromEngine?.();
+			detachFromEngine = void 0;
+		}
+	};
+}
+//#endregion
+exports.createDocumentStateStore = createDocumentStateStore;

package/dist/state/document-state-store.d.cts

@@ -0,0 +1,28 @@
+import { AssetWarning } from "../assets/asset-pipeline.cjs";
+import { DocumentEngineError } from "../engine/errors.cjs";
+import { SaveStatus } from "../save/save-controller.cjs";
+import { DocumentEngine } from "../engine/create-document-engine.cjs";
+//#region src/state/document-state-store.d.ts
+export interface DocumentState {
+  documentId: string;
+  isLoading: boolean;
+  loadError: DocumentEngineError | undefined;
+  saveStatus: SaveStatus;
+  isDirty: boolean;
+  isSaving: boolean;
+  revision: number;
+  lastSavedAt: string | undefined;
+  saveError: DocumentEngineError | undefined;
+  canUndo: boolean;
+  canRedo: boolean;
+  undoLabel: string | undefined;
+  redoLabel: string | undefined;
+  assetWarnings: AssetWarning[];
+}
+export interface DocumentStateStore {
+  getSnapshot(): DocumentState;
+  subscribe(listener: () => void): () => void;
+  destroy(): void;
+}
+export declare function createDocumentStateStore(engine: DocumentEngine): DocumentStateStore;
+//#endregion

package/dist/state/document-state-store.d.ts

@@ -0,0 +1,28 @@
+import { AssetWarning } from "../assets/asset-pipeline.js";
+import { DocumentEngineError } from "../engine/errors.js";
+import { SaveStatus } from "../save/save-controller.js";
+import { DocumentEngine } from "../engine/create-document-engine.js";
+//#region src/state/document-state-store.d.ts
+export interface DocumentState {
+  documentId: string;
+  isLoading: boolean;
+  loadError: DocumentEngineError | undefined;
+  saveStatus: SaveStatus;
+  isDirty: boolean;
+  isSaving: boolean;
+  revision: number;
+  lastSavedAt: string | undefined;
+  saveError: DocumentEngineError | undefined;
+  canUndo: boolean;
+  canRedo: boolean;
+  undoLabel: string | undefined;
+  redoLabel: string | undefined;
+  assetWarnings: AssetWarning[];
+}
+export interface DocumentStateStore {
+  getSnapshot(): DocumentState;
+  subscribe(listener: () => void): () => void;
+  destroy(): void;
+}
+export declare function createDocumentStateStore(engine: DocumentEngine): DocumentStateStore;
+//#endregion

package/dist/state/document-state-store.js

@@ -0,0 +1,114 @@
+//#region src/state/document-state-store.ts
+function initialState(engine) {
+	const saveState = engine.getSaveState();
+	const history = engine.getHistory();
+	return {
+		documentId: engine.getDocumentInfo().id,
+		isLoading: false,
+		loadError: void 0,
+		saveStatus: saveState.status,
+		isDirty: saveState.isDirty,
+		isSaving: saveState.isSaving,
+		revision: saveState.revision,
+		lastSavedAt: saveState.lastSavedAt,
+		saveError: saveState.error,
+		canUndo: history.undo.length > 0,
+		canRedo: history.redo.length > 0,
+		undoLabel: history.undo[0],
+		redoLabel: history.redo[0],
+		assetWarnings: []
+	};
+}
+function withLiveEngineValues(engine, previous) {
+	return {
+		...previous,
+		...initialState(engine),
+		isLoading: previous.isLoading,
+		loadError: previous.loadError,
+		assetWarnings: previous.assetWarnings
+	};
+}
+function isSameState(first, second) {
+	return Object.keys(first).every((key) => first[key] === second[key]);
+}
+function createDocumentStateStore(engine) {
+	let state = initialState(engine);
+	const listeners = /* @__PURE__ */ new Set();
+	let detachFromEngine;
+	function update(changes) {
+		const next = {
+			...state,
+			...changes
+		};
+		if (isSameState(state, next)) return;
+		state = next;
+		for (const listener of [...listeners]) listener();
+	}
+	function attachToEngine() {
+		const unsubscribers = [
+			engine.on("load:start", () => update({
+				isLoading: true,
+				loadError: void 0
+			})),
+			engine.on("load:success", ({ warnings }) => update({
+				isLoading: false,
+				assetWarnings: warnings
+			})),
+			engine.on("load:error", ({ error }) => {
+				if (error.code !== "LOAD_ABORTED") update({
+					isLoading: false,
+					loadError: error
+				});
+			}),
+			engine.on("document:change", ({ documentId }) => update({
+				documentId,
+				loadError: void 0
+			})),
+			engine.on("assets:warning", ({ warnings }) => update({ assetWarnings: warnings })),
+			engine.on("save:status", (saveState) => update({
+				saveStatus: saveState.status,
+				isDirty: saveState.isDirty,
+				isSaving: saveState.isSaving,
+				revision: saveState.revision,
+				lastSavedAt: saveState.lastSavedAt,
+				saveError: saveState.error
+			})),
+			engine.on("history:change", (history) => update({
+				canUndo: history.canUndo,
+				canRedo: history.canRedo,
+				undoLabel: history.undoLabel,
+				redoLabel: history.redoLabel
+			}))
+		];
+		return () => unsubscribers.forEach((unsubscribe) => unsubscribe());
+	}
+	function refreshWhileDetached() {
+		if (detachFromEngine) return;
+		const fresh = withLiveEngineValues(engine, state);
+		if (!isSameState(state, fresh)) state = fresh;
+	}
+	return {
+		getSnapshot() {
+			refreshWhileDetached();
+			return state;
+		},
+		subscribe(listener) {
+			refreshWhileDetached();
+			listeners.add(listener);
+			detachFromEngine ?? (detachFromEngine = attachToEngine());
+			return () => {
+				listeners.delete(listener);
+				if (listeners.size > 0) return;
+				detachFromEngine?.();
+				detachFromEngine = void 0;
+			};
+		},
+		destroy() {
+			listeners.clear();
+			detachFromEngine?.();
+			detachFromEngine = void 0;
+		}
+	};
+}
+//#endregion
+export { createDocumentStateStore };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fabricjs-document-engine",
-  "version": "0.6.0",
+  "version": "0.7.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",
@@ -19,7 +19,9 @@
     "editor",
     "typescript",
     "storage",
-    "recovery"
+    "recovery",
+    "react",
+    "react hooks"
   ],
   "license": "MIT",
   "author": "Sohail Khan (https://me.jscrate.dev)",
@@ -64,10 +66,20 @@
         "default": "./dist/recovery.cjs"
       }
     },
+    "./react": {
+      "import": {
+        "types": "./dist/react.d.ts",
+        "default": "./dist/react.js"
+      },
+      "require": {
+        "types": "./dist/react.d.cts",
+        "default": "./dist/react.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "scripts": {
-    "build": "tsdown && npm run lint:publint && npm run lint:attw",
+    "build": "tsdown && node scripts/verify-build.mjs && npm run lint:publint && npm run lint:attw",
     "dev": "tsdown --watch",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.tools.json",
     "test": "vitest run",
@@ -80,7 +92,8 @@
     "release": "changeset publish"
   },
   "peerDependencies": {
-    "fabric": "^6.0.0 || ^7.0.0"
+    "fabric": "^6.0.0 || ^7.0.0",
+    "react": "^18.0.0 || ^19.0.0"
   },
   "publishConfig": {
     "access": "public",
@@ -101,13 +114,22 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@changesets/cli": "^3.0.3",
     "@types/node": "^22.20.4",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@vitest/browser-playwright": "^5.0.2",
     "fabric": "^7.4.0",
     "fabric6": "npm:fabric@^6.9.1",
     "playwright": "^1.63.0",
     "publint": "^0.3.24",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "tsdown": "^0.23.0",
     "typescript": "^5.9.3",
     "vitest": "^5.0.2"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
   }
 }