polotno-node 3.0.2 → 3.0.4

package/lib/instance.js

@@ -8,6 +8,7 @@ import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 import { assertValidDesign } from "@polotno/schema";
 import * as fontCache from "./font-cache.js";
+import { polotnoError, rehydrateError } from "./errors.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Compiled to lib/instance.js; the client bundle is published to ../dist.
 const DEFAULT_CLIENT = `file:${path.join(__dirname, "..", "dist", "index.html")}`;
@@ -85,7 +86,7 @@ const guessExtension = (urlString, contentType) => {
 };
 const downloadUrlToFile = async (urlString, destinationPath) => {
     if (typeof fetch !== "function") {
-        throw new Error("Global fetch API is not available in this Node.js runtime. Please use Node 18+.");
+        throw polotnoError("FETCH_FAILED", "Global fetch API is not available in this Node.js runtime. Please use Node 18+.", { url: urlString });
     }
     const MAX_ATTEMPTS = 3;
     const BASE_DELAY_MS = 300;
@@ -113,10 +114,12 @@ const downloadUrlToFile = async (urlString, destinationPath) => {
                 ]
                     .filter(Boolean)
                     .join(", ");
-                throw new Error(`HTTP error while downloading: ${details}`);
+                throw polotnoError("FETCH_FAILED", `HTTP error while downloading: ${details}`, { url: urlString, status: res.status });
             }
             if (!res.body) {
-                throw new Error("Empty response body");
+                throw polotnoError("FETCH_FAILED", "Empty response body", {
+                    url: urlString,
+                });
             }
             await pipeline(Readable.fromWeb(res.body), fs.createWriteStream(destinationPath));
             return res.headers.get("content-type") || "";
@@ -131,7 +134,7 @@ const downloadUrlToFile = async (urlString, destinationPath) => {
         }
     }
     const message = lastError && lastError.message ? lastError.message : String(lastError);
-    throw new Error(`Failed to download media after ${MAX_ATTEMPTS} attempts: ${urlString}\nLast error: ${message}`);
+    throw polotnoError("FETCH_FAILED", `Failed to download media after ${MAX_ATTEMPTS} attempts: ${urlString}\nLast error: ${message}`, { url: urlString, attempts: MAX_ATTEMPTS }, lastError);
 };
 // Returns a human-readable reason string if the video file needs transcoding
 // for Chromium headless compatibility, or null if it is already render-safe.
@@ -400,37 +403,41 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
             // across all exports (dataURL/image/pdf/video).
             if (!window.__polotnoConsumeAssetError) {
                 window.__polotnoConsumeAssetError = (attrs) => {
-                    const error = window._polotnoError;
-                    if (!error)
+                    const payload = window._polotnoError;
+                    if (!payload)
                         return null;
                     // Clear immediately to avoid double-reporting.
                     window._polotnoError = null;
-                    const message = String(error);
-                    // Cross-package contract: every font-load error from polotno core
-                    // references the family as `font "<name>"` (e.g. `Timeout for
-                    // loading font "X"`, `Font "X" not found: ...`). Match that stable
-                    // marker rather than any one full sentence.
-                    const isFontError = /font\s+"/i.test(message);
-                    const skipFontError = isFontError && attrs && attrs.skipFontError;
-                    const isImageError = message.indexOf("image ") >= 0;
-                    const skipImageError = isImageError && attrs && attrs.skipImageError;
-                    if (skipFontError || skipImageError) {
+                    // The client stashes a structured `{code, message, details}`
+                    // payload (image timeouts arrive as IMAGE_FAILED/reason:'timeout',
+                    // so skip flags cover them too).
+                    const code = typeof payload === "object" ? payload.code : null;
+                    if (code === "FONT_FAILED" && attrs && attrs.skipFontError) {
+                        return null;
+                    }
+                    if (code === "IMAGE_FAILED" && attrs && attrs.skipImageError) {
                         return null;
                     }
-                    return message;
+                    // Return the payload as-is (object, or string from a legacy client);
+                    // the Node side rehydrates it into an Error with code + details.
+                    return payload;
                 };
             }
             if (!window.__polotnoThrowAssetErrorIfAny) {
                 window.__polotnoThrowAssetErrorIfAny = (attrs) => {
-                    const message = window.__polotnoConsumeAssetError(attrs);
-                    if (message) {
-                        throw new Error(message);
+                    const payload = window.__polotnoConsumeAssetError(attrs);
+                    if (payload) {
+                        // Re-stash so the Node side can pull the structured payload after
+                        // this throw is flattened by page.evaluate (thrown Errors cross
+                        // the boundary as message-only).
+                        window._polotnoError = payload;
+                        throw new Error(typeof payload === "string" ? payload : String(payload.message));
                     }
                 };
             }
         });
     }
-    async function consumeAssetLoadingErrorMessage(page, attrs) {
+    async function consumeAssetLoadingError(page, attrs) {
         try {
             return await page.evaluate((attrs) => {
                 if (window.__polotnoConsumeAssetError) {
@@ -449,7 +456,7 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
             ? await createPage(browser, visitPage, requestInterceptor, useFontCache)
             : firstPage;
         if (busyPages.indexOf(page) >= 0) {
-            throw new Error("Current rendering context is busy with another task. Please use `useParallelPages: true` option to run multiple tasks in parallel or make sure previous task is finished before starting a new one.");
+            throw polotnoError("EXPORT_FAILED", "Current rendering context is busy with another task. Please use `useParallelPages: true` option to run multiple tasks in parallel or make sure previous task is finished before starting a new one.", { reason: "busy" });
         }
         busyPages.push(page);
         // Setup profiling if profilePath is provided
@@ -478,7 +485,13 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
             await page.evaluate(() => {
                 if (window.config?.onLoadError) {
                     window.config.onLoadError((error) => {
-                        window._polotnoError = error;
+                        // New clients pass an Error with `code`/`details` — stash a JSON
+                        // form so both survive the trip to Node. Old clients pass a string.
+                        const e = error;
+                        window._polotnoError =
+                            e && e.code
+                                ? { code: e.code, message: String(e.message), details: e.details }
+                                : String(error);
                     });
                 }
                 else {
@@ -493,9 +506,9 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                 fs.writeFileSync(profilePath, JSON.stringify(profile));
                 console.log(`CPU profile saved to: ${profilePath}`);
             }
-            const assetErrorMessage = await consumeAssetLoadingErrorMessage(page, args[1]);
-            if (assetErrorMessage) {
-                throw new Error(assetErrorMessage);
+            const assetError = await consumeAssetLoadingError(page, args[1]);
+            if (assetError) {
+                throw rehydrateError(assetError);
             }
             // remove busy page
             busyPages.splice(busyPages.indexOf(page), 1);
@@ -519,14 +532,14 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
             }
             // If `page.evaluate()` failed (e.g. thrown during onProgress), still prefer
             // a captured Polotno asset-loading error when available.
-            const assetErrorMessage = await consumeAssetLoadingErrorMessage(page, args[1]);
+            const assetError = await consumeAssetLoadingError(page, args[1]);
             // remove busy page
             busyPages.splice(busyPages.indexOf(page), 1);
             if (useParallelPages) {
                 await page.close();
             }
-            if (assetErrorMessage) {
-                throw new Error(assetErrorMessage);
+            if (assetError) {
+                throw rehydrateError(assetError);
             }
             throw e;
         }
@@ -608,9 +621,9 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                 // even if user didn't provide onProgress
                 const progressCallback = (progress, frameTime) => {
                     // Check for asset-loading errors during render (without throwing)
-                    const errorMessage = window.__polotnoConsumeAssetError(attrs);
-                    if (errorMessage) {
-                        capturedError = errorMessage;
+                    const assetError = window.__polotnoConsumeAssetError(attrs);
+                    if (assetError) {
+                        capturedError = assetError;
                         abortController.abort();
                         return;
                     }
@@ -630,15 +643,19 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                     });
                 }
                 catch (e) {
-                    // If we aborted due to asset error, throw that instead
+                    // If we aborted due to asset error, throw that instead. Re-stash
+                    // it and let the shared helper own the flatten/re-stash protocol
+                    // (capturedError already passed the skip flags in consume).
                     if (capturedError) {
-                        throw new Error(capturedError);
+                        window._polotnoError = capturedError;
+                        window.__polotnoThrowAssetErrorIfAny(attrs);
                     }
                     throw e;
                 }
                 // Final check for any errors that occurred
                 if (capturedError) {
-                    throw new Error(capturedError);
+                    window._polotnoError = capturedError;
+                    window.__polotnoThrowAssetErrorIfAny(attrs);
                 }
                 // Stream blob in chunks via exposed function to avoid large payload issues.
                 // CRITICAL (!!!): Chunk size MUST be a multiple of 3 bytes because base64 encodes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polotno-node",
-  "version": "3.0.2",
+  "version": "3.0.4",
   "description": "Polotno workflow from NodeJS",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
@@ -16,6 +16,11 @@
       "types": "./lib/instance.d.ts",
       "import": "./lib/instance.js",
       "default": "./lib/instance.js"
+    },
+    "./errors": {
+      "types": "./lib/errors.d.ts",
+      "import": "./lib/errors.js",
+      "default": "./lib/errors.js"
     }
   },
   "files": [
@@ -42,8 +47,8 @@
     "vite": "^8.0.16",
     "vitest": "^4.1.9",
     "web-audio-api": "^1.5.1",
-    "polotno": "4.2.1",
-    "@polotno/video-export": "0.1.0"
+    "polotno": "4.3.0",
+    "@polotno/video-export": "0.2.0"
   },
   "overrides": {
     "@polotno/video-export": {
@@ -56,7 +61,7 @@
     "@sparticuz/chromium": "^149.0.0",
     "puppeteer": "25.1.0",
     "puppeteer-core": "25.1.0",
-    "@polotno/schema": "0.1.6"
+    "@polotno/schema": "0.2.0"
   },
   "bugs": {
     "url": "https://github.com/polotno-project/polotno-node/issues"