polotno-node 3.8.1 → 3.10.0

package/lib/types.d.ts

@@ -28,9 +28,31 @@ export interface PDFRenderOptions extends RenderOptions {
     unit?: 'pt' | 'mm' | 'cm' | 'in';
     cropMarkSize?: number;
 }
+/** Includes the browser stages from @polotno/video-export and Node I/O stages. */
+export type VideoExportStage = 'prepare-media' | 'load-client' | 'load-design' | 'setup' | 'frames' | 'audio-decode' | 'audio-render' | 'audio-encode' | 'finalize' | 'transfer' | 'postprocess' | 'read-output';
+export interface VideoExportProgress {
+    stage: VideoExportStage;
+    /** Completed media sources, pages, frames, audio sources, or bytes for this stage. */
+    completed?: number;
+    total?: number;
+}
+export interface VideoExportStatus extends VideoExportProgress {
+    state: 'running' | 'stalled' | 'completed' | 'failed';
+    elapsedMs: number;
+    /** Time since the last stage change, counter increase, or fraction increase. */
+    idleMs: number;
+    /** Time since the last tab heartbeat. Absent until the first heartbeat arrives. */
+    heartbeatAgeMs?: number;
+}
 export interface VideoRenderOptions extends RenderOptions {
     fps?: number;
-    onProgress?: (progress: number, frameTime?: number) => void;
+    onProgress?: (progress: number, frameTime?: number, status?: VideoExportStatus) => void;
+    /**
+     * Inactivity budget in ms, or overrides per stage (default: 60000).
+     * 0 disables stall notifications. Only used with onProgress.
+     * A stall notification never cancels, retries, or changes protocolTimeout.
+     */
+    stallTimeoutMs?: number | Partial<Record<VideoExportStage, number>>;
     /**
      * When using the default local client (no `createInstance({ url })`), polotno-node will
      * pre-download remote video/audio sources into a temp folder and serve them to the

package/lib/video-status.d.ts

@@ -0,0 +1,7 @@
+import type { VideoExportProgress, VideoRenderOptions } from './types.js';
+export declare function createVideoStatusMonitor({ onProgress, stallTimeoutMs, }: Pick<VideoRenderOptions, 'onProgress' | 'stallTimeoutMs'>): {
+    update: (next: VideoExportProgress, nextFraction?: number, nextFrameTime?: number) => void;
+    progress(fraction: number, frameTime?: number, details?: VideoExportProgress): void;
+    heartbeat(): void;
+    finish(result: "completed" | "failed"): void;
+};

package/lib/video-status.js

@@ -0,0 +1,107 @@
+import { polotnoError } from './errors.js';
+// Node owns this clock: a renderer that cannot execute JavaScript cannot run
+// its own stall detector. Heartbeats describe responsiveness, not useful work.
+export function createVideoStatusMonitor({ onProgress, stallTimeoutMs = 60000, }) {
+    const timeouts = typeof stallTimeoutMs === 'object' && stallTimeoutMs !== null
+        ? Object.values(stallTimeoutMs).filter((timeout) => timeout !== undefined)
+        : [stallTimeoutMs];
+    for (const timeout of timeouts) {
+        if (typeof timeout !== 'number' ||
+            !Number.isFinite(timeout) ||
+            timeout < 0 ||
+            timeout > 2147483647) {
+            throw polotnoError('EXPORT_FAILED', 'Invalid video stall timeout.', {
+                reason: 'invalid-options',
+                option: 'stallTimeoutMs',
+                value: String(timeout),
+            });
+        }
+    }
+    const startedAt = performance.now();
+    let advancedAt = startedAt;
+    let heartbeatAt;
+    let progress = { stage: 'prepare-media' };
+    let state = 'running';
+    let fraction = 0;
+    let frameTime;
+    let finished = false;
+    let timer;
+    async function emit() {
+        if (!onProgress)
+            return;
+        const now = performance.now();
+        const status = {
+            ...progress,
+            state,
+            elapsedMs: now - startedAt,
+            idleMs: now - advancedAt,
+            ...(heartbeatAt === undefined
+                ? {}
+                : { heartbeatAgeMs: now - heartbeatAt }),
+        };
+        // Observers cannot turn a successful render into a failed one, including
+        // when an async observer rejects. Never await user I/O in the render path.
+        try {
+            await onProgress(fraction, frameTime, status);
+        }
+        catch (error) {
+            console.error('Video status callback failed:', error);
+        }
+    }
+    function arm() {
+        clearTimeout(timer);
+        const timeout = typeof stallTimeoutMs === 'number'
+            ? stallTimeoutMs
+            : (stallTimeoutMs[progress.stage] ?? 60000);
+        if (!onProgress || timeout === 0)
+            return;
+        timer = setTimeout(() => {
+            state = 'stalled';
+            emit();
+        }, timeout);
+        timer.unref();
+    }
+    emit();
+    arm();
+    function update(next, nextFraction = fraction, nextFrameTime) {
+        if (finished || !onProgress)
+            return;
+        const fractionAdvanced = Number.isFinite(nextFraction) && nextFraction > fraction;
+        // Stage changes, counters, and legacy percentage advances are useful work.
+        // Repeated values and heartbeats must not keep a stuck job alive.
+        const advanced = next.stage !== progress.stage ||
+            fractionAdvanced ||
+            (next.completed !== undefined &&
+                next.completed > (progress.completed ?? -1));
+        if (!advanced)
+            return;
+        progress = { ...next };
+        if (fractionAdvanced)
+            fraction = Math.min(1, nextFraction);
+        frameTime = nextFrameTime;
+        advancedAt = performance.now();
+        state = 'running';
+        emit();
+        arm();
+    }
+    return {
+        update,
+        progress(fraction, frameTime, details) {
+            update(details ?? progress, fraction, frameTime);
+        },
+        heartbeat() {
+            if (!finished)
+                heartbeatAt = performance.now();
+        },
+        finish(result) {
+            if (finished)
+                return;
+            finished = true;
+            clearTimeout(timer);
+            state = result;
+            if (result === 'completed')
+                fraction = 1;
+            emit();
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polotno-node",
-  "version": "3.8.1",
+  "version": "3.10.0",
   "description": "Polotno workflow from NodeJS",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "module",
@@ -35,25 +35,23 @@
     "@polotno/video-export"
   ],
   "devDependencies": {
-    "@types/node": "^26.4.1",
-    "axios": "^1.20.0",
+    "@polotno/design-fixtures": "0.0.0",
+    "@polotno/video-export": "0.4.0",
+    "@types/node": "^26.6.1",
     "dotenv": "^17.4.2",
-    "fluent-ffmpeg": "^2.1.3",
     "jspdf": "^4.2.1",
-    "konva": "^10.3.2",
-    "mediabunny": "^1.55.5",
+    "konva": "^10.5.0",
+    "mediabunny": "^1.56.3",
     "pixelmatch": "^7.2.0",
     "pngjs": "^7.0.0",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
+    "polotno": "4.13.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "tmp": "^0.2.7",
     "typescript": "~6.0.3",
-    "vite": "^8.2.2",
-    "vitest": "^4.1.11",
-    "web-audio-api": "^1.5.5",
-    "@polotno/video-export": "0.2.5",
-    "polotno": "4.12.0",
-    "@polotno/design-fixtures": "0.0.0"
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1",
+    "web-audio-api": "^1.5.6"
   },
   "overrides": {
     "@polotno/video-export": {
@@ -63,10 +61,10 @@
   },
   "author": "Anton Lavrenov",
   "dependencies": {
-    "@sparticuz/chromium": "^149.0.0",
-    "puppeteer": "25.9.0",
-    "puppeteer-core": "25.9.0",
-    "@polotno/schema": "0.6.1"
+    "@polotno/schema": "0.6.2",
+    "@sparticuz/chromium": "^153.0.0",
+    "puppeteer": "25.11.0",
+    "puppeteer-core": "25.11.0"
   },
   "bugs": {
     "url": "https://github.com/polotno-project/polotno-node/issues"