perf: improve H264 playback on low-end machines; v1.7.3

docs/H264_PERFORMANCE.md

@@ -0,0 +1,50 @@
+# H.264 playback performance
+
+Use a representative, unmodified MCAP from the target workload rather than only the generated
+`public/examples/test_h264.mcap`. Record its size, duration, H.264 profile/level, resolution, frame
+rate, keyframe interval, and image topic. Do not copy or rewrite the recording for a benchmark.
+
+## Automated Chromium benchmark
+
+Start a production preview (`npm run build && npm run preview`), then run:
+
+```bash
+npm run benchmark:h264 -- \
+  --file /absolute/path/representative.mcap \
+  --base-url http://127.0.0.1:4173 \
+  --duration 60 \
+  --output benchmark-h264.json
+```
+
+The benchmark exposes the original file through a temporary read-only Range/CORS server. It records
+progress updates, random seeks, Image panel H.264 metrics, decode/page/console errors, and Chromium
+JS heap when available. Run `npm run benchmark:h264 -- --help` for all options.
+
+## Manual browser pass
+
+Expose the same original MCAP through a read-only HTTP server with byte Range and CORS support. In
+current stable Chrome, Edge, and Firefox, open
+`http://127.0.0.1:4173/?url=<percent-encoded-mcap-url>`, play for 60 seconds, and seek to three
+non-keyframe positions. Confirm that progress remains responsive, frames resume after each seek, and
+no decode failure appears. Firefox H.264/WebCodecs availability depends on the OS codec stack; record
+an unsupported-codec result separately instead of comparing it as a performance regression.
+
+Suggested acceptance targets:
+
+- The E2E smoke test observes at least two progress advances and at least 1 percentage point of
+  movement in about one second.
+- No decode, page, or console errors; Image metrics are non-negative and pressure is `normal`,
+  `degraded`, or `recovery`.
+- The H.264 pending queue is hard-bounded at 120 frames and a 1,000 ms media-time span. Soft
+  pressure keeps a sole complete GOP intact; if either hard bound is exceeded without a newer IDR
+  suffix that fits, the worker keeps the current picture, drops the complete backlog, and waits for
+  the next real IDR rather than decoding a truncated delta chain. Playback must recover after every
+  seek.
+- For a 60-second run, progress updates on at least 50% of 200 ms samples and the longest unexplained
+  stall is below 1 second.
+- After warm-up, JS heap does not grow continuously; investigate growth above 25% or 256 MiB. Treat
+  these as regression gates against a saved baseline, not universal limits.
+
+Record browser/version, OS, CPU, GPU, RAM, display resolution, power mode, hardware acceleration
+setting, cold/warm run, file metadata, and the JSON output. Compare results only on equivalent
+hardware and browser settings.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ioai/rosview",
-  "version": "1.7.2",
+  "version": "1.7.3",
   "description": "High-performance robotics data visualization for MCAP, ROS bag, ROS2 db3, HDF5 and BVH — embeddable React component and standalone SPA",
   "keywords": [
     "ros",
@@ -65,6 +65,7 @@
     "test": "vitest run",
     "preview": "npm run build && vite preview",
     "gen:e2e:fixtures": "node scripts/gen-e2e-fixtures.mjs",
+    "benchmark:h264": "node scripts/benchmark-h264.mjs",
     "pretest:e2e": "npm run gen:e2e:fixtures",
     "test:e2e": "playwright test"
   },