# Phase 5: Native Addon and DWM Capture - Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-04-12
**Phase:** 05-native-addon-and-dwm-capture
**Areas discussed:** API Validation Strategy, Crash Isolation Architecture, Yellow Border Policy, Test Validation Approach
**Mode:** Fully autonomous (user delegated all decisions)

---

## API Validation Strategy

| Option | Description | Selected |
|--------|-------------|----------|
| Build WGC directly | Research already concluded WGC is best; validate empirically during execution | ✓ |
| Test DwmGetDxSharedSurface first | Try undocumented API first per STATE.md note, fall back to WGC | |
| Build both and compare | Implement both APIs and benchmark | |

**User's choice:** Build WGC directly (auto-selected, recommended default)
**Notes:** Research thoroughly evaluated all three APIs. DwmGetDxSharedSurface is undocumented and rejected in ARCHITECTURE.md. STATE.md mentioned testing it first, but the research supersedes that early decision. Empirical validation of WGC against GDI/DirectX/occluded windows satisfies success criteria #5.

---

## Crash Isolation Architecture

| Option | Description | Selected |
|--------|-------------|----------|
| In-process with defensive coding | RAII, SEH, COM validation — simpler, faster | ✓ |
| Child-process IPC | Spawn capture helper process — crash-isolated but complex | |
| Worker thread pool | Dedicated capture threads — middle ground | |

**User's choice:** In-process with defensive coding (auto-selected, recommended default)
**Notes:** Child-process adds IPC overhead and complexity (shared memory or pipe protocol). PITFALLS.md recommends starting in-process with extensive defensive coding, with child-process as fallback if stability proves insufficient. Phase 6 handles the fallback-to-monitor-crop path which covers total addon failure.

---

## Yellow Border Policy

| Option | Description | Selected |
|--------|-------------|----------|
| Accept border in Phase 5 | Matches v1.1 out-of-scope decision | ✓ |
| Attempt borderless from start | Requires GraphicsCaptureAccess capability — complex for non-packaged app | |
| Hide border via overlay trick | Render over the border — fragile workaround | |

**User's choice:** Accept border in Phase 5 (auto-selected, recommended default)
**Notes:** REQUIREMENTS.md v1.1 out-of-scope explicitly says "If WGC is chosen, accept the border rather than adding interactive consent." This is a locked project decision.

---

## Test Validation Approach

| Option | Description | Selected |
|--------|-------------|----------|
| Automated smoke tests | Node script: load addon, capture Notepad, verify PNG dimensions + color | ✓ |
| Manual visual inspection | Developer reviews screenshots by eye | |
| Full test suite with fixtures | Pixel-perfect comparison against reference images | |

**User's choice:** Automated smoke tests with known windows (auto-selected, recommended default)
**Notes:** Success criteria are specific and testable: addon loads, PNG buffer decodes, occlusion-free capture works, no flicker. Automated smoke tests cover all five criteria. Full pixel-perfect tests would be brittle across different Windows themes/DPI settings.

---

## Claude's Discretion

- Native addon directory structure details
- stb_image_write integration specifics
- CMakeLists.txt exact configuration
- Error message wording
- isAvailable() sync vs async

## Deferred Ideas

None — discussion stayed within phase scope