polotno-node 3.8.1 → 3.9.0

package/README.md

@@ -252,6 +252,85 @@ const base64 = await instance.jsonToVideoBase64(json, {
 fs.writeFileSync('out.mp4', base64, 'base64');
 ```
 
+### Video status and inactivity detection
+
+Video export methods report status through the third argument of `onProgress(fraction, frameTime, status)`.
+The first argument remains a number between 0 and 1. Existing handlers can ignore the third argument.
+Monitoring runs only when you provide `onProgress`. It does not cancel an export, close a browser, or retry a job.
+
+```js
+await instance.jsonToVideoFile(json, 'out.mp4', {
+  onProgress: (fraction, frameTime, status) => {
+    console.log('Progress:', fraction, status);
+    if (status?.state === 'stalled') {
+      console.warn('No recent work progress:', status.stage, status.idleMs);
+    }
+  },
+  // Example advisory budgets. Tune these from healthy exports on your hosts.
+  stallTimeoutMs: {
+    frames: 60_000,
+    'audio-render': 180_000,
+    finalize: 180_000,
+  },
+});
+```
+
+The third argument contains:
+
+| Field                | Meaning                                                                      |
+| -------------------- | ---------------------------------------------------------------------------- |
+| `state`              | `running`, `stalled`, `completed`, or `failed`                               |
+| `stage`              | The last reported operation, listed in the next table                        |
+| `completed`, `total` | Work counters within the stage, when available                               |
+| `elapsedMs`          | Time since the export passed design validation                               |
+| `idleMs`             | Time since the last stage change, counter increase, or fraction increase     |
+| `heartbeatAgeMs`     | Time since the last tab heartbeat. Absent until the first heartbeat arrives. |
+
+Stages describe these operations:
+
+| Stage           | Operation and counter unit                                                                            |
+| --------------- | ----------------------------------------------------------------------------------------------------- |
+| `prepare-media` | Download and prepare remote media. Counts prepared sources.                                           |
+| `load-client`   | Open and configure the renderer page.                                                                 |
+| `load-design`   | Load the design and wait for its pages. Counts pages.                                                 |
+| `setup`         | Initialize the video exporter and codecs.                                                             |
+| `frames`        | Render and encode video frames. Counts frames.                                                        |
+| `audio-decode`  | Load and decode audio. Counts processed sources, including sources the exporter skips after an error. |
+| `audio-render`  | Mix audio through the native audio renderer.                                                          |
+| `audio-encode`  | Send the mixed audio to the encoder.                                                                  |
+| `finalize`      | Finish the video container.                                                                           |
+| `transfer`      | Transfer the video to Node. Counts bytes written to the output file.                                  |
+| `postprocess`   | Inspect the output file and convert its audio codec when necessary.                                   |
+| `read-output`   | Read the file for a base64 or data-URL result.                                                        |
+
+`stallTimeoutMs` accepts one number for every stage, or an object with overrides per stage.
+The default is 60000 ms, including stages without an override. A value of `0` disables stall notifications for that budget.
+The threshold is advisory. It is not a measured limit for healthy renders.
+
+The monitor emits one `stalled` notification per inactivity period.
+A new stage, counter increase, or fraction increase emits `running` and starts a new inactivity period.
+Repeated counters, repeated fractions, and tab heartbeats do not reset the inactivity clock.
+Stage changes and stall notifications can repeat the last fraction. Successful completion reports `1`.
+The last notification is `completed` or `failed`. Monitoring then stops, including after temporary-file cleanup.
+Callback errors are logged. Callback promises do not delay the export.
+
+The tab sends a heartbeat approximately once per second during the browser export.
+A recent heartbeat means that the tab could run JavaScript, even if the export made no visible progress.
+A missing heartbeat can indicate blocked JavaScript or host contention. It does not prove a permanent stall.
+Native audio processing and finalization can also take time without intermediate work counters.
+Custom clients with older video exporters can report fewer stages.
+
+The inactivity timer runs in Node, so it can report a blocked renderer without another CDP request.
+It cannot fire while Node itself is blocked, including during synchronous media conversion or base64 conversion.
+An independent parent-process monitor is necessary to detect that condition during the block.
+Existing `protocolTimeout` and navigation timeouts still apply.
+
+A confirmed renderer crash rejects the active render without waiting for its CDP timeout.
+Protocol failures skip further renderer diagnostics, which could otherwise consume another full timeout.
+Failed-page cleanup does not delay rejection or replace the original error. It does not terminate the browser.
+With the default `useParallelPages: true`, a later export opens a new page if the browser remains connected.
+Retries remain the caller's decision; inactivity notifications alone do not trigger them.
+
 ### `attrs` usage
 
 **NOTE: all export API will pass `attrs` object into relevant export function from `store`.**