fabricjs-document-engine 0.1.0 → 0.3.0

package/README.md

@@ -8,7 +8,9 @@ Fabric already draws objects, handles interaction and serializes to JSON. This p
 - **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.
+- **Safe saving.** It tracks unsaved changes and can autosave. Only one save runs at a time, so a slow older save can never overwrite newer work. Revision checks catch another tab or device saving the same document, and failed saves are retried with backoff.
+- **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.
 - **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.
 
@@ -37,20 +39,142 @@ await engine.loadDocument(JSON.parse(localStorage.getItem(document.id)!));
 
 ## Saving and loading through storage
 
+The built-in adapters are the quickest way to start:
+
 ```ts
+import { createLocalStorage, createMemoryStorage } from 'fabricjs-document-engine/storage';
+
 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(() => {}),
-  },
+  storage: createLocalStorage({ prefix: 'my-app:' }),
+  autosave: true,
 });
 
 await engine.load('project-42');
 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)`.
+
+### Your own backend
+
+A storage adapter is two functions:
+
+```ts
+import { createDocumentEngine, createConflictError } from 'fabricjs-document-engine';
+import type { DocumentStorage } from 'fabricjs-document-engine';
+
+const storage: DocumentStorage = {
+  async loadDocument(id) {
+    const response = await fetch(`/api/documents/${id}`);
+    return response.json();
+  },
+  async saveDocument(document, { expectedRevision, signal }) {
+    const response = await fetch(`/api/documents/${document.id}`, {
+      method: 'PUT',
+      headers: { 'If-Match': String(expectedRevision ?? '*') },
+      body: JSON.stringify(document),
+      signal,
+    });
+    if (response.status === 409) throw Object.assign(new Error('Saved elsewhere'), { code: 'SAVE_CONFLICT' });
+    if (response.status === 403) throw Object.assign(new Error('Not allowed'), { retryable: false });
+    if (!response.ok) throw new Error(`Save failed with ${response.status}`);
+    return { revision: document.revision };
+  },
+};
+```
+
+- `expectedRevision` is the revision this editor last saved or loaded. Reject the save when the stored document has a different revision. It is `null` when the user chose to overwrite.
+- `document.revision` is the next revision. If your backend assigns its own number, return `{ revision }`.
+- Throw an error with `code: 'SAVE_CONFLICT'`, or use `createConflictError(id, expected, actual)`, to report a conflict. Conflicts are never retried.
+- Throw an error with `retryable: false` for failures that retrying cannot fix. Every other error is retried.
+- Pass `signal` to `fetch`. The engine aborts it when another document is opened.
+
+## Safe saving
+
+```ts
+const engine = createDocumentEngine({
+  canvas,
+  storage,
+  autosave: { delay: 1000, maxWait: 10000 },
+  saveRetry: { attempts: 3, baseDelay: 500, maxDelay: 8000 },
+});
+
+engine.on('save:status', ({ status, isDirty, revision, lastSavedAt, error }) => {
+  statusLabel.textContent = status;
+});
+```
+
+`status` is one of `saved`, `unsaved`, `saving`, `error` or `conflict`.
+
+- **Unsaved changes.** Every recorded history step, undo, redo and metadata change marks the document as changed. `engine.isDirty()` tells you whether anything is unsaved. Edits made while a save is running stay unsaved until the next save.
+- **Autosave.** It saves after `delay` ms without edits, and at the latest `maxWait` ms after the first unsaved edit, even while the user keeps editing. `autosave: true` uses the defaults shown above.
+- **One save at a time.** Calling `save()` while a save is running queues exactly one follow-up save of the latest content. Responses can never arrive out of order.
+- **Stale responses.** If another document is loaded while a save is running, that save's response is ignored and any queued save is cancelled with `SAVE_CANCELLED`.
+- **Conflicts.** When another tab or device saved first, the save fails with `SAVE_CONFLICT` and the status becomes `conflict`. Either reload the document with `engine.load(id)`, or keep your version with `engine.save({ overwrite: true })`.
+- **Retries.** Temporary failures are retried with exponential backoff and jitter. Each retry emits `save:retry` with `{ attempt, delay, error }`.
+
+### Warn before leaving
+
+```ts
+import { bindUnsavedChangesWarning } from 'fabricjs-document-engine';
+
+const unbind = bindUnsavedChangesWarning(engine);
+```
+
+## Assets and fonts
+
+Every saved document carries an `assets` manifest that lists each image URL and font variant, together with the ids of the objects that use them. Images embedded as `data:` URLs are left out of the manifest because they need no fetching.
+
+```ts
+const engine = createDocumentEngine({
+  canvas,
+  storage,
+  assets: {
+    resolveUrl: (url) => url.replace('asset://', 'https://cdn.example.com/'),
+    replaceMissingImage: (image) => '/placeholder.png',
+    upload: async ({ blob }) => uploadToYourBucket(blob),
+    loadFont: async ({ family, weight, style }) => {
+      const face = new FontFace(family, `url(/fonts/${family}-${weight}.woff2)`, { weight, style });
+      document.fonts.add(await face.load());
+    },
+    requireFonts: false,
+  },
+});
+
+engine.on('assets:warning', ({ warnings }) => warnings.forEach((warning) => console.warn(warning.message)));
+```
+
+### When a document is opened
+
+1. `resolveUrl` can rewrite each stored URL, for example to sign it or to map asset ids to a CDN.
+2. `loadFont` runs for each font variant. Then the engine checks that the font really renders, rather than silently falling back to a default.
+3. Every image loads in parallel. If any are missing, `replaceMissingImage` can supply a replacement URL for each one. Return `null` to leave it missing.
+4. If images are still missing, loading fails with `MISSING_ASSETS`, and `error.missingAssets` lists each `{ url, objectIds }`. The canvas is not touched.
+
+Fonts that are not available produce a `FONT_UNAVAILABLE` warning and the text uses a fallback font. Set `requireFonts: true` to fail with `MISSING_FONTS` instead. Warnings are also delivered with `load:success` as `{ document, warnings }`.
+
+### When a document is saved
+
+Images that exist only in this tab (`blob:` URLs) and embedded `data:` images are passed to `upload` once, and the document stores the returned URL. Without an `upload` handler, `blob:` images produce an `ASSET_NOT_PORTABLE` warning, because another device cannot open them.
+
+### Cross-origin images
+
+An image from another site without `crossOrigin: 'anonymous'` taints the canvas, and exporting it will fail. The engine warns with `IMAGE_CROSS_ORIGIN` so you can fix it before the user tries to export.
+
+### Checking and replacing at any time
+
+```ts
+const report = await engine.checkAssets();
+report.missingImages;
+report.unavailableFonts;
+report.warnings;
+
+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.
+
 ## Custom objects
 
 ```ts
@@ -125,9 +249,14 @@ interface FabricDocument {
   id: string;
   createdAt: string;
   updatedAt: string;
+  revision?: number;
   fabricVersion?: string;
   canvas: { width: number; height: number; background?: unknown };
   objects: SerializedFabricObject[];
+  assets?: {
+    images: Array<{ url: string; objectIds: string[] }>;
+    fonts: Array<{ family: string; weight: string; style: string; objectIds: string[] }>;
+  };
   metadata: Record<string, unknown>;
 }
 ```
@@ -141,12 +270,18 @@ Keep project data such as titles, owners and tags in `metadata` with `engine.upd
 | `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.load(id)` / `engine.save({ overwrite? })` | Reads from or writes to your storage adapter. |
+| `engine.isDirty()` | Tells you whether there are unsaved changes. |
+| `engine.getSaveState()` | Returns `{ status, isDirty, isSaving, revision, lastSavedAt, error }`. |
+| `bindUnsavedChangesWarning(engine)` | Asks the browser to confirm before closing a page with unsaved changes. Returns an unbind function. |
 | `engine.newDocument({ id?, metadata? })` | Clears the canvas and starts a fresh document. |
 | `engine.getDocumentInfo()` | Returns the current document's id, dates and metadata. |
 | `engine.updateMetadata(changes)` | Merges changes into the document metadata. |
 | `engine.getObjectById(id)` | Finds any object by id, including objects inside groups. |
 | `engine.registerObject({ fabricClass, properties })` | Registers a custom class after the engine is created. |
+| `engine.getAssetManifest()` | Lists the images and fonts used on the canvas. |
+| `engine.checkAssets()` | Resolves to `{ manifest, missingImages, unavailableFonts, warnings }` for the current canvas. |
+| `engine.replaceImage(oldUrl, newUrl)` | Replaces every image with that URL as one undo step. Resolves to the number of images replaced. |
 | `engine.transaction(label, work)` | Runs `work` and records everything it changed as one undo step. Returns what `work` returns. |
 | `engine.commit(label?)` | Records changes made since the last step. Returns `false` when nothing changed. |
 | `engine.undo()` / `engine.redo()` | Resolves to `true` when a step was applied. Calls run one after another. |
@@ -154,7 +289,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`, `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`, `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. |
 
@@ -169,7 +304,13 @@ Every failure is a `DocumentEngineError` with a `code` you can switch on:
 | `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. |
+| `MISSING_ASSETS` | Images could not be loaded and had no replacement. `error.missingAssets` lists each `{ url, objectIds }`. |
+| `MISSING_FONTS` | Fonts are not available and `requireFonts` is on. `error.missingFonts` lists them. |
+| `ASSET_UPLOAD_FAILED` | Your `upload` handler failed while saving. |
+| `SAVE_FAILED` | Your storage adapter rejected the save after all retries. `error.retryable` tells you whether trying again could help. |
+| `SAVE_CONFLICT` | Another tab or device saved this document first. |
+| `SAVE_CANCELLED` | A queued save was dropped because another document was opened. |
+| `DOCUMENT_NOT_FOUND` | The built-in adapters have no document with that id. |
 | `HISTORY_FAILED` | Undo or redo could not rebuild an object, for example because an image is gone. The step is kept and the canvas is unchanged. |
 | `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. |
@@ -179,18 +320,18 @@ 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 |
+| Stage | Focus | Released in |
+| --- | --- | --- |
+| 1 | Document foundation: ids, save and load, validation, custom objects | 0.0.0 |
+| 2 | Undo and redo with transactions | 0.1.0 |
+| 3 | Safe saving: dirty state, autosave, stale-response protection | 0.2.0 |
+| 4 | Assets and fonts | 0.3.0 |
+| 5 | Recovery after a refresh or crash | |
+| 6 | PNG, JPEG, SVG and JSON export with preflight checks | |
+| 7 | Named versions and schema migrations | |
+| 8 | React adapter and examples | |
+| 9 | Hardening and benchmarks | |
+| 10 | Stable API | 1.0.0 |
 
 ## License
 

package/dist/assets/asset-manifest.cjs

@@ -0,0 +1,43 @@
+const require_asset_references = require("./asset-references.cjs");
+//#region src/assets/asset-manifest.ts
+function isEmbeddedUrl(url) {
+	return url.startsWith("data:");
+}
+function fontKey(font) {
+	return `${font.style}|${font.weight}|${font.family}`;
+}
+function addObjectId(objectIds, objectId) {
+	if (objectId !== void 0 && !objectIds.includes(objectId)) objectIds.push(objectId);
+}
+function buildAssetManifest(objects) {
+	const imagesByUrl = /* @__PURE__ */ new Map();
+	for (const reference of require_asset_references.findImageReferences(objects)) {
+		if (isEmbeddedUrl(reference.url)) continue;
+		const image = imagesByUrl.get(reference.url) ?? {
+			url: reference.url,
+			objectIds: []
+		};
+		addObjectId(image.objectIds, reference.objectId);
+		imagesByUrl.set(reference.url, image);
+	}
+	const fontsByKey = /* @__PURE__ */ new Map();
+	for (const reference of require_asset_references.findFontReferences(objects)) {
+		const key = fontKey(reference);
+		const font = fontsByKey.get(key) ?? {
+			family: reference.family,
+			weight: reference.weight,
+			style: reference.style,
+			objectIds: []
+		};
+		addObjectId(font.objectIds, reference.objectId);
+		fontsByKey.set(key, font);
+	}
+	return {
+		images: [...imagesByUrl.values()],
+		fonts: [...fontsByKey.values()]
+	};
+}
+//#endregion
+exports.buildAssetManifest = buildAssetManifest;
+exports.fontKey = fontKey;
+exports.isEmbeddedUrl = isEmbeddedUrl;

package/dist/assets/asset-manifest.d.cts

@@ -0,0 +1,16 @@
+//#region src/assets/asset-manifest.d.ts
+export interface ImageAsset {
+  url: string;
+  objectIds: string[];
+}
+export interface FontAsset {
+  family: string;
+  weight: string;
+  style: string;
+  objectIds: string[];
+}
+export interface AssetManifest {
+  images: ImageAsset[];
+  fonts: FontAsset[];
+}
+//#endregion

package/dist/assets/asset-manifest.d.ts

@@ -0,0 +1,16 @@
+//#region src/assets/asset-manifest.d.ts
+export interface ImageAsset {
+  url: string;
+  objectIds: string[];
+}
+export interface FontAsset {
+  family: string;
+  weight: string;
+  style: string;
+  objectIds: string[];
+}
+export interface AssetManifest {
+  images: ImageAsset[];
+  fonts: FontAsset[];
+}
+//#endregion

package/dist/assets/asset-manifest.js

@@ -0,0 +1,41 @@
+import { findFontReferences, findImageReferences } from "./asset-references.js";
+//#region src/assets/asset-manifest.ts
+function isEmbeddedUrl(url) {
+	return url.startsWith("data:");
+}
+function fontKey(font) {
+	return `${font.style}|${font.weight}|${font.family}`;
+}
+function addObjectId(objectIds, objectId) {
+	if (objectId !== void 0 && !objectIds.includes(objectId)) objectIds.push(objectId);
+}
+function buildAssetManifest(objects) {
+	const imagesByUrl = /* @__PURE__ */ new Map();
+	for (const reference of findImageReferences(objects)) {
+		if (isEmbeddedUrl(reference.url)) continue;
+		const image = imagesByUrl.get(reference.url) ?? {
+			url: reference.url,
+			objectIds: []
+		};
+		addObjectId(image.objectIds, reference.objectId);
+		imagesByUrl.set(reference.url, image);
+	}
+	const fontsByKey = /* @__PURE__ */ new Map();
+	for (const reference of findFontReferences(objects)) {
+		const key = fontKey(reference);
+		const font = fontsByKey.get(key) ?? {
+			family: reference.family,
+			weight: reference.weight,
+			style: reference.style,
+			objectIds: []
+		};
+		addObjectId(font.objectIds, reference.objectId);
+		fontsByKey.set(key, font);
+	}
+	return {
+		images: [...imagesByUrl.values()],
+		fonts: [...fontsByKey.values()]
+	};
+}
+//#endregion
+export { buildAssetManifest, fontKey, isEmbeddedUrl };

package/dist/assets/asset-pipeline.cjs

@@ -0,0 +1,174 @@
+const require_asset_references = require("./asset-references.cjs");
+const require_asset_manifest = require("./asset-manifest.cjs");
+const require_errors = require("../engine/errors.cjs");
+const require_font_check = require("./font-check.cjs");
+const require_image_check = require("./image-check.cjs");
+//#region src/assets/asset-pipeline.ts
+function cloneDocument(document) {
+	return JSON.parse(JSON.stringify(document));
+}
+function groupByUrl(references) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const reference of references) {
+		const group = groups.get(reference.url) ?? [];
+		group.push(reference);
+		groups.set(reference.url, group);
+	}
+	return groups;
+}
+function objectIdsOf(references) {
+	return [...new Set(references.map((reference) => reference.objectId).filter((id) => id !== void 0))];
+}
+function pointTo(references, url) {
+	for (const reference of references) {
+		reference.holder[reference.key] = url;
+		reference.url = url;
+	}
+}
+async function rewriteUrls(document, rewrite) {
+	const groups = groupByUrl(require_asset_references.findImageReferences(document.objects));
+	await Promise.all([...groups].map(async ([url, references]) => {
+		const next = await rewrite(url, references);
+		if (next !== url) pointTo(references, next);
+	}));
+}
+function crossOriginWarnings(document) {
+	const warnings = [];
+	for (const [url, references] of groupByUrl(require_asset_references.findImageReferences(document.objects))) {
+		if (!require_image_check.isCrossOriginUrl(url) || references.every((reference) => reference.crossOrigin)) continue;
+		warnings.push({
+			code: "IMAGE_CROSS_ORIGIN",
+			message: `The image ${url} comes from another site without crossOrigin set, so exporting the canvas will fail`,
+			url,
+			objectIds: objectIdsOf(references)
+		});
+	}
+	return warnings;
+}
+function fontWarnings(fonts) {
+	return fonts.map((font) => ({
+		code: "FONT_UNAVAILABLE",
+		message: `The font "${font.family}" (${font.weight}, ${font.style}) is not available, text will use a fallback font`,
+		family: font.family,
+		objectIds: font.objectIds
+	}));
+}
+async function inspectAssets(document, options, signal) {
+	const manifest = require_asset_manifest.buildAssetManifest(document.objects);
+	const uniqueImages = [...groupByUrl(require_asset_references.findImageReferences(document.objects).filter((reference) => !require_asset_manifest.isEmbeddedUrl(reference.url)))].map(([url, references]) => ({
+		url,
+		crossOrigin: references[0].crossOrigin
+	}));
+	const [missingUrls, unavailableFonts] = await Promise.all([options.checkImages === false ? Promise.resolve([]) : require_image_check.findMissingImages(uniqueImages, signal), require_font_check.findUnavailableFonts(manifest.fonts, options.loadFont)]);
+	const missing = new Set(missingUrls);
+	return {
+		manifest,
+		missingImages: manifest.images.filter((image) => missing.has(image.url)),
+		unavailableFonts,
+		warnings: [...crossOriginWarnings(document), ...fontWarnings(unavailableFonts)]
+	};
+}
+async function replaceMissingImages(document, missingImages, options, signal) {
+	const replace = options.replaceMissingImage;
+	if (!replace || missingImages.length === 0) return {
+		stillMissing: [...missingImages],
+		warnings: []
+	};
+	const replacements = /* @__PURE__ */ new Map();
+	for (const image of missingImages) {
+		const replacement = await replace(image);
+		if (typeof replacement === "string" && replacement.length > 0) replacements.set(image.url, replacement);
+	}
+	const brokenReplacements = new Set(await require_image_check.findMissingImages([...replacements.values()].map((url) => ({
+		url,
+		crossOrigin: null
+	})), signal));
+	const stillMissing = [];
+	const warnings = [];
+	const groups = groupByUrl(require_asset_references.findImageReferences(document.objects));
+	for (const image of missingImages) {
+		const replacement = replacements.get(image.url);
+		if (replacement === void 0 || brokenReplacements.has(replacement)) {
+			stillMissing.push(image);
+			continue;
+		}
+		pointTo(groups.get(image.url) ?? [], replacement);
+		warnings.push({
+			code: "IMAGE_REPLACED",
+			message: `The missing image ${image.url} was replaced with ${replacement}`,
+			url: image.url,
+			objectIds: image.objectIds
+		});
+	}
+	return {
+		stillMissing,
+		warnings
+	};
+}
+async function prepareAssetsForLoad(input, options, signal) {
+	const document = cloneDocument(input);
+	const { resolveUrl } = options;
+	if (resolveUrl) await rewriteUrls(document, async (url) => resolveUrl(url));
+	const report = await inspectAssets(document, options, signal);
+	if (options.requireFonts && report.unavailableFonts.length > 0) {
+		const families = report.unavailableFonts.map((font) => font.family).join(", ");
+		throw new require_errors.DocumentEngineError("MISSING_FONTS", `These fonts are not available: ${families}`, { missingFonts: report.unavailableFonts });
+	}
+	const { stillMissing, warnings } = await replaceMissingImages(document, report.missingImages, options, signal);
+	if (stillMissing.length > 0) {
+		const urls = stillMissing.map((image) => image.url).join(", ");
+		throw new require_errors.DocumentEngineError("MISSING_ASSETS", `These images could not be loaded: ${urls}`, { missingAssets: stillMissing });
+	}
+	return {
+		document,
+		warnings: [...report.warnings, ...warnings]
+	};
+}
+async function uploadOnce(url, references, upload) {
+	try {
+		return await upload({
+			url,
+			blob: await (await fetch(url)).blob(),
+			objectIds: objectIdsOf(references)
+		});
+	} catch (error) {
+		if (require_errors.isDocumentEngineError(error)) throw error;
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new require_errors.DocumentEngineError("ASSET_UPLOAD_FAILED", `Could not upload the image ${url.slice(0, 60)}: ${reason}`, {
+			cause: error,
+			retryable: true
+		});
+	}
+}
+async function prepareAssetsForSave(document, options, uploadedUrls) {
+	const { upload } = options;
+	const warnings = [];
+	await rewriteUrls(document, async (url, references) => {
+		if (!(url.startsWith("blob:") || url.startsWith("data:"))) return url;
+		if (!upload) {
+			if (!require_image_check.isPortableUrl(url)) warnings.push({
+				code: "ASSET_NOT_PORTABLE",
+				message: `The image ${url} only exists in this browser tab. Pass assets.upload to store it before saving.`,
+				url,
+				objectIds: objectIdsOf(references)
+			});
+			return url;
+		}
+		let uploading = uploadedUrls.get(url);
+		if (!uploading) {
+			uploading = uploadOnce(url, references, upload);
+			uploadedUrls.set(url, uploading);
+			uploading.catch(() => uploadedUrls.delete(url));
+		}
+		return uploading;
+	});
+	document.assets = require_asset_manifest.buildAssetManifest(document.objects);
+	return {
+		document,
+		warnings
+	};
+}
+//#endregion
+exports.inspectAssets = inspectAssets;
+exports.prepareAssetsForLoad = prepareAssetsForLoad;
+exports.prepareAssetsForSave = prepareAssetsForSave;

package/dist/assets/asset-pipeline.d.cts

@@ -0,0 +1,31 @@
+import { AssetManifest, FontAsset, ImageAsset } from "./asset-manifest.cjs";
+import { FontLoader } from "./font-check.cjs";
+//#region src/assets/asset-pipeline.d.ts
+export type AssetWarningCode = "IMAGE_CROSS_ORIGIN" | "FONT_UNAVAILABLE" | "ASSET_NOT_PORTABLE" | "IMAGE_REPLACED";
+export interface AssetWarning {
+  code: AssetWarningCode;
+  message: string;
+  url?: string;
+  family?: string;
+  objectIds: string[];
+}
+export interface UploadRequest {
+  url: string;
+  blob: Blob;
+  objectIds: string[];
+}
+export interface AssetOptions {
+  resolveUrl?: (url: string) => string | Promise<string>;
+  replaceMissingImage?: (image: ImageAsset) => string | null | undefined | Promise<string | null | undefined>;
+  upload?: (request: UploadRequest) => Promise<string>;
+  loadFont?: FontLoader;
+  checkImages?: boolean;
+  requireFonts?: boolean;
+}
+export interface AssetReport {
+  manifest: AssetManifest;
+  missingImages: ImageAsset[];
+  unavailableFonts: FontAsset[];
+  warnings: AssetWarning[];
+}
+//#endregion

package/dist/assets/asset-pipeline.d.ts

@@ -0,0 +1,31 @@
+import { AssetManifest, FontAsset, ImageAsset } from "./asset-manifest.js";
+import { FontLoader } from "./font-check.js";
+//#region src/assets/asset-pipeline.d.ts
+export type AssetWarningCode = "IMAGE_CROSS_ORIGIN" | "FONT_UNAVAILABLE" | "ASSET_NOT_PORTABLE" | "IMAGE_REPLACED";
+export interface AssetWarning {
+  code: AssetWarningCode;
+  message: string;
+  url?: string;
+  family?: string;
+  objectIds: string[];
+}
+export interface UploadRequest {
+  url: string;
+  blob: Blob;
+  objectIds: string[];
+}
+export interface AssetOptions {
+  resolveUrl?: (url: string) => string | Promise<string>;
+  replaceMissingImage?: (image: ImageAsset) => string | null | undefined | Promise<string | null | undefined>;
+  upload?: (request: UploadRequest) => Promise<string>;
+  loadFont?: FontLoader;
+  checkImages?: boolean;
+  requireFonts?: boolean;
+}
+export interface AssetReport {
+  manifest: AssetManifest;
+  missingImages: ImageAsset[];
+  unavailableFonts: FontAsset[];
+  warnings: AssetWarning[];
+}
+//#endregion