improve: validate per-machine matrix runs in helper script

Co-authored-by: Richie McIlroy <richiemcilroy@users.noreply.github.com>

Author: cursoragent

crates/editor/PLAYBACK-BENCHMARKS.md

@@ -111,6 +111,7 @@ Automated helper for machine runs:
 
 ```bash
 node scripts/run-playback-benchmark-matrix.js --platform macos-13 --gpu apple-silicon --output-dir /tmp/playback-matrix --fps 60 --input-dir /tmp/cap-real-device-tests
+node scripts/run-playback-benchmark-matrix.js --platform windows-11 --gpu nvidia-discrete --output-dir /tmp/playback-matrix-windows-nvidia --fps 60 --require-formats mp4,fragmented --input-dir /tmp/cap-real-device-tests
 ```
 
 | Platform | GPU Class | MP4 Full | Fragmented Full | MP4 Scrub | Fragmented Scrub | Notes |

crates/editor/PLAYBACK-FINDINGS.md

@@ -182,6 +182,7 @@ cargo run -p cap-recording --example playback-test-runner -- full
 10. **Added matrix run helper for platform/GPU benchmark execution (2026-02-13)**
    - `scripts/run-playback-benchmark-matrix.js` runs `full` and `scrub` scenarios with tagged notes and JSON output.
    - Automatically generates aggregate markdown for each machine run directory.
+   - Performs per-machine post-run validation for required scenarios and optional format requirements.
 
 11. **Added matrix completeness validator (2026-02-13)**
    - `scripts/validate-playback-matrix.js` validates required platform/gpu/scenario cells.

crates/editor/PLAYBACK-MATRIX-RUNBOOK.md

@@ -43,13 +43,14 @@ node scripts/run-playback-benchmark-matrix.js \
   --gpu "<gpu-label>" \
   --output-dir "$OUT_DIR" \
   --fps 60 \
+  --require-formats mp4,fragmented \
   --input-dir "$INPUT_DIR"
 ```
 
 Equivalent shortcut:
 
 ```bash
-pnpm bench:playback:matrix -- --platform "<platform-label>" --gpu "<gpu-label>" --output-dir "$OUT_DIR" --fps 60 --input-dir "$INPUT_DIR"
+pnpm bench:playback:matrix -- --platform "<platform-label>" --gpu "<gpu-label>" --output-dir "$OUT_DIR" --fps 60 --require-formats mp4,fragmented --input-dir "$INPUT_DIR"
 ```
 
 Examples:

scripts/run-playback-benchmark-matrix.js

@@ -12,6 +12,8 @@ function parseArgs(argv) {
 		fps: 60,
 		recordingPath: null,
 		inputDir: null,
+		validate: true,
+		requireFormats: [],
 	};
 
 	for (let i = 2; i < argv.length; i++) {
@@ -51,14 +53,26 @@ function parseArgs(argv) {
 			options.inputDir = argv[++i] ?? null;
 			continue;
 		}
+		if (arg === "--skip-validate") {
+			options.validate = false;
+			continue;
+		}
+		if (arg === "--require-formats") {
+			const value = argv[++i] ?? "";
+			options.requireFormats = value
+				.split(",")
+				.map((entry) => entry.trim().toLowerCase())
+				.filter(Boolean);
+			continue;
+		}
 		throw new Error(`Unknown argument: ${arg}`);
 	}
 
 	return options;
 }
 
 function usage() {
-	console.log(`Usage: node scripts/run-playback-benchmark-matrix.js --platform <name> --gpu <name> --output-dir <dir> [--fps 60] [--recording-path <path>] [--input-dir <path>]
+	console.log(`Usage: node scripts/run-playback-benchmark-matrix.js --platform <name> --gpu <name> --output-dir <dir> [--fps 60] [--recording-path <path>] [--input-dir <path>] [--require-formats mp4,fragmented]
 
 Runs playback benchmark matrix scenarios and writes JSON outputs.
 
@@ -70,7 +84,9 @@ Required:
 Optional:
   --fps           FPS for benchmark runs (default: 60)
   --recording-path  Specific recording path
-  --input-dir       Recording discovery directory`);
+  --input-dir       Recording discovery directory
+  --require-formats Required formats for local validation (comma-separated)
+  --skip-validate   Skip post-run validation`);
 }
 
 function run(command, args) {
@@ -156,6 +172,26 @@ function main() {
 		aggregatePath,
 	]);
 	console.log(`Aggregate markdown: ${aggregatePath}`);
+
+	if (options.validate) {
+		const validateArgs = [
+			"scripts/validate-playback-matrix.js",
+			"--input",
+			options.outputDir,
+			"--no-default-matrix",
+			"--require-cell",
+			`${options.platform}:${options.gpu}:full`,
+			"--require-cell",
+			`${options.platform}:${options.gpu}:scrub`,
+		];
+
+		if (options.requireFormats.length > 0) {
+			validateArgs.push("--require-formats", options.requireFormats.join(","));
+		}
+
+		run("node", validateArgs);
+		console.log("Matrix run validation passed");
+	}
 }
 
 try {