LlamaCasty/HANDOFF.md

HANDOFF — 2026-09-17 (webcam app-default gate slice; committed locally — no push)

Branch / Commit State

main HEAD = 1e4017d webcam startup resource lifecycle (local). The gate slice lands on top as a NEW commit (stays commit-local until greenlight). Below: 94a934f (reader-ladder), 64a5a6d (slice-18 C4 cache), slice-17, slice-16, slice-15, c01206f, b22d08e (signed audio-sync, pushed). No push after this commit either — still awaiting the device take + user greenlight.

⚠️ Branding (2026-09-14, creator-corrected): product = llamacasty, internals = ytLive

Product is llamacasty; repo path, csproj AssemblyName/RootNamespace, DB/log paths (%APPDATA%\ytLlive\...), most code names are legacy ytLive/ytLlive. User-facing text: "llamacasty" / UI labels use the catalog names ("Web Cam", "YouTube Chat", "Countdown Timer"…).

✅ Committed — webcam app-default gate slice (creator-visible goal: Web Cam offered when switching to Live)

Background: the DB truth (%APPDATA%\ytLlive\ytLlive.db; NOT layout.db, a 0-byte legacy file) put the single WebcamSceneConfig in Chat, so the old TASK 26 app-wide rule grayed Live's "+" → Web Cam even though the camera was available and in use. The creator ruled (rigorous resource model): the webcam is an app-level resource — ONE app-wide default selection, usable in every scene that can host it; it is NOT blocked by other scenes' placements. Scope of this slice: the availability layer. TASK 26's app-wide gate is superseded by creator directive.

• Per-scene gate: CanAddWebcam = StagedScene is { WebcamConfig: null } && IsWebcamAttainable. A scene already hosting the webcam stays gray (one webcam per stream); another scene holding it does NOT gray the row elsewhere.
• Attainable = a live lock, not a saved identity (creator refinement): IsWebcamAttainable = _webcam != null && CameraManager.IsRunning(_webcam.DeviceId). An identity whose camera is unplugged / can't start leaves the row greyed (tooltip "No webcam is currently available…"), and it un-greys the moment a session is running (startup lock, first frame, picker + acquire).
• Add places the default directly: when attainable, "Add Webcam" creates the placement with NO picker; the Windows picker runs only for the initial selection (_webcam == null).
• Identity survives last-placement removal: RemoveElement no longer nulls _webcam (that was the TASK 26 rule). LayoutStore writes the singleton whenever it's non-null, so it persists.
• Startup lays an app-wide BASE lock: the single-camera branch ALWAYS acquires (the old IsRunning skip is gone) — on an already-running session it just bumps the refcount, and that ref is the app's own hold. Result: removing every scene's placement leaves RefCount = 1, the session stays alive, and the row stays offered (the app default outlives the scenes). It still adopts a solo camera as the app default when no identity exists, so a clean layout offers Web Cam at once.
• Dynamic why-gray tooltip: WebcamAddToolTip (raised wherever the gate can flip: staging, removal, startup lock success, first frame, camera failure, identity swap) — "Already in this scene — one webcam per stream. A second camera means you've graduated to OBS." / "No webcam is currently available — plug one in, or allow camera access in Windows." / "Adds the app default webcam to this scene."
• Good Dog integration tests WebcamMenuGateTests (real app + temp DB + camera seams): (1) Chat's identity does NOT gray Live; Add in Live places the same wc-1 without a picker; scene-with- placement stays gray; identity survives both removals (DB row count keeps 1, session kept by the base lock). (2) Negation: identity loaded but its session can't start → row NOT offered. WebcamStartupResourceTests test 1 strengthened: after startup the single camera is adopted → CanAddWebcam true. 305 tests (304 pass + the known audio flake, see Landmines); build 0 warnings.

Task docs: TASKS.md Open items + ai.md Webcam section updated (supersession recorded).

✅ Earlier committed — webcam resource lifecycle (startup slice, 1e4017d)

Startup poll + tri-state (ValidateWebcamResourceStartupAsync after LoadLayout): 0 → run on, no alarm; 1 → AcquireAsync as app-wide lock (now always runs — see base-lock note above); ≥2 → no auto-lock (App Settings selector next). Lock failure → persistent red alert (WebcamLockAlert in the Layers panel + Retry), re-polls every 5 s (_webcamLockPollTimer), clears on lock success or any first real frame. CameraManager.IsRunning(deviceId) = session exists (started OR starting). Camera test seams CameraEnumeratorOverride/CameraFrameSourceFactoryOverride (mirror LayoutPathOverride). Attribution correction committed: "NVIDIA Broadcast opens the webcam exclusively" is a suspect-list claim — CameraConflictProbe reads process names only, no device handles; do not restate as fact.

⚠️ Open items

• Webcam take fix 2 of 2 — the 09:16 crash is UNFIXED (hard, untested): hypothesis — native WMF death when MediaCapture.Failed fires mid-stream and SafeStopAsync (fire-and-forget) disposes reader+capture while the frame thread sits in TryAcquireLatestFrame/Marshal.Copy (outside the frame's try/catch). No repro, no integration test, native race not catchable — deferred per spin-guard. Record a second occurrence's pattern.
• Multi-camera selector slice (user-queued): when ≥2 webcams exist, add web-cam selection text + control to the App Settings dialog (gear icon, OverlayHost — left-click opens settings, right-click the context menu). Selecting + successfully allocating/locking activates the WebCam layer. Currently ≥2 cameras → nothing shows in settings. Also: the "Change Webcam" picker should carry the OBS one-liner (one webcam per stream — a second means OBS).
• Static (+) catalog slice (user-queued): all catalog rows always listed (Background, "Web Cam", "Countdown Timer", "Web Resource", "YouTube Chat", "YouTube Event"…), gray only for (1) system-level unavailability (persistent alert), (2) max already allocated, (3) not available for the current scene; tooltips must name the reason. Static labels only, no new code-behind.
• Device re-verify (one take session): 1. slice-18 cache verdicts (NR/WH hits, stalls, band ~60); 2. webcam: fresh launch with the browser holding the camera must show the webcam or a NAMED chip (now also the persistent red alert, and the alert must clear after the browser closes + retry); 3. verify Live now OFFERS the Web Cam layer even while Chat holds the camera (the exact creator goal: "webcam offered in the layer stack when I switch over to the Live view").
• No push yet — after the take verdict, re-measure the clap offset (/tmp/opencode/avsync.py), then decide push with the user.

Open threads (carried)

• Audio-silence verification — fixed (724af14); creator heard real audio.
• Webcam MJPG missing / ~10–14Hz, layer SortOrder, truncation-with-dynamic-scenes — queued.
• Sync control user-doc tutorial — REQUIRED before 1.0 (creator directive; TASK 22).
• Signed A/V sync: verify the negative (advance) direction on device.
• Focus-loss capture lag — closed as NOT the cause (1824: delivery healthy ~60-100/s).

Landmines

• testhost shares startup.log — filter by time; the app also writes fake-device failures ('test-camera', 'dev-physical-9') from CameraManager unit tests.
• cmd.exe /c "taskkill /F /IM ytLive.exe" (WSL double-slashes mangle) before rebuilds — a live app process locks ytLive.exe (MSB3021).
• Build/tests: Windows dotnet host (/mnt/c/Program Files/dotnet/dotnet.exe). 0 warnings — only ./scripts/verify.sh "<files>"'s clean build counts. Running ytLive.csproj alone does NOT rebuild ytLive.Tests.dll — run the Tests csproj before vstest. Known audio flake: Mix_HonorsProviderGains_AndGameMute_KillsTheLoopback — a stale loopback sample still in the pipe when the mute flips (phase 2's Assert.Equal(0f, f, 6) sees 0.4). Confirmed pre-existing and currently deterministic in this environment: it fails on clean 9d00955 (stash test) and on the working tree, alone and in-suite. Unrelated to camera work; do not "fix" it inside a webcam slice.
• Assert footguns in this repo's xUnit: Assert.Null(x, "msg")/Assert.Single(coll, "msg") do NOT take a message — the 2-arg overloads mean something else (predicate/item). Empty message = 1 arg.
• The webcam's real state lives in %APPDATA%\ytLlive\ytLlive.db (layout.db there is a 0-byte legacy file). sqlite3 at /home/gramps/android-sdk/platform-tools/sqlite3.
• Contention failure modes (startup.log): "no frames within 4s" = init OK but starved; "OutputFormatNotSupported" = reader subtype below the MJPG-active camera; "file being used by another process / CaptureMode is SharedReadOnly" = re-negotiation refused while others hold the device. CameraConflictProbe = suspect list, not handle evidence.
• FramePump tests asserting per-frame CONTENT need a STABLE scene; cache-sensitive assertions can't use a call-count resolver flip (tick resolves twice) — key alternation on OutputIndex.
• ffmpeg/ffprobe: /mnt/c/Program Files/Krita (x64)/bin/ with Windows paths.
• MyMistakes.md: WINRT resource-allocation RECIPE, freeze-audit RECIPE, A/V sync recipe, deadline pacing, CoreMessaging DQ, WGC-CLIP + slice blocks. Grep before re-deriving.
• C:\tmpout is for ffmpeg evidence artifacts; keep them out of the repo.

Next step

The multi-camera App Settings selector slice (+ static catalog rows after), then the creator's take on this build. The webcam gate slice answers the creator's "go" ask — switching to the Live view must now offer Web Cam in the layer stack (Chat holding the camera no longer blocks it). The red Layers alert remains the new expected behavior to eyeball on the take: browser holds the camera → fresh launch → alert (unless Chat's config grabbed it) that clears after a Retry once the browser closes.