feat: summarize video transitions

[thymikee]

Summary

Add transition summaries for visual frame sequences and recordings via diff frames and diff video.

diff frames accepts a PNG directory or explicit PNG frame paths, while diff video uses external ffmpeg/ffprobe to sample recordings into frames without adding JS dependencies. The summarizer reuses screenshot diff region/OCR hints only on selected transition boundaries, supports gesture telemetry labels such as after tap, and writes keyframe/diff artifacts under --out.

Example from a synthetic Settings-like frame sequence:

Frame transition summary: 1 transition, sampled 5 frames
  Artifacts: /tmp/.../out3

1. 0ms-300ms after tap x=150 y=74
   screen replacement; large center large-area changed
   peak=7.79% avg=6.35% duration=300ms
   changed: large center large-area, 51.08% of diff, mixed
   keyframes: before=/tmp/.../frames/settings-0.png mid=/tmp/.../frames/settings-2.png after=/tmp/.../frames/settings-3.png
   diff: /tmp/.../out3/transition-1.diff.png

diff video prerequisite behavior when FFmpeg is missing:

Error (TOOL_MISSING): diff video requires ffmpeg and ffprobe in PATH
Hint: Install FFmpeg, then retry diff video.

Touched-file count: 10. Scope stayed within the diff/media command family plus docs/skill guidance.

Validation

• pnpm format
• pnpm check:quick
• pnpm vitest run src/utils/__tests__/transition-summary.test.ts src/__tests__/cli-diff.test.ts src/utils/__tests__/cli-option-schema.test.ts
• pnpm test:smoke
• pnpm build
• git diff --check
• Manual synthetic Settings-like pnpm ad diff frames <frames-dir> --out <out-dir> --telemetry <telemetry.json> --threshold 0
• Manual pnpm ad diff video /tmp/missing.mp4 --out /tmp/transition-video-out in an environment without FFmpeg/FFprobe to verify the prerequisite error

Known gap: full pnpm check:unit/all-unit Vitest runs were attempted, but the tool session was terminated before Vitest printed a final summary; targeted unit/CLI tests, smoke tests, typecheck/lint, and build passed.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://callstackincubator.github.io/agent-device/pr-preview/pr-410/
Built to branch gh-pages at 2026-04-13 19:55 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a7e96b9406

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Clear stale frame artifacts before reading extracted frames

When diff video is run with an existing --out directory, this code reads every frame-*.png in that folder after extraction, but the folder is never cleaned first. If a previous run produced more frames than the current run, leftover PNGs are included in files, so transition analysis uses stale frames and reports incorrect timing/content. This is reproducible by running diff video twice against the same output dir with different --max-frames or video lengths.

Useful? React with 👍 / 👎.