fabricjs-document-engine 0.4.0 → 0.6.0

package/README.md

@@ -12,6 +12,8 @@ Fabric already draws objects, handles interaction and serializes to JSON. This p
 - **Your storage.** Plug in any backend with two functions, or use the built-in memory and localStorage adapters. No hosted service is needed.
 - **Assets and fonts.** Documents record the images and fonts they need. When a document is opened, every image and font is checked first. You get the exact list of what is missing, can offer replacements, and tab-only images are uploaded when you save.
 - **Recovery.** Unsaved work is copied to IndexedDB while the user edits, and again at the moment the tab is closed or refreshed. After a crash or refresh you can offer to restore it, including images that only existed in the old tab.
+- **Dependable export.** PNG, JPEG, WebP, SVG and editable JSON. You choose the area, scale and background. A preflight check means an export either succeeds or tells you exactly which image or font prevents it.
+- **Versions and migration.** Keep named versions, restore any of them as a new revision, and open plain Fabric JSON or documents saved by older versions of this package.
 - **Reliable undo and redo.** One user action is one undo step. Transactions group several code changes into one labelled step, and ids survive undo and redo.
 - **Fabric 6 and 7.** Every release is tested against both.
 
@@ -176,6 +178,74 @@ await engine.replaceImage('/old-logo.png', '/new-logo.png');
 
 `replaceImage` swaps every image that uses a URL. Each image keeps its size on the page, and the change is one undo step. `engine.getAssetManifest()` returns the manifest for the current canvas.
 
+## Export
+
+```ts
+import { downloadExport } from 'fabricjs-document-engine';
+
+const result = await engine.export({ format: 'png', scale: 2 });
+downloadExport(result, 'poster.png');
+```
+
+`result` is `{ format, mimeType, blob, width, height, warnings }`. JSON exports also include `document`.
+
+| Option | Values | Default |
+| --- | --- | --- |
+| `format` | `'png'`, `'jpeg'`, `'webp'`, `'svg'` or `'json'` | required |
+| `scale` | Output size multiplier, such as `2` for retina | `1` |
+| `quality` | 0 to 1, for JPEG and WebP | `0.92` |
+| `area` | `'canvas'`, `'content'` (every object), `'selection'`, or `{ left, top, width, height }` | `'canvas'` |
+| `padding` | Extra space around `content` or `selection` | `0` |
+| `background` | `'keep'`, `'transparent'` or any CSS color | `'keep'` |
+| `signal` | An `AbortSignal` to cancel | |
+
+- The current zoom and pan do not matter. Exports always use document coordinates, and the view is restored afterwards.
+- A JPEG has no transparency, so an empty or transparent background becomes white instead of black.
+- The export never changes the canvas, the history or the unsaved state.
+- A JSON export is the same portable document a save produces, including uploaded images when `assets.upload` is set.
+
+### Preflight and errors
+
+Before rendering, the engine checks the objects on the canvas:
+
+- **`MISSING_IMAGE`**: an image failed to load.
+- **`CROSS_ORIGIN_IMAGE`**: an image from another site without CORS would make the browser block a PNG, JPEG or WebP export. SVG and JSON are not affected.
+- **`MISSING_FONT`**: a font is not available and `assets.requireFonts` is on. Otherwise you get a `FONT_UNAVAILABLE` warning.
+
+If any problem is found, `export` rejects with `EXPORT_BLOCKED`, and `error.problems` lists each `{ code, message, url?, family?, objectIds }`. You can run the same check first to show it in your UI:
+
+```ts
+const check = await engine.preflightExport({ format: 'png' });
+if (!check.ok) showProblems(check.problems);
+```
+
+## Versions
+
+```ts
+const version = await engine.createVersion('Sent to client');
+const versions = await engine.listVersions();
+await engine.restoreVersion(version.id);
+await engine.deleteVersion(version.id);
+```
+
+- Versions are full copies of the document, kept in your storage adapter. The built-in adapters support them. A custom adapter adds four methods: `saveVersion(version)`, `listVersions(documentId)`, `loadVersion(documentId, versionId)` and `deleteVersion(documentId, versionId)`.
+- `listVersions` returns summaries, newest first: `{ id, documentId, name, kind, createdAt, revision }`. `kind` is `named` or `auto`.
+- **Restoring never loses work.** The engine first keeps an automatic version named `Before restoring "..."`. It then loads the old content as a new, unsaved revision of the same document. The next save stores it as the newest revision, and history stays linear. To undo a restore, restore the automatic version.
+- **Automatic versions.** Use `versions: { autoEvery: 10, keepAuto: 20 }` to keep a version after every 10 successful saves. Named versions are never pruned. Only the newest `keepAuto` automatic versions are kept, 20 by default.
+- Undo and redo cover recent edits in this session. Versions preserve chosen states for later.
+
+## Migration and importing Fabric JSON
+
+Plain Fabric JSON, such as the output of `canvas.toJSON()` from Fabric 5, 6 or 7, opens directly:
+
+```ts
+await engine.importFabricJson(savedJsonText, { id: 'plan-42', metadata: { source: 'old editor' } });
+```
+
+`loadDocument` and `load(id)` also recognise plain Fabric JSON, so projects stored by an existing Fabric app open without a separate import step. A document loaded with `load(id)` keeps that id, and its next save stores it in the current format.
+
+Every document records its `schemaVersion`. When the package format changes, older documents are upgraded step by step when they are opened. `load:success` reports `migratedFrom` when that happened. A failed step rejects with `MIGRATION_FAILED`, and `error.migrationFrom` names the version it started from. A document from a newer version of the package is refused with `UNSUPPORTED_SCHEMA` rather than being misread. `migrateDocument(value, context)` and `detectSchemaVersion(value)` are exported for tooling such as server-side batch upgrades.
+
 ## Recovery
 
 ```ts
@@ -300,6 +370,9 @@ Keep project data such as titles, owners and tags in `metadata` with `engine.upd
 | `engine.toDocument()` | Serializes the canvas into the versioned document format. |
 | `engine.loadDocument(document, { restoreCanvasSize? })` | Validates and loads a document. Resolves when the objects are on the canvas. |
 | `engine.load(id)` / `engine.save({ overwrite? })` | Reads from or writes to your storage adapter. |
+| `engine.importFabricJson(json, { id?, metadata? })` | Opens plain Fabric JSON, as text or an object. |
+| `engine.createVersion(name?)` / `engine.listVersions()` | Keeps a named version, or lists versions newest first. |
+| `engine.restoreVersion(id)` / `engine.deleteVersion(id)` | Restores a version as a new unsaved revision, or deletes it. |
 | `engine.isDirty()` | Tells you whether there are unsaved changes. |
 | `engine.getSaveState()` | Returns `{ status, isDirty, isSaving, revision, lastSavedAt, error }`. |
 | `bindUnsavedChangesWarning(engine)` | Asks the browser to confirm before closing a page with unsaved changes. Returns an unbind function. |
@@ -311,6 +384,9 @@ Keep project data such as titles, owners and tags in `metadata` with `engine.upd
 | `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. |
@@ -322,7 +398,7 @@ Keep project data such as titles, owners and tags in `metadata` with `engine.upd
 | `engine.getHistory()` | Returns `{ undo, redo }` label lists, newest first. |
 | `engine.clearHistory()` | Forgets all steps. Loading a document or starting a new one also does this. |
 | `bindKeyboardShortcuts(engine, { target? })` | Adds the undo and redo shortcuts. Returns an unbind function. |
-| `engine.on(event, handler)` | Listens to `load:start`, `load:success`, `load:error`, `save:start`, `save:success`, `save:error`, `save:retry`, `save:status`, `assets:warning`, `recovery:checkpoint`, `recovery:restored`, `recovery:error`, `history:change` or `history:error`. Returns an unsubscribe function. |
+| `engine.on(event, handler)` | Listens to `load:start`, `load:success`, `load:error`, `save:start`, `save:success`, `save:error`, `save:retry`, `save:status`, `assets:warning`, `recovery:checkpoint`, `recovery:restored`, `recovery:error`, `export:success`, `export:error`, `version:created`, `version:restored`, `version:error`, `history:change` or `history:error`. Returns an unsubscribe function. |
 | `engine.destroy()` | Stops listening to the canvas and cancels a running load. |
 | `validateDocument(value)` | Returns a list of issues with the exact path of each problem. |
 
@@ -345,6 +421,14 @@ Every failure is a `DocumentEngineError` with a `code` you can switch on:
 | `SAVE_CANCELLED` | A queued save was dropped because another document was opened. |
 | `DOCUMENT_NOT_FOUND` | The built-in adapters have no document with that id. |
 | `HISTORY_FAILED` | Undo or redo could not rebuild an object, for example because an image is gone. The step is kept and the canvas is unchanged. |
+| `MIGRATION_FAILED` | An older document could not be upgraded. `error.migrationFrom` is the schema version it started from. |
+| `VERSIONS_UNSUPPORTED` | The storage adapter has no version methods. |
+| `VERSION_NOT_FOUND` | There is no version with that id. |
+| `VERSION_FAILED` | An automatic version could not be kept. It is delivered as a `version:error` event. |
+| `EXPORT_BLOCKED` | The preflight found problems. `error.problems` lists each one with the objects involved. |
+| `INVALID_EXPORT_OPTIONS` | The format, scale, quality, area or padding is not valid, or the area is empty. |
+| `EXPORT_ABORTED` | The export was cancelled with its `signal`. |
+| `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. |
@@ -363,8 +447,8 @@ A failed load never clears or half-fills your canvas.
 | 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 | |
-| 7 | Named versions and schema migrations | |
+| 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 | |
 | 9 | Hardening and benchmarks | |
 | 10 | Stable API | 1.0.0 |

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

@@ -2,16 +2,22 @@ const require_asset_manifest = require("../assets/asset-manifest.cjs");
 const require_errors = require("./errors.cjs");
 const require_image_check = require("../assets/image-check.cjs");
 const require_asset_pipeline = require("../assets/asset-pipeline.cjs");
+const require_export_area = require("../export/export-area.cjs");
+const require_export_options = require("../export/export-options.cjs");
+const require_object_ids = require("../fabric/object-ids.cjs");
+const require_walk_objects = require("../fabric/walk-objects.cjs");
+const require_preflight_export = require("../export/preflight-export.cjs");
+const require_render_export = require("../export/render-export.cjs");
 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_object_registry = require("../fabric/object-registry.cjs");
 const require_create_history = require("../history/create-history.cjs");
+const require_migrate_document = require("../migrations/migrate-document.cjs");
 const require_recovery_controller = require("../recovery/recovery-controller.cjs");
+const require_document_version = require("../versions/document-version.cjs");
 const require_save_controller = require("../save/save-controller.cjs");
 const require_event_emitter = require("./event-emitter.cjs");
 //#region src/engine/create-document-engine.ts
@@ -87,6 +93,7 @@ function createDocumentEngine(options) {
 		onSuccess: (document) => {
 			if (recovery && !saving.state().isDirty) recovery.remove(document.id);
 			events.emit("save:success", { document });
+			createAutomaticVersionAfterSave(document);
 		},
 		onError: (error) => events.emit("save:error", { error }),
 		onRetry: (event) => events.emit("save:retry", event)
@@ -151,7 +158,10 @@ function createDocumentEngine(options) {
 		if (unknownTypes.length > 0) throw new require_errors.DocumentEngineError("UNKNOWN_OBJECT_TYPE", `The document uses object types that are not registered: ${unknownTypes.join(", ")}. Register them with customObjects or engine.registerObject before loading.`, { unknownTypes });
 		return document;
 	}
-	async function loadDocument(input, loadOptions = {}) {
+	function loadDocument(input, loadOptions = {}) {
+		return loadMigratedDocument(input, loadOptions, {});
+	}
+	async function loadMigratedDocument(input, loadOptions, importDetails) {
 		ensureUsable();
 		activeLoad?.abort();
 		const controller = new AbortController();
@@ -161,7 +171,12 @@ function createDocumentEngine(options) {
 		try {
 			await recovery?.markLoadStarted(documentId);
 			if (controller.signal.aborted) throw new Error("aborted");
-			const checked = checkDocument(input);
+			const { document: migrated, migratedFrom } = require_migrate_document.migrateDocument(input, {
+				canvasWidth: canvas.getWidth(),
+				canvasHeight: canvas.getHeight(),
+				...importDetails
+			});
+			const checked = checkDocument(migrated);
 			const { document, warnings } = await require_asset_pipeline.prepareAssetsForLoad(checked, assetOptions, controller.signal);
 			if (controller.signal.aborted) throw new Error("aborted");
 			await history.withoutRecording(() => require_fabric_adapter.loadIntoCanvas(canvas, {
@@ -188,7 +203,8 @@ function createDocumentEngine(options) {
 			if (warnings.length > 0) events.emit("assets:warning", { warnings });
 			events.emit("load:success", {
 				document,
-				warnings
+				warnings,
+				migratedFrom
 			});
 			return document;
 		} catch (error) {
@@ -202,6 +218,90 @@ function createDocumentEngine(options) {
 			}
 		}
 	}
+	function importFabricJson(json, importOptions = {}) {
+		let parsed = json;
+		if (typeof json === "string") try {
+			parsed = JSON.parse(json);
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			return Promise.reject(new require_errors.DocumentEngineError("INVALID_DOCUMENT", `The text is not valid JSON: ${reason}`, { cause: error }));
+		}
+		const { id, metadata, ...loadOptions } = importOptions;
+		return loadMigratedDocument(parsed, loadOptions, {
+			id,
+			metadata
+		});
+	}
+	let savesSinceAutomaticVersion = 0;
+	let lastVersionTime = 0;
+	function nextVersionTimestamp() {
+		lastVersionTime = Math.max(Date.now(), lastVersionTime + 1);
+		return new Date(lastVersionTime).toISOString();
+	}
+	function requireVersions() {
+		ensureUsable();
+		if (!require_document_version.supportsVersions(storage)) throw new require_errors.DocumentEngineError("VERSIONS_UNSUPPORTED", "The storage adapter needs saveVersion, listVersions, loadVersion and deleteVersion to keep versions");
+		return storage;
+	}
+	async function pruneAutomaticVersions(versionStorage, documentId) {
+		const keepAuto = options.versions?.keepAuto ?? 20;
+		const existing = await versionStorage.listVersions(documentId);
+		await Promise.all(require_document_version.versionsToPrune(existing, keepAuto).map((version) => versionStorage.deleteVersion(documentId, version.id)));
+	}
+	async function storeVersion(name, kind, document) {
+		const versionStorage = requireVersions();
+		const content = document ?? (await require_asset_pipeline.prepareAssetsForSave(toDocument(), assetOptions, uploadedUrls)).document;
+		const version = {
+			id: require_ids.createId(),
+			documentId: content.id,
+			name,
+			kind,
+			createdAt: nextVersionTimestamp(),
+			revision: content.revision ?? saving.state().revision,
+			document: content
+		};
+		await versionStorage.saveVersion(version);
+		await pruneAutomaticVersions(versionStorage, content.id);
+		const summary = require_document_version.summarize(version);
+		events.emit("version:created", summary);
+		return summary;
+	}
+	function reportVersionError(error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		const engineError = require_errors.isDocumentEngineError(error) ? error : new require_errors.DocumentEngineError("VERSION_FAILED", `Could not keep an automatic version: ${reason}`, { cause: error });
+		events.emit("version:error", { error: engineError });
+	}
+	function createAutomaticVersionAfterSave(document) {
+		const every = options.versions?.autoEvery ?? 0;
+		if (every <= 0 || !require_document_version.supportsVersions(storage)) return;
+		savesSinceAutomaticVersion += 1;
+		if (savesSinceAutomaticVersion < every) return;
+		savesSinceAutomaticVersion = 0;
+		storeVersion(`Autosave ${(/* @__PURE__ */ new Date()).toLocaleString()}`, "auto", document).catch(reportVersionError);
+	}
+	async function restoreVersion(versionId) {
+		const versionStorage = requireVersions();
+		const current = documentInfo;
+		const version = await versionStorage.loadVersion(current.id, versionId);
+		await storeVersion(`Before restoring "${version.name}"`, "auto");
+		const { document: migrated } = require_migrate_document.migrateDocument(version.document, {
+			canvasWidth: canvas.getWidth(),
+			canvasHeight: canvas.getHeight()
+		});
+		const baseRevision = saving.state().revision;
+		const loaded = await loadDocument({
+			...migrated,
+			id: current.id,
+			createdAt: current.createdAt,
+			revision: baseRevision
+		});
+		noteContentChange();
+		events.emit("version:restored", {
+			version: require_document_version.summarize(version),
+			document: loaded
+		});
+		return loaded;
+	}
 	function requireStorage() {
 		if (!storage) throw new require_errors.DocumentEngineError("STORAGE_MISSING", "Pass a storage adapter to createDocumentEngine to use load and save");
 		return storage;
@@ -218,7 +318,7 @@ function createDocumentEngine(options) {
 			events.emit("load:error", { error: engineError });
 			throw engineError;
 		}
-		return loadDocument(stored, loadOptions);
+		return loadMigratedDocument(stored, loadOptions ?? {}, { id: documentId });
 	}
 	function save(saveOptions) {
 		try {
@@ -270,6 +370,92 @@ function createDocumentEngine(options) {
 		canvas.requestRenderAll();
 		return images.length;
 	}
+	function fontsOnCanvas() {
+		rebuildIndex();
+		return require_asset_manifest.buildAssetManifest(require_fabric_adapter.serializeCanvas(canvas, registry.propertiesToInclude()).objects).fonts;
+	}
+	async function checkBeforeExport(exportOptions) {
+		ensureUsable();
+		const { format } = require_export_options.normalizeExportOptions(exportOptions);
+		return require_preflight_export.preflightExport(canvas, format, format === "json" ? [] : fontsOnCanvas(), assetOptions);
+	}
+	function describeProblems(check) {
+		return check.problems.map((problem) => problem.message).join("; ");
+	}
+	async function exportContent(exportOptions) {
+		const settings = require_export_options.normalizeExportOptions(exportOptions);
+		const stopIfCancelled = () => {
+			if (settings.signal?.aborted) throw new require_errors.DocumentEngineError("EXPORT_ABORTED", "The export was cancelled");
+		};
+		stopIfCancelled();
+		if (settings.format === "json") {
+			const prepared = await require_asset_pipeline.prepareAssetsForSave(toDocument(), assetOptions, uploadedUrls);
+			stopIfCancelled();
+			return {
+				format: "json",
+				mimeType: require_render_export.mimeTypes.json,
+				blob: new Blob([JSON.stringify(prepared.document)], { type: require_render_export.mimeTypes.json }),
+				width: prepared.document.canvas.width,
+				height: prepared.document.canvas.height,
+				warnings: prepared.warnings,
+				document: prepared.document
+			};
+		}
+		const check = await checkBeforeExport(settings);
+		stopIfCancelled();
+		if (!check.ok) throw new require_errors.DocumentEngineError("EXPORT_BLOCKED", `The export cannot run: ${describeProblems(check)}`, { problems: check.problems });
+		const format = settings.format;
+		try {
+			const rendered = require_render_export.withExportView(canvas, settings.background, format, () => {
+				const area = require_export_area.resolveExportArea(canvas, settings.area, settings.padding);
+				return {
+					area,
+					content: format === "svg" ? require_render_export.renderSvg(canvas, area, settings.scale) : require_render_export.renderRaster(canvas, area, format, settings.scale, settings.quality)
+				};
+			});
+			const blob = format === "svg" ? new Blob([rendered.content], { type: require_render_export.mimeTypes.svg }) : require_render_export.dataUrlToBlob(rendered.content);
+			return {
+				format,
+				mimeType: blob.type || require_render_export.mimeTypes[format],
+				blob,
+				width: Math.round(rendered.area.width * settings.scale),
+				height: Math.round(rendered.area.height * settings.scale),
+				warnings: check.warnings
+			};
+		} catch (error) {
+			if (require_errors.isDocumentEngineError(error)) throw error;
+			if (error?.name === "SecurityError") {
+				const problem = {
+					code: "CROSS_ORIGIN_IMAGE",
+					message: "The browser blocked the export because the canvas shows an image from another site without CORS",
+					objectIds: []
+				};
+				throw new require_errors.DocumentEngineError("EXPORT_BLOCKED", problem.message, {
+					problems: [problem],
+					cause: error
+				});
+			}
+			const reason = error instanceof Error ? error.message : String(error);
+			throw new require_errors.DocumentEngineError("EXPORT_FAILED", `Fabric could not export the canvas: ${reason}`, { cause: error });
+		}
+	}
+	async function exportDocument(exportOptions) {
+		ensureUsable();
+		try {
+			const result = await exportContent(exportOptions);
+			events.emit("export:success", {
+				format: result.format,
+				width: result.width,
+				height: result.height,
+				warnings: result.warnings
+			});
+			return result;
+		} catch (error) {
+			const engineError = require_errors.isDocumentEngineError(error) ? error : new require_errors.DocumentEngineError("EXPORT_FAILED", String(error), { cause: error });
+			events.emit("export:error", { error: engineError });
+			throw engineError;
+		}
+	}
 	function requireRecovery() {
 		ensureUsable();
 		if (!recovery) throw new require_errors.DocumentEngineError("RECOVERY_MISSING", "Pass recovery: { store } to createDocumentEngine to use recovery");
@@ -329,6 +515,11 @@ function createDocumentEngine(options) {
 		toDocument,
 		loadDocument,
 		load,
+		importFabricJson,
+		createVersion: (name) => storeVersion(name ?? `Version ${(/* @__PURE__ */ new Date()).toLocaleString()}`, "named"),
+		listVersions: async (documentId) => requireVersions().listVersions(documentId ?? documentInfo.id),
+		restoreVersion,
+		deleteVersion: async (versionId) => requireVersions().deleteVersion(documentInfo.id, versionId),
 		save,
 		isDirty: () => saving.state().isDirty,
 		getSaveState: () => saving.state(),
@@ -343,6 +534,8 @@ function createDocumentEngine(options) {
 		},
 		checkAssets,
 		replaceImage,
+		export: exportDocument,
+		preflightExport: checkBeforeExport,
 		flushRecovery: async () => requireRecovery().flush(),
 		getRecoverableDocuments: async () => requireRecovery().list(),
 		getRecovery: async (documentId) => requireRecovery().read(documentId ?? documentInfo.id),

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

@@ -1,9 +1,12 @@
 import { DocumentInfo, FabricDocument } from "../document/document-format.cjs";
 import { AssetManifest } from "../assets/asset-manifest.cjs";
 import { AssetOptions, AssetReport, AssetWarning } from "../assets/asset-pipeline.cjs";
+import { ExportFormat, ExportOptions } from "../export/export-options.cjs";
+import { ExportPreflight } from "../export/preflight-export.cjs";
 import { NewDocumentOptions } from "../document/create-document.cjs";
 import { CustomObjectDefinition } from "../fabric/object-registry.cjs";
 import { HistoryOptions, HistoryState } from "../history/create-history.cjs";
+import { VersionOptions, VersionSummary } from "../versions/document-version.cjs";
 import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "../recovery/recovery-controller.cjs";
 import { AutosaveOptions } from "../save/autosave-scheduler.cjs";
 import { RetryOptions } from "../save/retry.cjs";
@@ -23,10 +26,24 @@ export interface DocumentEngineOptions {
   saveRetry?: RetryOptions;
   assets?: AssetOptions;
   recovery?: RecoveryOptions;
+  versions?: VersionOptions;
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
 }
+export interface ImportOptions extends LoadOptions {
+  id?: string;
+  metadata?: Record<string, unknown>;
+}
+export interface ExportResult {
+  format: ExportFormat;
+  mimeType: string;
+  blob: Blob;
+  width: number;
+  height: number;
+  warnings: AssetWarning[];
+  document?: FabricDocument;
+}
 export interface DocumentEngineEvents {
   "load:start": {
     documentId: string | undefined;
@@ -34,6 +51,7 @@ export interface DocumentEngineEvents {
   "load:success": {
     document: FabricDocument;
     warnings: AssetWarning[];
+    migratedFrom: number | undefined;
   };
   "assets:warning": {
     warnings: AssetWarning[];
@@ -66,6 +84,23 @@ export interface DocumentEngineEvents {
   "recovery:error": {
     error: DocumentEngineError;
   };
+  "export:success": {
+    format: ExportFormat;
+    width: number;
+    height: number;
+    warnings: AssetWarning[];
+  };
+  "export:error": {
+    error: DocumentEngineError;
+  };
+  "version:created": VersionSummary;
+  "version:restored": {
+    version: VersionSummary;
+    document: FabricDocument;
+  };
+  "version:error": {
+    error: DocumentEngineError;
+  };
 }
 export interface DocumentEngine {
   readonly canvas: StaticCanvas;
@@ -75,6 +110,11 @@ export interface DocumentEngine {
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
+  importFabricJson(json: string | Record<string, unknown>, options?: ImportOptions): Promise<FabricDocument>;
+  createVersion(name?: string): Promise<VersionSummary>;
+  listVersions(documentId?: string): Promise<VersionSummary[]>;
+  restoreVersion(versionId: string): Promise<FabricDocument>;
+  deleteVersion(versionId: string): Promise<void>;
   save(options?: SaveOptions): Promise<FabricDocument>;
   isDirty(): boolean;
   getSaveState(): SaveState;
@@ -94,6 +134,8 @@ export interface DocumentEngine {
   getAssetManifest(): AssetManifest;
   checkAssets(): Promise<AssetReport>;
   replaceImage(oldUrl: string, newUrl: string): Promise<number>;
+  export(options: ExportOptions): Promise<ExportResult>;
+  preflightExport(options: ExportOptions): Promise<ExportPreflight>;
   flushRecovery(): Promise<void>;
   getRecoverableDocuments(): Promise<RecoveryRecord[]>;
   getRecovery(documentId?: string): Promise<RecoveryRecord | undefined>;

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

@@ -1,9 +1,12 @@
 import { DocumentInfo, FabricDocument } from "../document/document-format.js";
 import { AssetManifest } from "../assets/asset-manifest.js";
 import { AssetOptions, AssetReport, AssetWarning } from "../assets/asset-pipeline.js";
+import { ExportFormat, ExportOptions } from "../export/export-options.js";
+import { ExportPreflight } from "../export/preflight-export.js";
 import { NewDocumentOptions } from "../document/create-document.js";
 import { CustomObjectDefinition } from "../fabric/object-registry.js";
 import { HistoryOptions, HistoryState } from "../history/create-history.js";
+import { VersionOptions, VersionSummary } from "../versions/document-version.js";
 import { InterruptedLoad, RecoveryOptions, RecoveryRecord } from "../recovery/recovery-controller.js";
 import { AutosaveOptions } from "../save/autosave-scheduler.js";
 import { RetryOptions } from "../save/retry.js";
@@ -23,10 +26,24 @@ export interface DocumentEngineOptions {
   saveRetry?: RetryOptions;
   assets?: AssetOptions;
   recovery?: RecoveryOptions;
+  versions?: VersionOptions;
 }
 export interface LoadOptions {
   restoreCanvasSize?: boolean;
 }
+export interface ImportOptions extends LoadOptions {
+  id?: string;
+  metadata?: Record<string, unknown>;
+}
+export interface ExportResult {
+  format: ExportFormat;
+  mimeType: string;
+  blob: Blob;
+  width: number;
+  height: number;
+  warnings: AssetWarning[];
+  document?: FabricDocument;
+}
 export interface DocumentEngineEvents {
   "load:start": {
     documentId: string | undefined;
@@ -34,6 +51,7 @@ export interface DocumentEngineEvents {
   "load:success": {
     document: FabricDocument;
     warnings: AssetWarning[];
+    migratedFrom: number | undefined;
   };
   "assets:warning": {
     warnings: AssetWarning[];
@@ -66,6 +84,23 @@ export interface DocumentEngineEvents {
   "recovery:error": {
     error: DocumentEngineError;
   };
+  "export:success": {
+    format: ExportFormat;
+    width: number;
+    height: number;
+    warnings: AssetWarning[];
+  };
+  "export:error": {
+    error: DocumentEngineError;
+  };
+  "version:created": VersionSummary;
+  "version:restored": {
+    version: VersionSummary;
+    document: FabricDocument;
+  };
+  "version:error": {
+    error: DocumentEngineError;
+  };
 }
 export interface DocumentEngine {
   readonly canvas: StaticCanvas;
@@ -75,6 +110,11 @@ export interface DocumentEngine {
   toDocument(): FabricDocument;
   loadDocument(document: unknown, options?: LoadOptions): Promise<FabricDocument>;
   load(documentId: string, options?: LoadOptions): Promise<FabricDocument>;
+  importFabricJson(json: string | Record<string, unknown>, options?: ImportOptions): Promise<FabricDocument>;
+  createVersion(name?: string): Promise<VersionSummary>;
+  listVersions(documentId?: string): Promise<VersionSummary[]>;
+  restoreVersion(versionId: string): Promise<FabricDocument>;
+  deleteVersion(versionId: string): Promise<void>;
   save(options?: SaveOptions): Promise<FabricDocument>;
   isDirty(): boolean;
   getSaveState(): SaveState;
@@ -94,6 +134,8 @@ export interface DocumentEngine {
   getAssetManifest(): AssetManifest;
   checkAssets(): Promise<AssetReport>;
   replaceImage(oldUrl: string, newUrl: string): Promise<number>;
+  export(options: ExportOptions): Promise<ExportResult>;
+  preflightExport(options: ExportOptions): Promise<ExportPreflight>;
   flushRecovery(): Promise<void>;
   getRecoverableDocuments(): Promise<RecoveryRecord[]>;
   getRecovery(documentId?: string): Promise<RecoveryRecord | undefined>;