polotno-node 3.1.2 → 3.2.0

package/lib/instance.js

@@ -1,17 +1,17 @@
-import path from "path";
-import fs from "fs";
-import os from "os";
-import crypto from "crypto";
-import { execSync } from "child_process";
-import { pathToFileURL, fileURLToPath } from "url";
-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";
+import path from 'path';
+import fs from 'fs';
+import os from 'os';
+import crypto from 'crypto';
+import { execSync } from 'child_process';
+import { pathToFileURL, fileURLToPath } from 'url';
+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")}`;
+const DEFAULT_CLIENT = `file:${path.join(__dirname, '..', 'dist', 'index.html')}`;
 // Walk Polotno nodes recursively (depth-first)
 // cb(node) may return true to stop traversing the current branch early
 const forEveryChild = (node, cb) => {
@@ -32,61 +32,61 @@ const collectMediaSourcePointers = (json) => {
     // videos in elements tree
     for (const page of json?.pages || []) {
         for (const el of page?.children || []) {
-            if (el?.type === "video" && typeof el.src === "string") {
-                pointers.push({ kind: "video", target: el, key: "src" });
+            if (el?.type === 'video' && typeof el.src === 'string') {
+                pointers.push({ kind: 'video', target: el, key: 'src' });
             }
             forEveryChild(el, (child) => {
-                if (child?.type === "video" && typeof child.src === "string") {
-                    pointers.push({ kind: "video", target: child, key: "src" });
+                if (child?.type === 'video' && typeof child.src === 'string') {
+                    pointers.push({ kind: 'video', target: child, key: 'src' });
                 }
             });
         }
     }
     // audios array
     for (const audio of json?.audios || []) {
-        if (audio && typeof audio.src === "string") {
-            pointers.push({ kind: "audio", target: audio, key: "src" });
+        if (audio && typeof audio.src === 'string') {
+            pointers.push({ kind: 'audio', target: audio, key: 'src' });
         }
     }
     return pointers;
 };
 const isDataOrFileSrc = (src) => {
-    if (typeof src !== "string")
+    if (typeof src !== 'string')
         return true;
-    return (src.startsWith("data:") ||
-        src.startsWith("file:") ||
-        src.startsWith("blob:"));
+    return (src.startsWith('data:') ||
+        src.startsWith('file:') ||
+        src.startsWith('blob:'));
 };
 const guessExtension = (urlString, contentType) => {
     try {
         const u = new URL(urlString);
-        const ext = path.extname(u.pathname || "");
+        const ext = path.extname(u.pathname || '');
         if (ext)
             return ext;
     }
     catch (e) {
         // ignore; fallback to content-type
     }
-    const ct = String(contentType || "")
-        .split(";")[0]
+    const ct = String(contentType || '')
+        .split(';')[0]
         .trim()
         .toLowerCase();
     const map = {
-        "video/mp4": ".mp4",
-        "video/webm": ".webm",
-        "video/quicktime": ".mov",
-        "audio/mpeg": ".mp3",
-        "audio/mp4": ".m4a",
-        "audio/wav": ".wav",
-        "audio/x-wav": ".wav",
-        "audio/ogg": ".ogg",
-        "audio/webm": ".webm",
+        'video/mp4': '.mp4',
+        'video/webm': '.webm',
+        'video/quicktime': '.mov',
+        'audio/mpeg': '.mp3',
+        'audio/mp4': '.m4a',
+        'audio/wav': '.wav',
+        'audio/x-wav': '.wav',
+        'audio/ogg': '.ogg',
+        'audio/webm': '.webm',
     };
-    return map[ct] || ".bin";
+    return map[ct] || '.bin';
 };
 const downloadUrlToFile = async (urlString, destinationPath) => {
-    if (typeof fetch !== "function") {
-        throw polotnoError("FETCH_FAILED", "Global fetch API is not available in this Node.js runtime. Please use Node 18+.", { url: urlString });
+    if (typeof fetch !== 'function') {
+        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;
@@ -98,11 +98,11 @@ const downloadUrlToFile = async (urlString, destinationPath) => {
             const res = await fetch(urlString);
             if (!res.ok) {
                 // Best-effort read of error body (small) for debugging.
-                let bodyPreview = "";
+                let bodyPreview = '';
                 try {
                     bodyPreview = await res.text();
                     if (bodyPreview.length > 500) {
-                        bodyPreview = bodyPreview.slice(0, 500) + "...";
+                        bodyPreview = bodyPreview.slice(0, 500) + '...';
                     }
                 }
                 catch (e) {
@@ -113,16 +113,16 @@ const downloadUrlToFile = async (urlString, destinationPath) => {
                     bodyPreview ? `body: ${JSON.stringify(bodyPreview)}` : null,
                 ]
                     .filter(Boolean)
-                    .join(", ");
-                throw polotnoError("FETCH_FAILED", `HTTP error while downloading: ${details}`, { url: urlString, status: res.status });
+                    .join(', ');
+                throw polotnoError('FETCH_FAILED', `HTTP error while downloading: ${details}`, { url: urlString, status: res.status });
             }
             if (!res.body) {
-                throw polotnoError("FETCH_FAILED", "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") || "";
+            return res.headers.get('content-type') || '';
         }
         catch (e) {
             lastError = e;
@@ -134,24 +134,24 @@ const downloadUrlToFile = async (urlString, destinationPath) => {
         }
     }
     const message = lastError && lastError.message ? lastError.message : String(lastError);
-    throw polotnoError("FETCH_FAILED", `Failed to download media after ${MAX_ATTEMPTS} attempts: ${urlString}\nLast error: ${message}`, { url: urlString, attempts: MAX_ATTEMPTS }, lastError);
+    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.
 const getVideoNormalizationReason = (filePath) => {
     try {
-        const raw = execSync(`ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,codec_tag_string,pix_fmt -of json "${filePath}"`, { encoding: "utf8" });
+        const raw = execSync(`ffprobe -v error -select_streams v:0 -show_entries stream=codec_name,codec_tag_string,pix_fmt -of json "${filePath}"`, { encoding: 'utf8' });
         const info = JSON.parse(raw);
         const vs = info?.streams?.[0];
         if (!vs)
             return null;
-        const codec = (vs.codec_name || "").toLowerCase();
-        const tag = (vs.codec_tag_string || "").toLowerCase();
-        if (["hevc", "h265"].includes(codec) || ["hvc1", "hev1"].includes(tag)) {
-            return "HEVC/H.265 is not supported by Chromium headless";
+        const codec = (vs.codec_name || '').toLowerCase();
+        const tag = (vs.codec_tag_string || '').toLowerCase();
+        if (['hevc', 'h265'].includes(codec) || ['hvc1', 'hev1'].includes(tag)) {
+            return 'HEVC/H.265 is not supported by Chromium headless';
         }
-        const pix = (vs.pix_fmt || "").toLowerCase();
-        if (pix && pix !== "yuv420p") {
+        const pix = (vs.pix_fmt || '').toLowerCase();
+        if (pix && pix !== 'yuv420p') {
             return `pixel format "${pix}" is not the preferred yuv420p`;
         }
         return null;
@@ -162,7 +162,7 @@ const getVideoNormalizationReason = (filePath) => {
 };
 const isFfmpegAvailable = () => {
     try {
-        execSync("ffmpeg -version", { stdio: "ignore" });
+        execSync('ffmpeg -version', { stdio: 'ignore' });
         return true;
     }
     catch {
@@ -171,7 +171,7 @@ const isFfmpegAvailable = () => {
 };
 const getAudioCodec = (filePath) => {
     try {
-        const result = execSync(`ffprobe -v error -select_streams a:0 -show_entries stream=codec_name -of csv=p=0 "${filePath}"`, { encoding: "utf8" });
+        const result = execSync(`ffprobe -v error -select_streams a:0 -show_entries stream=codec_name -of csv=p=0 "${filePath}"`, { encoding: 'utf8' });
         return result.trim();
     }
     catch {
@@ -180,7 +180,7 @@ const getAudioCodec = (filePath) => {
 };
 const convertAudioToAac = (inputPath, outputPath) => {
     execSync(`ffmpeg -y -i "${inputPath}" -c:v copy -c:a aac "${outputPath}"`, {
-        stdio: "ignore",
+        stdio: 'ignore',
     });
 };
 const prepareLocalMediaForVideoExport = async (json) => {
@@ -195,7 +195,7 @@ const prepareLocalMediaForVideoExport = async (json) => {
             continue;
         try {
             const u = new URL(src);
-            if (u.protocol !== "http:" && u.protocol !== "https:")
+            if (u.protocol !== 'http:' && u.protocol !== 'https:')
                 continue;
         }
         catch (e) {
@@ -205,13 +205,13 @@ const prepareLocalMediaForVideoExport = async (json) => {
             rewriteMap.set(src, null);
             urlsToDownload.push(src);
         }
-        if (p.kind === "video")
+        if (p.kind === 'video')
             videoUrls.add(src);
     }
     if (urlsToDownload.length === 0) {
         return { json: clonedJson, cleanup: async () => { } };
     }
-    const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "polotno-node-assets-"));
+    const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'polotno-node-assets-'));
     let didCleanup = false;
     const cleanup = async () => {
         if (didCleanup)
@@ -223,7 +223,7 @@ const prepareLocalMediaForVideoExport = async (json) => {
         await Promise.all(urlsToDownload.map(async (src) => {
             const tmpBase = crypto.randomUUID
                 ? crypto.randomUUID()
-                : crypto.randomBytes(16).toString("hex");
+                : crypto.randomBytes(16).toString('hex');
             const tmpPath = path.join(tempDir, tmpBase);
             const contentType = await downloadUrlToFile(src, tmpPath);
             const ext = guessExtension(src, contentType);
@@ -232,8 +232,8 @@ const prepareLocalMediaForVideoExport = async (json) => {
             if (videoUrls.has(src)) {
                 const reason = getVideoNormalizationReason(finalPath);
                 if (reason) {
-                    const normalizedPath = finalPath + ".normalized.mp4";
-                    execSync(`ffmpeg -y -i "${finalPath}" -c:v libx264 -pix_fmt yuv420p -c:a aac -movflags +faststart "${normalizedPath}"`, { stdio: "ignore" });
+                    const normalizedPath = finalPath + '.normalized.mp4';
+                    execSync(`ffmpeg -y -i "${finalPath}" -c:v libx264 -pix_fmt yuv420p -c:a aac -movflags +faststart "${normalizedPath}"`, { stdio: 'ignore' });
                     finalPath = normalizedPath;
                 }
             }
@@ -253,16 +253,23 @@ const prepareLocalMediaForVideoExport = async (json) => {
         throw e;
     }
 };
-export const createPage = async (browser, url, requestInterceptor, useFontCache = true) => {
+// `page.goto` below used to inherit the browser driver's 30s default. That is
+// too tight for this navigation — it loads the whole polotno client bundle, and
+// on a slow or loaded machine createInstance would throw `Navigation timeout of
+// 30000 ms exceeded` with no option to tune: `protocolTimeout` governs CDP
+// calls, not the navigation lifecycle. 2 minutes is generous but still bounded,
+// unlike `timeout: 0` ("disabled"), which turns a wedged load into a hang.
+const DEFAULT_NAVIGATION_TIMEOUT = 120 * 1000;
+export const createPage = async (browser, url, requestInterceptor, useFontCache = true, navigationTimeout = DEFAULT_NAVIGATION_TIMEOUT) => {
     const page = await browser.newPage();
     // Attach request interceptor if provided
-    if (useFontCache || typeof requestInterceptor === "function") {
+    if (useFontCache || typeof requestInterceptor === 'function') {
         await page.setRequestInterception(true);
-        page.on("request", (request) => {
+        page.on('request', (request) => {
             if (useFontCache && fontCache.tryRespond(request)) {
                 return;
             }
-            if (typeof requestInterceptor === "function") {
+            if (typeof requestInterceptor === 'function') {
                 requestInterceptor(request);
             }
             else {
@@ -270,7 +277,7 @@ export const createPage = async (browser, url, requestInterceptor, useFontCache
             }
         });
         if (useFontCache) {
-            page.on("response", (response) => fontCache.capture(response));
+            page.on('response', (response) => fontCache.capture(response));
         }
     }
     // we need to make sure that headless is inside user agent
@@ -278,31 +285,31 @@ export const createPage = async (browser, url, requestInterceptor, useFontCache
     // but also lets NOT just overwrite default one, because Google Fonts may send "reduced" version of font
     // so some languages may not work
     const userAgent = await page.evaluate(() => navigator.userAgent);
-    if (userAgent.indexOf("Headless") === -1) {
-        await page.setUserAgent(userAgent + " Chrome Headless");
+    if (userAgent.indexOf('Headless') === -1) {
+        await page.setUserAgent(userAgent + ' Chrome Headless');
     }
-    page.on("console", (msg) => {
+    page.on('console', (msg) => {
         msg.args().forEach(async (message) => {
             // skip style information
-            if (message.toString().indexOf("margin") >= 0) {
+            if (message.toString().indexOf('margin') >= 0) {
                 return;
             }
             const { subtype, description } = message.remoteObject();
-            if (subtype === "error") {
+            if (subtype === 'error') {
                 console.error(description);
                 return;
             }
             const text = message
                 .toString()
-                .replace("JSHandle:", "")
-                .replace("%c", "");
+                .replace('JSHandle:', '')
+                .replace('%c', '');
             console.log(text);
         });
     });
-    page.on("pageerror", (msg) => {
+    page.on('pageerror', (msg) => {
         console.error(msg);
     });
-    await page.goto(url);
+    await page.goto(url, { timeout: navigationTimeout });
     return page;
 };
 export const run = async (page, func, args) => {
@@ -355,18 +362,30 @@ export const jsonToBlob = async (page, json, attrs) => {
 // is an enable-only flag: the setter is called with `true` only when the option
 // is truthy (passing `false` is a no-op, leaving the client default in place).
 const CONFIG_OPTION_SETTERS = [
-    { option: "assetLoadTimeout", method: "setAssetLoadTimeout", arg: "value" },
-    { option: "fontLoadTimeout", method: "setFontLoadTimeout", arg: "value" },
-    { option: "legacyRichTextEnabled", method: "setLegacyRichTextEnabled", arg: true },
-    { option: "textVerticalResizeEnabled", method: "setTextVerticalResizeEnabled", arg: "value" },
-    { option: "textSplitAllowed", method: "unstable_setTextSplitAllowed", arg: true },
-    { option: "textOverflow", method: "setTextOverflow", arg: "value" },
+    { option: 'assetLoadTimeout', method: 'setAssetLoadTimeout', arg: 'value' },
+    { option: 'fontLoadTimeout', method: 'setFontLoadTimeout', arg: 'value' },
+    {
+        option: 'legacyRichTextEnabled',
+        method: 'setLegacyRichTextEnabled',
+        arg: true,
+    },
+    {
+        option: 'textVerticalResizeEnabled',
+        method: 'setTextVerticalResizeEnabled',
+        arg: 'value',
+    },
+    {
+        option: 'textSplitAllowed',
+        method: 'unstable_setTextSplitAllowed',
+        arg: true,
+    },
+    { option: 'textOverflow', method: 'setTextOverflow', arg: 'value' },
 ];
 // Apply the option→config setters above to a page in a single round-trip.
 const applyConfigOptions = async (page, attrs = {}) => {
     const calls = [];
     for (const { option, method, arg } of CONFIG_OPTION_SETTERS) {
-        if (arg === "value") {
+        if (arg === 'value') {
             // value passthrough — apply on any explicit value, including `false`
             if (attrs[option] !== undefined)
                 calls.push({ method, value: attrs[option] });
@@ -391,12 +410,13 @@ const applyConfigOptions = async (page, attrs = {}) => {
 };
 const busyPages = [];
 const createdInstances = [];
-export const createInstance = async ({ key, url, useParallelPages = true, browser, requestInterceptor, useFontCache = true, } = {}) => {
+export const createInstance = async ({ key, url, useParallelPages = true, browser, requestInterceptor, useFontCache = true, navigationTimeout, } = {}) => {
     const visitPage = url || `${DEFAULT_CLIENT}?key=${key}`;
     const hasCustomClientUrl = Boolean(url);
-    const firstPage = useParallelPages
-        ? null
-        : await createPage(browser, visitPage, requestInterceptor, useFontCache);
+    // Every page this instance opens is configured identically; bind it once so
+    // the three call sites below cannot drift apart.
+    const openClientPage = () => createPage(browser, visitPage, requestInterceptor, useFontCache, navigationTimeout);
+    const firstPage = useParallelPages ? null : await openClientPage();
     async function ensureAssetErrorHelpers(page) {
         await page.evaluate(() => {
             // Define helpers once per page. They unify asset-loading error handling
@@ -411,11 +431,11 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                     // 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) {
+                    const code = typeof payload === 'object' ? payload.code : null;
+                    if (code === 'FONT_FAILED' && attrs && attrs.skipFontError) {
                         return null;
                     }
-                    if (code === "IMAGE_FAILED" && attrs && attrs.skipImageError) {
+                    if (code === 'IMAGE_FAILED' && attrs && attrs.skipImageError) {
                         return null;
                     }
                     // Return the payload as-is (object, or string from a legacy client);
@@ -431,7 +451,7 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                         // 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));
+                        throw new Error(typeof payload === 'string' ? payload : String(payload.message));
                     }
                 };
             }
@@ -452,11 +472,9 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
         }
     }
     const run = async (func, ...args) => {
-        const page = useParallelPages
-            ? await createPage(browser, visitPage, requestInterceptor, useFontCache)
-            : firstPage;
+        const page = useParallelPages ? await openClientPage() : firstPage;
         if (busyPages.indexOf(page) >= 0) {
-            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" });
+            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
@@ -464,15 +482,15 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
         const profilePath = args[1]?.profilePath;
         if (profilePath) {
             cdpSession = await page.target().createCDPSession();
-            await cdpSession.send("Profiler.enable");
-            await cdpSession.send("Profiler.start");
+            await cdpSession.send('Profiler.enable');
+            await cdpSession.send('Profiler.start');
         }
         try {
             // All direct `window.config.*` setters are applied from one table.
             await applyConfigOptions(page, args[1]);
             if (args[1]?.onProgress) {
                 const originalProgress = args[1].onProgress;
-                await page.exposeFunction("onProgress", async (progress, frameTime) => {
+                await page.exposeFunction('onProgress', async (progress, frameTime) => {
                     originalProgress(progress, frameTime);
                 });
             }
@@ -490,19 +508,23 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                         const e = error;
                         window._polotnoError =
                             e && e.code
-                                ? { code: e.code, message: String(e.message), details: e.details }
+                                ? {
+                                    code: e.code,
+                                    message: String(e.message),
+                                    details: e.details,
+                                }
                                 : String(error);
                     });
                 }
                 else {
-                    console.error("onLoadError function is not defined in the client. Error handling will not work.");
+                    console.error('onLoadError function is not defined in the client. Error handling will not work.');
                 }
             });
             await ensureAssetErrorHelpers(page);
             const result = await page.evaluate(func, ...args);
             // Stop profiler and save profile if enabled
             if (cdpSession && profilePath) {
-                const { profile } = await cdpSession.send("Profiler.stop");
+                const { profile } = await cdpSession.send('Profiler.stop');
                 fs.writeFileSync(profilePath, JSON.stringify(profile));
                 console.log(`CPU profile saved to: ${profilePath}`);
             }
@@ -520,14 +542,14 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
         catch (e) {
             // Stop profiler and save profile even on error
             if (cdpSession && profilePath) {
-                console.log("saving profile");
+                console.log('saving profile');
                 try {
-                    const { profile } = await cdpSession.send("Profiler.stop");
+                    const { profile } = await cdpSession.send('Profiler.stop');
                     fs.writeFileSync(profilePath, JSON.stringify(profile));
                     console.log(`CPU profile saved to: ${profilePath}`);
                 }
                 catch (profileError) {
-                    console.error("Failed to save profile:", profileError.message);
+                    console.error('Failed to save profile:', profileError.message);
                 }
             }
             // If `page.evaluate()` failed (e.g. thrown during onProgress), still prefer
@@ -550,7 +572,7 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
     // than rejecting input the store would happily render), so this only throws on
     // genuinely malformed JSON.
     const assertValidJson = (json) => {
-        assertValidDesign(json, { mode: "partial" });
+        assertValidDesign(json, { mode: 'partial' });
     };
     const jsonToDataURL = async (json, attrs) => {
         await assertValidJson(json);
@@ -562,11 +584,11 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
     };
     const jsonToGIFBase64 = async (json, attrs) => {
         const url = await jsonToGIFDataURL(json, attrs);
-        return url.split("base64,")[1];
+        return url.split('base64,')[1];
     };
     const jsonToImageBase64 = async (json, attrs) => {
         const url = await jsonToDataURL(json, attrs);
-        return url.split("base64,")[1];
+        return url.split('base64,')[1];
     };
     const jsonToPDFDataURL = async (json, attrs) => {
         await assertValidJson(json);
@@ -574,11 +596,11 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
     };
     const jsonToPDFBase64 = async (json, attrs) => {
         const url = await jsonToPDFDataURL(json, attrs);
-        return url.split("base64,")[1];
+        return url.split('base64,')[1];
     };
     const jsonToBlob = async (json, attrs) => {
         const base64 = await jsonToImageBase64(json, attrs);
-        const blob = Buffer.from(base64, "base64");
+        const blob = Buffer.from(base64, 'base64');
         return blob;
     };
     const jsonToVideoFile = async (json, outputPath, attrs = {}) => {
@@ -609,9 +631,9 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                 }
                 // For video export, we always use 'resize' text overflow mode
                 // to ensure text fits properly in animations. User preferences are ignored for now.
-                window.config.setTextOverflow("resize");
+                window.config.setTextOverflow('resize');
                 if (!window.__polotnoLoadVideoExport) {
-                    throw new Error("Video export module loader is not defined in the client. Expected window.__polotnoLoadVideoExport().");
+                    throw new Error('Video export module loader is not defined in the client. Expected window.__polotnoLoadVideoExport().');
                 }
                 const { storeToVideo } = await window.__polotnoLoadVideoExport();
                 // Create abort controller to cancel video render on error
@@ -667,7 +689,7 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                 for (let offset = 0; offset < uint8Array.length; offset += CHUNK_SIZE) {
                     const end = Math.min(offset + CHUNK_SIZE, uint8Array.length);
                     const chunk = uint8Array.slice(offset, end);
-                    let binary = "";
+                    let binary = '';
                     for (let i = 0; i < chunk.length; i++) {
                         binary += String.fromCharCode(chunk[i]);
                     }
@@ -678,18 +700,18 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                 ...attrs,
                 exposeFunctions: {
                     __polotnoWriteChunk: (base64Chunk) => {
-                        const buffer = Buffer.from(base64Chunk, "base64");
+                        const buffer = Buffer.from(base64Chunk, 'base64');
                         writeStream.write(buffer);
                     },
                 },
             });
             writeStream.end();
-            await new Promise((resolve) => writeStream.on("finish", resolve));
+            await new Promise((resolve) => writeStream.on('finish', resolve));
             // Convert audio to AAC if needed
             if (isFfmpegAvailable()) {
                 const codec = getAudioCodec(outputPath);
-                if (codec && codec !== "aac") {
-                    const tempPath = outputPath + ".tmp.mp4";
+                if (codec && codec !== 'aac') {
+                    const tempPath = outputPath + '.tmp.mp4';
                     convertAudioToAac(outputPath, tempPath);
                     await fs.promises.rename(tempPath, outputPath);
                 }
@@ -705,7 +727,7 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
         try {
             const mimeType = await jsonToVideoFile(json, tempPath, attrs);
             const buffer = await fs.promises.readFile(tempPath);
-            return `data:${mimeType || "video/mp4"};base64,${buffer.toString("base64")}`;
+            return `data:${mimeType || 'video/mp4'};base64,${buffer.toString('base64')}`;
         }
         finally {
             await fs.promises.rm(tempPath, { force: true });
@@ -716,7 +738,7 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
         try {
             await jsonToVideoFile(json, tempPath, attrs);
             const buffer = await fs.promises.readFile(tempPath);
-            return buffer.toString("base64");
+            return buffer.toString('base64');
         }
         finally {
             await fs.promises.rm(tempPath, { force: true });
@@ -740,7 +762,7 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
         jsonToVideoDataURL,
         jsonToVideoBase64,
         jsonToVideoFile,
-        createPage: async () => await createPage(browser, visitPage, requestInterceptor, useFontCache),
+        createPage: openClientPage,
     };
     createdInstances.push(instance);
     return instance;
@@ -750,7 +772,7 @@ const closeAllInstances = async () => {
     await Promise.all(createdInstances.map((instance) => instance.close()));
 };
 // Also handle other termination signals
-["SIGINT", "SIGTERM", "SIGQUIT", "exit"].forEach((signal) => {
+['SIGINT', 'SIGTERM', 'SIGQUIT', 'exit'].forEach((signal) => {
     process.on(signal, () => {
         closeAllInstances();
     });

package/lib/types.d.ts

@@ -56,6 +56,13 @@ export interface InstanceOptions {
     requestInterceptor?: (request: any) => void;
     /** Cache Google Fonts responses for the process lifetime and serve them to every page (default: true) */
     useFontCache?: boolean;
+    /**
+     * Budget for the initial navigation to the client page, in ms (default:
+     * 120000). Distinct from `protocolTimeout`, which governs CDP calls and not
+     * the navigation lifecycle. Raise it on slow machines; `0` disables it, at
+     * the cost of turning a wedged load into a permanent hang.
+     */
+    navigationTimeout?: number;
 }
 export interface PolotnoInstance {
     close: () => Promise<void>;