polotno-node 3.4.0 → 3.5.0

package/lib/local-media.js

@@ -0,0 +1,169 @@
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+// Serve local files to the renderer over the request-interception seam, so that
+// no `file:` URL ever reaches the browser.
+//
+// A `file:` URL looks like the obvious way to hand a downloaded video to the
+// page, and it is a trap. `chrome-headless-shell` refuses `fetch()` on that
+// scheme whatever flags we pass (`--allow-file-access-from-files` lifts it for
+// XHR only), so the loader that reads media bytes fails — sometimes silently,
+// leaving a video with no sound. A browser on another host cannot see this
+// host's disk at all. And the rule "a URL is a URL" should hold for whichever
+// API the client happens to use, today or later.
+//
+// So a local file is registered here and handed to the client as an ordinary
+// `https:` URL, which `tryRespond` answers from Node — the same interface
+// `font-cache.ts` uses, installed on every page by `createPage`.
+//
+// Two properties are deliberate:
+//   * `.invalid` is reserved (RFC 6761) and never resolves, so a request that
+//     escapes interception fails instead of reaching a real host.
+//   * the URL carries an id and nothing else. Paths come from the registry, so
+//     a design cannot name a path here that it could not already read.
+export const ORIGIN = 'https://polotno-local-media.invalid/';
+/** id → the local path it stands for. */
+const registry = new Map();
+const EXTENSION_CONTENT_TYPE = {
+    '.mp4': 'video/mp4',
+    '.m4v': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.webm': 'video/webm',
+    '.mp3': 'audio/mpeg',
+    '.m4a': 'audio/mp4',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.avif': 'image/avif',
+    '.svg': 'image/svg+xml',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+    '.ttf': 'font/ttf',
+    '.otf': 'font/otf',
+};
+/**
+ * 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 const contentTypeForPath = (filePath) => EXTENSION_CONTENT_TYPE[path.extname(filePath).toLowerCase()] ||
+    'application/octet-stream';
+/** Register a local file and return the URL the client should load it from. */
+export const register = (filePath) => {
+    const id = crypto.randomUUID();
+    registry.set(id, filePath);
+    return ORIGIN + id;
+};
+/** Drop registrations once the render that needed them is over. */
+export const release = (urls) => {
+    for (const url of urls) {
+        registry.delete(url.slice(ORIGIN.length));
+    }
+};
+// A media element opens a file with `bytes=0-` — "everything" — and a 500MB
+// video answered literally is 500MB buffered in Node and base64'd over the
+// devtools protocol. Answering less than was asked for is what a range request
+// is for: the client comes back for the next slice.
+export const MAX_SLICE = 8 * 1024 * 1024;
+// `bytes=0-1023`, `bytes=1024-` and `bytes=-512` (the last N bytes). A request
+// for several ranges at once is answered in full instead — Chromium never asks
+// for one, and a `multipart/byteranges` body would be the only correct reply.
+//
+// `null` means "no range asked for", and 'unsatisfiable' means one was and this
+// file cannot answer it. The two must not collapse: a reader hunting an MP4's
+// trailing `moov` atom asks for the last N bytes, and answering a plain 200
+// from offset 0 hands it the front of the file under a header saying otherwise.
+const parseRange = (header, size) => {
+    const match = /^bytes=(\d*)-(\d*)$/.exec((header || '').trim());
+    if (!match || (!match[1] && !match[2]))
+        return null;
+    // A suffix range longer than the file asks for all of it.
+    const start = match[1]
+        ? Number(match[1])
+        : Math.max(0, size - Number(match[2]));
+    const end = match[1] && match[2] ? Number(match[2]) : size - 1;
+    if (start >= size || end < start)
+        return 'unsatisfiable';
+    return { start, end: Math.min(end, size - 1, start + MAX_SLICE - 1) };
+};
+// Returns the bytes actually read, which the caller reports as the range it
+// served. A read can come up short, and a buffer padded with the zeroes it was
+// allocated with — described by a `content-range` claiming the full slice — is
+// media that decodes to silence or garbage instead of failing.
+const readSlice = async (filePath, start, end) => {
+    const handle = await fs.promises.open(filePath, 'r');
+    try {
+        const buffer = Buffer.alloc(end - start + 1);
+        let filled = 0;
+        while (filled < buffer.length) {
+            const { bytesRead } = await handle.read(buffer, filled, buffer.length - filled, start + filled);
+            if (bytesRead === 0)
+                break; // end of file
+            filled += bytesRead;
+        }
+        return buffer.subarray(0, filled);
+    }
+    finally {
+        await handle.close();
+    }
+};
+/**
+ * Answer a request for a registered file and return true, or return false so
+ * the caller keeps handling the request itself.
+ */
+export const tryRespond = (request) => {
+    const url = request.url();
+    if (!url.startsWith(ORIGIN))
+        return false;
+    const filePath = registry.get(url.slice(ORIGIN.length));
+    const respond = async () => {
+        if (!filePath) {
+            await request.respond({ status: 404, body: 'Unknown media id' });
+            return;
+        }
+        const { size } = await fs.promises.stat(filePath);
+        const range = parseRange(request.headers()['range'], size);
+        if (range === 'unsatisfiable') {
+            await request.respond({
+                status: 416,
+                headers: { 'content-range': `bytes */${size}` },
+                body: 'Range not satisfiable',
+            });
+            return;
+        }
+        const { start, end } = range || { start: 0, end: size - 1 };
+        const body = await readSlice(filePath, start, end);
+        // A media element streams: it asks for a range, gets a 206, and comes back
+        // for the next one. A plain `fetch()` takes the whole body in one response,
+        // which is what the `file:` path did as well.
+        await request.respond({
+            status: range ? 206 : 200,
+            contentType: contentTypeForPath(filePath),
+            headers: {
+                'accept-ranges': 'bytes',
+                // The client page is a `file:` origin, so every read of this URL is
+                // cross-origin. Our launch args carry `--disable-web-security`, which
+                // would hide a missing header from us but not from a caller who brings
+                // their own browser.
+                'access-control-allow-origin': '*',
+                ...(range
+                    ? {
+                        'content-range': `bytes ${start}-${start + body.length - 1}/${size}`,
+                    }
+                    : {}),
+            },
+            body,
+        });
+    };
+    respond().catch(() => {
+        // The page may be gone, or the file unreadable. Fail the request rather
+        // than leave it hanging until the asset timeout.
+        request.abort('failed').catch(() => { });
+    });
+    return true;
+};

package/lib/types.d.ts

@@ -33,8 +33,10 @@ export interface VideoRenderOptions extends RenderOptions {
     onProgress?: (progress: number, frameTime?: number) => void;
     /**
      * When using the default local client (no `createInstance({ url })`), polotno-node will
-     * pre-download remote video/audio sources into a temp folder and rewrite them to `file://...`
-     * URLs for more reliable and faster loading. Set `skipDownloads: true` to disable that.
+     * pre-download remote video/audio sources into a temp folder and serve them to the
+     * renderer from there, for more reliable and faster loading. Set `skipDownloads: true`
+     * to disable that and let the browser load the original URLs itself. Local (`file:`)
+     * sources are always served, whatever this is set to.
      */
     skipDownloads?: boolean;
     /**
@@ -74,6 +76,12 @@ export interface InstanceOptions {
      * google-chrome-stable, say. Ignored when you pass your own `browser`.
      */
     executablePath?: string;
+    /**
+     * Which headless mode to launch. Defaults to puppeteer's `chrome-headless-shell`
+     * wherever we resolve the browser ourselves; `true` forces full Chrome.
+     * Ignored when you pass your own `browser`.
+     */
+    headless?: boolean | 'shell';
     /** Intercept every page request (e.g. to block or rewrite asset loads). */
     requestInterceptor?: (request: any) => void;
     /** Cache Google Fonts responses for the process lifetime and serve them to every page (default: true) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polotno-node",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Polotno workflow from NodeJS",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
@@ -36,12 +36,12 @@
   ],
   "devDependencies": {
     "@types/node": "^26.1.2",
-    "mediabunny": "^1.52.3",
     "axios": "^1.19.0",
     "dotenv": "^17.4.2",
     "fluent-ffmpeg": "^2.1.3",
     "jspdf": "^4.2.1",
-    "konva": "^10.3.0",
+    "konva": "^10.3.1",
+    "mediabunny": "^1.52.3",
     "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
     "react": "^19.2.8",
@@ -51,8 +51,9 @@
     "vite": "^8.2.1",
     "vitest": "^4.1.10",
     "web-audio-api": "^1.5.3",
-    "@polotno/video-export": "0.2.3",
-    "polotno": "4.8.0"
+    "polotno": "4.9.0",
+    "@polotno/design-fixtures": "0.0.0",
+    "@polotno/video-export": "0.2.3"
   },
   "overrides": {
     "@polotno/video-export": {
@@ -75,9 +76,9 @@
   "scripts": {
     "build": "rm -rf ./lib ./dist && tsc -p tsconfig.json && vite build ./client/ --base=./ --outDir ../dist --emptyOutDir --logLevel error",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "pnpm exec turbo run build --filter=polotno-node --output-logs=new-only --log-order=stream && vitest run test/unit test/static/static.test.mjs",
+    "test": "if [ -z \"$TURBO_HASH\" ]; then pnpm exec turbo run build --filter=polotno-node --output-logs=new-only --log-order=stream; fi && vitest run test/unit test/static",
     "test:video": "pnpm exec turbo run build --filter=polotno-node && vitest run test/video/video.test.mjs",
-    "test:all": "pnpm exec turbo run build --filter=polotno-node && vitest run test/unit test/static/static.test.mjs test/video/video.test.mjs",
+    "test:all": "pnpm exec turbo run build --filter=polotno-node && vitest run test/unit test/static test/video",
     "dev": "vite ./client.html"
   }
 }