polotno-node 3.4.0 → 3.6.0

package/lib/index.js

@@ -1,7 +1,7 @@
 import puppeteerCore from 'puppeteer-core';
 import os from 'os';
 import { createInstance as createInstanceImpl } from './instance.js';
-import { BUNDLED_CHROMIUM_PLATFORM, resolveBrowserArgs, resolveExecutablePath, } from './launch-options.js';
+import { BUNDLED_CHROMIUM_PLATFORM, resolveBrowserArgs, resolveExecutablePath, resolveHeadless, } from './launch-options.js';
 export { args } from './launch-options.js';
 // Off the bundled chromium's platform, use full puppeteer — it brings its own
 // Chromium. ESM imports are immutable, so resolve the variant via a dynamic
@@ -12,32 +12,84 @@ if (os.platform() !== BUNDLED_CHROMIUM_PLATFORM) {
     puppeteer = (await import('puppeteer')).default;
 }
 const browserProps = {
-    headless: true,
     // make large timeout, because some renders may take a lot of time
     // like large PDF or video render
     protocolTimeout: 60 * 60 * 1000,
     ignoreHTTPSErrors: true,
 };
+let warnedAboutShellFallback = false;
+/**
+ * The browser puppeteer itself is configured to launch, from
+ * `PUPPETEER_EXECUTABLE_PATH` or a `.puppeteerrc`. It wins over every binary we
+ * would resolve — including the headless shell — so it has to count as a
+ * browser we did not pick, exactly like an `executablePath` argument. Asking
+ * this instance is what makes that true on both entry points: only full
+ * `puppeteer` reads that configuration, and the Linux path runs
+ * `puppeteer-core`, which does not.
+ */
+async function configuredExecutablePath() {
+    try {
+        return (await puppeteer.configuration())?.executablePath;
+    }
+    catch (e) {
+        return undefined;
+    }
+}
 export async function createBrowser(options = {}) {
-    // Both are resolved below, so neither may also reach the spread — a caller
+    // All three are resolved below, so none may also reach the spread — a caller
     // forwarding an unset env var (`executablePath:
     // process.env.PUPPETEER_EXECUTABLE_PATH`) would overwrite the resolved path
     // with `undefined` and leave puppeteer-core with no browser at all.
-    const { browserArgs, executablePath, ...rest } = options;
-    return puppeteer.launch({
-        args: resolveBrowserArgs(options),
-        executablePath: await resolveExecutablePath(options),
+    const { browserArgs, executablePath, headless, ...rest } = options;
+    const resolved = {
+        ...options,
+        executablePath: executablePath || (await configuredExecutablePath()),
+    };
+    const launchOptions = {
+        args: resolveBrowserArgs(resolved),
+        executablePath: await resolveExecutablePath(resolved),
+        headless: resolveHeadless(resolved),
         ...browserProps,
         ...rest,
-    });
+    };
+    try {
+        return await puppeteer.launch(launchOptions);
+    }
+    catch (e) {
+        // The headless shell is ours to pick, so its absence is ours to survive:
+        // puppeteer installs it next to `chrome` by default, but a caller can skip
+        // it (`PUPPETEER_SKIP_CHROME_HEADLESS_SHELL_DOWNLOAD`, or an image that
+        // copies only the `chrome` folder out of the cache). Try the other binary
+        // before giving up — but only when WE chose the shell, never when the
+        // caller asked for it by name, and never at the cost of the real error.
+        if (launchOptions.headless !== 'shell' || headless !== undefined)
+            throw e;
+        let browser;
+        try {
+            browser = await puppeteer.launch({ ...launchOptions, headless: true });
+        }
+        catch {
+            // Full Chrome is no better off, so the shell was never the problem: the
+            // first error is the one worth reading.
+            throw e;
+        }
+        if (!warnedAboutShellFallback) {
+            warnedAboutShellFallback = true;
+            console.warn('polotno-node: could not launch chrome-headless-shell, falling back to full Chrome. ' +
+                'Install it with `npx puppeteer browsers install chrome-headless-shell`; on macOS it ' +
+                'also avoids a crash dialog when rendering without a desktop session.');
+        }
+        return browser;
+    }
 }
 export const createInstance = async (options = {}) => {
     // Named here only because they shape the browser; everything else is passed
     // straight through. Relisting each option by name is how `navigationTimeout`
     // came to be declared, honoured downstream, and silently dropped in between.
-    const { browser, executablePath, browserArgs, ...rest } = options;
+    const { browser, executablePath, browserArgs, headless, ...rest } = options;
     return await createInstanceImpl({
         ...rest,
-        browser: browser || (await createBrowser({ browserArgs, executablePath })),
+        browser: browser ||
+            (await createBrowser({ browserArgs, executablePath, headless })),
     });
 };

package/lib/instance.d.ts

@@ -10,6 +10,27 @@ declare global {
         __polotnoWriteChunk?: (chunk: string) => void;
     }
 }
+export declare const URL_FIELDS: string[];
+/**
+ * Visit every URL-holding field in a design: `visit(node, key, value)` for each
+ * string under one of `URL_FIELDS`, `custom` skipped whole.
+ *
+ * Exported because `@polotno/fidelity` inlines a fixture's local assets over
+ * the same fields — which subtrees a rewrite may enter is one rule, and two
+ * copies of it drift. Changing either one needs that package's `test:unit`.
+ */
+export declare const forEveryUrlField: (node: any, visit: any) => void;
+/**
+ * Rewrite every `file:` source in a design to a URL the client can load with
+ * any API. Designs without one — the common case — come back untouched, so this
+ * costs a walk and nothing else. `release()` drops the registrations; hold them
+ * until the render is finished.
+ */
+export declare const serveLocalFiles: (json: any) => {
+    json: any;
+    serving: boolean;
+    release: () => void;
+};
 export declare const guessExtension: (contentType: any, kind: any) => any;
 export declare const prepareLocalMediaForVideoExport: (json: any, policy?: FetchPolicy) => Promise<{
     json: any;

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 * as localMedia from './local-media.js';
 import { polotnoError, rehydrateError } from './errors.js';
 import { assertUrlAllowed } from './ssrf-guard.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -51,6 +52,97 @@ const collectMediaSourcePointers = (json) => {
     }
     return pointers;
 };
+// Design fields that carry a URL the renderer loads. A `file:` value in any of
+// them is served over the local-media channel instead — see `local-media.ts`
+// for why the browser must never see that scheme. Every other value is passed
+// through exactly as the caller wrote it.
+//
+// A list, rather than "rewrite every `file:` string anywhere", because a design
+// carries text: a text element whose content reads `file:///notes.txt` is
+// content, and rewriting it corrupts the render. `custom` is arbitrary caller
+// data with the same problem, so the walk does not enter it at all. And
+// `test/unit/local-media.test.mjs` fails when the schema grows a field named
+// like one that is missing here.
+export const URL_FIELDS = ['src', 'clipSrc', 'maskSrc', 'background', 'url'];
+const URL_FIELD_SET = new Set(URL_FIELDS);
+/**
+ * Visit every URL-holding field in a design: `visit(node, key, value)` for each
+ * string under one of `URL_FIELDS`, `custom` skipped whole.
+ *
+ * Exported because `@polotno/fidelity` inlines a fixture's local assets over
+ * the same fields — which subtrees a rewrite may enter is one rule, and two
+ * copies of it drift. Changing either one needs that package's `test:unit`.
+ */
+export const forEveryUrlField = (node, visit) => {
+    if (!node || typeof node !== 'object')
+        return;
+    if (Array.isArray(node)) {
+        for (const item of node)
+            forEveryUrlField(item, visit);
+        return;
+    }
+    for (const key of Object.keys(node)) {
+        if (key === 'custom')
+            continue;
+        const value = node[key];
+        if (typeof value === 'string') {
+            if (URL_FIELD_SET.has(key))
+                visit(node, key, value);
+        }
+        else if (value && typeof value === 'object') {
+            forEveryUrlField(value, visit);
+        }
+    }
+};
+// Not `toLowerCase().startsWith`: a `src` is routinely a data URL of several
+// MB, and that would copy every one of them on every render.
+const isFileUrl = (value) => /^file:/i.test(value);
+// The design goes to the browser as the caller wrote it, and there is nothing
+// to release or to switch on.
+const nothingToServe = (json) => ({ json, serving: false, release: () => { } });
+/**
+ * Rewrite every `file:` source in a design to a URL the client can load with
+ * any API. Designs without one — the common case — come back untouched, so this
+ * costs a walk and nothing else. `release()` drops the registrations; hold them
+ * until the render is finished.
+ */
+export const serveLocalFiles = (json) => {
+    let found = false;
+    forEveryUrlField(json, (_node, _key, value) => {
+        found || (found = isFileUrl(value));
+    });
+    if (!found)
+        return nothingToServe(json);
+    const cloned = JSON.parse(JSON.stringify(json));
+    // One URL per file, however many elements name it — the same URL twice is a
+    // request the browser answers from its own cache.
+    const byPath = new Map();
+    forEveryUrlField(cloned, (target, key, value) => {
+        if (!isFileUrl(value))
+            return;
+        let filePath;
+        try {
+            filePath = fileURLToPath(value);
+        }
+        catch (e) {
+            // Not a file URL we can resolve to a path. Leave it alone: the client
+            // reports it as a failed asset, exactly as it does today.
+            return;
+        }
+        if (!byPath.has(filePath))
+            byPath.set(filePath, localMedia.register(filePath));
+        target[key] = byPath.get(filePath);
+    });
+    const urls = [...byPath.values()];
+    // `serving` is per render, and the page-level switch is gated on it: a
+    // process-wide "is anything registered" would let one render turn
+    // interception on for another's page.
+    return {
+        json: cloned,
+        serving: urls.length > 0,
+        release: () => localMedia.release(urls),
+    };
+};
 const isDataOrFileSrc = (src) => {
     if (typeof src !== 'string')
         return true;
@@ -69,8 +161,8 @@ const CONTENT_TYPE_EXTENSION = {
     'audio/ogg': '.ogg',
     'audio/webm': '.webm',
 };
-// The temp file's extension is later passed to ffmpeg/ffprobe and used by
-// Chromium for the `file://` MIME. Take it ONLY from the response content-type,
+// The temp file's extension is later passed to ffmpeg/ffprobe, and backs the
+// content type we serve it with. Take it ONLY from the response content-type,
 // never the URL — a URL-derived extension like `x.$(touch pwned)` is how the
 // original RCE injected a shell command (CWE-78). The name is otherwise a UUID.
 export const guessExtension = (contentType, kind) => {
@@ -265,10 +357,7 @@ export const prepareLocalMediaForVideoExport = async (json, policy = {}) => {
     };
     try {
         await Promise.all(urlsToDownload.map(async (src) => {
-            const tmpBase = crypto.randomUUID
-                ? crypto.randomUUID()
-                : crypto.randomBytes(16).toString('hex');
-            const tmpPath = path.join(tempDir, tmpBase);
+            const tmpPath = path.join(tempDir, crypto.randomUUID());
             const contentType = await downloadUrlToFile(src, tmpPath, policy);
             const kind = videoUrls.has(src) ? 'video' : 'audio';
             const ext = guessExtension(contentType, kind);
@@ -295,6 +384,9 @@ export const prepareLocalMediaForVideoExport = async (json, policy = {}) => {
                     finalPath = normalizedPath;
                 }
             }
+            // A `file:` URL, which `serveLocalFiles` turns into one the browser can
+            // read — the same path a caller's own local file takes. One place makes
+            // that decision, and the extension we just derived carries the type.
             rewriteMap.set(src, pathToFileURL(finalPath).toString());
         }));
         for (const p of pointers) {
@@ -318,25 +410,68 @@ export const prepareLocalMediaForVideoExport = async (json, policy = {}) => {
 // 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;
+// Pages that have request interception on. It is a page-level switch, and the
+// one handler each page carries must stay out of the way while it is off.
+const intercepting = new WeakSet();
+// Pages `createPage` opened, and so the only ones carrying the handler that
+// answers a local-media URL. A caller who brings their own page keeps their own
+// request handling, and their design keeps the URLs they wrote.
+const ourPages = new WeakSet();
+/**
+ * Turn request interception on for a page, once. Interception is on already for
+ * everyone who keeps the font cache; this covers the caller who turned it off
+ * and then renders a design that carries local files.
+ */
+const ensureServing = async (page) => {
+    if (intercepting.has(page))
+        return;
+    await page.setRequestInterception(true);
+    // After the await, never before: a page marked while the switch failed to
+    // flip would let the handler respond on a page that is not intercepting, and
+    // the asset would fail silently. Nothing can slip in between — the statement
+    // runs in the same microtask the await resolves on.
+    intercepting.add(page);
+};
 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') {
-        await page.setRequestInterception(true);
-        page.on('request', (request) => {
-            if (useFontCache && fontCache.tryRespond(request)) {
-                return;
-            }
-            if (typeof requestInterceptor === 'function') {
-                requestInterceptor(request);
-            }
-            else {
-                request.continue().catch(() => { });
-            }
-        });
-        if (useFontCache) {
-            page.on('response', (response) => fontCache.capture(response));
+    ourPages.add(page);
+    // `goto` was raised to 120s because 30s could not load this client bundle on
+    // a loaded box. Every OTHER wait on the page was left at puppeteer's same 30s
+    // default — acquiring an execution context for `evaluate`, waiting for a
+    // target — and those wait on that same bundle, in the same conditions. One
+    // budget raised and its siblings left behind is the same defect in a
+    // different place, so give them the one budget.
+    //
+    // Not observed failing: three forced whole-repo runs and six at 74 concurrent
+    // instances (load 25 on 16 cores) stayed green. This closes the gap the
+    // reasoning above implies, rather than a failure anyone has seen.
+    //
+    // 0 passes through as puppeteer's "no timeout", exactly as it does for
+    // `goto`: a caller who disabled the budget meant it.
+    page.setDefaultTimeout(navigationTimeout);
+    // One handler per page, always attached, because `ensureServing` may turn
+    // interception on later. It stays inert until then.
+    page.on('request', (request) => {
+        if (!intercepting.has(page))
+            return;
+        if (localMedia.tryRespond(request)) {
+            return;
+        }
+        if (useFontCache && fontCache.tryRespond(request)) {
+            return;
+        }
+        if (typeof requestInterceptor === 'function') {
+            requestInterceptor(request);
+        }
+        else {
+            request.continue().catch(() => { });
         }
+    });
+    if (useFontCache) {
+        page.on('response', (response) => fontCache.capture(response));
+    }
+    if (useFontCache || typeof requestInterceptor === 'function') {
+        await ensureServing(page);
     }
     // we need to make sure that headless is inside user agent
     // because we use it for key validation check
@@ -370,9 +505,26 @@ export const createPage = async (browser, url, requestInterceptor, useFontCache
     await page.goto(url, { timeout: navigationTimeout });
     return page;
 };
-export const run = async (page, func, args) => {
-    return await page.evaluate(func, ...args);
+/**
+ * Evaluate on a page the caller owns, with the design's local files served
+ * first — and only when the page came from `createPage`, the one that carries
+ * the handler answering a local-media URL. Rewriting for any other page would
+ * trade a URL the browser might load for one nothing answers.
+ */
+const evaluateServed = async (page, func, json, ...rest) => {
+    const served = ourPages.has(page)
+        ? serveLocalFiles(json)
+        : nothingToServe(json);
+    try {
+        if (served.serving)
+            await ensureServing(page);
+        return await page.evaluate(func, served.json, ...rest);
+    }
+    finally {
+        served.release();
+    }
 };
+export const run = async (page, func, args) => evaluateServed(page, func, args[0], ...args.slice(1));
 // In-page export recipes. These run inside the browser (via page.evaluate / run),
 // so they may only reference page globals (`store`, `window`) — not module scope.
 // Defining them once lets the instance methods and the module-level page-taking
@@ -405,15 +557,9 @@ const recipeToGIFDataURL = async (json, attrs) => {
     store.loadJSON(json);
     return await store.toGIFDataURL(attrs);
 };
-export const jsonToDataURL = async (page, json, attrs) => {
-    return await page.evaluate(recipeToDataURL, json, attrs || {});
-};
-export const jsonToPDFDataURL = async (page, json, attrs) => {
-    return page.evaluate(recipeToPDFDataURL, json, attrs || {});
-};
-export const jsonToBlob = async (page, json, attrs) => {
-    return page.evaluate(recipeToBlob, json, attrs || {});
-};
+export const jsonToDataURL = async (page, json, attrs) => evaluateServed(page, recipeToDataURL, json, attrs || {});
+export const jsonToPDFDataURL = async (page, json, attrs) => evaluateServed(page, recipeToPDFDataURL, json, attrs || {});
+export const jsonToBlob = async (page, json, attrs) => evaluateServed(page, recipeToBlob, json, attrs || {});
 // Render options that map directly to a `window.config.*` setter on the client.
 // `arg: "value"` passes the option value through whenever it is explicitly set
 // (including `false`, so a client-side default can be turned off). `arg: true`
@@ -534,16 +680,26 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
         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' });
         }
+        // Every export and every caller recipe passes the design here, so this is
+        // the one place that serves its local files. Before the page is marked
+        // busy, because a design this cannot walk — a cyclic object reaches `run`
+        // unvalidated — would throw and leave the page busy for the rest of the
+        // instance's life.
+        const served = serveLocalFiles(args[0]);
+        const runArgs = [served.json, ...args.slice(1)];
         busyPages.push(page);
         // Setup profiling if profilePath is provided
         let cdpSession = null;
         const profilePath = args[1]?.profilePath;
-        if (profilePath) {
-            cdpSession = await page.target().createCDPSession();
-            await cdpSession.send('Profiler.enable');
-            await cdpSession.send('Profiler.start');
-        }
         try {
+            if (served.serving) {
+                await ensureServing(page);
+            }
+            if (profilePath) {
+                cdpSession = await page.target().createCDPSession();
+                await cdpSession.send('Profiler.enable');
+                await cdpSession.send('Profiler.start');
+            }
             // All direct `window.config.*` setters are applied from one table.
             await applyConfigOptions(page, args[1]);
             if (args[1]?.onProgress) {
@@ -579,7 +735,7 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                 }
             });
             await ensureAssetErrorHelpers(page);
-            const result = await page.evaluate(func, ...args);
+            const result = await page.evaluate(func, ...runArgs);
             // Stop profiler and save profile if enabled
             if (cdpSession && profilePath) {
                 const { profile } = await cdpSession.send('Profiler.stop');
@@ -623,6 +779,9 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
             }
             throw e;
         }
+        finally {
+            served.release();
+        }
     };
     // Pre-flight schema check: catch malformed JSON before launching the browser
     // and throw `Invalid Polotno design: …`. `assertValidDesign` mirrors the core

package/lib/launch-options.d.ts

@@ -22,6 +22,27 @@ export declare function usesBundledChromium(options?: BrowserOptions, platform?:
  * `browserArgs` win over both.
  */
 export declare function resolveBrowserArgs(options?: BrowserOptions, platform?: string): string[];
+/**
+ * The headless mode to launch with.
+ *
+ * `'shell'` is puppeteer's separate `chrome-headless-shell` binary, and we
+ * prefer it wherever puppeteer resolves the browser for us. Full Chrome in
+ * headless mode calls `TransformProcessType` on macOS, only to hide a Dock icon
+ * it does not have. That call needs the window server, so in a sandbox without
+ * a GUI session — an agent's shell, ssh, a launchd daemon — the browser aborts
+ * at launch and macOS shows a crash dialog. The shell binary never makes the
+ * call. It is also about 3x faster to open a page and renders identically; the
+ * only measured difference is the antialiasing of a fallback font.
+ *
+ * Two cases keep full Chrome:
+ *   - an `executablePath`: `'shell'` does not switch binaries then, it only
+ *     passes `--headless` to the one named, which Chrome 132+ reads as new
+ *     headless anyway. A silent no-op is worse than saying `true`.
+ *   - `@sparticuz/chromium`: it ships one binary and no shell build.
+ *
+ * A caller's own `headless` always wins.
+ */
+export declare function resolveHeadless(options?: BrowserOptions, platform?: string): boolean | 'shell';
 /**
  * The browser to launch: the caller's, else the bundled chromium where we use
  * it, else puppeteer's own. Resolving the bundled one is not free — it inflates

package/lib/launch-options.js

@@ -109,6 +109,33 @@ export function resolveBrowserArgs(options = {}, platform = os.platform()) {
         ? mergeArgs(chrome.args, args, browserArgs)
         : mergeArgs(args, browserArgs);
 }
+/**
+ * The headless mode to launch with.
+ *
+ * `'shell'` is puppeteer's separate `chrome-headless-shell` binary, and we
+ * prefer it wherever puppeteer resolves the browser for us. Full Chrome in
+ * headless mode calls `TransformProcessType` on macOS, only to hide a Dock icon
+ * it does not have. That call needs the window server, so in a sandbox without
+ * a GUI session — an agent's shell, ssh, a launchd daemon — the browser aborts
+ * at launch and macOS shows a crash dialog. The shell binary never makes the
+ * call. It is also about 3x faster to open a page and renders identically; the
+ * only measured difference is the antialiasing of a fallback font.
+ *
+ * Two cases keep full Chrome:
+ *   - an `executablePath`: `'shell'` does not switch binaries then, it only
+ *     passes `--headless` to the one named, which Chrome 132+ reads as new
+ *     headless anyway. A silent no-op is worse than saying `true`.
+ *   - `@sparticuz/chromium`: it ships one binary and no shell build.
+ *
+ * A caller's own `headless` always wins.
+ */
+export function resolveHeadless(options = {}, platform = os.platform()) {
+    if (options.headless !== undefined)
+        return options.headless;
+    if (options.executablePath)
+        return true;
+    return usesBundledChromium(options, platform) ? true : 'shell';
+}
 /**
  * The browser to launch: the caller's, else the bundled chromium where we use
  * it, else puppeteer's own. Resolving the bundled one is not free — it inflates

package/lib/local-media.d.ts

@@ -0,0 +1,18 @@
+export declare const ORIGIN = "https://polotno-local-media.invalid/";
+/**
+ * Content type to serve a path with. From the extension, which is what Chromium
+ * itself read a `file:` URL as, so no design renders differently for it. A video,
+ * an audio track and a font are decoded off the declared type, so a wrong guess
+ * here is an asset that never loads.
+ */
+export declare const contentTypeForPath: (filePath: string) => string;
+/** Register a local file and return the URL the client should load it from. */
+export declare const register: (filePath: string) => string;
+/** Drop registrations once the render that needed them is over. */
+export declare const release: (urls: string[]) => void;
+export declare const MAX_SLICE: number;
+/**
+ * Answer a request for a registered file and return true, or return false so
+ * the caller keeps handling the request itself.
+ */
+export declare const tryRespond: (request: any) => boolean;