docs(70): queue the Live Window App overlay layer

Record the creator's Live-only, single-layer scope and distinguish it from the existing session-scoped Capture Window backdrop pin. Include HWND lifecycle, protected-window, visual-only, and duplicate-underlay boundaries. Reference scan: Microsoft HWND capture item API and OBS Window Capture: https://learn.microsoft.com/en-us/windows/win32/api/windows.graphics.capture.interop/nf-windows-graphics-capture-interop-igraphicscaptureiteminterop-createforwindow https://obsproject.com/kb/window-capture-sources
2026-11-11 07:42:37 -08:00
parent 4e5b4e3999
commit 2c5a3d8c11
3 changed files with 49 additions and 3 deletions
@@ -0,0 +1,45 @@
+# TASK 70 — Window App layer
+
+**Status:** ☐ Queued (creator request 2026-11-11); scheduled after TASK 69 and before the gold pass.
+
+## Request and locked limits
+
+Add a **Window App** layer that captures a specific running app window and composites it above the
+Live scene's game/display Background. Example: show a terminal over a game. This is an ordinary
+foreground visual layer, not the existing TASK 38 **Capture Window…** action, which replaces the
+locked Background itself.
+
+- Available in **Live only**.
+- At most **one Window App layer** may be active in the layout.
+- It cannot remove or mask the target from the underlying game/display capture. If the app is already
+  visible in those captured pixels, it may appear twice; do not select the game/already-captured app as
+  the overlay target.
+- Visual only; no independent per-app audio capture or routing.
+- Enumerate visible top-level windows of other processes. A process with several windows may offer
+  several titled entries; this selects a window, not every window owned by the process.
+
+## Capture boundaries
+
+- Target HWNDs are session-scoped. Never resurrect a raw HWND after restart: Windows can recycle it to
+  an unrelated window. The creator must select the window again for a new session.
+- If the target closes, minimizes, suspends rendering, or cannot be captured, its image may freeze,
+  disappear, or go black; release the dead capture rather than leaving an apparently live layer.
+- Secure/protected content may be returned black or excluded by Windows. This is an OS restriction,
+  not something LlamaCasty can bypass.
+
+## Acceptance
+
+- Add → Window App lists eligible windows and selection adds one Live-scene layer above the Background.
+- The source updates while its target window is running, independent of whether another window covers it.
+- The app refuses a second Window App layer and refuses adding this source outside Live.
+- Target closure/failure is surfaced and releases the capture; restarting never reuses a saved HWND.
+- One Good Dog integration test drives a fake capture source/enumerator. A real Windows visual check is
+  required before commit.
+
+## Reference scan
+
+- Windows Graphics Capture exposes HWND-targeted items via
+  [`IGraphicsCaptureItemInterop::CreateForWindow`](https://learn.microsoft.com/en-us/windows/win32/api/windows.graphics.capture.interop/nf-windows.graphics.capture.interop-igraphicscaptureiteminterop-createforwindow).
+- OBS's [Window Capture source](https://obsproject.com/kb/window-capture-sources) confirms the intended
+  foreground-source behavior; Windows documents that protected windows may be black or omitted in
+  [New Ways to do Screen Capture](https://blogs.windows.com/windowsdeveloper/2019/09/16/new-ways-to-do-screen-capture/).