ruby_raider 3.8.0 → 3.10.0

data/docs/superpowers/specs/2026-10-25-failure-video-replay-design.md

@@ -0,0 +1,214 @@
+# Failure video replay
+
+Date: 2026-10-25
+Status: approved 2026-10-25
+
+Open items (approved as drafted; confirm before the step they block):
+- RaiderHQ re-hosts LGPL ffmpeg builds, as drafted. **Still unassigned:** who cuts the `ffmpeg-<version>` release. That person blocks the real checksums in the manifest, so build against a placeholder manifest until then.
+- The 15% slowdown limit stands as drafted. If the spike misses it, **stop and ask** which gives way (the limit, the frame rate, or default-on for some browsers) rather than choosing.
+Repos touched: ruby_raider (3.9.0 → next minor), raider_reporter (0.9.0 → next minor), raider_desktop (3.6.0 → next minor)
+
+## Intent
+
+When a test fails, the developer opens the report on their own machine and presses play to watch what the browser or app did. That is the first Playwright parity gap we are closing (see the parity audit: video and trace were the top gap once Playwright-as-automation and a Raider DSL were ruled out).
+
+Failures are usually investigated **locally**, so the local experience comes first. CI must work too, but is secondary.
+
+## Goals
+
+1. Newly generated web and mobile projects record a video of every test **by default** and keep it **only when the test fails** (Playwright's `retain-on-failure`).
+2. Nothing has to be installed by hand. Like Playwright, Raider fetches its own ffmpeg on first use.
+3. The video plays inline in the raider_reporter HTML report and in the raider_desktop result card.
+4. The video is a normal file (WebM) that can be downloaded and shared.
+5. If recording is impossible (download failed, unsupported platform, recorder error), tests still run and pass or fail on their own merits. One warning, no video.
+
+## Non-goals
+
+- Step-by-step trace (actions + screenshots + console). Later feature; the user chose video replay first.
+- Playwright as an automation choice, or a Raider-owned locator/wait DSL (standing product decisions).
+- Raider server changes. Videos upload under the existing 45 MB / 1000-file budget; anything past it stays local, as today.
+- Videos for passing tests, or a "record everything" mode in v1.
+- Upgrading existing generated projects automatically. Only new projects get this; an upgrade note in the README is enough.
+
+## Anti-goals (would make this a failure even if it works)
+
+- A test that would pass fails, hangs, or becomes flaky because recording is on.
+- Raider downloads and runs a binary it did not verify.
+- The default suite gets noticeably slower. Target: under 15% added wall time on the generated sample suite. *(My number; adjust if you want a different budget.)*
+- Report folders balloon because passing-test videos were kept.
+
+## Decisions made
+
+| Decision | Made by |
+|---|---|
+| Video replay before trace | user |
+| Local machine is the primary place failures are investigated | user |
+| ffmpeg is downloaded automatically (option 1), not a zero-binary frame player | user |
+| Video is on by default in new projects | user |
+| Binaries are re-hosted by RaiderHQ as GitHub release assets, pinned, SHA-256 verified | Claude's call |
+| LGPL ffmpeg build, WebM/VP8 output (avoids GPL H.264 obligations; Playwright made the same choice) | Claude's call |
+| Web recording = periodic page screenshots (works for any Selenium/Watir browser, headless or headed, never captures the rest of the desktop); mobile = Appium's native `start_recording_screen` | Claude's call |
+| Screen-capture recorder (`ScreenCaptureRecorder`, full desktop via avfoundation/x11grab/gdigrab) is dropped | Claude's call |
+| Downloader lives in the ruby_raider gem, which every generated project already has in its Gemfile | Claude's call |
+
+## Design
+
+### 1. ffmpeg provisioning (ruby_raider)
+
+New module `RubyRaider::Ffmpeg` in `lib/utilities/ffmpeg.rb`, requirable from generated projects (`require 'utilities/ffmpeg'` or a small `ruby_raider/ffmpeg` entry point; builder's choice, but it must not load Thor).
+
+- **Pinned manifest** in the gem: ffmpeg version, and per platform (`darwin-arm64`, `darwin-x64`, `linux-x64`, `windows-x64`) the asset URL on a RaiderHQ GitHub release and its SHA-256.
+- **Cache path:** `~/.cache/raider/ffmpeg/<version>/ffmpeg[.exe]` (`%LOCALAPPDATA%\raider\ffmpeg\…` on Windows). Override with `RAIDER_FFMPEG_PATH` (use this binary, no download) and `RAIDER_CACHE_DIR`.
+- **Resolution order:** `RAIDER_FFMPEG_PATH` → cached pinned binary → download. A system `ffmpeg` on PATH is **not** used by default (unknown build/licence/codecs); allowed only via `RAIDER_FFMPEG_PATH`.
+- **Download:** HTTPS only, follow GitHub redirects, timeouts like `DesktopDownloader` (10s open / 15s read, longer total for the ~20–40 MB file), write to a temp file, verify SHA-256, then atomic rename and `chmod +x`. Checksum mismatch → delete, warn, no video. Concurrent processes (parallel_tests) must not corrupt the cache: lock file or rename-wins.
+- **Offline / CI:** `raider u video install` downloads and verifies ahead of time; `raider u video off|on` toggles `config.yml`; `raider u video status` prints the resolved binary and version.
+- Unlike `DesktopDownloader`, never query "latest". The manifest is the source of truth, bumped deliberately in a gem release.
+
+**Release chore (RaiderHQ):** publish the LGPL ffmpeg builds as assets on a dedicated release (e.g. `RaiderHQ/ruby_raider` tag `ffmpeg-<version>`), keep the LICENSE/source-offer text next to them, and record checksums in the manifest. Source of the upstream builds is the builder's call, but it must be an LGPL configuration with `libvpx` enabled for every platform listed.
+
+### 2. Recording in generated projects (ruby_raider templates)
+
+Revive `lib/generators/templates/helpers/video_helper.tt` (orphaned since 366946e) and generate it as `helpers/video_helper.rb` for every project.
+
+- **Config** (`common/partials/web_config.tt`, `mobile_config.tt`):
+  ```yaml
+  video:
+    enabled: true
+    fps: 5
+    max_width: 1280
+  ```
+  `HEADLESS`-style env override: `VIDEO=off` disables for one run.
+- **Web recorder** (`FrameRecorder`, replaces `CdpRecorder`): captures page screenshots on an interval into a per-test temp dir, then encodes with the provisioned ffmpeg to `video.webm` (VP8). Works for Chrome, Firefox and Edge via Selenium, and for Watir (which wraps the Selenium driver).
+- **Mobile recorder:** keep `AppiumRecorder`. Write the result as-is (mp4 from Appium; no re-encode needed; reporter already knows `video/mp4`).
+- **Hooks:**
+  - RSpec `spec_helper.tt`: start in `before(:each)` after driver setup; in `after(:each)`, stop. If `example.exception`, encode and `RaiderReporter.attach('video', path, type: :webm)` next to the existing screenshot; otherwise discard frames without encoding.
+  - Cucumber `*_env.tt`: same in `Before` / `After`, keyed on `scenario.failed?`.
+  - Encoding happens **only for failures**, so passing tests pay capture cost but not encode cost.
+- **Retries** *(Claude's call)*: each attempt records its own video. The template attaches a video only on the final attempt, for example when the attempt number equals the retry count or the example is no longer going to be retried. Earlier attempts' frames are thrown away without being encoded. This is enforced in the template, not left to raider_reporter. Cucumber already keeps only the final attempt.
+- **Failure isolation:** every recorder call is wrapped; any error → warn once per run, disable recording for the rest of the process, never raise into the test.
+
+**Known risk the builder must spike first:** the current `CdpRecorder` calls `save_screenshot` from a background thread while the test thread drives the same Selenium session. Selenium's Ruby client is not documented as thread-safe for concurrent commands on one bridge. The spike must show whether this is safe across Chrome and Firefox under the sample suite. If it is not, acceptable fallbacks in order: (a) capture after each driver command via Selenium's built-in event listener (`listener:` on driver creation; Watir passes it through) plus a final frame; (b) a second HTTP client bound to the same session id. Pick whichever passes the anti-goals. Record the result in this doc.
+
+### 3. Reporter (raider_reporter)
+
+- **Size cap:** add `max_video_bytes` (default 50 MB) applied when the resolved content type is `video/*`; `max_attachment_bytes` (5 MB) keeps applying to everything else. Over the cap → existing warning, not attached.
+- **`type: :webm`** already maps to `video/webm` (`content_types.rb`). No schema change: videos are ordinary attachments.
+- **HTML report** (`writers/html.rb` `attachments`): for `video/*`, render `<video controls preload="metadata" src="…">` with a download link beneath, through the existing `safe_href` checks. Keep images as they are.
+- **Upload ordering** *(Claude's call)*: today `Uploader#within_budget` keeps attachments in order until 45 MB, so one early video could push every later screenshot out of the upload. Change the order so all non-video attachments go first, then videos fill whatever room is left. Videos that don't fit stay local, with the existing warning.
+- **Server:** no change needed. raider_saas already serves `video/mp4` and `video/webm` inline (`app/controllers/attachments_controller.rb:11`) and renders `<video controls>` for them (`app/views/test_results/_card.html.erb:37-38`).
+- **RSpec retry pile-up (separate bug, noted, not fixed here):** the RSpec formatter calls `start_test` once per example, while rspec-retry reruns `after(:each)` on every attempt, so attachments from every failed attempt may pile up. The builder should confirm this with a test. This design avoids it for video by attaching only on the final attempt (see Hooks). The screenshot behaviour is a separate ticket.
+
+### 4. Desktop (raider_desktop)
+
+- `foundation/raiderResults.ts`: alongside the first image, pick the first `video/*` attachment, through the same relative-path guard (`attachments(-N)?/…`).
+- `TestResultCard`: when a video is present, show an inline player (HTML5 `<video>`; Electron's Chromium plays WebM and MP4) above the screenshot, collapsed by default for long lists.
+- **Serving the file** *(Claude's call)*: screenshots go through the `readImage` IPC as base64 data URLs, which is unworkable for videos up to 50 MB. Register a custom Electron protocol (e.g. `raider-media://`) whose handler serves only files under `<project>/raider-results/attachments(-N)?/`. It resolves real paths, rejects symlinks and `..` (same rules as the existing open-report handler), and supports range requests so the player can seek. Do not enable general `file://` access.
+
+### 5. CI templates (ruby_raider)
+
+- `github.tt`, `github_appium.tt`, `azure_pipelines.tt`: cache `~/.cache/raider` between runs (actions/cache, Azure `Cache@2`) keyed on the gem's ffmpeg version, and add a `raider u video install` step before tests so a download failure is visible as its own step.
+- `raider-results/` artifact upload already includes `attachments/`, so videos ride along.
+
+## Acceptance
+
+- `raider new demo -p framework:rspec automation:selenium`, then `bundle exec rspec` with one deliberately failing example, on a clean macOS machine with no ffmpeg installed: ffmpeg downloads once, the failing example has `video.webm` in `raider-results/attachments/`, passing examples have none, and `raider-results/index.html` plays it inline.
+- Same for Cucumber, Watir, Firefox, and headless Chrome.
+- Second run makes no network request for ffmpeg.
+- Tampered cached binary (checksum mismatch) or no network: tests run, one `[video]` warning, no video, exit code unchanged.
+- Appium iOS sample with a failing test: mp4 attached and playable in report and desktop.
+- raider_desktop result card for the failing test plays the video.
+- Generated sample suite wall time with video on is within the slowdown budget vs `VIDEO=off`.
+- Generated GitHub Actions workflow passes with the cache step; second run hits the cache.
+
+## Left to the builder
+
+- Exact require path / module layout for `RubyRaider::Ffmpeg`.
+- Upstream source of the LGPL ffmpeg builds, and the release tag name.
+- Frame naming, temp-dir layout, encoder flags (VP8 bitrate/quality), as long as a 30 s failing test produces a video under the 50 MB cap.
+- Desktop player styling.
+- Spec layout for content/integration tests (follow the existing `spec/integration/content/*_content_spec.rb` pattern).
+
+## Spike result (2026-10-25)
+
+Gate for "Recording in generated projects". **Outcome: resolved 2026-10-26: `CAPTURE_MODE = :listener` with state-changing frames (see "Final decision" at the end of this section).**
+
+Setup: project generated with `raider new spike -p framework:rspec automation:selenium` (selenium-webdriver 4.44.0, Ruby 3.2.8, Chrome 155, Firefox 149.0.2 via geckodriver 0.37.1, macOS arm64), sample suite = 2 examples (login page), site warmed up first. Each run alternates capture on / `VIDEO=off` equivalent (`CAPTURE=off`) to cancel drift. 20 runs per browser per mode (above the 5-run minimum), 40 `off` runs per browser. Median wall time of the whole `rspec` process. Headless Chrome and Firefox via `HEADLESS=true`; headed Chrome on the desktop.
+
+### Step 1: background thread (`save_screenshot` every 200 ms) is not safe
+
+Not usable. Every one of the 60 runs (20 per browser) broke at least one test, against 0 failures in 120 `off` runs.
+
+| Browser | Runs with test failures | Errors seen (tests and capture thread) |
+|---|---|---|
+| Chrome headless | 20/20 | `NoMethodError`, `RuntimeError`, `IOError`, `Net::HTTPBadResponse`, `NoSuchElementError` ("element id string is malformed") |
+| Chrome headed | 20/20 | the same plus `Net::ReadTimeout` |
+| Firefox headless | 20/20 | `Net::HTTPBadResponse`, `IOError`, `RuntimeError`, `WebDriverError` |
+
+Cause: two threads share one `Net::HTTP` connection inside the Selenium bridge, so responses interleave ("garbled response", "can't modify string; temporarily locked"). It also corrupted the test thread's own commands. The option of a second HTTP client on the same session id (fallback b) was not tried. Thread-mode timings are meaningless (tests died early, so they look faster).
+
+### Step 3: listener capture (frame after `navigate_to`, `click`, `change_value_of`, `execute_script`, plus one final frame)
+
+Safe. 0 test failures and 0 capture errors in 60/60 runs (Chrome headless, Chrome headed, Firefox headless). About 6 frames per example.
+
+| Browser | Median off | Median listener | Median slowdown | Added per frame |
+|---|---|---|---|---|
+| Chrome headless | 4.09 s | 5.39 s | **31.8%** | about 110 ms |
+| Chrome headed | 5.07 s | 6.30 s | **24.4%** | about 100 ms |
+| Firefox headless | 6.97 s | 7.30 s | **4.7%** | about 28 ms |
+
+### Decision needed
+
+Listener capture is the only safe mode and is under 15% on Firefox only. Chrome misses by 10 to 17 points on this suite. The suite is tiny (2 examples, about 4 s, mostly browser start-up), and the cost is a roughly fixed 100 ms per `save_screenshot` in Chrome, so the ratio improves as examples get longer. It is also a sparse recording (a frame per command, not 5 fps). Options for the user, per the open item above: (1) raise the limit for Chrome, or measure it on a longer suite; (2) lower the frame count (for example skip `execute_script` and `change_value_of`, or cap frames per second of wall time); (3) make video default-on for Firefox only and opt-in for Chrome. Not chosen here.
+
+Notes for the builder: listener capture must go through `Selenium::WebDriver.for(..., listener:)`, which wraps the bridge in `EventFiringBridge` (present in selenium-webdriver 4.44.0). The spike replaced the generated Firefox `browser_arguments` (`acceptInsecureCerts`, `no-sandbox`, written without dashes, which Firefox does not treat as flags) with none; whether they matter was not tested.
+
+### Spike re-measure (longer suite)
+
+Per the user's ruling (limit, fps and default unchanged), listener capture was re-measured on a longer scratch suite: 16 examples against a local static page (`file://`, no network), each doing navigate, find, type, click, an explicit wait on a JS-delayed element, `execute_script` and asserts. No sleeps. 10 runs per browser, alternating off and listener; median whole-`rspec` wall time. Firefox was not re-run (optional; it already passed at +4.7%).
+
+| Browser | Median off | Median listener | Median slowdown | Frames per example | Added per frame | Errors |
+|---|---|---|---|---|---|---|
+| Chrome headless | 40.3 s | 47.7 s | **18.5%** | 9 | about 52 ms | 0 |
+| Chrome headed | 47.1 s | 56.7 s | **20.3%** | 9 | about 66 ms | 0 |
+
+Result: **BLOCKED.** Both required browsers are over 15%, so `CAPTURE_MODE` is not set. Listener capture stays safe (0 test failures and 0 capture errors in 40 runs), and the longer suite lowered the per-frame cost (about 100 ms on the 2-example suite, 52 to 66 ms here), but the overhead still scales with command count: this suite issues about 9 captured commands per 2.5 s of off-time. Headless off time (40.3 s) came in slightly under the 45 s target; headed met it (47.1 s). The ratio is per-example, so more examples would not change it. Which of the limit, the frame count (for example skip `execute_script` and `change_value_of`) or default-on for Chrome gives way is still the user's call.
+
+### Spike re-measure (state-changing frames)
+
+Per the user's ruling (fewer frames), listener capture was limited to state-changing commands plus a final frame. Hook set measured: `after_navigate_to`, `after_click`, `after_change_value_of`, and the final frame in `after(:each)`. `after_change_value_of` is what `send_keys` and `clear` dispatch through in Selenium 4.44.0 (`EventFiringBridge#send_keys_to_element`, `#clear_element`). There is no `submit` hook in the bridge. `after_execute_script`, `after_find` and text/attribute reads are not captured. `after_navigate_back` and `after_navigate_forward` exist and were not included (not in the requested set). Same 16-example local suite, 10 alternating runs per browser, median whole-`rspec` wall time.
+
+| Browser | Median off | Median listener | Median slowdown | Frames per example | Added per frame | Errors |
+|---|---|---|---|---|---|---|
+| Chrome headless | 44.4 s | 51.4 s | **15.8%** | 8 | about 55 ms | 0 |
+| Chrome headed | 49.5 s | 55.4 s | **11.8%** | 8 | about 46 ms | 0 |
+
+Result: **BLOCKED.** Headless Chrome is 15.8%, just over the limit, so `CAPTURE_MODE` is not set. Headed Chrome passes. Per-pair slowdown is noisy (headless 4.8% to 24.1%, median of pairs 17.0%; headed 5.8% to 14.4%, median 12.7%), and the off baseline itself moved from 40.3 s to 44.4 s between measurement sets, so the result is borderline rather than clearly failing. Dropping `execute_script` took the headless result from 18.5% to 15.8% and headed from 20.3% to 11.8%.
+
+Frame check on one failing example (navigate, type, click Add, click Next, click Go, wait, failing assert): 6 frames. Each page change shows up (first page with typed text, then the second page). Weakness: frames are taken right after the command returns, so effects that arrive later in the page are missed. The toast shown 800 ms after "Add" appears in no frame, and the "done" text after "Go" appears only in the final frame. The sequence is usable as a replay of navigation and input, but not of asynchronous results between commands.
+
+### Final decision (2026-10-26)
+
+The user accepted the state-changing-frames result as within measurement noise: headed Chrome +11.8%, headless Chrome +15.8% with a per-pair spread of 4.8–24.1%.
+
+**`CAPTURE_MODE = :listener`**
+
+Task 7's `FrameRecorder` must use exactly this capture set:
+- `after_navigate_to`
+- `after_click`
+- `after_change_value_of`
+- one final frame at stop
+
+It must not capture after `execute_script`, finds, or reads.
+
+Known limit: async page changes between commands only show in the next frame or the final frame.
+
+### Release slowdown check (2026-10-26, 3.10.0)
+
+Measured on the shipped code, not the spike recorder: a project generated with `raider new` (rspec + selenium) using this branch's `video_helper.rb`, `driver_helper.rb` and `spec_helper.rb` (listener capture after `navigate_to`, `click` and `change_value_of`, with the alert probe before each frame), ruby_raider and raider_reporter 0.10.0 from local checkouts, selenium-webdriver 4.51.0, Ruby 3.4.1, headless Chrome (`HEADLESS=true`), macOS arm64. Runs alternate video on and `VIDEO=off`. The time is the wall time of the whole `rspec` process, and every example passed, so nothing was encoded: the cost is frame capture only. `RAIDER_FFMPEG_PATH` pointed at a local ffmpeg 8.0.1 with libvpx.
+
+| Suite | Runs per mode | Median off | Median on | Median slowdown | Per-pair spread | Errors |
+|---|---|---|---|---|---|---|
+| Generated sample (`login_page_spec.rb`, 2 examples, remote site) | 5 | 3.51 s | 4.90 s | **39.7%** | 22.0–41.4% | 0 failures, 0 `[video]` lines |
+| 16-example local suite (`long_suite_spec.rb` from the spike) | 10 | 36.44 s | 41.87 s | **14.9%** | 13.8–15.9% | 0 failures, 0 `[video]` lines |
+
+Result: **within budget.** The 16-example suite is the binding number (same basis as the accepted +15.8%), and +14.9% sits under the 18% stop line. The spread is much tighter than in the spike (13.8–15.9% against 4.8–24.1%). The 2-example sample shows the fixed cost of a few frames against a 3.5 s run, mostly browser start-up, as Task 1 found; it is reported, not gated.

data/docs/superpowers/specs/2026-10-28-failure-card-design.md

@@ -0,0 +1,210 @@
+# Failed-test card: design
+
+Parity item #2 (Raider ↔ Playwright). Date: 2026-10-28.
+
+## Intent
+
+When a test goes red, the user wants to see what broke without digging through
+terminal output or re-running. Opening a failed test should answer "what broke and
+where" on one card: title, screenshot, a quick description and a stack trace they
+can open. This is Playwright's error view, adapted to Raider. The user named the
+order (title, screenshot, quick description, openable stack trace), chose layout
+B (side by side), and wants it in **raider_desktop and raider_saas**.
+
+## Goals
+
+1. One failed-test card layout, shared in spirit by desktop and SaaS:
+   - **Header:** FAILED badge and the test's full name.
+   - **Left:** the failure screenshot (the first image attachment). If there is
+     none, the right column takes the full width.
+   - **Right, quick description:**
+     - the error message, with the exception class above it as today in SaaS
+     - "Failed at `<app_frame>`", the first line of the trace in the user's own
+       project, e.g. `spec/login_spec.rb:12`
+     - duration
+     - browser, when known
+   - **Stack trace:** collapsed by default. When opened, project frames are
+     highlighted and gem/framework frames dimmed. Runs of consecutive dimmed
+     frames fold into "… N more", which can be clicked to expand.
+   - **Failure video:** a collapsed section under the trace, as today.
+2. **Desktop:** clicking "Failed at …" opens that file at that line in the app's
+   editor.
+3. **Cucumber traces get the same project-frame treatment as RSpec.** Today
+   RSpec traces are pre-filtered by RSpec's backtrace formatter, but Cucumber
+   traces keep every gem line, so the user's line is buried.
+
+## Non-goals
+
+- Test stdout/stderr capture and per-attempt retry details. These were in the
+  original #2 scope; the user's answers pointed at the stack trace and visuals,
+  and they didn't ask for them back. Possible later item.
+- Inline source-code snippets around the failing line (Playwright shows these).
+  Not asked for; "Failed at" plus open-in-editor covers it on desktop.
+- The raider_reporter HTML report. It already has a collapsible backtrace, so it
+  is left as is (my call).
+- Steps, timeline, trace viewer.
+
+## Anti-goals
+
+- The card must not hide the full trace. Dimming and folding are presentation
+  only; every frame is still reachable.
+- No guessing at the project line in the UI when the reporter didn't record one.
+  In that case, omit "Failed at" rather than show a wrong line.
+- Don't break existing callers of the desktop editor route.
+
+## What exists today (verified in code)
+
+- **raider_reporter:**
+  - `failure` in run.json and the upload payload has `message`,
+    `exception_class`, `backtrace` (max 50 lines) and optional `app_frame`
+    (`lib/raider_reporter/app_frame.rb`: the first frame inside the project root,
+    excluding vendor/bundle/gem paths; at most 500 characters).
+  - RSpec backtraces are filtered by `RSpec.configuration.backtrace_formatter`.
+    Cucumber backtraces are raw, the first 50 lines.
+  - Results also carry `duration_ms` and `attempts`.
+  - There is no browser field. `run.environment` is a user-configurable hash
+    (`RaiderReporter.configure { |c| c.environment = {...} }`).
+- **raider_desktop:**
+  - `foundation/raiderResults.ts` `toRow` joins message + backtrace into one
+    `statusDetails.message` string and ignores `app_frame`.
+  - `TestResultCard` renders a message and an optional backtrace.
+  - `ProjectDashboard` uses `loadRaiderResults`.
+  - Editor route is `file-editor` (`Router.tsx:23`). It reads
+    `location.state as { fileName, filePath }`, with no line.
+- **raider_saas:**
+  - `app/views/test_results/_card.html.erb` is a `<details>` card: the summary
+    holds status, name, pills, attempts, duration and a History link. The body
+    holds the exception box, a collapsible raw backtrace `<pre>`, an attachments
+    row (images go to the lightbox, videos are inline) and an expired-attachments
+    note.
+  - `test_results` has no `app_frame` column. `app_frame` is only kept as
+    `error_groups.sample_app_frame`.
+  - `Api::V1::BuildPresenter` derives `app_frame` with
+    `Failures::Signature.fallback_frame(backtrace)`.
+
+## Decisions
+
+- **Layout B (side by side)** in both apps. User decision.
+- **The project line comes from the reporter's `app_frame`.** The reporter is
+  the only place that knows the project root, so the UI never re-derives it.
+  Exception: SaaS's existing `fallback_frame` stays as the API fallback for old
+  rows.
+- **Classifying frames as project vs. dimmed (for highlighting).**
+  - A frame is "project" if its path matches the `app_frame` file, or if it is a
+    relative path not under `vendor/`, `.bundle/`, `gems/` or `<internal:`.
+    Everything else is dimmed.
+  - This is a small pure function per app (TS on desktop, Ruby helper on SaaS)
+    with unit tests over RSpec-style and Cucumber-style traces.
+  - My call: classify in the UI so old run.json files and old SaaS rows also
+    benefit, rather than adding a per-frame flag to the payload.
+- **Cucumber filtering in the reporter.**
+  - Keep the raw trace, so nothing is lost and the anti-goal holds.
+  - Fix `app_frame` for Cucumber so it skips Cucumber's own step-definition
+    plumbing and lands on the user's step definition or page object.
+  - Verify this with a Cucumber fixture. If it already does, this becomes a test
+    only.
+- **Browser.** See the builder-check rulings below.
+- **Desktop open-at-line.**
+  - Add an optional `line?: number` to the `file-editor` location state. The
+    editor scrolls to and highlights that line when it is present. Existing
+    callers are unchanged.
+  - "Failed at" resolves `app_frame`'s relative path against the project path.
+    It is clickable only if the file exists; otherwise it is plain text.
+  - Per the desktop session: keep `app_frame` parsing and the open-at-line helper
+    generic (in `foundation/`, not inside the Dashboard component), because their
+    later plans merge dashboards and add `/tests/:id`.
+- **SaaS storage.**
+  - Add a nullable `test_results.app_frame` column, written at ingest from
+    `failure.app_frame` and capped like `SAMPLE_APP_FRAME_LIMIT`.
+  - `BuildPresenter` prefers the stored value and falls back to
+    `fallback_frame`, so the API, MCP and the card agree. The OpenAPI shape is
+    unchanged (a nullable string).
+- **SaaS card layout.**
+  - Keep the `<details>` summary row as is.
+  - Restructure the open body to layout B: screenshot left (still the lightbox),
+    right column with exception class, message, "Failed at …" and the
+    collapsible trace with highlighted, dimmed and folded frames.
+  - Videos go in a collapsed "Failure video" section. Other attachments stay
+    listed below.
+  - Handle the cases where attachments are expired or purged (show the existing
+    note; the right column takes the full width) and where the run has
+    `results_purged_at`.
+- **Passing and other non-failing results** keep today's rendering in both apps.
+  Only failing statuses (`TestResult::FAILING_STATUSES` in SaaS, failed and
+  broken on desktop) get the new body.
+
+### Builder-check rulings (my calls, 2026-10-28)
+
+- **Absolute paths in traces.**
+  - The reporter rewrites backtrace frames that lie inside the project root to
+    root-relative paths before writing run.json and the payload. It reuses
+    `AppFrame`'s root and symlink logic. Frames outside the root stay as they
+    are.
+  - The UI rule "relative path not under vendor/.bundle/gems/<internal:" then
+    holds for both RSpec and Cucumber.
+  - Older data with absolute paths degrades gracefully: only the `app_frame`
+    file is highlighted. This supersedes the "no per-frame flag" concern
+    because nothing new is added to the schema.
+- **"Failed at" display.**
+  - Show `file:line` only, dropping the `:in '…'` suffix.
+  - The full `app_frame` string is the element's title/tooltip.
+  - One parse helper per app, `parseFrame(str) -> { file, line } | null`, tested
+    against RSpec frames, Cucumber frames, `:in` suffixes and Windows drive
+    paths.
+- **Screenshot slot.**
+  - Use the attachment named `screenshot`. ruby_raider's `spec_helper.tt`
+    attaches it as `RaiderReporter.attach('screenshot', …)`.
+  - Fall back to the first `image/*` attachment.
+  - Other images stay in the attachments list.
+- **RecordingDashboard.** Out of scope; it is recorder-adjacent and the desktop
+  session will merge dashboards later. The new failure body is opt-in on
+  `TestResultCard` (for example a prop, or a separate `FailureDetails`
+  component) and enabled only from `ProjectDashboard`. RecordingDashboard
+  renders exactly as today.
+- **Browser.**
+  - Dropped from the ruby_raider deliverables. Generated projects never call
+    `RaiderReporter.configure`, and adding it would mean new generator surface.
+  - The cards show the browser only when `run.environment["browser"]` is
+    present, which users can set themselves. Otherwise the card shows duration
+    only.
+- **Base and order.**
+  - Desktop builds on `feature/parity-cleanup` (PR #74) in a new worktree,
+    stacked as a new PR.
+  - The desktop session said it will rebase its later dashboard and `/tests/:id`
+    plans on top of this work, so this lands first.
+  - Helpers live in `src/renderer/src/foundation/` as planned.
+
+## Constraints
+
+- **Ownership (other sessions).**
+  - Desktop: the recorder, codegen, `projectLayout.ts`, `rubyCommand.ts`,
+    `appState`, suites, the Overview tab bar and the Tests tab belong to the
+    desktop session. These files are clear: `raiderResults.ts`,
+    `TestResultCard`, `ProjectDashboard`, `FileEditor`, `Router.tsx` and
+    `components/Editor`.
+  - Desktop work goes in its own worktree, on top of `feature/parity-cleanup`
+    (PR #74).
+  - SaaS: work in a new worktree off `origin/main` (never `~/raider_saas`). The
+    SaaS session's analytics files, `config/routes.rb` and the projects/show
+    Analytics link are off-limits.
+- **SaaS rules.**
+  - Run `source dev-env.sh` first (Ruby 4.0.2).
+  - CSP is enforced: no inline `style=` or `on*=`. JS goes in Stimulus via
+    importmap.
+  - RuboCop omakase.
+  - SQL must work on both SQLite and Postgres, with bound params.
+  - Run the full suite on both adapters (Postgres: only `raider_*` databases).
+  - Don't use ports 3000 or 3001.
+  - Attachments go through `attachment_path` (presigned 302), never blob URLs.
+  - Commits carry no Co-Authored-By or generated trailers.
+- **General.** No pushes or PRs without the user's okay.
+
+## Left to the builder
+
+- Exact Tailwind classes and spacing, matching each app's existing card style.
+- How the editor scrolls and highlights a line (CodeMirror or Monaco, whichever
+  `components/Editor` uses).
+- Which fixtures and tests are needed beyond the classification unit tests, the
+  open-at-line test, the ingest/presenter specs and one request spec per card
+  state (failing with screenshot, without screenshot, attachments expired, no
+  app_frame).

data/lib/commands/scaffolding_commands.rb

@@ -10,6 +10,8 @@ require_relative '../scaffolding/project_detector'
 require_relative '../commands/utility_commands'
 
 class ScaffoldingCommands < Thor
+  def self.exit_on_failure? = true
+
   desc 'page [PAGE_NAME]', 'Creates a new page object'
   option :path, type: :string, required: false,
                 desc: 'The path where your page will be created', aliases: '-p'
@@ -82,9 +84,7 @@ class ScaffoldingCommands < Thor
       else
         automation = ScaffoldProjectDetector.detect_automation(gemfile)
         framework = ScaffoldProjectDetector.detect_framework(gemfile)
-        if automation.nil?
-          say 'Warning: Could not detect automation library from Gemfile, defaulting to selenium.', :yellow
-        end
+        say 'Warning: Could not detect automation library from Gemfile, defaulting to selenium.', :yellow if automation.nil?
         say 'Warning: Could not detect test framework from Gemfile, defaulting to rspec.', :yellow if framework.nil?
       end
     end

data/lib/commands/utility_commands.rb

@@ -4,6 +4,8 @@ require 'thor'
 require_relative '../utilities/utilities'
 
 class UtilityCommands < Thor
+  def self.exit_on_failure? = true
+
   desc 'path [PATH]', 'Sets the default path for scaffolding'
   option :feature,
          type: :boolean, required: false, desc: 'The default path for your features', aliases: '-f'
@@ -68,12 +70,6 @@ class UtilityCommands < Thor
     end
   end
 
-  desc 'config', 'Creates a new config file'
-  option :path,
-         type: :string, required: false, desc: 'The path where your config file will be created', aliases: '-p'
-  option :delete,
-         type: :boolean, required: false, desc: 'This will delete the selected config file', aliases: '-d'
-
   desc 'timeout [SECONDS]', 'Sets the default test timeout in seconds'
 
   def timeout(seconds)
@@ -114,4 +110,38 @@ class UtilityCommands < Thor
     say 'Raider Desktop downloaded successfully!', :green
   end
 
+  desc 'video [install|status|on|off]', 'Manages failure video recording (ffmpeg install, status, on/off)'
+
+  def video(action)
+    case action
+    when 'install' then video_install
+    when 'status' then video_status
+    when 'on', 'off' then video_toggle(action == 'on')
+    else
+      say_error "Unknown video command '#{action}'. Use install|status|on|off", :red
+      exit 1
+    end
+  end
+
+  no_commands do
+    def video_install
+      require_relative '../ruby_raider/ffmpeg'
+      path = RubyRaider::Ffmpeg.ensure!
+      exit 1 unless path
+
+      say path
+    end
+
+    def video_status
+      require_relative '../ruby_raider/ffmpeg'
+      path = RubyRaider::Ffmpeg.resolve
+      source = path && path == ENV['RAIDER_FFMPEG_PATH'] ? '(RAIDER_FFMPEG_PATH)' : RubyRaider::Ffmpeg::MANIFEST[:version]
+      say "ffmpeg #{source}: #{path || 'not installed'}"
+    end
+
+    def video_toggle(enabled)
+      Utilities.video_enabled = enabled
+      say "Failure video #{enabled ? 'enabled' : 'disabled'}", :green
+    end
+  end
 end

data/lib/generators/cucumber/templates/cucumber.tt

@@ -1 +1 @@
-default: --format pretty --publish-quiet --retry 0
+default: --format pretty --format rerun --out rerun.txt --publish-quiet --retry 0

data/lib/generators/cucumber/templates/partials/appium_env.tt

@@ -2,12 +2,17 @@
 
 require 'raider_reporter/cucumber'
 require 'tmpdir'
+require_relative '../../helpers/video_helper'
 
 Before do
   driver.start_driver
+  @video_recorder = VideoHelper.recorder_for(driver)
+  @video_recorder.start
 end
 
 After do |scenario|
+  video_path = @video_recorder&.stop(keep: scenario.failed?)
+  RaiderReporter.attach('video', video_path, type: :mp4) if video_path
   if scenario.failed?
     Dir.mktmpdir do |temp_folder|
       screenshot_path = File.join(temp_folder, 'screenshot.png')
@@ -16,5 +21,6 @@ After do |scenario|
     end
   end
 ensure
+  @video_recorder&.cleanup
   driver.quit_driver
 end

data/lib/generators/cucumber/templates/partials/selenium_env.tt

@@ -7,6 +7,7 @@ require 'rspec'
 require 'raider_reporter/cucumber'
 require 'tmpdir'
 require 'yaml'
+require_relative '../../helpers/video_helper'
 
 Before do
   viewport = YAML.load_file('config/config.yml')['viewport']
@@ -15,9 +16,13 @@ Before do
   else
     driver.manage.window.maximize
   end
+  @video_recorder = VideoHelper.recorder_for(driver)
+  @video_recorder.start
 end
 
 After do |scenario|
+  video_path = @video_recorder&.stop(keep: scenario.failed?)
+  RaiderReporter.attach('video', video_path, type: :webm) if video_path
   if scenario.failed?
     Dir.mktmpdir do |temp_folder|
       screenshot_path = File.join(temp_folder, 'screenshot.png')
@@ -26,5 +31,6 @@ After do |scenario|
     end
   end
 ensure
+  @video_recorder&.cleanup
   driver.quit
 end

data/lib/generators/cucumber/templates/partials/watir_env.tt

@@ -3,6 +3,7 @@
 require 'raider_reporter/cucumber'
 require 'tmpdir'
 require 'yaml'
+require_relative '../../helpers/video_helper'
 
 Before do
   viewport = YAML.load_file('config/config.yml')['viewport']
@@ -11,9 +12,13 @@ Before do
   else
     browser.window.maximize
   end
+  @video_recorder = VideoHelper.recorder_for(browser)
+  @video_recorder.start
 end
 
 After do |scenario|
+  video_path = @video_recorder&.stop(keep: scenario.failed?)
+  RaiderReporter.attach('video', video_path, type: :webm) if video_path
   if scenario.failed?
     Dir.mktmpdir do |temp_folder|
       screenshot_path = File.join(temp_folder, 'screenshot.png')
@@ -22,5 +27,6 @@ After do |scenario|
     end
   end
 ensure
+  @video_recorder&.cleanup
   browser.quit
 end

data/lib/generators/helper_generator.rb

@@ -8,6 +8,7 @@ class HelpersGenerator < Generator
     generate_driver_helper
     generate_appium_helper
     generate_spec_helper
+    generate_video_helper
   end
 
   private
@@ -30,10 +31,13 @@ class HelpersGenerator < Generator
     template('helpers/driver_helper.tt', "#{name}/helpers/driver_helper.rb")
   end
 
+  def generate_video_helper
+    template('helpers/video_helper.tt', "#{name}/helpers/video_helper.rb")
+  end
+
   def generate_appium_helper
     return unless cross_platform?
 
     template('helpers/appium_helper.tt', "#{name}/helpers/appium_helper.rb")
   end
-
 end

data/lib/generators/infrastructure/azure_generator.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../generator'
+require_relative '../../ruby_raider/ffmpeg'
 
 class AzureGenerator < Generator
   def generate_azure_pipeline

data/lib/generators/infrastructure/github_generator.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative '../generator'
+require_relative '../../ruby_raider/ffmpeg'
 
 class GithubGenerator < Generator
   def generate_actions_file