fabricjs-document-engine 0.1.0 → 0.3.0

package/dist/assets/asset-pipeline.js

@@ -0,0 +1,172 @@
+import { findImageReferences } from "./asset-references.js";
+import { buildAssetManifest, isEmbeddedUrl } from "./asset-manifest.js";
+import { DocumentEngineError, isDocumentEngineError } from "../engine/errors.js";
+import { findUnavailableFonts } from "./font-check.js";
+import { findMissingImages, isCrossOriginUrl, isPortableUrl } from "./image-check.js";
+//#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(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(findImageReferences(document.objects))) {
+		if (!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 = buildAssetManifest(document.objects);
+	const uniqueImages = [...groupByUrl(findImageReferences(document.objects).filter((reference) => !isEmbeddedUrl(reference.url)))].map(([url, references]) => ({
+		url,
+		crossOrigin: references[0].crossOrigin
+	}));
+	const [missingUrls, unavailableFonts] = await Promise.all([options.checkImages === false ? Promise.resolve([]) : findMissingImages(uniqueImages, signal), 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 findMissingImages([...replacements.values()].map((url) => ({
+		url,
+		crossOrigin: null
+	})), signal));
+	const stillMissing = [];
+	const warnings = [];
+	const groups = groupByUrl(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 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 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 (isDocumentEngineError(error)) throw error;
+		const reason = error instanceof Error ? error.message : String(error);
+		throw new 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 (!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 = buildAssetManifest(document.objects);
+	return {
+		document,
+		warnings
+	};
+}
+//#endregion
+export { inspectAssets, prepareAssetsForLoad, prepareAssetsForSave };

package/dist/assets/asset-references.cjs

@@ -0,0 +1,83 @@
+//#region src/assets/asset-references.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function visitObjects(objects, visit) {
+	const pending = objects.map((object) => ({
+		object,
+		ownerId: object.id
+	})).reverse();
+	while (pending.length > 0) {
+		const { object, ownerId } = pending.pop();
+		const id = object.id ?? ownerId;
+		visit(object, id);
+		const children = (object.objects ?? []).map((child) => ({
+			object: child,
+			ownerId: child.id ?? id
+		}));
+		if (object.clipPath) children.push({
+			object: object.clipPath,
+			ownerId: id
+		});
+		pending.push(...children.reverse());
+	}
+}
+function findImageReferences(objects) {
+	const references = [];
+	visitObjects(objects, (object, objectId) => {
+		if (typeof object.src === "string" && object.src.length > 0) references.push({
+			url: object.src,
+			objectId,
+			crossOrigin: object.crossOrigin,
+			holder: object,
+			key: "src"
+		});
+		for (const paintKey of ["fill", "stroke"]) {
+			const paint = object[paintKey];
+			if (isPlainObject(paint) && typeof paint.source === "string" && paint.source.length > 0) references.push({
+				url: paint.source,
+				objectId,
+				crossOrigin: paint.crossOrigin,
+				holder: paint,
+				key: "source"
+			});
+		}
+	});
+	return references;
+}
+function characterStylesOf(styles) {
+	if (Array.isArray(styles)) return styles.map((range) => isPlainObject(range) && isPlainObject(range.style) ? range.style : {});
+	if (!isPlainObject(styles)) return [];
+	return Object.values(styles).flatMap((line) => isPlainObject(line) ? Object.values(line).filter(isPlainObject) : []);
+}
+function textOf(value, fallback) {
+	if (typeof value === "string" && value.length > 0) return value;
+	if (typeof value === "number") return String(value);
+	return fallback;
+}
+function findFontReferences(objects) {
+	const references = [];
+	visitObjects(objects, (object, objectId) => {
+		if (typeof object.fontFamily !== "string") return;
+		const base = {
+			family: object.fontFamily,
+			weight: textOf(object.fontWeight, "normal"),
+			style: textOf(object.fontStyle, "normal"),
+			objectId
+		};
+		references.push(base);
+		for (const characterStyle of characterStylesOf(object.styles)) {
+			if (characterStyle.fontFamily === void 0 && characterStyle.fontWeight === void 0 && characterStyle.fontStyle === void 0) continue;
+			references.push({
+				family: textOf(characterStyle.fontFamily, base.family),
+				weight: textOf(characterStyle.fontWeight, base.weight),
+				style: textOf(characterStyle.fontStyle, base.style),
+				objectId
+			});
+		}
+	});
+	return references;
+}
+//#endregion
+exports.findFontReferences = findFontReferences;
+exports.findImageReferences = findImageReferences;

package/dist/assets/asset-references.js

@@ -0,0 +1,82 @@
+//#region src/assets/asset-references.ts
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function visitObjects(objects, visit) {
+	const pending = objects.map((object) => ({
+		object,
+		ownerId: object.id
+	})).reverse();
+	while (pending.length > 0) {
+		const { object, ownerId } = pending.pop();
+		const id = object.id ?? ownerId;
+		visit(object, id);
+		const children = (object.objects ?? []).map((child) => ({
+			object: child,
+			ownerId: child.id ?? id
+		}));
+		if (object.clipPath) children.push({
+			object: object.clipPath,
+			ownerId: id
+		});
+		pending.push(...children.reverse());
+	}
+}
+function findImageReferences(objects) {
+	const references = [];
+	visitObjects(objects, (object, objectId) => {
+		if (typeof object.src === "string" && object.src.length > 0) references.push({
+			url: object.src,
+			objectId,
+			crossOrigin: object.crossOrigin,
+			holder: object,
+			key: "src"
+		});
+		for (const paintKey of ["fill", "stroke"]) {
+			const paint = object[paintKey];
+			if (isPlainObject(paint) && typeof paint.source === "string" && paint.source.length > 0) references.push({
+				url: paint.source,
+				objectId,
+				crossOrigin: paint.crossOrigin,
+				holder: paint,
+				key: "source"
+			});
+		}
+	});
+	return references;
+}
+function characterStylesOf(styles) {
+	if (Array.isArray(styles)) return styles.map((range) => isPlainObject(range) && isPlainObject(range.style) ? range.style : {});
+	if (!isPlainObject(styles)) return [];
+	return Object.values(styles).flatMap((line) => isPlainObject(line) ? Object.values(line).filter(isPlainObject) : []);
+}
+function textOf(value, fallback) {
+	if (typeof value === "string" && value.length > 0) return value;
+	if (typeof value === "number") return String(value);
+	return fallback;
+}
+function findFontReferences(objects) {
+	const references = [];
+	visitObjects(objects, (object, objectId) => {
+		if (typeof object.fontFamily !== "string") return;
+		const base = {
+			family: object.fontFamily,
+			weight: textOf(object.fontWeight, "normal"),
+			style: textOf(object.fontStyle, "normal"),
+			objectId
+		};
+		references.push(base);
+		for (const characterStyle of characterStylesOf(object.styles)) {
+			if (characterStyle.fontFamily === void 0 && characterStyle.fontWeight === void 0 && characterStyle.fontStyle === void 0) continue;
+			references.push({
+				family: textOf(characterStyle.fontFamily, base.family),
+				weight: textOf(characterStyle.fontWeight, base.weight),
+				style: textOf(characterStyle.fontStyle, base.style),
+				objectId
+			});
+		}
+	});
+	return references;
+}
+//#endregion
+export { findFontReferences, findImageReferences };

package/dist/assets/font-check.cjs

@@ -0,0 +1,59 @@
+//#region src/assets/font-check.ts
+const genericFamilies = /* @__PURE__ */ new Set([
+	"serif",
+	"sans-serif",
+	"monospace",
+	"cursive",
+	"fantasy",
+	"system-ui",
+	"ui-serif",
+	"ui-sans-serif",
+	"ui-monospace",
+	"ui-rounded",
+	"emoji",
+	"math",
+	"fangsong"
+]);
+const fallbackFamilies = [
+	"monospace",
+	"serif",
+	"sans-serif"
+];
+const sampleText = "mmmmmmmmmmlli WwQq 0123456789";
+function firstFamily(family) {
+	return (family.split(",")[0] ?? family).trim().replace(/^["']|["']$/g, "");
+}
+function cssFamily(family) {
+	return genericFamilies.has(family.toLowerCase()) ? family : `"${family.replace(/"/g, "\\\"")}"`;
+}
+function fontDescriptor(font, size = 32) {
+	return `${font.style} ${font.weight} ${size}px ${cssFamily(firstFamily(font.family))}`;
+}
+function createMeasuringContext() {
+	if (typeof document === "undefined") return null;
+	return document.createElement("canvas").getContext("2d");
+}
+function isFontRenderable(font, context = createMeasuringContext()) {
+	const family = firstFamily(font.family);
+	if (context === null || genericFamilies.has(family.toLowerCase())) return true;
+	return fallbackFamilies.some((fallback) => {
+		context.font = `${font.style} ${font.weight} 72px ${fallback}`;
+		const fallbackWidth = context.measureText(sampleText).width;
+		context.font = `${font.style} ${font.weight} 72px ${cssFamily(family)}, ${fallback}`;
+		return context.measureText(sampleText).width !== fallbackWidth;
+	});
+}
+async function prepareFont(font, loadFont) {
+	if (loadFont) await loadFont(font);
+	const fontSet = typeof document === "undefined" ? void 0 : document.fonts;
+	if (fontSet) await fontSet.load(fontDescriptor(font), sampleText);
+}
+async function findUnavailableFonts(fonts, loadFont) {
+	await Promise.allSettled(fonts.map((font) => prepareFont(font, loadFont)));
+	const context = createMeasuringContext();
+	return fonts.filter((font) => !isFontRenderable(font, context));
+}
+//#endregion
+exports.findUnavailableFonts = findUnavailableFonts;
+exports.fontDescriptor = fontDescriptor;
+exports.isFontRenderable = isFontRenderable;

package/dist/assets/font-check.d.cts

@@ -0,0 +1,4 @@
+import { FontAsset } from "./asset-manifest.cjs";
+//#region src/assets/font-check.d.ts
+export type FontLoader = (font: FontAsset) => void | Promise<void>;
+//#endregion

package/dist/assets/font-check.d.ts

@@ -0,0 +1,4 @@
+import { FontAsset } from "./asset-manifest.js";
+//#region src/assets/font-check.d.ts
+export type FontLoader = (font: FontAsset) => void | Promise<void>;
+//#endregion

package/dist/assets/font-check.js

@@ -0,0 +1,57 @@
+//#region src/assets/font-check.ts
+const genericFamilies = /* @__PURE__ */ new Set([
+	"serif",
+	"sans-serif",
+	"monospace",
+	"cursive",
+	"fantasy",
+	"system-ui",
+	"ui-serif",
+	"ui-sans-serif",
+	"ui-monospace",
+	"ui-rounded",
+	"emoji",
+	"math",
+	"fangsong"
+]);
+const fallbackFamilies = [
+	"monospace",
+	"serif",
+	"sans-serif"
+];
+const sampleText = "mmmmmmmmmmlli WwQq 0123456789";
+function firstFamily(family) {
+	return (family.split(",")[0] ?? family).trim().replace(/^["']|["']$/g, "");
+}
+function cssFamily(family) {
+	return genericFamilies.has(family.toLowerCase()) ? family : `"${family.replace(/"/g, "\\\"")}"`;
+}
+function fontDescriptor(font, size = 32) {
+	return `${font.style} ${font.weight} ${size}px ${cssFamily(firstFamily(font.family))}`;
+}
+function createMeasuringContext() {
+	if (typeof document === "undefined") return null;
+	return document.createElement("canvas").getContext("2d");
+}
+function isFontRenderable(font, context = createMeasuringContext()) {
+	const family = firstFamily(font.family);
+	if (context === null || genericFamilies.has(family.toLowerCase())) return true;
+	return fallbackFamilies.some((fallback) => {
+		context.font = `${font.style} ${font.weight} 72px ${fallback}`;
+		const fallbackWidth = context.measureText(sampleText).width;
+		context.font = `${font.style} ${font.weight} 72px ${cssFamily(family)}, ${fallback}`;
+		return context.measureText(sampleText).width !== fallbackWidth;
+	});
+}
+async function prepareFont(font, loadFont) {
+	if (loadFont) await loadFont(font);
+	const fontSet = typeof document === "undefined" ? void 0 : document.fonts;
+	if (fontSet) await fontSet.load(fontDescriptor(font), sampleText);
+}
+async function findUnavailableFonts(fonts, loadFont) {
+	await Promise.allSettled(fonts.map((font) => prepareFont(font, loadFont)));
+	const context = createMeasuringContext();
+	return fonts.filter((font) => !isFontRenderable(font, context));
+}
+//#endregion
+export { findUnavailableFonts, fontDescriptor, isFontRenderable };

package/dist/assets/image-check.cjs

@@ -0,0 +1,36 @@
+let fabric = require("fabric");
+//#region src/assets/image-check.ts
+function isCrossOriginUrl(url) {
+	const location = globalThis.location;
+	if (!location || url.startsWith("data:") || url.startsWith("blob:")) return false;
+	try {
+		const parsed = new URL(url, location.href);
+		return (parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.origin !== location.origin;
+	} catch {
+		return false;
+	}
+}
+function isPortableUrl(url) {
+	return !url.startsWith("blob:");
+}
+function isSameUrl(first, second) {
+	if (first === second) return true;
+	const location = globalThis.location;
+	try {
+		return new URL(first, location?.href).href === new URL(second, location?.href).href;
+	} catch {
+		return false;
+	}
+}
+async function findMissingImages(images, signal) {
+	const results = await Promise.allSettled(images.map((image) => fabric.util.loadImage(image.url, {
+		signal,
+		crossOrigin: image.crossOrigin ?? null
+	})));
+	return images.filter((_, index) => results[index].status === "rejected").map((image) => image.url);
+}
+//#endregion
+exports.findMissingImages = findMissingImages;
+exports.isCrossOriginUrl = isCrossOriginUrl;
+exports.isPortableUrl = isPortableUrl;
+exports.isSameUrl = isSameUrl;

package/dist/assets/image-check.js

@@ -0,0 +1,33 @@
+import { util } from "fabric";
+//#region src/assets/image-check.ts
+function isCrossOriginUrl(url) {
+	const location = globalThis.location;
+	if (!location || url.startsWith("data:") || url.startsWith("blob:")) return false;
+	try {
+		const parsed = new URL(url, location.href);
+		return (parsed.protocol === "http:" || parsed.protocol === "https:") && parsed.origin !== location.origin;
+	} catch {
+		return false;
+	}
+}
+function isPortableUrl(url) {
+	return !url.startsWith("blob:");
+}
+function isSameUrl(first, second) {
+	if (first === second) return true;
+	const location = globalThis.location;
+	try {
+		return new URL(first, location?.href).href === new URL(second, location?.href).href;
+	} catch {
+		return false;
+	}
+}
+async function findMissingImages(images, signal) {
+	const results = await Promise.allSettled(images.map((image) => util.loadImage(image.url, {
+		signal,
+		crossOrigin: image.crossOrigin ?? null
+	})));
+	return images.filter((_, index) => results[index].status === "rejected").map((image) => image.url);
+}
+//#endregion
+export { findMissingImages, isCrossOriginUrl, isPortableUrl, isSameUrl };

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

@@ -1,3 +1,4 @@
+import { AssetManifest } from "../assets/asset-manifest.cjs";
 //#region src/document/document-format.d.ts
 export declare const CURRENT_SCHEMA_VERSION = 1;
 export interface SerializedFabricObject {
@@ -17,9 +18,11 @@ export interface FabricDocument {
   id: string;
   createdAt: string;
   updatedAt: string;
+  revision?: number;
   fabricVersion?: string;
   canvas: DocumentCanvas;
   objects: SerializedFabricObject[];
+  assets?: AssetManifest;
   metadata: Record<string, unknown>;
 }
 export interface DocumentInfo {

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

@@ -1,3 +1,4 @@
+import { AssetManifest } from "../assets/asset-manifest.js";
 //#region src/document/document-format.d.ts
 export declare const CURRENT_SCHEMA_VERSION = 1;
 export interface SerializedFabricObject {
@@ -17,9 +18,11 @@ export interface FabricDocument {
   id: string;
   createdAt: string;
   updatedAt: string;
+  revision?: number;
   fabricVersion?: string;
   canvas: DocumentCanvas;
   objects: SerializedFabricObject[];
+  assets?: AssetManifest;
   metadata: Record<string, unknown>;
 }
 export interface DocumentInfo {

package/dist/document/validate-document.cjs

@@ -57,6 +57,11 @@ function validateDocument(value) {
 	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 (value.revision !== void 0 && !(Number.isInteger(value.revision) && value.revision >= 0)) issues.push(invalid("revision", "must be a whole number of zero or more when present"));
+	if (value.assets !== void 0) {
+		const assets = value.assets;
+		if (!isPlainObject(assets) || !Array.isArray(assets.images) || !Array.isArray(assets.fonts)) issues.push(invalid("assets", "must be an object with images and fonts arrays when present"));
+	}
 	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 {

package/dist/document/validate-document.js

@@ -57,6 +57,11 @@ function validateDocument(value) {
 	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 (value.revision !== void 0 && !(Number.isInteger(value.revision) && value.revision >= 0)) issues.push(invalid("revision", "must be a whole number of zero or more when present"));
+	if (value.assets !== void 0) {
+		const assets = value.assets;
+		if (!isPlainObject(assets) || !Array.isArray(assets.images) || !Array.isArray(assets.fonts)) issues.push(invalid("assets", "must be an object with images and fonts arrays when present"));
+	}
 	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 {