polotno-node 3.8.1 → 3.9.0

package/lib/instance.js

@@ -11,6 +11,7 @@ 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';
+import { createVideoStatusMonitor } from './video-status.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')}`;
@@ -337,7 +338,7 @@ const getAudioCodec = (filePath) => {
 const convertAudioToAac = (inputPath, outputPath) => {
     execFileSync('ffmpeg', ['-y', '-i', inputPath, '-c:v', 'copy', '-c:a', 'aac', outputPath], { stdio: 'ignore' });
 };
-export const prepareLocalMediaForVideoExport = async (json, policy = {}) => {
+export const prepareLocalMediaForVideoExport = async (json, policy = {}, onProgress) => {
     const clonedJson = JSON.parse(JSON.stringify(json));
     const pointers = collectMediaSourcePointers(clonedJson);
     const rewriteMap = new Map();
@@ -362,6 +363,8 @@ export const prepareLocalMediaForVideoExport = async (json, policy = {}) => {
         if (p.kind === 'video')
             videoUrls.add(src);
     }
+    let completed = 0;
+    onProgress?.(completed, urlsToDownload.length);
     if (urlsToDownload.length === 0) {
         return { json: clonedJson, cleanup: async () => { } };
     }
@@ -406,6 +409,7 @@ export const prepareLocalMediaForVideoExport = async (json, policy = {}) => {
             // 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());
+            onProgress?.(++completed, urlsToDownload.length);
         }));
         for (const p of pointers) {
             const src = p.target[p.key];
@@ -417,7 +421,9 @@ export const prepareLocalMediaForVideoExport = async (json, policy = {}) => {
         return { json: clonedJson, cleanup };
     }
     catch (e) {
-        await cleanup();
+        await cleanup().catch((error) => {
+            console.error('Failed to remove temporary media:', error);
+        });
         throw e;
     }
 };
@@ -450,78 +456,135 @@ const ensureServing = async (page) => {
     // runs in the same microtask the await resolves on.
     intercepting.add(page);
 };
+// Match names across caller-supplied Puppeteer copies, not class identity.
+const isProtocolFailure = (error) => error instanceof Error &&
+    ['ProtocolError', 'TargetCloseError', 'ConnectionClosedError'].includes(error.name);
+// Puppeteer emits a page error on renderer crash, but leaves pending CDP
+// evaluations waiting for protocolTimeout. Heartbeat silence is not this signal:
+// healthy synchronous JavaScript can also delay progress.
+const watchRenderer = (page) => {
+    let crashError;
+    let reportCrash;
+    const crashed = new Promise((resolve) => {
+        reportCrash = resolve;
+    });
+    const onCrash = (error) => {
+        crashError = error;
+        reportCrash(error);
+    };
+    page.on('error', onCrash);
+    return {
+        get failed() {
+            return Boolean(crashError);
+        },
+        async run(operation) {
+            if (crashError)
+                throw crashError;
+            return Promise.race([
+                operation(),
+                crashed.then((error) => {
+                    throw error;
+                }),
+            ]);
+        },
+        dispose() {
+            page.off('error', onCrash);
+        },
+    };
+};
+// The failed call owns its page, never the browser. Cleanup must neither
+// replace the primary error nor add another protocol timeout before rejection.
+const closeFailedPage = (page) => {
+    if (page.isClosed() || !page.browser().connected)
+        return;
+    void Promise.resolve()
+        .then(() => page.close())
+        .catch((error) => {
+        console.error('Failed to close export page:', error);
+    });
+};
 export const createPage = async (browser, url, requestInterceptor, useFontCache = true, navigationTimeout = DEFAULT_NAVIGATION_TIMEOUT) => {
     const page = await browser.newPage();
-    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;
+    const renderer = watchRenderer(page);
+    try {
+        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 (typeof requestInterceptor === 'function') {
-            requestInterceptor(request);
+        if (useFontCache || typeof requestInterceptor === 'function') {
+            await renderer.run(() => ensureServing(page));
         }
-        else {
-            request.continue().catch(() => { });
+        // we need to make sure that headless is inside user agent
+        // because we use it for key validation check
+        // 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 renderer.run(() => page.evaluate(() => navigator.userAgent));
+        if (userAgent.indexOf('Headless') === -1) {
+            await renderer.run(() => page.setUserAgent(userAgent + ' Chrome Headless'));
         }
-    });
-    if (useFontCache) {
-        page.on('response', (response) => fontCache.capture(response));
+        page.on('console', (msg) => {
+            msg.args().forEach(async (message) => {
+                // skip style information
+                if (message.toString().indexOf('margin') >= 0) {
+                    return;
+                }
+                const { subtype, description } = message.remoteObject();
+                if (subtype === 'error') {
+                    console.error(description);
+                    return;
+                }
+                const text = message
+                    .toString()
+                    .replace('JSHandle:', '')
+                    .replace('%c', '');
+                console.log(text);
+            });
+        });
+        page.on('pageerror', (msg) => {
+            console.error(msg);
+        });
+        await renderer.run(() => page.goto(url, { timeout: navigationTimeout }));
+        return page;
     }
-    if (useFontCache || typeof requestInterceptor === 'function') {
-        await ensureServing(page);
+    catch (error) {
+        closeFailedPage(page);
+        throw error;
     }
-    // we need to make sure that headless is inside user agent
-    // because we use it for key validation check
-    // 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');
+    finally {
+        renderer.dispose();
     }
-    page.on('console', (msg) => {
-        msg.args().forEach(async (message) => {
-            // skip style information
-            if (message.toString().indexOf('margin') >= 0) {
-                return;
-            }
-            const { subtype, description } = message.remoteObject();
-            if (subtype === 'error') {
-                console.error(description);
-                return;
-            }
-            const text = message
-                .toString()
-                .replace('JSHandle:', '')
-                .replace('%c', '');
-            console.log(text);
-        });
-    });
-    page.on('pageerror', (msg) => {
-        console.error(msg);
-    });
-    await page.goto(url, { timeout: navigationTimeout });
-    return page;
 };
 /**
  * Evaluate on a page the caller owns, with the design's local files served
@@ -713,31 +776,36 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
         busyPages.push(page);
         // Setup profiling if profilePath is provided
         let cdpSession = null;
+        let profilerStopped = false;
         const profilePath = args[1]?.profilePath;
+        const renderer = watchRenderer(page);
+        const withRenderer = renderer.run;
+        let succeeded = false;
         try {
             if (served.serving) {
-                await ensureServing(page);
+                await withRenderer(() => ensureServing(page));
             }
             if (profilePath) {
-                cdpSession = await page.target().createCDPSession();
-                await cdpSession.send('Profiler.enable');
-                await cdpSession.send('Profiler.start');
+                cdpSession = await withRenderer(() => page.target().createCDPSession());
+                await withRenderer(() => cdpSession.send('Profiler.enable'));
+                await withRenderer(() => cdpSession.send('Profiler.start'));
             }
             // All direct `window.config.*` setters are applied from one table.
-            await applyConfigOptions(page, args[1]);
+            await withRenderer(() => applyConfigOptions(page, args[1]));
             if (args[1]?.onProgress) {
                 const originalProgress = args[1].onProgress;
-                await page.exposeFunction('onProgress', async (progress, frameTime) => {
-                    originalProgress(progress, frameTime);
-                });
+                await withRenderer(() => page.exposeFunction('onProgress', async (progress, frameTime, status) => {
+                    originalProgress(progress, frameTime, status);
+                }));
             }
             // Allow exposing custom functions (used for chunked data transfer)
             if (args[1]?.exposeFunctions) {
-                for (const [name, fn] of Object.entries(args[1].exposeFunctions)) {
-                    await page.exposeFunction(name, fn);
+                const functions = args[1].exposeFunctions;
+                for (const [name, fn] of Object.entries(functions)) {
+                    await withRenderer(() => page.exposeFunction(name, fn));
                 }
             }
-            await page.evaluate(() => {
+            await withRenderer(() => page.evaluate(() => {
                 if (window.config?.onLoadError) {
                     window.config.onLoadError((error) => {
                         // New clients pass an Error with `code`/`details` — stash a JSON
@@ -756,53 +824,63 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
                 else {
                     console.error('onLoadError function is not defined in the client. Error handling will not work.');
                 }
-            });
-            await ensureAssetErrorHelpers(page);
-            const result = await page.evaluate(func, ...runArgs);
+            }));
+            await withRenderer(() => ensureAssetErrorHelpers(page));
+            const result = await withRenderer(() => page.evaluate(func, ...runArgs));
             // Stop profiler and save profile if enabled
             if (cdpSession && profilePath) {
-                const { profile } = await cdpSession.send('Profiler.stop');
+                profilerStopped = true;
+                const { profile } = await withRenderer(() => cdpSession.send('Profiler.stop'));
                 fs.writeFileSync(profilePath, JSON.stringify(profile));
                 console.log(`CPU profile saved to: ${profilePath}`);
             }
-            const assetError = await consumeAssetLoadingError(page, args[1]);
+            const assetError = await withRenderer(() => consumeAssetLoadingError(page, args[1]));
             if (assetError) {
                 throw rehydrateError(assetError);
             }
-            // remove busy page
-            busyPages.splice(busyPages.indexOf(page), 1);
             if (useParallelPages) {
-                await page.close();
+                await withRenderer(() => page.close());
             }
+            succeeded = true;
             return result;
         }
         catch (e) {
-            // Stop profiler and save profile even on error
-            if (cdpSession && profilePath) {
+            // Protocol failures (including CDP timeouts) cannot safely ask the same
+            // renderer for diagnostics: each request can cost another full export
+            // timeout. Use names to also support caller-supplied Puppeteer copies.
+            let rendererUnavailable = renderer.failed || isProtocolFailure(e);
+            // Application errors can still produce a useful CPU profile.
+            if (!rendererUnavailable &&
+                cdpSession &&
+                profilePath &&
+                !profilerStopped) {
                 console.log('saving profile');
                 try {
-                    const { profile } = await cdpSession.send('Profiler.stop');
+                    profilerStopped = true;
+                    const { profile } = await withRenderer(() => cdpSession.send('Profiler.stop'));
                     fs.writeFileSync(profilePath, JSON.stringify(profile));
                     console.log(`CPU profile saved to: ${profilePath}`);
                 }
                 catch (profileError) {
+                    rendererUnavailable || (rendererUnavailable = renderer.failed || isProtocolFailure(profileError));
                     console.error('Failed to save profile:', profileError.message);
                 }
             }
             // If `page.evaluate()` failed (e.g. thrown during onProgress), still prefer
             // a captured Polotno asset-loading error when available.
-            const assetError = await consumeAssetLoadingError(page, args[1]);
-            // remove busy page
-            busyPages.splice(busyPages.indexOf(page), 1);
-            if (useParallelPages) {
-                await page.close();
-            }
+            const assetError = rendererUnavailable || renderer.failed
+                ? null
+                : await withRenderer(() => consumeAssetLoadingError(page, args[1])).catch(() => null);
             if (assetError) {
                 throw rehydrateError(assetError);
             }
             throw e;
         }
         finally {
+            renderer.dispose();
+            busyPages.splice(busyPages.indexOf(page), 1);
+            if (!succeeded && useParallelPages)
+                closeFailedPage(page);
             served.release();
         }
     };
@@ -843,114 +921,171 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
         const blob = Buffer.from(base64, 'base64');
         return blob;
     };
-    const jsonToVideoFile = async (json, outputPath, attrs = {}) => {
-        await assertValidJson(json);
+    const renderVideoFile = async (json, outputPath, attrs, status) => {
         const shouldDownloadMedia = !hasCustomClientUrl && !(attrs && attrs.skipDownloads);
         const prepared = shouldDownloadMedia
             ? await prepareLocalMediaForVideoExport(json, {
                 blockPrivateNetwork: attrs?.blockPrivateNetwork,
                 fetchGuard: attrs?.fetchGuard,
-            })
+            }, (completed, total) => status.update({ stage: 'prepare-media', completed, total }))
             : { json, cleanup: async () => { } };
-        const writeStream = fs.createWriteStream(outputPath);
+        let outputFile;
+        let writeError;
+        let failed = false;
         try {
+            const file = await fs.promises.open(outputPath, 'w');
+            outputFile = file;
+            status.update({ stage: 'load-client' });
             const mimeType = await run(async (json, attrs) => {
-                const pixelRatio = attrs.pixelRatio || 1;
-                store.loadJSON(json);
-                window.__polotnoThrowAssetErrorIfAny(attrs);
-                // keep store internals consistent with image/pdf exports
-                store.setElementsPixelRatio(pixelRatio);
-                // loop through all pages and wait for loading for all layout calculations
-                // (this helps stabilize text/layout across multi-page designs)
-                for (const page of store.pages) {
-                    store.selectPage(page.id);
-                    await store.waitLoading();
-                    window.__polotnoThrowAssetErrorIfAny(attrs);
-                }
-                if (store.pages.length > 0) {
-                    store.selectPage(store.pages[0].id);
-                    await store.waitLoading();
-                    window.__polotnoThrowAssetErrorIfAny(attrs);
-                }
-                // 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');
-                if (!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
-                const abortController = new AbortController();
-                let capturedError = null;
-                // Always have an internal progress callback to check for errors,
-                // even if user didn't provide onProgress
-                const progressCallback = (progress, frameTime) => {
-                    // Check for asset-loading errors during render (without throwing)
-                    const assetError = window.__polotnoConsumeAssetError(attrs);
-                    if (assetError) {
-                        capturedError = assetError;
-                        abortController.abort();
-                        return;
-                    }
-                    // Call user's progress callback if provided
-                    if (window.onProgress) {
-                        window.onProgress(progress, frameTime);
+                const reportStatus = (progress) => {
+                    if (attrs.reportProgress) {
+                        void window.onProgress(0, undefined, progress).catch(() => { });
                     }
                 };
-                let videoBlob;
+                let heartbeat;
+                if (attrs.reportProgress) {
+                    const beat = () => {
+                        void window.__polotnoVideoHeartbeat().catch(() => { });
+                    };
+                    beat();
+                    heartbeat = setInterval(beat, 1000);
+                }
                 try {
-                    videoBlob = await storeToVideo({
-                        store,
-                        fps: attrs.fps,
-                        pixelRatio,
-                        onProgress: progressCallback,
-                        signal: abortController.signal,
+                    const pixelRatio = attrs.pixelRatio || 1;
+                    reportStatus({
+                        stage: 'load-design',
+                        completed: 0,
+                        total: json.pages?.length ?? 0,
                     });
-                }
-                catch (e) {
-                    // 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).
+                    store.loadJSON(json);
+                    window.__polotnoThrowAssetErrorIfAny(attrs);
+                    // keep store internals consistent with image/pdf exports
+                    store.setElementsPixelRatio(pixelRatio);
+                    // loop through all pages and wait for loading for all layout calculations
+                    // (this helps stabilize text/layout across multi-page designs)
+                    let loadedPages = 0;
+                    for (const page of store.pages) {
+                        store.selectPage(page.id);
+                        await store.waitLoading();
+                        window.__polotnoThrowAssetErrorIfAny(attrs);
+                        reportStatus({
+                            stage: 'load-design',
+                            completed: ++loadedPages,
+                            total: store.pages.length,
+                        });
+                    }
+                    if (store.pages.length > 0) {
+                        store.selectPage(store.pages[0].id);
+                        await store.waitLoading();
+                        window.__polotnoThrowAssetErrorIfAny(attrs);
+                    }
+                    // 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');
+                    if (!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
+                    const abortController = new AbortController();
+                    let capturedError = null;
+                    // Always have an internal progress callback to check for errors,
+                    // even if user didn't provide onProgress
+                    const progressCallback = (progress, frameTime, details) => {
+                        // Check for asset-loading errors during render (without throwing)
+                        const assetError = window.__polotnoConsumeAssetError(attrs);
+                        if (assetError) {
+                            capturedError = assetError;
+                            abortController.abort();
+                            return;
+                        }
+                        // Call user's progress callback if provided
+                        if (attrs.reportProgress) {
+                            void window
+                                .onProgress(progress, frameTime, details)
+                                .catch(() => { });
+                        }
+                    };
+                    reportStatus({ stage: 'setup' });
+                    let videoBlob;
+                    try {
+                        videoBlob = await storeToVideo({
+                            store,
+                            fps: attrs.fps,
+                            pixelRatio,
+                            onProgress: progressCallback,
+                            signal: abortController.signal,
+                        });
+                    }
+                    catch (e) {
+                        // 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) {
+                            window._polotnoError = capturedError;
+                            window.__polotnoThrowAssetErrorIfAny(attrs);
+                        }
+                        throw e;
+                    }
+                    // Final check for any errors that occurred
                     if (capturedError) {
                         window._polotnoError = capturedError;
                         window.__polotnoThrowAssetErrorIfAny(attrs);
                     }
-                    throw e;
-                }
-                // Final check for any errors that occurred
-                if (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
-                // 3 bytes -> 4 characters. If chunks aren't aligned, each chunk gets padding
-                // (= or ==) at the end, and joining them creates invalid base64 and video may corrupt.
-                const CHUNK_SIZE = 3 * 1024 * 1024; // 3MB, divisible by 3
-                const arrayBuffer = await videoBlob.arrayBuffer();
-                const uint8Array = new Uint8Array(arrayBuffer);
-                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 = '';
-                    for (let i = 0; i < chunk.length; i++) {
-                        binary += String.fromCharCode(chunk[i]);
+                    // Transfer bounded chunks; Node decodes each one independently.
+                    const CHUNK_SIZE = 3 * 1024 * 1024;
+                    reportStatus({
+                        stage: 'transfer',
+                        completed: 0,
+                        total: videoBlob.size,
+                    });
+                    const arrayBuffer = await videoBlob.arrayBuffer();
+                    const uint8Array = new Uint8Array(arrayBuffer);
+                    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 = '';
+                        for (let i = 0; i < chunk.length; i++) {
+                            binary += String.fromCharCode(chunk[i]);
+                        }
+                        await window.__polotnoWriteChunk(btoa(binary));
+                        reportStatus({
+                            stage: 'transfer',
+                            completed: end,
+                            total: uint8Array.length,
+                        });
                     }
-                    await window.__polotnoWriteChunk(btoa(binary));
+                    return videoBlob.type;
+                }
+                finally {
+                    clearInterval(heartbeat);
                 }
-                return videoBlob.type;
             }, prepared.json, {
                 ...attrs,
+                reportProgress: Boolean(attrs.onProgress),
+                onProgress: attrs.onProgress ? status.progress : undefined,
                 exposeFunctions: {
-                    __polotnoWriteChunk: (base64Chunk) => {
-                        const buffer = Buffer.from(base64Chunk, 'base64');
-                        writeStream.write(buffer);
+                    ...(attrs.onProgress
+                        ? {
+                            __polotnoVideoHeartbeat: status.heartbeat,
+                        }
+                        : {}),
+                    __polotnoWriteChunk: async (base64Chunk) => {
+                        try {
+                            await file.writeFile(Buffer.from(base64Chunk, 'base64'));
+                        }
+                        catch (error) {
+                            // Keep filesystem details that Puppeteer would flatten.
+                            writeError = error;
+                            throw error;
+                        }
                     },
                 },
             });
-            writeStream.end();
-            await new Promise((resolve) => writeStream.on('finish', resolve));
+            outputFile = undefined;
+            await file.close();
             // Convert audio to AAC if needed
+            status.update({ stage: 'postprocess' });
             if (isFfmpegAvailable()) {
                 const codec = getAudioCodec(outputPath);
                 if (codec && codec !== 'aac') {
@@ -961,32 +1096,70 @@ export const createInstance = async ({ key, url, useParallelPages = true, browse
             }
             return mimeType;
         }
+        catch (error) {
+            failed = true;
+            // A close failure must not replace the render or write failure.
+            await outputFile?.close().catch((closeError) => {
+                console.error('Failed to close video output:', closeError);
+            });
+            throw writeError ?? error;
+        }
         finally {
-            await prepared.cleanup();
+            try {
+                await prepared.cleanup();
+            }
+            catch (error) {
+                if (!failed)
+                    throw error;
+                console.error('Failed to remove temporary media:', error);
+            }
         }
     };
-    const jsonToVideoDataURL = async (json, attrs) => {
-        const tempPath = path.join(os.tmpdir(), `polotno-video-${Date.now()}-${Math.random().toString(36).slice(2)}.mp4`);
+    const withVideoStatus = async (json, attrs, render) => {
+        await assertValidJson(json);
+        const status = createVideoStatusMonitor(attrs);
         try {
-            const mimeType = await jsonToVideoFile(json, tempPath, attrs);
-            const buffer = await fs.promises.readFile(tempPath);
-            return `data:${mimeType || 'video/mp4'};base64,${buffer.toString('base64')}`;
+            const result = await render(status);
+            status.finish('completed');
+            return result;
         }
-        finally {
-            await fs.promises.rm(tempPath, { force: true });
+        catch (error) {
+            status.finish('failed');
+            throw error;
         }
     };
-    const jsonToVideoBase64 = async (json, attrs) => {
+    const jsonToVideoFile = (json, outputPath, attrs = {}) => withVideoStatus(json, attrs, (status) => renderVideoFile(json, outputPath, attrs, status));
+    // Both string APIs own a temporary file. Keep monitoring until it is read
+    // and removed, so a read/cleanup failure cannot follow a completed event.
+    const renderVideoString = (json, attrs, dataURL) => withVideoStatus(json, attrs, async (status) => {
         const tempPath = path.join(os.tmpdir(), `polotno-video-${Date.now()}-${Math.random().toString(36).slice(2)}.mp4`);
+        let failed = false;
         try {
-            await jsonToVideoFile(json, tempPath, attrs);
+            const mimeType = await renderVideoFile(json, tempPath, attrs, status);
+            status.update({ stage: 'read-output' });
             const buffer = await fs.promises.readFile(tempPath);
-            return buffer.toString('base64');
+            const base64 = buffer.toString('base64');
+            return dataURL
+                ? `data:${mimeType || 'video/mp4'};base64,${base64}`
+                : base64;
+        }
+        catch (error) {
+            failed = true;
+            throw error;
         }
         finally {
-            await fs.promises.rm(tempPath, { force: true });
+            try {
+                await fs.promises.rm(tempPath, { force: true });
+            }
+            catch (error) {
+                if (!failed)
+                    throw error;
+                console.error('Failed to remove temporary video:', error);
+            }
         }
-    };
+    });
+    const jsonToVideoDataURL = (json, attrs = {}) => renderVideoString(json, attrs, true);
+    const jsonToVideoBase64 = (json, attrs = {}) => renderVideoString(json, attrs, false);
     const instance = {
         close: async () => {
             createdInstances.splice(createdInstances.indexOf(instance), 1);