LlamaCasty/HANDOFF.md

# HANDOFF — Session State

## Branch / Commit State

**`main`**, clean working tree, **fully pushed to `origin/main`** (nothing pending).
Last work boundary: `097dd0d` (docs: hand off TASK 21 UI picker slice). No uncommitted
work; no local commits ahead of origin.

Recent commit series (all pushed, before this session's end):
- `097dd0d` — docs: hand off TASK 21 UI picker slice (acquisition + loop wiring spec)
- `881addb` — TASK 21 slice 3: loop control in MediaVideoSource (process factory + Loop flag)
- `a2219be` — TASK 21 slice 2b: native-FPS pacing in MediaVideoSource (probe -> delay seam)
- `8fa7842` — TASK 21 slice 2a: native-FPS probe seam (ffprobe parse + derive sibling)
- `071ec8b` — TASK 21 slice 1 step 4: wire media into resolver + preview routing
- `480ead0` — TASK 21 slice 1 step 3: IMediaFrameSource + MediaVideoSourceManager
- `a1d9751` — docs: ffmpeg decode-contract verification recipe + WSL CLR boundary
- `8f49010` — TASK 21 Increment B: FFmpeg rawvideo video decoder -> VideoFrame

## Why the session ended

User ready for a break after a substantial day. No mid-flight work — everything is
committed and pushed. This is a clean stopping point.

## What's In Flight

Nothing actively mid-flight. The last TASK 21 work unit (the **UI picker / acquisition
slice**) is **handed off**, not in progress — spec reproduced in the section below.
It is a GUI feature that must be built + verified natively on Windows.

## Project-wide code-complete picture (2026-08-31, user's framing)

The user revisited the ongoing "how code-complete are we" question. Current agreed read:

- **Feature/code completeness ≈ 88–92%**, after removing from consideration:
  - **TASK 13 = MARCOM, not code** (social media launch kit) — does not count against code-complete.
  - **TASK 10 (monetization / Polar billing / Velopack distribution + updater) — deliberately
    parked by the user until it is the dead-last thing to do.** Not a blocker for feature completion.
- Remaining real code before feature-complete:
  - **TASK 21 UI picker** slice (the handoff below) — the one genuinely open feature unit.
  - **TASK 9** — visibility picker (drop the always-Private lock, let user pick
    Private/Unlisted/Public) + a couple stream-management items.
  - **TASK 4** — background removal (excluded by design) + a few capture-pipeline items.
- **Biggest actual risk is not code — it is the missing native-Windows verification pass.**
  Real ffmpeg media decode/loop/pacing, recording, and the GUI suites have only ever run
  headless in WSL or against fakes. Crossing-the-line "works on Windows" readiness is lower
  than the code-complete number would suggest until that pass happens.

## @ User note — no suggestions for the time being

The user asked to **stop with forward-looking suggestions** (they read as distracting). Do
not volunteer next-step options or "what's next" lists unless the user asks. Answer what is
asked; stay quiet on roadmap unless prompted.

## UI picker slice — handoff spec (2026-08-31)

Nothing `AcquireAsync`s a media path yet, so **no frames flow in a running app** —
the decoder, manager, pacing, and loop mechanism are all shipped and unit-tested,
but a media Source has no way to start a session. Deliverables, in order:

1. **File picker + add/remove commands** (mirror `MainViewModel.Background.cs`/`Trax.cs`
   `OpenFileDialog` usage — see `MainViewModel.Trax.cs:68`). A "Media" source action
   opens an `OpenFileDialog` filtered to video (mp4/mov/avi); on OK set `Source.MediaPath`,
   add to scene, and **`AcquireAsync(MediaPath)`**; on remove **`ReleaseAllAsync(MediaPath)`**.
   On `StagedScene` layout loads/teardown, call `ReleaseAllAsync` for every media path no
   longer present (and acquire new ones) so sessions track the live scene.
2. **Wire `Source.MediaIsLooping` → `IMediaFrameSource.Looping`** — needs a manager-level
   per-**path** loop provider (see ambiguity: sessions are refcounted per `MediaPath` and
   shared across scenes, but `MediaIsLooping` is per-`Source`; a scene set → the path's
   session `Looping` = any live reference has it on, so one scene turning it on while
   another shares the file is shared behaviour — pick a rule and record it).
3. **Loop toggle + volume slider** in the source context menu / inspector (TASKS 11/10).
4. `MediaVolume`/`MediaPlaybackState` wiring (audio path for media is future work).

**Design notes to preserve:** `ResolveOutputFrame` reads `_mediaManager.GetLatestFrame(MediaPath)`;
`OnMediaPreviewBitmapChanged` adopts the shared `WriteableBitmap` per path; `MediaFailed` →
`OnMediaFailed` (currently `Debug.WriteLine`, surface in UI). Composer scales any frame size
(media renders through the generic `frameFor(element)` path — no compositor change needed).
The real-ffmpeg decode/loop/restart path is only exercised natively on Windows — first
GUI smoke test should add a short mp4, confirm it plays and previews, then crash further.

## Landmine

- A stale `testhost` can lock `ytLive.Tests`'s `ytLive.dll` and break `dotnet build` of the
  test project — kill it first (`cmd.exe /c "taskkill /PID N /F"`) on MSB3027.
- Full-suite vstest hangs headless (RealAppHost/WASAPI) — only filtered pure tests run in
  WSL; user verifies the GUI suites on native Windows PowerShell (which may also hang if
  WASAPI startup blocks — pre-existing, not this change).
- **WSL can only run the Windows-bound dotnet CLR shim** — it cannot spawn Linux ffmpeg/ffprobe
  (Win32Exception 193). Verify ffmpeg contracts via shell/python; leave CLR→real-ffmpeg to the
  native Windows suite. Linux static ffmpeg/ffprobe 7.0.2 live at
  `/tmp/opencode/ffmpeg-7.0.2-amd64-static/`; `/tmp/opencode/clip.mp4` = 640x360 30fps 1s.

## The directive (2026-08-31, user)

Rewrite the project into functional components to aid AI retrieval —
`Services/ChatOverlayLayer.cs` / `SceneGraph.cs` style (owner-state extraction),
not line-count chasing. Audio assumption is now an explicit contract (README
"Audio Assumption"): the app uses system defaults, never fights Windows device
locking, and does not debug user audio issues — OS's problem, not ours.