fabricjs-document-engine 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sohail Khan (resohail.me)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# fabricjs-document-engine
+
+Turn an existing [Fabric.js](https://fabricjs.com) canvas into a dependable editable document.
+
+Fabric already draws objects, handles interaction and serializes to JSON. This package coordinates those pieces into a document workflow you can trust. You keep your own canvas, toolbar and UI.
+
+- **Stable object ids.** Every object, including children of groups, gets an id that survives moving, styling, grouping, saving and reopening.
+- **A versioned document format.** It records the schema version, canvas size, background, object order and your own metadata.
+- **Safe loading.** Documents are validated first. Unknown object types are refused before the canvas is touched. A missing image fails the load instead of silently disappearing. When loads overlap, the newest one wins.
+- **Custom objects.** Register your own Fabric classes and the extra properties they need to keep.
+- **Your storage.** Plug in any backend with two functions. No hosted service is needed.
+- **Fabric 6 and 7.** Every release is tested against both.
+
+## Install
+
+```bash
+npm install fabricjs-document-engine fabric
+```
+
+## Quick start
+
+```ts
+import { Canvas, Rect } from 'fabric';
+import { createDocumentEngine } from 'fabricjs-document-engine';
+
+const canvas = new Canvas('editor', { width: 800, height: 600 });
+const engine = createDocumentEngine({ canvas });
+
+canvas.add(new Rect({ width: 100, height: 80, fill: 'tomato' }));
+
+const document = engine.toDocument();
+localStorage.setItem(document.id, JSON.stringify(document));
+
+await engine.loadDocument(JSON.parse(localStorage.getItem(document.id)!));
+```
+
+## Saving and loading through storage
+
+```ts
+const engine = createDocumentEngine({
+  canvas,
+  storage: {
+    loadDocument: (id) => fetch(`/api/documents/${id}`).then((response) => response.json()),
+    saveDocument: (document) =>
+      fetch(`/api/documents/${document.id}`, { method: 'PUT', body: JSON.stringify(document) }).then(() => {}),
+  },
+});
+
+await engine.load('project-42');
+await engine.save();
+```
+
+## Custom objects
+
+```ts
+import { Rect } from 'fabric';
+
+class Sticker extends Rect {
+  static type = 'Sticker';
+  declare label: string;
+}
+
+const engine = createDocumentEngine({
+  canvas,
+  customObjects: [{ fabricClass: Sticker, properties: ['label'] }],
+});
+```
+
+If a document contains a type that has not been registered, loading fails with `UNKNOWN_OBJECT_TYPE` and lists the missing types. Your object is never turned into something else.
+
+## Document format
+
+```ts
+interface FabricDocument {
+  schemaVersion: number;
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  fabricVersion?: string;
+  canvas: { width: number; height: number; background?: unknown };
+  objects: SerializedFabricObject[];
+  metadata: Record<string, unknown>;
+}
+```
+
+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()` | Reads from or writes to your storage adapter. |
+| `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.on(event, handler)` | Listens to `load:start`, `load:success`, `load:error`, `save:start`, `save:success` or `save:error`. Returns an unsubscribe function. |
+| `engine.destroy()` | Stops listening to the canvas and cancels a running load. |
+| `validateDocument(value)` | Returns a list of issues with the exact path of each problem. |
+
+## Errors
+
+Every failure is a `DocumentEngineError` with a `code` you can switch on:
+
+| Code | Meaning |
+| --- | --- |
+| `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. |
+| `SAVE_FAILED` | Your storage adapter rejected the save. |
+| `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
+
+| Version | Focus |
+| --- | --- |
+| 0.1 | Document foundation: ids, save and load, validation, custom objects |
+| 0.2 | Undo and redo with transactions |
+| 0.3 | Safe saving: dirty state, autosave, stale-response protection |
+| 0.4 | Assets and fonts |
+| 0.5 | Recovery after a refresh or crash |
+| 0.6 | PNG, JPEG, SVG and JSON export with preflight checks |
+| 0.7 | Named versions and schema migrations |
+| 0.8 | React adapter and examples |
+| 0.9 | Hardening and benchmarks |
+| 1.0 | Stable API |
+
+## License
+
+MIT

package/dist/document/create-document.cjs

@@ -0,0 +1,13 @@
+const require_ids = require("./ids.cjs");
+//#region src/document/create-document.ts
+function createDocumentInfo(options = {}) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		id: options.id ?? require_ids.createId(),
+		createdAt: now,
+		updatedAt: now,
+		metadata: { ...options.metadata }
+	};
+}
+//#endregion
+exports.createDocumentInfo = createDocumentInfo;

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

@@ -0,0 +1,6 @@
+//#region src/document/create-document.d.ts
+export interface NewDocumentOptions {
+  id?: string;
+  metadata?: Record<string, unknown>;
+}
+//#endregion

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

@@ -0,0 +1,6 @@
+//#region src/document/create-document.d.ts
+export interface NewDocumentOptions {
+  id?: string;
+  metadata?: Record<string, unknown>;
+}
+//#endregion

package/dist/document/create-document.js

@@ -0,0 +1,13 @@
+import { createId } from "./ids.js";
+//#region src/document/create-document.ts
+function createDocumentInfo(options = {}) {
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	return {
+		id: options.id ?? createId(),
+		createdAt: now,
+		updatedAt: now,
+		metadata: { ...options.metadata }
+	};
+}
+//#endregion
+export { createDocumentInfo };

package/dist/document/document-format.cjs

@@ -0,0 +1,4 @@
+//#region src/document/document-format.ts
+const CURRENT_SCHEMA_VERSION = 1;
+//#endregion
+exports.CURRENT_SCHEMA_VERSION = CURRENT_SCHEMA_VERSION;

package/dist/document/document-format.d.cts

@@ -0,0 +1,31 @@
+//#region src/document/document-format.d.ts
+export declare const CURRENT_SCHEMA_VERSION = 1;
+export interface SerializedFabricObject {
+  type: string;
+  id?: string;
+  objects?: SerializedFabricObject[];
+  clipPath?: SerializedFabricObject;
+  [property: string]: unknown;
+}
+export interface DocumentCanvas {
+  width: number;
+  height: number;
+  background?: unknown;
+}
+export interface FabricDocument {
+  schemaVersion: number;
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  fabricVersion?: string;
+  canvas: DocumentCanvas;
+  objects: SerializedFabricObject[];
+  metadata: Record<string, unknown>;
+}
+export interface DocumentInfo {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  metadata: Record<string, unknown>;
+}
+//#endregion

package/dist/document/document-format.d.ts

@@ -0,0 +1,31 @@
+//#region src/document/document-format.d.ts
+export declare const CURRENT_SCHEMA_VERSION = 1;
+export interface SerializedFabricObject {
+  type: string;
+  id?: string;
+  objects?: SerializedFabricObject[];
+  clipPath?: SerializedFabricObject;
+  [property: string]: unknown;
+}
+export interface DocumentCanvas {
+  width: number;
+  height: number;
+  background?: unknown;
+}
+export interface FabricDocument {
+  schemaVersion: number;
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  fabricVersion?: string;
+  canvas: DocumentCanvas;
+  objects: SerializedFabricObject[];
+  metadata: Record<string, unknown>;
+}
+export interface DocumentInfo {
+  id: string;
+  createdAt: string;
+  updatedAt: string;
+  metadata: Record<string, unknown>;
+}
+//#endregion

package/dist/document/document-format.js

@@ -0,0 +1,4 @@
+//#region src/document/document-format.ts
+const CURRENT_SCHEMA_VERSION = 1;
+//#endregion
+export { CURRENT_SCHEMA_VERSION };

package/dist/document/ids.cjs

@@ -0,0 +1,11 @@
+//#region src/document/ids.ts
+let fallbackCounter = 0;
+function createId() {
+	const cryptoApi = globalThis.crypto;
+	if (typeof cryptoApi?.randomUUID === "function") return cryptoApi.randomUUID();
+	fallbackCounter += 1;
+	const randomPart = Math.random().toString(36).slice(2, 10);
+	return `${Date.now().toString(36)}-${fallbackCounter.toString(36)}-${randomPart}`;
+}
+//#endregion
+exports.createId = createId;

package/dist/document/ids.js

@@ -0,0 +1,11 @@
+//#region src/document/ids.ts
+let fallbackCounter = 0;
+function createId() {
+	const cryptoApi = globalThis.crypto;
+	if (typeof cryptoApi?.randomUUID === "function") return cryptoApi.randomUUID();
+	fallbackCounter += 1;
+	const randomPart = Math.random().toString(36).slice(2, 10);
+	return `${Date.now().toString(36)}-${fallbackCounter.toString(36)}-${randomPart}`;
+}
+//#endregion
+export { createId };

package/dist/document/validate-document.cjs

@@ -0,0 +1,70 @@
+require("./document-format.cjs");
+//#region src/document/validate-document.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPositiveNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function invalid(path, message) {
+	return {
+		code: "INVALID_DOCUMENT",
+		path,
+		message
+	};
+}
+function validateObjectList(list, path, issues) {
+	if (!Array.isArray(list)) {
+		issues.push(invalid(path, "must be an array of objects"));
+		return;
+	}
+	const pending = list.map((value, index) => ({
+		value,
+		path: `${path}[${index}]`
+	}));
+	while (pending.length > 0) {
+		const { value, path: objectPath } = pending.pop();
+		if (!isPlainObject(value)) {
+			issues.push(invalid(objectPath, "must be an object"));
+			continue;
+		}
+		if (typeof value.type !== "string" || value.type.length === 0) issues.push(invalid(`${objectPath}.type`, "must be a non-empty string"));
+		if (value.id !== void 0 && typeof value.id !== "string") issues.push(invalid(`${objectPath}.id`, "must be a string when present"));
+		if (value.objects !== void 0) {
+			if (!Array.isArray(value.objects)) issues.push(invalid(`${objectPath}.objects`, "must be an array of objects"));
+			else value.objects.forEach((child, index) => {
+				pending.push({
+					value: child,
+					path: `${objectPath}.objects[${index}]`
+				});
+			});
+		}
+		if (value.clipPath !== void 0) pending.push({
+			value: value.clipPath,
+			path: `${objectPath}.clipPath`
+		});
+	}
+}
+function validateDocument(value) {
+	if (!isPlainObject(value)) return [invalid("", "document must be an object")];
+	if (typeof value.schemaVersion !== "number" || !Number.isInteger(value.schemaVersion)) return [invalid("schemaVersion", "must be an integer")];
+	if (value.schemaVersion > 1 || value.schemaVersion < 1) return [{
+		code: "UNSUPPORTED_SCHEMA",
+		path: "schemaVersion",
+		message: `schema version ${value.schemaVersion} is not supported, expected 1`
+	}];
+	const issues = [];
+	if (typeof value.id !== "string" || value.id.length === 0) issues.push(invalid("id", "must be a non-empty string"));
+	if (typeof value.createdAt !== "string") issues.push(invalid("createdAt", "must be an ISO date string"));
+	if (typeof value.updatedAt !== "string") issues.push(invalid("updatedAt", "must be an ISO date string"));
+	if (!isPlainObject(value.metadata)) issues.push(invalid("metadata", "must be an object"));
+	if (!isPlainObject(value.canvas)) issues.push(invalid("canvas", "must be an object"));
+	else {
+		if (!isPositiveNumber(value.canvas.width)) issues.push(invalid("canvas.width", "must be a positive number"));
+		if (!isPositiveNumber(value.canvas.height)) issues.push(invalid("canvas.height", "must be a positive number"));
+	}
+	validateObjectList(value.objects, "objects", issues);
+	return issues;
+}
+//#endregion
+exports.validateDocument = validateDocument;

package/dist/document/validate-document.d.cts

@@ -0,0 +1,4 @@
+import { DocumentIssue } from "../engine/errors.cjs";
+//#region src/document/validate-document.d.ts
+export declare function validateDocument(value: unknown): DocumentIssue[];
+//#endregion

package/dist/document/validate-document.d.ts

@@ -0,0 +1,4 @@
+import { DocumentIssue } from "../engine/errors.js";
+//#region src/document/validate-document.d.ts
+export declare function validateDocument(value: unknown): DocumentIssue[];
+//#endregion

package/dist/document/validate-document.js

@@ -0,0 +1,70 @@
+import "./document-format.js";
+//#region src/document/validate-document.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPositiveNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+function invalid(path, message) {
+	return {
+		code: "INVALID_DOCUMENT",
+		path,
+		message
+	};
+}
+function validateObjectList(list, path, issues) {
+	if (!Array.isArray(list)) {
+		issues.push(invalid(path, "must be an array of objects"));
+		return;
+	}
+	const pending = list.map((value, index) => ({
+		value,
+		path: `${path}[${index}]`
+	}));
+	while (pending.length > 0) {
+		const { value, path: objectPath } = pending.pop();
+		if (!isPlainObject(value)) {
+			issues.push(invalid(objectPath, "must be an object"));
+			continue;
+		}
+		if (typeof value.type !== "string" || value.type.length === 0) issues.push(invalid(`${objectPath}.type`, "must be a non-empty string"));
+		if (value.id !== void 0 && typeof value.id !== "string") issues.push(invalid(`${objectPath}.id`, "must be a string when present"));
+		if (value.objects !== void 0) {
+			if (!Array.isArray(value.objects)) issues.push(invalid(`${objectPath}.objects`, "must be an array of objects"));
+			else value.objects.forEach((child, index) => {
+				pending.push({
+					value: child,
+					path: `${objectPath}.objects[${index}]`
+				});
+			});
+		}
+		if (value.clipPath !== void 0) pending.push({
+			value: value.clipPath,
+			path: `${objectPath}.clipPath`
+		});
+	}
+}
+function validateDocument(value) {
+	if (!isPlainObject(value)) return [invalid("", "document must be an object")];
+	if (typeof value.schemaVersion !== "number" || !Number.isInteger(value.schemaVersion)) return [invalid("schemaVersion", "must be an integer")];
+	if (value.schemaVersion > 1 || value.schemaVersion < 1) return [{
+		code: "UNSUPPORTED_SCHEMA",
+		path: "schemaVersion",
+		message: `schema version ${value.schemaVersion} is not supported, expected 1`
+	}];
+	const issues = [];
+	if (typeof value.id !== "string" || value.id.length === 0) issues.push(invalid("id", "must be a non-empty string"));
+	if (typeof value.createdAt !== "string") issues.push(invalid("createdAt", "must be an ISO date string"));
+	if (typeof value.updatedAt !== "string") issues.push(invalid("updatedAt", "must be an ISO date string"));
+	if (!isPlainObject(value.metadata)) issues.push(invalid("metadata", "must be an object"));
+	if (!isPlainObject(value.canvas)) issues.push(invalid("canvas", "must be an object"));
+	else {
+		if (!isPositiveNumber(value.canvas.width)) issues.push(invalid("canvas.width", "must be a positive number"));
+		if (!isPositiveNumber(value.canvas.height)) issues.push(invalid("canvas.height", "must be a positive number"));
+	}
+	validateObjectList(value.objects, "objects", issues);
+	return issues;
+}
+//#endregion
+export { validateDocument };

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

@@ -0,0 +1,218 @@
+require("../document/document-format.cjs");
+const require_ids = require("../document/ids.cjs");
+const require_create_document = require("../document/create-document.cjs");
+const require_validate_document = require("../document/validate-document.cjs");
+const require_walk_objects = require("../fabric/walk-objects.cjs");
+const require_fabric_adapter = require("../fabric/fabric-adapter.cjs");
+const require_object_ids = require("../fabric/object-ids.cjs");
+const require_errors = require("./errors.cjs");
+const require_object_registry = require("../fabric/object-registry.cjs");
+const require_event_emitter = require("./event-emitter.cjs");
+//#region src/engine/create-document-engine.ts
+function describeDocumentId(value) {
+	const id = value?.id;
+	return typeof id === "string" ? id : void 0;
+}
+function createDocumentEngine(options) {
+	const { canvas, storage } = options;
+	const registry = require_object_registry.createObjectRegistry(options.customObjects);
+	const events = require_event_emitter.createEventEmitter();
+	const objectsById = /* @__PURE__ */ new Map();
+	let documentInfo = require_create_document.createDocumentInfo(options.document);
+	let activeLoad = null;
+	let destroyed = false;
+	function ensureUsable() {
+		if (destroyed) throw new require_errors.DocumentEngineError("ENGINE_DESTROYED", "This document engine was destroyed");
+	}
+	function indexObjectTree(root) {
+		require_walk_objects.walkObjects([root], (object) => {
+			let id = require_object_ids.readObjectId(object);
+			const owner = id === void 0 ? void 0 : objectsById.get(id);
+			if (id === void 0 || owner !== void 0 && owner !== object) {
+				id = require_ids.createId();
+				require_object_ids.writeObjectId(object, id);
+			}
+			objectsById.set(id, object);
+		});
+	}
+	function removeObjectTreeFromIndex(root) {
+		require_walk_objects.walkObjects([root], (object) => {
+			const id = require_object_ids.readObjectId(object);
+			if (id !== void 0 && objectsById.get(id) === object) objectsById.delete(id);
+		});
+	}
+	function rebuildIndex() {
+		objectsById.clear();
+		canvas.getObjects().forEach(indexObjectTree);
+	}
+	const handleObjectAdded = ({ target }) => indexObjectTree(target);
+	const handleObjectRemoved = ({ target }) => removeObjectTreeFromIndex(target);
+	canvas.on("object:added", handleObjectAdded);
+	canvas.on("object:removed", handleObjectRemoved);
+	rebuildIndex();
+	function toDocument() {
+		ensureUsable();
+		rebuildIndex();
+		const serialized = require_fabric_adapter.serializeCanvas(canvas, registry.propertiesToInclude());
+		documentInfo = {
+			...documentInfo,
+			updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+		};
+		const document = {
+			schemaVersion: 1,
+			id: documentInfo.id,
+			createdAt: documentInfo.createdAt,
+			updatedAt: documentInfo.updatedAt,
+			canvas: {
+				width: canvas.getWidth(),
+				height: canvas.getHeight()
+			},
+			objects: serialized.objects,
+			metadata: { ...documentInfo.metadata }
+		};
+		if (serialized.version !== void 0) document.fabricVersion = serialized.version;
+		if (serialized.background !== void 0) document.canvas.background = serialized.background;
+		return document;
+	}
+	function toLoadError(error, signal) {
+		if (require_errors.isDocumentEngineError(error)) return error;
+		if (signal.aborted) return new require_errors.DocumentEngineError("LOAD_ABORTED", "Loading stopped because a newer load started", { cause: error });
+		const reason = error instanceof Error ? error.message : String(error);
+		return new require_errors.DocumentEngineError("LOAD_FAILED", `Fabric could not load the document: ${reason}`, { cause: error });
+	}
+	function checkDocument(input) {
+		const issues = require_validate_document.validateDocument(input);
+		if (issues.length > 0) {
+			const summary = issues.map((issue) => `${issue.path || "document"} ${issue.message}`).join("; ");
+			throw new require_errors.DocumentEngineError(issues[0].code, `The document is not valid: ${summary}`, { issues });
+		}
+		const document = input;
+		const unknownTypes = registry.findUnknownTypes(require_walk_objects.collectSerializedTypes(document.objects));
+		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 = {}) {
+		ensureUsable();
+		activeLoad?.abort();
+		const controller = new AbortController();
+		activeLoad = controller;
+		events.emit("load:start", { documentId: describeDocumentId(input) });
+		try {
+			const document = checkDocument(input);
+			await require_fabric_adapter.loadIntoCanvas(canvas, {
+				version: document.fabricVersion,
+				background: document.canvas.background,
+				objects: document.objects
+			}, controller.signal);
+			if (controller.signal.aborted) throw new Error("aborted");
+			if (loadOptions.restoreCanvasSize ?? true) canvas.setDimensions({
+				width: document.canvas.width,
+				height: document.canvas.height
+			});
+			documentInfo = {
+				id: document.id,
+				createdAt: document.createdAt,
+				updatedAt: document.updatedAt,
+				metadata: { ...document.metadata }
+			};
+			rebuildIndex();
+			canvas.requestRenderAll();
+			events.emit("load:success", { document });
+			return document;
+		} catch (error) {
+			const engineError = toLoadError(error, controller.signal);
+			events.emit("load:error", { error: engineError });
+			throw engineError;
+		} finally {
+			if (activeLoad === controller) activeLoad = null;
+		}
+	}
+	function requireStorage() {
+		if (!storage) throw new require_errors.DocumentEngineError("STORAGE_MISSING", "Pass a storage adapter to createDocumentEngine to use load and save");
+		return storage;
+	}
+	async function load(documentId, loadOptions) {
+		ensureUsable();
+		const source = requireStorage();
+		let stored;
+		try {
+			stored = await source.loadDocument(documentId);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			const engineError = new require_errors.DocumentEngineError("LOAD_FAILED", `Storage could not load "${documentId}": ${reason}`, { cause: error });
+			events.emit("load:error", { error: engineError });
+			throw engineError;
+		}
+		return loadDocument(stored, loadOptions);
+	}
+	async function save() {
+		ensureUsable();
+		const target = requireStorage();
+		const document = toDocument();
+		events.emit("save:start", { document });
+		try {
+			await target.saveDocument(document);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			const engineError = new require_errors.DocumentEngineError("SAVE_FAILED", `Storage could not save the document: ${reason}`, { cause: error });
+			events.emit("save:error", { error: engineError });
+			throw engineError;
+		}
+		events.emit("save:success", { document });
+		return document;
+	}
+	function newDocument(newOptions) {
+		ensureUsable();
+		activeLoad?.abort();
+		canvas.clear();
+		objectsById.clear();
+		documentInfo = require_create_document.createDocumentInfo(newOptions);
+	}
+	function getObjectById(id) {
+		ensureUsable();
+		const indexed = objectsById.get(id);
+		if (indexed !== void 0) return indexed;
+		rebuildIndex();
+		return objectsById.get(id);
+	}
+	function destroy() {
+		if (destroyed) return;
+		destroyed = true;
+		activeLoad?.abort();
+		canvas.off("object:added", handleObjectAdded);
+		canvas.off("object:removed", handleObjectRemoved);
+		objectsById.clear();
+		events.clear();
+	}
+	return {
+		canvas,
+		getDocumentInfo: () => ({
+			...documentInfo,
+			metadata: { ...documentInfo.metadata }
+		}),
+		updateMetadata(changes) {
+			ensureUsable();
+			documentInfo = {
+				...documentInfo,
+				metadata: {
+					...documentInfo.metadata,
+					...changes
+				}
+			};
+		},
+		newDocument,
+		toDocument,
+		loadDocument,
+		load,
+		save,
+		registerObject(definition) {
+			ensureUsable();
+			registry.register(definition);
+		},
+		getObjectById,
+		on: (name, handler) => events.on(name, handler),
+		destroy
+	};
+}
+//#endregion
+exports.createDocumentEngine = createDocumentEngine;