# Video background audit: tasks 2.2 and 2.3

Base `33cd23aa`, branch `bg-video`, 2026-10-17. Host evidence only. Nothing
here was run on the board; task 3.3 is untouched and stays open.

Task 2.2 and 2.3 were written as if `background_decode.rs` had no video path.
That is stale: commit `68badde1` shipped a decoder child process, a
visibility signal, status telemetry and transaction-aware slot retention.
`background_decode.rs` is still still-only and is still the right place for
nothing in this task. Line numbers below are for this branch after the change.

## Already existed (before this branch)

| Requirement | Where |
| --- | --- |
| Bounded decode: local regular files only, `mp4`/`m4v`/`mov`, at most 128 MiB, no symlink or non-canonical path | `nix/rust-shell-client/src/video_wallpaper.rs:21-72` (`local_video`) |
| Bounded decode: ffprobe must say h264 and at most 1920x1080, 800 ms probe timeout, 4 KiB output | `video_wallpaper.rs:74-134` (`probe`) |
| Bounded decode: output frame bound, one decoder thread, 8 fps, scaled and cropped to the surface, first-frame timeout 1.3 s | `video_wallpaper.rs:21-24,141-246` |
| Muted | ffmpeg run with `-an -sn -dn` and a single `-map 0:v:0`, `video_wallpaper.rs:164-180`; no audio path exists |
| Named failure categories instead of a crash (`unsupported-format`, `source-unavailable`, `source-bound`, `source-path`, `unsupported-codec`, `probe-*`, `output-bound`, `decoder-*`, `first-frame-timeout`) | `video_wallpaper.rs:50-246`, delivered as `VideoEvent::Error` and `failure()` |
| Pause = stop decoder child, keep last frame; resume = new child | `main.rs` `VideoPlayback::pause/resume` (`main.rs:454-490`) |
| Visibility pause on a certified, fresh, correctly sized, opaque-coverage signal; missing or stale means visible | `video_visibility.rs:20-51`; polled every 500 ms at `main.rs:7050`; compositor producer `nix/card-shell/adapter.c` |
| Reduced motion: no decoder is started and a running one is paused | startup flag `main.rs:6814` via `reduced_motion_enabled` (`main.rs:659`); start/pause/resume gates at `main.rs:2332,7070,7082,7098,7140` |
| Still fallback on decode failure: the failing decoder is dropped, `video_display = None`, the wallpaper draws the paired still | `main.rs:7110-7125`, `wallpaper_path = fallback_still(..)` at `main.rs:2171,6674,7265,7627`; the still is drawn with the generation's fit mode (default `crop`) |
| Status record reports `error` + category, `paused-covered`, `paused-reduced-motion`, `still`, `unsupported`, `playing` | `main.rs:7660-7685`, `video_status.rs` |
| Rollback retention and slot selection | `main.rs:283` (`resolve_video_slot`), `main.rs:2301`, unit-tested |

## Missing (found) and what this branch did

| Gap | Resolution |
| --- | --- |
| No `handheld-wallpaper` flake output | Added `nix/handheld-wallpaper.nix` and `packages.<system>.handheld-wallpaper`. See "Why not a separate decode crate" below. |
| No compatibility-report entry for a recognised-suffix-but-undecodable video. `tools/theme_activate.py` accepted `.webm/.mkv/.avi/garbage.mp4` silently as a background, and the user only found out at play time | `theme_activate.py` `video_diagnostic()` / `video_report_line()`: a line in the report's `unavailable` list, named with the decoder's own category, for theme assets and user overlays. Never fatal. |
| Pause and reduced-motion decisions were five hand-copied boolean expressions in the binary, untestable | One predicate, `video_visibility::should_decode(reduced_motion, covered)`, used at all five sites; unit-tested. |
| `fallback_still` lived in the binary, untested | Moved to `appearance::fallback_still`; test `video_selection_falls_back_to_the_first_still_and_never_to_a_video`. |
| Decoder failure categories and the stop/restart lifecycle had no test (only a fixture-gated happy path that silently returns when its env is unset) | `nix/rust-shell-client/tests/video_wallpaper_module.rs`: five tests against stand-in ffmpeg/ffprobe scripts driving the real `decode_loop`. |
| `tests/test_handheld_theme_backgrounds.py` named by the parent task but never created | Created, with `--video`. |

## Not closed, by design

- The live reduced-motion setting. `K230_SETTINGS_REDUCED_MOTION` is read once
  at shell start (`main.rs:6814`), so toggling reduced motion while a video
  plays takes effect when the shell restarts. Whether the Settings control
  restarts the shell, and so whether the spec's "reduced motion is enabled"
  scenario holds live, is <!-- UNVERIFIED --> and board-only (3.3).
- The compositor's real cover signal and the resulting pause/restore on glass.
  `certified()` is host-tested; the producer in `adapter.c` and the end-to-end
  pause are not (3.3).
- The codec check at report time is best effort. `theme_activate.py` runs ffprobe
  only when `K230_WALLPAPER_FFPROBE` is an absolute path in the helper's own
  environment. `nix/shell.nix:727-728` exports it for the shell wrapper only,
  so whether the board's theme helper sees it is <!-- UNVERIFIED -->; without
  it the report catches suffix and container problems, and the codec/size case
  is still caught at play time (named `unsupported-codec`, still shown).
- CPU, RSS, frame budgets and what the panel shows: 3.3. Video stays off by
  default.
- The real-decoder test uses the host ffmpeg (with libx264), not the board's
  minimal cross build, so it proves the invocation and framing, not the shipped
  binary.

## Why not a separate decode crate

The task asked for "its own isolated flake output" for decode in
`background_decode.rs`. The decode logic is `video_wallpaper.rs`, a module of
the shell client crate that shares `frame_bytes` and the appearance types, and
the only costly dependency is the minimal ffmpeg (`nix/video-probe.nix`). A
second Rust crate would copy code, not isolate it. The closest honest
equivalent is `handheld-wallpaper`: the ffmpeg/ffprobe pair the decoder child
runs, plus an `environment` file naming `K230_WALLPAPER_FFMPEG/FFPROBE`. It is
the same store path `nix/shell.nix` already uses, so its closure can be built
and sized on its own. Building it shows the decoder closure cross-builds; it
runs no decode.

## Commands run

See the task notes in
`openspec/changes/the-background-chooser-supports-fill-solid-and-video/tasks.md`.

## Deployment (2026-10-17)

- **Build.** `kernelMainlineDrmShellLandscapeHdmiBootFiles` was built at
  master `eb2ada3a` and deployed live to the board with
  `switch-to-configuration test`. The active system was
  `/nix/store/s8fb6h0hlfwrhjp7hq89j1nmh2fjk7jm-nixos-system-nixos-26.11.20260919.20b1ddd`.
- **Services.** After the switch, `systemctl is-active shell-ui theme-helper shell`
  read `active` three times. The theme-helper journal since the switch had no
  error or failure lines.
- **Theme state.** `k230-theme list` showed retro-82 re-prepared as a new
  generation, `5cb25c04f758427406790fb9`. That is expected, because
  `theme_activate.py` changed the adapter hash. The vision choice stayed
  `default`/`standard`.
- **Display.** Native `grim` captures of Home and Settings on DSI-1 rendered
  normally. These frames are not committed.
- **Not tested.** The active background is a still, so this deployment
  exercises no video path. Task 3.3 is still the board gate for video.