From 472904bd0bef661f9fc5366cdfd05c9d148ba513 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 05:13:49 -0400
Subject: [PATCH 1/7] feat(scripts): flag a capture region that briefly returns
 to an older picture

check-capture-reversion.mjs compares cropped, downscaled frames and
reports a frame that differs between two matching frames within a
window. Continuous motion is not flagged. Adds a unit test and a short
section in CONTRIBUTING.
---
 CONTRIBUTING.md                          |   4 +
 package.json                             |   2 +-
 scripts/check-capture-reversion.mjs      | 137 +++++++++++++++++++++++
 scripts/check-capture-reversion.test.mjs |  32 ++++++
 4 files changed, 174 insertions(+), 1 deletion(-)
 create mode 100644 scripts/check-capture-reversion.mjs
 create mode 100644 scripts/check-capture-reversion.test.mjs

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 43025de04c..53ed8631ba 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -147,6 +147,10 @@ The script wipes `docs/catalog/` before regenerating, so deleted items are autom
 - CI must pass before merge (build, typecheck, tests, semantic PR title)
 - PRs require at least 1 approval
 
+### Checking a capture
+
+A screen recording attached to a PR must not show a region briefly returning to an older picture (a clip that reappears for one frame, a panel that flashes its previous state). Run `node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] <video>...` once per region that matters; it needs `ffmpeg` and `ffprobe`, exits 1 on a flagged video, and names the frames that differ and the two matching frames around them. Continuous motion is not flagged, but a toast or cursor inside the crop can be, so crop it out or check the named frames by eye.
+
 ## Packages
 
 | Package                 | Description                                 |
diff --git a/package.json b/package.json
index 2fbb9f79a9..12fcb76355 100644
--- a/package.json
+++ b/package.json
@@ -49,7 +49,7 @@
     "player:perf": "bun run --filter @hyperframes/player perf",
     "format:check": "oxfmt --check .",
     "knip": "knip",
-    "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-large-files.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/publish-workflow.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/lint-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts && vitest run scripts/catalog/",
+    "test:scripts": "node --import tsx --test scripts/animejs-v4-guidance.test.mjs scripts/check-tracked-artifacts.test.mjs scripts/check-no-main-deletions.test.mjs scripts/check-pr-captures.test.mjs scripts/check-docs-snippet-motion.test.mjs scripts/registry-target-paths.test.mjs scripts/check-workspace-contracts.test.mjs scripts/check-package-cycles.test.mjs scripts/check-cli-process-ownership.test.mjs scripts/check-large-files.test.mjs scripts/check-capture-reversion.test.mjs scripts/package-subpaths.test.mjs scripts/validate-release-channel.test.mjs scripts/publish-workflow.test.mjs scripts/install-workspace-dependencies.test.mjs scripts/draft-changelog.test.ts scripts/set-version.test.ts scripts/release-prepare.test.ts scripts/cli-options.test.ts scripts/changelog-weekly.test.ts scripts/claude-plugin-compression.test.ts scripts/catalog-payload-assets.test.ts scripts/host-registry-assets.test.ts scripts/catalog-preview-temp.test.ts scripts/catalog-hosted-files.test.ts scripts/player-cdn-pin.test.ts scripts/studio-runtime-smoke.test.mjs scripts/verify-packed-manifests.test.mjs scripts/lint-skills.test.mjs scripts/creator-editing-recipes.test.mjs packages/gcp-cloud-run/check-dockerfile-workspaces.test.mjs packages/core/scripts/writeGeneratedFile.test.ts && vitest run scripts/catalog/",
     "typecheck:scripts": "tsc --noEmit -p scripts/tsconfig.json",
     "test:skills": "node --test 'skills/**/*.test.mjs'",
     "generate:previews": "tsx scripts/generate-template-previews.ts",
diff --git a/scripts/check-capture-reversion.mjs b/scripts/check-capture-reversion.mjs
new file mode 100644
index 0000000000..aaf493a724
--- /dev/null
+++ b/scripts/check-capture-reversion.mjs
@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+// Flags a capture region that briefly returns to an older picture (A, B, A frames).
+// node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] [--window=N] [--change=D] [--same=D] <video>...
+// Frames are cropped, 96px wide, gray; D is mean abs pixel diff (0-255). Exit 1 if flagged.
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const WIDTH = 96;
+const args = { crop: undefined, window: 20, change: 1.0, same: 0.25 };
+
+function readFrames(path, crop) {
+  return new Promise((resolve, reject) => {
+    const scale = `scale=${WIDTH}:-2:flags=area,format=gray`;
+    const vf = crop ? `crop=${crop},${scale}` : scale;
+    const child = spawn("ffmpeg", ["-v", "error", "-i", path, "-vf", vf, "-f", "rawvideo", "-"]);
+    const chunks = [];
+    let stderr = "";
+    child.stdout.on("data", (c) => chunks.push(c));
+    child.stderr.on("data", (c) => (stderr += c));
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code !== 0) return reject(new Error(`ffmpeg exited ${code} for ${path}: ${stderr}`));
+      resolve(Buffer.concat(chunks));
+    });
+  });
+}
+
+// The frame height depends on the crop aspect; probe it from the buffer size
+// by asking ffprobe would add a dependency, so derive it from the crop or the
+// video's own size.
+function probeSize(path) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("ffprobe", [
+      "-v",
+      "error",
+      "-select_streams",
+      "v:0",
+      "-show_entries",
+      "stream=width,height",
+      "-of",
+      "csv=p=0",
+      path,
+    ]);
+    let out = "";
+    child.stdout.on("data", (c) => (out += c));
+    child.on("error", reject);
+    child.on("close", () => {
+      const [w, h] = out.trim().split(",").map(Number);
+      resolve({ w, h });
+    });
+  });
+}
+
+function dist(buf, frameSize, a, b) {
+  let sum = 0;
+  const ao = a * frameSize;
+  const bo = b * frameSize;
+  for (let p = 0; p < frameSize; p++) sum += Math.abs(buf[ao + p] - buf[bo + p]);
+  return sum / frameSize;
+}
+
+function peakBetween(buf, frameSize, i, k, change) {
+  let peak = -1;
+  let peakD = change;
+  for (let j = i + 1; j < k; j++) {
+    const d = Math.min(dist(buf, frameSize, i, j), dist(buf, frameSize, j, k));
+    if (d > peakD) {
+      peak = j;
+      peakD = d;
+    }
+  }
+  return { peak, delta: peakD };
+}
+
+// fallow-ignore-next-line complexity
+export function findReversions(buf, frameSize, { window, change, same }) {
+  const count = Math.floor(buf.length / frameSize);
+  const byPeak = new Map();
+  for (let i = 0; i < count; i++) {
+    for (let k = i + 2; k <= Math.min(count - 1, i + window); k++) {
+      if (dist(buf, frameSize, i, k) > same) continue;
+      const { peak, delta } = peakBetween(buf, frameSize, i, k, change);
+      const known = byPeak.get(peak);
+      if (peak >= 0 && (!known || known.delta < delta)) {
+        byPeak.set(peak, { from: i, changed: peak, back: k, delta });
+      }
+    }
+  }
+  return [...byPeak.values()].sort((x, y) => x.changed - y.changed);
+}
+
+function parseArgs(argv) {
+  const paths = [];
+  for (const arg of argv) {
+    const m = /^--(crop|window|change|same)=(.*)$/.exec(arg);
+    if (m) args[m[1]] = m[1] === "crop" ? m[2] : Number(m[2]);
+    else paths.push(arg);
+  }
+  return paths;
+}
+
+// fallow-ignore-next-line complexity
+async function checkVideo(path) {
+  const size = await probeSize(path);
+  const [cw, ch] = args.crop ? args.crop.split(":").map(Number) : [size.w, size.h];
+  const frameSize = WIDTH * 2 * Math.round((WIDTH * (ch / cw)) / 2);
+  const buf = await readFrames(path, args.crop);
+  const frames = Math.floor(buf.length / frameSize);
+  const hits = findReversions(buf, frameSize, args);
+  const crop = args.crop ? `  crop=${args.crop}` : "";
+  console.log(
+    `${hits.length ? "FLAGGED" : "clean"}  ${path}${crop}  (${frames} frames checked, 0-${frames - 1})`,
+  );
+  for (const h of hits) {
+    console.log(
+      `  frame ${h.changed} differs (mean diff ${h.delta.toFixed(2)}) between frame ${h.from} and frame ${h.back}, which match`,
+    );
+  }
+  return hits.length > 0;
+}
+
+// fallow-ignore-next-line complexity
+async function main(argv) {
+  const paths = parseArgs(argv);
+  if (paths.length === 0) {
+    console.error(
+      "usage: node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] [--window=N] [--change=D] [--same=D] <video> ...",
+    );
+    process.exit(2);
+  }
+  let flagged = false;
+  for (const path of paths) flagged = (await checkVideo(path)) || flagged;
+  process.exit(flagged ? 1 : 0);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
diff --git a/scripts/check-capture-reversion.test.mjs b/scripts/check-capture-reversion.test.mjs
new file mode 100644
index 0000000000..5c8b5e0090
--- /dev/null
+++ b/scripts/check-capture-reversion.test.mjs
@@ -0,0 +1,32 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+
+import { findReversions } from "./check-capture-reversion.mjs";
+
+const OPTS = { window: 20, change: 1, same: 0.25 };
+const SIZE = 4;
+
+function frames(...levels) {
+  return Buffer.concat(levels.map((v) => Buffer.alloc(SIZE, v)));
+}
+
+test("a region that returns to an earlier picture is flagged at the changed frame", () => {
+  const hits = findReversions(frames(10, 10, 200, 10, 10), SIZE, OPTS);
+  assert.deepEqual(
+    hits.map((h) => [h.from, h.changed, h.back]),
+    [[0, 2, 3]],
+  );
+});
+
+test("a change that stays is not a reversion", () => {
+  assert.deepEqual(findReversions(frames(10, 10, 200, 200, 200), SIZE, OPTS), []);
+});
+
+test("continuous motion never returns to an earlier picture", () => {
+  assert.deepEqual(findReversions(frames(10, 30, 50, 70, 90), SIZE, OPTS), []);
+});
+
+test("a return further away than the window is ignored", () => {
+  const far = frames(10, 200, 10);
+  assert.deepEqual(findReversions(far, SIZE, { ...OPTS, window: 1 }), []);
+});

From d2855252c18aac07c9a1e9c149a30d6e757da94a Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 05:18:19 -0400
Subject: [PATCH 2/7] refactor(scripts): skip the size probe when a crop is
 given

Also replaces a stale comment on probeSize that contradicted the code.
---
 scripts/check-capture-reversion.mjs | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/scripts/check-capture-reversion.mjs b/scripts/check-capture-reversion.mjs
index aaf493a724..6abe2fdd8a 100644
--- a/scripts/check-capture-reversion.mjs
+++ b/scripts/check-capture-reversion.mjs
@@ -26,9 +26,7 @@ function readFrames(path, crop) {
   });
 }
 
-// The frame height depends on the crop aspect; probe it from the buffer size
-// by asking ffprobe would add a dependency, so derive it from the crop or the
-// video's own size.
+// Source video size, used to derive the output frame height when no crop is given.
 function probeSize(path) {
   return new Promise((resolve, reject) => {
     const child = spawn("ffprobe", [
@@ -102,8 +100,9 @@ function parseArgs(argv) {
 
 // fallow-ignore-next-line complexity
 async function checkVideo(path) {
-  const size = await probeSize(path);
-  const [cw, ch] = args.crop ? args.crop.split(":").map(Number) : [size.w, size.h];
+  const [cw, ch] = args.crop
+    ? args.crop.split(":").map(Number)
+    : Object.values(await probeSize(path));
   const frameSize = WIDTH * 2 * Math.round((WIDTH * (ch / cw)) / 2);
   const buf = await readFrames(path, args.crop);
   const frames = Math.floor(buf.length / frameSize);

From d9972db407cb83d6cf2078ba7ab5ebc6c1a9bbf1 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 05:33:12 -0400
Subject: [PATCH 3/7] fix(scripts): the capture checker exits 2 when it cannot
 check

A bad option, a missing binary or file, or an undecodable video used to
read as clean or crash with exit 1, which the caller cannot tell from a
flagged capture. Options are now validated, the frame height is passed
to ffmpeg explicitly so it always matches the size the check assumes,
and the tests pin the thresholds, window boundary, ordering and mean.
---
 CONTRIBUTING.md                          |  2 +-
 scripts/check-capture-reversion.mjs      | 74 +++++++++++++++---------
 scripts/check-capture-reversion.test.mjs | 48 ++++++++++++++-
 3 files changed, 95 insertions(+), 29 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 53ed8631ba..69d8752311 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -149,7 +149,7 @@ The script wipes `docs/catalog/` before regenerating, so deleted items are autom
 
 ### Checking a capture
 
-A screen recording attached to a PR must not show a region briefly returning to an older picture (a clip that reappears for one frame, a panel that flashes its previous state). Run `node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] <video>...` once per region that matters; it needs `ffmpeg` and `ffprobe`, exits 1 on a flagged video, and names the frames that differ and the two matching frames around them. Continuous motion is not flagged, but a toast or cursor inside the crop can be, so crop it out or check the named frames by eye.
+A screen recording attached to a PR must not show a region briefly returning to an older picture (a clip that reappears for one frame, a panel that flashes its previous state). Run `node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] <video>...` once per region that matters; it needs `ffmpeg` (and `ffprobe` when no `--crop` is given), takes `--window`, `--change` and `--same` to tune the match, exits 0 when clean, 1 when a video is flagged and 2 when it could not check (bad option, missing binary or file), and names the frames that differ and the two matching frames around them. Continuous motion is not flagged, but a toast or cursor inside the crop can be, so crop it out or check the named frames by eye.
 
 ## Packages
 
diff --git a/scripts/check-capture-reversion.mjs b/scripts/check-capture-reversion.mjs
index 6abe2fdd8a..1b2e39c80b 100644
--- a/scripts/check-capture-reversion.mjs
+++ b/scripts/check-capture-reversion.mjs
@@ -1,17 +1,23 @@
 #!/usr/bin/env node
 // Flags a capture region that briefly returns to an older picture (A, B, A frames).
 // node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] [--window=N] [--change=D] [--same=D] <video>...
-// Frames are cropped, 96px wide, gray; D is mean abs pixel diff (0-255). Exit 1 if flagged.
+// Frames are cropped, 96px wide, gray; D is mean abs pixel diff (0-255). Exit 0 clean, 1 flagged, 2 could not check.
 
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 const WIDTH = 96;
-const args = { crop: undefined, window: 20, change: 1.0, same: 0.25 };
+const USAGE =
+  "usage: node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] [--window=N] [--change=D] [--same=D] <video> ...";
 
-function readFrames(path, crop) {
+/** Output frame height for a source of cw x ch scaled to WIDTH: even, at least 2. */
+export function frameHeight(cw, ch) {
+  return Math.max(2, 2 * Math.round((WIDTH * (ch / cw)) / 2));
+}
+
+function readFrames(path, crop, height) {
   return new Promise((resolve, reject) => {
-    const scale = `scale=${WIDTH}:-2:flags=area,format=gray`;
+    const scale = `scale=${WIDTH}:${height}:flags=area,format=gray`;
     const vf = crop ? `crop=${crop},${scale}` : scale;
     const child = spawn("ffmpeg", ["-v", "error", "-i", path, "-vf", vf, "-f", "rawvideo", "-"]);
     const chunks = [];
@@ -43,9 +49,10 @@ function probeSize(path) {
     let out = "";
     child.stdout.on("data", (c) => (out += c));
     child.on("error", reject);
-    child.on("close", () => {
+    child.on("close", (code) => {
       const [w, h] = out.trim().split(",").map(Number);
-      resolve({ w, h });
+      if (code !== 0 || !(w > 0) || !(h > 0)) return reject(new Error(`ffprobe found no video size in ${path}`));
+      resolve([w, h]);
     });
   });
 }
@@ -88,26 +95,39 @@ export function findReversions(buf, frameSize, { window, change, same }) {
   return [...byPeak.values()].sort((x, y) => x.changed - y.changed);
 }
 
-function parseArgs(argv) {
+/** Options and video paths from argv; throws on a malformed flag so a typo cannot read as "clean". */
+export function parseArgs(argv) {
+  const options = { crop: undefined, window: 20, change: 1.0, same: 0.25 };
   const paths = [];
   for (const arg of argv) {
-    const m = /^--(crop|window|change|same)=(.*)$/.exec(arg);
-    if (m) args[m[1]] = m[1] === "crop" ? m[2] : Number(m[2]);
-    else paths.push(arg);
+    const m = /^--([a-z]+)=(.*)$/.exec(arg);
+    if (!m) {
+      if (arg.startsWith("--")) throw new Error(`unknown option ${arg}`);
+      paths.push(arg);
+    } else if (m[1] === "crop") {
+      if (!/^[1-9]\d*:[1-9]\d*:\d+:\d+$/.test(m[2])) throw new Error(`--crop needs W:H:X:Y, got ${m[2]}`);
+      options.crop = m[2];
+    } else if (m[1] in options) {
+      const n = Number(m[2]);
+      if (m[2] === "" || !Number.isFinite(n) || n < 0) throw new Error(`--${m[1]} needs a number, got ${m[2]}`);
+      options[m[1]] = n;
+    } else {
+      throw new Error(`unknown option ${arg}`);
+    }
   }
-  return paths;
+  return { options, paths };
 }
 
 // fallow-ignore-next-line complexity
-async function checkVideo(path) {
-  const [cw, ch] = args.crop
-    ? args.crop.split(":").map(Number)
-    : Object.values(await probeSize(path));
-  const frameSize = WIDTH * 2 * Math.round((WIDTH * (ch / cw)) / 2);
-  const buf = await readFrames(path, args.crop);
+async function checkVideo(path, options) {
+  const [cw, ch] = options.crop ? options.crop.split(":").map(Number) : await probeSize(path);
+  const height = frameHeight(cw, ch);
+  const frameSize = WIDTH * height;
+  const buf = await readFrames(path, options.crop, height);
   const frames = Math.floor(buf.length / frameSize);
-  const hits = findReversions(buf, frameSize, args);
-  const crop = args.crop ? `  crop=${args.crop}` : "";
+  if (frames === 0) throw new Error(`no frames decoded from ${path}`);
+  const hits = findReversions(buf, frameSize, options);
+  const crop = options.crop ? `  crop=${options.crop}` : "";
   console.log(
     `${hits.length ? "FLAGGED" : "clean"}  ${path}${crop}  (${frames} frames checked, 0-${frames - 1})`,
   );
@@ -121,16 +141,16 @@ async function checkVideo(path) {
 
 // fallow-ignore-next-line complexity
 async function main(argv) {
-  const paths = parseArgs(argv);
-  if (paths.length === 0) {
-    console.error(
-      "usage: node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] [--window=N] [--change=D] [--same=D] <video> ...",
-    );
+  try {
+    const { options, paths } = parseArgs(argv);
+    if (paths.length === 0) throw new Error(USAGE);
+    let flagged = false;
+    for (const path of paths) flagged = (await checkVideo(path, options)) || flagged;
+    process.exit(flagged ? 1 : 0);
+  } catch (error) {
+    console.error(`check-capture-reversion: ${error.message}`);
     process.exit(2);
   }
-  let flagged = false;
-  for (const path of paths) flagged = (await checkVideo(path)) || flagged;
-  process.exit(flagged ? 1 : 0);
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
diff --git a/scripts/check-capture-reversion.test.mjs b/scripts/check-capture-reversion.test.mjs
index 5c8b5e0090..5d01f60fd1 100644
--- a/scripts/check-capture-reversion.test.mjs
+++ b/scripts/check-capture-reversion.test.mjs
@@ -1,7 +1,7 @@
 import { strict as assert } from "node:assert";
 import { test } from "node:test";
 
-import { findReversions } from "./check-capture-reversion.mjs";
+import { findReversions, frameHeight, parseArgs } from "./check-capture-reversion.mjs";
 
 const OPTS = { window: 20, change: 1, same: 0.25 };
 const SIZE = 4;
@@ -30,3 +30,49 @@ test("a return further away than the window is ignored", () => {
   const far = frames(10, 200, 10);
   assert.deepEqual(findReversions(far, SIZE, { ...OPTS, window: 1 }), []);
 });
+
+test("the window boundary is inclusive", () => {
+  const hits = findReversions(frames(10, 200, 10), SIZE, { ...OPTS, window: 2 });
+  assert.equal(hits.length, 1);
+});
+
+test("a change below the threshold is not flagged, one above it is", () => {
+  assert.deepEqual(findReversions(frames(10, 11, 10), SIZE, { ...OPTS, change: 1 }), []);
+  assert.equal(findReversions(frames(10, 12, 10), SIZE, { ...OPTS, change: 1 }).length, 1);
+});
+
+test("a middle frame that matches only one side is not a reversion", () => {
+  assert.deepEqual(findReversions(frames(10, 10, 10, 200), SIZE, OPTS), []);
+});
+
+test("hits come back ordered by the changed frame", () => {
+  const hits = findReversions(frames(10, 200, 10, 10, 90, 10), SIZE, OPTS);
+  assert.deepEqual(
+    hits.map((h) => h.changed),
+    [1, 4],
+  );
+});
+
+test("the reported delta is the mean difference, not the sum", () => {
+  const [hit] = findReversions(frames(10, 110, 10), SIZE, OPTS);
+  assert.equal(hit.delta, 100);
+});
+
+test("frame height is even and never below 2", () => {
+  assert.equal(frameHeight(1280, 200), 16);
+  assert.equal(frameHeight(1280, 800), 60);
+  assert.equal(frameHeight(1000, 2), 2);
+});
+
+test("a malformed option throws instead of reading as clean", () => {
+  for (const bad of ["--crop=iw:200:0:0", "--window=abc", "--change=", "--same=-1", "--crp=1:1:0:0"]) {
+    assert.throws(() => parseArgs([bad, "v.webm"]), bad);
+  }
+});
+
+test("options and paths are separated", () => {
+  const { options, paths } = parseArgs(["--crop=1280:200:0:600", "--window=5", "a.webm", "b.webm"]);
+  assert.deepEqual(paths, ["a.webm", "b.webm"]);
+  assert.equal(options.crop, "1280:200:0:600");
+  assert.equal(options.window, 5);
+});

From 7874f242de20c187a772719584baaa5ab57d724f Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 05:52:57 -0400
Subject: [PATCH 4/7] fix(scripts): the capture checker runs when invoked
 through a symlink

The entry-point guard compared argv[1] with a realpath, so a symlinked
path (macOS /tmp) skipped main and exited 0 with no output. It now
compares realpaths, checks every video before exiting with the most
severe code, and the tests drive the real CLI for exit 0, 1 and 2.
---
 scripts/check-capture-reversion.mjs      | 28 ++++++---
 scripts/check-capture-reversion.test.mjs | 74 +++++++++++++++++++++++-
 2 files changed, 91 insertions(+), 11 deletions(-)

diff --git a/scripts/check-capture-reversion.mjs b/scripts/check-capture-reversion.mjs
index 1b2e39c80b..74a63e7cc7 100644
--- a/scripts/check-capture-reversion.mjs
+++ b/scripts/check-capture-reversion.mjs
@@ -4,6 +4,7 @@
 // Frames are cropped, 96px wide, gray; D is mean abs pixel diff (0-255). Exit 0 clean, 1 flagged, 2 could not check.
 
 import { spawn } from "node:child_process";
+import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 const WIDTH = 96;
@@ -51,7 +52,8 @@ function probeSize(path) {
     child.on("error", reject);
     child.on("close", (code) => {
       const [w, h] = out.trim().split(",").map(Number);
-      if (code !== 0 || !(w > 0) || !(h > 0)) return reject(new Error(`ffprobe found no video size in ${path}`));
+      if (code !== 0 || !(w > 0) || !(h > 0))
+        return reject(new Error(`ffprobe found no video size in ${path}`));
       resolve([w, h]);
     });
   });
@@ -105,11 +107,13 @@ export function parseArgs(argv) {
       if (arg.startsWith("--")) throw new Error(`unknown option ${arg}`);
       paths.push(arg);
     } else if (m[1] === "crop") {
-      if (!/^[1-9]\d*:[1-9]\d*:\d+:\d+$/.test(m[2])) throw new Error(`--crop needs W:H:X:Y, got ${m[2]}`);
+      if (!/^[1-9]\d*:[1-9]\d*:\d+:\d+$/.test(m[2]))
+        throw new Error(`--crop needs W:H:X:Y, got ${m[2]}`);
       options.crop = m[2];
     } else if (m[1] in options) {
       const n = Number(m[2]);
-      if (m[2] === "" || !Number.isFinite(n) || n < 0) throw new Error(`--${m[1]} needs a number, got ${m[2]}`);
+      if (m[2] === "" || !Number.isFinite(n) || n < 0)
+        throw new Error(`--${m[1]} needs a number, got ${m[2]}`);
       options[m[1]] = n;
     } else {
       throw new Error(`unknown option ${arg}`);
@@ -139,18 +143,26 @@ async function checkVideo(path, options) {
   return hits.length > 0;
 }
 
+/** Checks every video; 2 if any could not be checked, else 1 if any is flagged, else 0. */
 // fallow-ignore-next-line complexity
 async function main(argv) {
+  let code = 0;
   try {
     const { options, paths } = parseArgs(argv);
     if (paths.length === 0) throw new Error(USAGE);
-    let flagged = false;
-    for (const path of paths) flagged = (await checkVideo(path, options)) || flagged;
-    process.exit(flagged ? 1 : 0);
+    for (const path of paths) {
+      try {
+        if (await checkVideo(path, options)) code = Math.max(code, 1);
+      } catch (error) {
+        console.error(`check-capture-reversion: ${error.message}`);
+        code = 2;
+      }
+    }
   } catch (error) {
     console.error(`check-capture-reversion: ${error.message}`);
-    process.exit(2);
+    code = 2;
   }
+  process.exit(code);
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
+if (realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
diff --git a/scripts/check-capture-reversion.test.mjs b/scripts/check-capture-reversion.test.mjs
index 5d01f60fd1..2b02727745 100644
--- a/scripts/check-capture-reversion.test.mjs
+++ b/scripts/check-capture-reversion.test.mjs
@@ -1,4 +1,9 @@
 import { strict as assert } from "node:assert";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { test } from "node:test";
 
 import { findReversions, frameHeight, parseArgs } from "./check-capture-reversion.mjs";
@@ -46,10 +51,10 @@ test("a middle frame that matches only one side is not a reversion", () => {
 });
 
 test("hits come back ordered by the changed frame", () => {
-  const hits = findReversions(frames(10, 200, 10, 10, 90, 10), SIZE, OPTS);
+  const hits = findReversions(frames(60, 10, 60, 10, 200, 60, 10), SIZE, OPTS);
   assert.deepEqual(
     hits.map((h) => h.changed),
-    [1, 4],
+    [1, 2, 4],
   );
 });
 
@@ -65,7 +70,13 @@ test("frame height is even and never below 2", () => {
 });
 
 test("a malformed option throws instead of reading as clean", () => {
-  for (const bad of ["--crop=iw:200:0:0", "--window=abc", "--change=", "--same=-1", "--crp=1:1:0:0"]) {
+  for (const bad of [
+    "--crop=iw:200:0:0",
+    "--window=abc",
+    "--change=",
+    "--same=-1",
+    "--crp=1:1:0:0",
+  ]) {
     assert.throws(() => parseArgs([bad, "v.webm"]), bad);
   }
 });
@@ -76,3 +87,60 @@ test("options and paths are separated", () => {
   assert.equal(options.crop, "1280:200:0:600");
   assert.equal(options.window, 5);
 });
+
+const SCRIPT = fileURLToPath(new URL("./check-capture-reversion.mjs", import.meta.url));
+const hasFfmpeg = spawnSync("ffmpeg", ["-version"]).status === 0;
+
+function run(script, ...args) {
+  return spawnSync(process.execPath, [script, ...args], { encoding: "utf8" });
+}
+
+function makeClip(dir, name, filter) {
+  const path = join(dir, name);
+  const r = spawnSync("ffmpeg", [
+    "-v",
+    "error",
+    "-y",
+    "-f",
+    "lavfi",
+    "-i",
+    filter,
+    "-frames:v",
+    "6",
+    path,
+  ]);
+  assert.equal(r.status, 0, String(r.stderr));
+  return path;
+}
+
+test("the CLI exits 2 with no videos, even when run through a symlink", () => {
+  const dir = mkdtempSync(join(tmpdir(), "reversion-"));
+  const link = join(dir, "check.mjs");
+  symlinkSync(SCRIPT, link);
+  for (const script of [SCRIPT, link]) {
+    const r = run(script);
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /usage/);
+  }
+});
+
+test(
+  "the CLI exits 0 clean, 1 flagged, 2 unreadable, and keeps going past a bad file",
+  { skip: !hasFfmpeg },
+  () => {
+    const dir = mkdtempSync(join(tmpdir(), "reversion-"));
+    const still = makeClip(dir, "still.mp4", "color=c=black:s=64x64:r=10");
+    const blink = makeClip(
+      dir,
+      "blink.mp4",
+      "color=c=black:s=64x64:r=10,drawbox=x=0:y=0:w=64:h=64:c=white:t=fill:enable='between(n,2,2)'",
+    );
+    assert.equal(run(SCRIPT, still).status, 0);
+    const flagged = run(SCRIPT, blink);
+    assert.equal(flagged.status, 1);
+    assert.match(flagged.stdout, /FLAGGED/);
+    const mixed = run(SCRIPT, blink, join(dir, "missing.mp4"), still);
+    assert.equal(mixed.status, 2);
+    assert.match(mixed.stdout, /FLAGGED[\s\S]*clean/);
+  },
+);

From 97a197115497f3f5d76350cfd113446f9efd9102 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 05:56:56 -0400
Subject: [PATCH 5/7] fix(scripts): the capture checker fails after a time
 limit instead of spinning

A crop only two pixels tall made the assumed frame size zero, so the
comparison loop never ended. A non-positive frame size now throws, and
each video has a wall-clock limit (default 120s, --timeout) covering the
ffmpeg decode and the comparison; hitting it exits 2.
---
 CONTRIBUTING.md                          |  2 +-
 scripts/check-capture-reversion.mjs      | 31 ++++++++++++++++++------
 scripts/check-capture-reversion.test.mjs | 14 +++++++++++
 3 files changed, 39 insertions(+), 8 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 69d8752311..520a269423 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -149,7 +149,7 @@ The script wipes `docs/catalog/` before regenerating, so deleted items are autom
 
 ### Checking a capture
 
-A screen recording attached to a PR must not show a region briefly returning to an older picture (a clip that reappears for one frame, a panel that flashes its previous state). Run `node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] <video>...` once per region that matters; it needs `ffmpeg` (and `ffprobe` when no `--crop` is given), takes `--window`, `--change` and `--same` to tune the match, exits 0 when clean, 1 when a video is flagged and 2 when it could not check (bad option, missing binary or file), and names the frames that differ and the two matching frames around them. Continuous motion is not flagged, but a toast or cursor inside the crop can be, so crop it out or check the named frames by eye.
+A screen recording attached to a PR must not show a region briefly returning to an older picture (a clip that reappears for one frame, a panel that flashes its previous state). Run `node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] <video>...` once per region that matters; it needs `ffmpeg` (and `ffprobe` when no `--crop` is given), takes `--window`, `--change` and `--same` to tune the match and `--timeout=S` (default 120) to bound each video, exits 0 when clean, 1 when a video is flagged and 2 when it could not check (bad option, missing binary or file), and names the frames that differ and the two matching frames around them. Continuous motion is not flagged, but a toast or cursor inside the crop can be, so crop it out or check the named frames by eye.
 
 ## Packages
 
diff --git a/scripts/check-capture-reversion.mjs b/scripts/check-capture-reversion.mjs
index 74a63e7cc7..2bf4fa739e 100644
--- a/scripts/check-capture-reversion.mjs
+++ b/scripts/check-capture-reversion.mjs
@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // Flags a capture region that briefly returns to an older picture (A, B, A frames).
-// node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] [--window=N] [--change=D] [--same=D] <video>...
+// node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] [--window=N] [--change=D] [--same=D] [--timeout=S] <video>...
 // Frames are cropped, 96px wide, gray; D is mean abs pixel diff (0-255). Exit 0 clean, 1 flagged, 2 could not check.
 
 import { spawn } from "node:child_process";
@@ -8,25 +8,31 @@ import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 const WIDTH = 96;
+const DEFAULT_TIMEOUT_S = 120;
 const USAGE =
-  "usage: node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] [--window=N] [--change=D] [--same=D] <video> ...";
+  "usage: node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] [--window=N] [--change=D] [--same=D] [--timeout=S] <video> ...";
 
 /** Output frame height for a source of cw x ch scaled to WIDTH: even, at least 2. */
 export function frameHeight(cw, ch) {
   return Math.max(2, 2 * Math.round((WIDTH * (ch / cw)) / 2));
 }
 
-function readFrames(path, crop, height) {
+function readFrames(path, crop, height, timeoutMs) {
   return new Promise((resolve, reject) => {
     const scale = `scale=${WIDTH}:${height}:flags=area,format=gray`;
     const vf = crop ? `crop=${crop},${scale}` : scale;
     const child = spawn("ffmpeg", ["-v", "error", "-i", path, "-vf", vf, "-f", "rawvideo", "-"]);
     const chunks = [];
     let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error(`ffmpeg did not finish within ${timeoutMs / 1000}s for ${path}`));
+    }, timeoutMs);
     child.stdout.on("data", (c) => chunks.push(c));
     child.stderr.on("data", (c) => (stderr += c));
     child.on("error", reject);
     child.on("close", (code) => {
+      clearTimeout(timer);
       if (code !== 0) return reject(new Error(`ffmpeg exited ${code} for ${path}: ${stderr}`));
       resolve(Buffer.concat(chunks));
     });
@@ -81,10 +87,14 @@ function peakBetween(buf, frameSize, i, k, change) {
 }
 
 // fallow-ignore-next-line complexity
-export function findReversions(buf, frameSize, { window, change, same }) {
+export function findReversions(buf, frameSize, { window, change, same }, deadline = Infinity) {
+  if (!Number.isInteger(frameSize) || frameSize <= 0) {
+    throw new Error(`frame size must be a positive integer, got ${frameSize}`);
+  }
   const count = Math.floor(buf.length / frameSize);
   const byPeak = new Map();
   for (let i = 0; i < count; i++) {
+    if (Date.now() > deadline) throw new Error("comparison did not finish within the time limit");
     for (let k = i + 2; k <= Math.min(count - 1, i + window); k++) {
       if (dist(buf, frameSize, i, k) > same) continue;
       const { peak, delta } = peakBetween(buf, frameSize, i, k, change);
@@ -99,7 +109,13 @@ export function findReversions(buf, frameSize, { window, change, same }) {
 
 /** Options and video paths from argv; throws on a malformed flag so a typo cannot read as "clean". */
 export function parseArgs(argv) {
-  const options = { crop: undefined, window: 20, change: 1.0, same: 0.25 };
+  const options = {
+    crop: undefined,
+    window: 20,
+    change: 1.0,
+    same: 0.25,
+    timeout: DEFAULT_TIMEOUT_S,
+  };
   const paths = [];
   for (const arg of argv) {
     const m = /^--([a-z]+)=(.*)$/.exec(arg);
@@ -127,10 +143,11 @@ async function checkVideo(path, options) {
   const [cw, ch] = options.crop ? options.crop.split(":").map(Number) : await probeSize(path);
   const height = frameHeight(cw, ch);
   const frameSize = WIDTH * height;
-  const buf = await readFrames(path, options.crop, height);
+  const deadline = Date.now() + options.timeout * 1000;
+  const buf = await readFrames(path, options.crop, height, options.timeout * 1000);
   const frames = Math.floor(buf.length / frameSize);
   if (frames === 0) throw new Error(`no frames decoded from ${path}`);
-  const hits = findReversions(buf, frameSize, options);
+  const hits = findReversions(buf, frameSize, options, deadline);
   const crop = options.crop ? `  crop=${options.crop}` : "";
   console.log(
     `${hits.length ? "FLAGGED" : "clean"}  ${path}${crop}  (${frames} frames checked, 0-${frames - 1})`,
diff --git a/scripts/check-capture-reversion.test.mjs b/scripts/check-capture-reversion.test.mjs
index 2b02727745..5d6591928b 100644
--- a/scripts/check-capture-reversion.test.mjs
+++ b/scripts/check-capture-reversion.test.mjs
@@ -144,3 +144,17 @@ test(
     assert.match(mixed.stdout, /FLAGGED[\s\S]*clean/);
   },
 );
+
+test("a zero or fractional frame size throws instead of looping", () => {
+  for (const bad of [0, -4, 1.5, Number.NaN]) {
+    assert.throws(() => findReversions(frames(10, 10, 10), bad, OPTS), /positive integer/);
+  }
+});
+
+test("a comparison past its deadline throws", () => {
+  assert.throws(() => findReversions(frames(10, 200, 10), SIZE, OPTS, 0), /time limit/);
+});
+
+test("--timeout is parsed as seconds", () => {
+  assert.equal(parseArgs(["--timeout=30", "v.webm"]).options.timeout, 30);
+});

From 0dc697044f8befee8d344837c6c0f2873db6f4dd Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 06:32:07 -0400
Subject: [PATCH 6/7] fix(scripts): the capture checker time limit covers every
 step

The limit is now one budget per video shared by ffprobe, ffmpeg and the
comparison, checked on every frame pair so a large --window cannot run
past it. A timed-out tool is killed with its whole process group, so a
shell-wrapper ffmpeg leaves no orphan. --timeout is capped below the
Node timer limit and inherited option names are rejected.
---
 scripts/check-capture-reversion.mjs      | 83 ++++++++++++------------
 scripts/check-capture-reversion.test.mjs | 50 +++++++++++++-
 2 files changed, 92 insertions(+), 41 deletions(-)

diff --git a/scripts/check-capture-reversion.mjs b/scripts/check-capture-reversion.mjs
index 2bf4fa739e..c0e182167c 100644
--- a/scripts/check-capture-reversion.mjs
+++ b/scripts/check-capture-reversion.mjs
@@ -9,6 +9,7 @@ import { fileURLToPath } from "node:url";
 
 const WIDTH = 96;
 const DEFAULT_TIMEOUT_S = 120;
+const MAX_TIMEOUT_S = 86400;
 const USAGE =
   "usage: node scripts/check-capture-reversion.mjs [--crop=W:H:X:Y] [--window=N] [--change=D] [--same=D] [--timeout=S] <video> ...";
 
@@ -17,52 +18,50 @@ export function frameHeight(cw, ch) {
   return Math.max(2, 2 * Math.round((WIDTH * (ch / cw)) / 2));
 }
 
-function readFrames(path, crop, height, timeoutMs) {
+/** Runs a tool to completion, killing its whole process group if it outlives timeoutMs. */
+function runTool(cmd, args, timeoutMs, label) {
   return new Promise((resolve, reject) => {
-    const scale = `scale=${WIDTH}:${height}:flags=area,format=gray`;
-    const vf = crop ? `crop=${crop},${scale}` : scale;
-    const child = spawn("ffmpeg", ["-v", "error", "-i", path, "-vf", vf, "-f", "rawvideo", "-"]);
+    const child = spawn(cmd, args, { detached: process.platform !== "win32" });
     const chunks = [];
     let stderr = "";
     const timer = setTimeout(() => {
-      child.kill();
-      reject(new Error(`ffmpeg did not finish within ${timeoutMs / 1000}s for ${path}`));
+      try {
+        process.kill(process.platform === "win32" ? child.pid : -child.pid);
+      } catch {}
+      reject(new Error(`${cmd} did not finish within ${timeoutMs / 1000}s for ${label}`));
     }, timeoutMs);
     child.stdout.on("data", (c) => chunks.push(c));
     child.stderr.on("data", (c) => (stderr += c));
-    child.on("error", reject);
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
     child.on("close", (code) => {
       clearTimeout(timer);
-      if (code !== 0) return reject(new Error(`ffmpeg exited ${code} for ${path}: ${stderr}`));
-      resolve(Buffer.concat(chunks));
+      if (code === 0) resolve(Buffer.concat(chunks));
+      else reject(new Error(`${cmd} exited ${code} for ${label}: ${stderr}`));
     });
   });
 }
 
-// Source video size, used to derive the output frame height when no crop is given.
-function probeSize(path) {
-  return new Promise((resolve, reject) => {
-    const child = spawn("ffprobe", [
-      "-v",
-      "error",
-      "-select_streams",
-      "v:0",
-      "-show_entries",
-      "stream=width,height",
-      "-of",
-      "csv=p=0",
-      path,
-    ]);
-    let out = "";
-    child.stdout.on("data", (c) => (out += c));
-    child.on("error", reject);
-    child.on("close", (code) => {
-      const [w, h] = out.trim().split(",").map(Number);
-      if (code !== 0 || !(w > 0) || !(h > 0))
-        return reject(new Error(`ffprobe found no video size in ${path}`));
-      resolve([w, h]);
-    });
-  });
+function readFrames(path, crop, height, timeoutMs) {
+  const scale = `scale=${WIDTH}:${height}:flags=area,format=gray`;
+  const vf = crop ? `crop=${crop},${scale}` : scale;
+  return runTool(
+    "ffmpeg",
+    ["-v", "error", "-i", path, "-vf", vf, "-f", "rawvideo", "-"],
+    timeoutMs,
+    path,
+  );
+}
+
+/** Source video size, used to derive the output frame height when no crop is given. */
+async function probeSize(path, timeoutMs) {
+  const args = ["-v", "error", "-select_streams", "v:0", "-show_entries", "stream=width,height"];
+  const out = await runTool("ffprobe", [...args, "-of", "csv=p=0", path], timeoutMs, path);
+  const [w, h] = out.toString().trim().split(",").map(Number);
+  if (!(w > 0) || !(h > 0)) throw new Error(`ffprobe found no video size in ${path}`);
+  return [w, h];
 }
 
 function dist(buf, frameSize, a, b) {
@@ -94,8 +93,8 @@ export function findReversions(buf, frameSize, { window, change, same }, deadlin
   const count = Math.floor(buf.length / frameSize);
   const byPeak = new Map();
   for (let i = 0; i < count; i++) {
-    if (Date.now() > deadline) throw new Error("comparison did not finish within the time limit");
     for (let k = i + 2; k <= Math.min(count - 1, i + window); k++) {
+      if (Date.now() > deadline) throw new Error("comparison did not finish within the time limit");
       if (dist(buf, frameSize, i, k) > same) continue;
       const { peak, delta } = peakBetween(buf, frameSize, i, k, change);
       const known = byPeak.get(peak);
@@ -126,9 +125,9 @@ export function parseArgs(argv) {
       if (!/^[1-9]\d*:[1-9]\d*:\d+:\d+$/.test(m[2]))
         throw new Error(`--crop needs W:H:X:Y, got ${m[2]}`);
       options.crop = m[2];
-    } else if (m[1] in options) {
+    } else if (Object.hasOwn(options, m[1])) {
       const n = Number(m[2]);
-      if (m[2] === "" || !Number.isFinite(n) || n < 0)
+      if (m[2] === "" || !Number.isFinite(n) || n < 0 || (m[1] === "timeout" && n > MAX_TIMEOUT_S))
         throw new Error(`--${m[1]} needs a number, got ${m[2]}`);
       options[m[1]] = n;
     } else {
@@ -140,11 +139,14 @@ export function parseArgs(argv) {
 
 // fallow-ignore-next-line complexity
 async function checkVideo(path, options) {
-  const [cw, ch] = options.crop ? options.crop.split(":").map(Number) : await probeSize(path);
+  const deadline = Date.now() + options.timeout * 1000;
+  const left = () => Math.max(1, deadline - Date.now());
+  const [cw, ch] = options.crop
+    ? options.crop.split(":").map(Number)
+    : await probeSize(path, left());
   const height = frameHeight(cw, ch);
   const frameSize = WIDTH * height;
-  const deadline = Date.now() + options.timeout * 1000;
-  const buf = await readFrames(path, options.crop, height, options.timeout * 1000);
+  const buf = await readFrames(path, options.crop, height, left());
   const frames = Math.floor(buf.length / frameSize);
   if (frames === 0) throw new Error(`no frames decoded from ${path}`);
   const hits = findReversions(buf, frameSize, options, deadline);
@@ -182,4 +184,5 @@ async function main(argv) {
   process.exit(code);
 }
 
-if (realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
+const entry = process.argv[1] && realpathSync(process.argv[1]);
+if (entry === fileURLToPath(import.meta.url)) main(process.argv.slice(2));
diff --git a/scripts/check-capture-reversion.test.mjs b/scripts/check-capture-reversion.test.mjs
index 5d6591928b..b6f9eb5561 100644
--- a/scripts/check-capture-reversion.test.mjs
+++ b/scripts/check-capture-reversion.test.mjs
@@ -1,6 +1,6 @@
 import { strict as assert } from "node:assert";
 import { spawnSync } from "node:child_process";
-import { mkdtempSync, symlinkSync } from "node:fs";
+import { chmodSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -158,3 +158,51 @@ test("a comparison past its deadline throws", () => {
 test("--timeout is parsed as seconds", () => {
   assert.equal(parseArgs(["--timeout=30", "v.webm"]).options.timeout, 30);
 });
+
+test("a comparison that outlives --timeout stops at the deadline, not after the frame", () => {
+  const big = Buffer.alloc(SIZE * 400, 7);
+  const opts = { window: 400, change: 0, same: 255 };
+  const started = Date.now();
+  assert.throws(() => findReversions(big, SIZE, opts, started + 20), /time limit/);
+  assert.ok(Date.now() - started < 2000);
+});
+
+test("--timeout stops a hung ffmpeg or ffprobe wrapper, children included, with exit 2", () => {
+  const dir = mkdtempSync(join(tmpdir(), "reversion-"));
+  for (const tool of ["ffmpeg", "ffprobe"]) {
+    writeFileSync(join(dir, tool), "#!/bin/sh\nsleep 37.31\n");
+    chmodSync(join(dir, tool), 0o755);
+  }
+  const env = { ...process.env, PATH: `${dir}:${process.env.PATH}` };
+  for (const extra of [["--crop=32:32:0:0"], []]) {
+    const started = Date.now();
+    const r = spawnSync(process.execPath, [SCRIPT, "--timeout=1", ...extra, "any.mp4"], {
+      encoding: "utf8",
+      env,
+    });
+    assert.equal(r.status, 2);
+    assert.match(r.stderr, /did not finish within 1s/);
+    assert.ok(Date.now() - started < 10000);
+  }
+  const orphans = spawnSync("pgrep", ["-f", "sleep 37.31"], { encoding: "utf8" });
+  assert.notEqual(orphans.status, 0, `orphaned children: ${orphans.stdout}`);
+});
+
+test("--timeout above the timer limit and inherited option names are rejected", () => {
+  assert.throws(() => parseArgs(["--timeout=1e10", "v.mp4"]));
+  assert.throws(() => parseArgs(["--constructor=5", "v.mp4"]));
+});
+
+test(
+  "a flagged video is not hidden when a later one is missing or an earlier one is",
+  { skip: !hasFfmpeg },
+  () => {
+    const dir = mkdtempSync(join(tmpdir(), "reversion-"));
+    const blink = makeClip(
+      dir,
+      "blink.mp4",
+      "color=c=black:s=64x64:r=10,drawbox=x=0:y=0:w=64:h=64:c=white:t=fill:enable='between(n,2,2)'",
+    );
+    assert.equal(run(SCRIPT, join(dir, "missing.mp4"), blink).status, 2);
+  },
+);

From fe5ac6fee0a1cfc8a6d622c9807422838445a0c6 Mon Sep 17 00:00:00 2001
From: Miguel Angel Simon Sierra <miguel.sierra@heygen.com>
Date: Sat, 19 Sep 2026 06:46:28 -0400
Subject: [PATCH 7/7] fix(scripts): stopping the capture checker also stops its
 ffmpeg

The tool runs in its own process group so a timeout can kill a wrapper
script and its children. That left the child running when the checker
itself got SIGINT or SIGTERM. Live groups are now killed on either
signal, and the checker exits 2.
---
 scripts/check-capture-reversion.mjs      | 20 +++++++++++++++++---
 scripts/check-capture-reversion.test.mjs | 15 ++++++++++++++-
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/scripts/check-capture-reversion.mjs b/scripts/check-capture-reversion.mjs
index c0e182167c..907a7988fd 100644
--- a/scripts/check-capture-reversion.mjs
+++ b/scripts/check-capture-reversion.mjs
@@ -18,25 +18,39 @@ export function frameHeight(cw, ch) {
   return Math.max(2, 2 * Math.round((WIDTH * (ch / cw)) / 2));
 }
 
+const live = new Set();
+const killGroup = (child) => {
+  try {
+    process.kill(process.platform === "win32" ? child.pid : -child.pid);
+  } catch {}
+};
+for (const signal of ["SIGINT", "SIGTERM"]) {
+  process.on(signal, () => {
+    live.forEach(killGroup);
+    process.exit(2);
+  });
+}
+
 /** Runs a tool to completion, killing its whole process group if it outlives timeoutMs. */
 function runTool(cmd, args, timeoutMs, label) {
   return new Promise((resolve, reject) => {
     const child = spawn(cmd, args, { detached: process.platform !== "win32" });
     const chunks = [];
     let stderr = "";
+    live.add(child);
     const timer = setTimeout(() => {
-      try {
-        process.kill(process.platform === "win32" ? child.pid : -child.pid);
-      } catch {}
+      killGroup(child);
       reject(new Error(`${cmd} did not finish within ${timeoutMs / 1000}s for ${label}`));
     }, timeoutMs);
     child.stdout.on("data", (c) => chunks.push(c));
     child.stderr.on("data", (c) => (stderr += c));
     child.on("error", (error) => {
+      live.delete(child);
       clearTimeout(timer);
       reject(error);
     });
     child.on("close", (code) => {
+      live.delete(child);
       clearTimeout(timer);
       if (code === 0) resolve(Buffer.concat(chunks));
       else reject(new Error(`${cmd} exited ${code} for ${label}: ${stderr}`));
diff --git a/scripts/check-capture-reversion.test.mjs b/scripts/check-capture-reversion.test.mjs
index b6f9eb5561..b1d4f7cad1 100644
--- a/scripts/check-capture-reversion.test.mjs
+++ b/scripts/check-capture-reversion.test.mjs
@@ -1,5 +1,5 @@
 import { strict as assert } from "node:assert";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 import { chmodSync, mkdtempSync, symlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -206,3 +206,16 @@ test(
     assert.equal(run(SCRIPT, join(dir, "missing.mp4"), blink).status, 2);
   },
 );
+
+test("SIGTERM to the checker also stops its ffmpeg child", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "reversion-"));
+  writeFileSync(join(dir, "ffmpeg"), "#!/bin/sh\nsleep 41.73\n");
+  chmodSync(join(dir, "ffmpeg"), 0o755);
+  const env = { ...process.env, PATH: `${dir}:${process.env.PATH}` };
+  const child = spawn(process.execPath, [SCRIPT, "--crop=32:32:0:0", "any.mp4"], { env });
+  await new Promise((resolve) => setTimeout(resolve, 1000));
+  child.kill("SIGTERM");
+  await new Promise((resolve) => child.on("close", resolve));
+  const orphans = spawnSync("pgrep", ["-f", "sleep 41.73"], { encoding: "utf8" });
+  assert.notEqual(orphans.status, 0, `orphaned children: ${orphans.stdout}`);
+});