---
phase: 05-native-addon-and-dwm-capture
verified: 2026-04-12T23:45:00Z
status: human_needed
score: 3/5
overrides_applied: 0
human_verification:
  - test: "Capture Notepad window and verify PNG shows correct content with correct colors"
    expected: "PNG image shows Notepad window content; red text is red, not blue (BGRA swap correct)"
    why_human: "Requires visual inspection of captured image with a running Notepad window"
  - test: "Capture Notepad while partially covered by another window"
    expected: "Captured image shows only Notepad content, no bleed-through from overlapping window"
    why_human: "Requires visual inspection of occlusion behavior; cannot verify programmatically"
  - test: "Watch Notepad window during capture for flicker or rendering disruption"
    expected: "No visible flicker, flash, or WM_PRINT-style redraw in Notepad during capture"
    why_human: "Visual/temporal behavior; no automated check possible"
---

# Phase 5: Native Addon and DWM Capture Verification Report

**Phase Goal:** A loadable native addon can capture any window by HWND and return a correct PNG buffer, using the empirically validated best DWM API
**Verified:** 2026-04-12T23:45:00Z
**Status:** human_needed
**Re-verification:** No -- initial verification

## Goal Achievement

### Observable Truths

| # | Truth | Status | Evidence |
|---|-------|--------|----------|
| 1 | Addon loads without errors and reports DWM capture availability | VERIFIED | `node -e "require('./native/build/Release/dwm-capture.node')"` outputs `{"isAvailable":true,"exports":["isAvailable","captureWindow"]}` |
| 2 | captureWindow(hwnd) on GDI app returns valid PNG | ? UNCERTAIN | Full capture pipeline exists in code (DwmGetDxSharedSurface -> OpenSharedResource -> CopyResource -> Map -> EncodeBgraToPng). Summary claims 241KB PNG from Notepad++. Cannot verify without a visible window. Routes to human. |
| 3 | Occluded window capture shows only target content | ? UNCERTAIN | DwmGetDxSharedSurface reads from DWM composition (inherently occlusion-immune by design). Summary 05-03 does not explicitly document a dedicated occlusion test result. Routes to human. |
| 4 | No visible flicker during capture | ? UNCERTAIN | DwmGetDxSharedSurface does not send messages to target window (no WM_PRINT). Summary claims no flicker. Requires human visual confirmation. |
| 5 | API choice resolved via empirical testing and documented | VERIFIED | CONTEXT.md documents pivot from WGC to DwmGetDxSharedSurface per user decision (D-01, D-02). Summary 05-02 explains the pivot rationale. Summary 05-03 documents validation results. |

**Score:** 3/5 truths verified (2 uncertain pending human visual checks, plus SC5 verified making 3)

Note: SC2, SC3, and SC4 are inherently visual/behavioral checks. The code pipeline is complete and wired (verified below), but actual capture output quality requires human eyes.

### Required Artifacts

| Artifact | Expected | Status | Details |
|----------|----------|--------|---------|
| `native/CMakeLists.txt` | cmake-js build config for C++17, D3D11 linking | VERIFIED | C++17 (correct for DwmGetDxSharedSurface pivot), NAPI_VERSION=8, d3d11.lib+dxgi.lib+dwmapi.lib linked, src/capture.cpp in source list |
| `native/src/addon.cpp` | NAPI module init with captureWindow and isAvailable exports | VERIFIED | NODE_API_MODULE, isAvailable checks D3D11 + DwmGetDxSharedSurface presence, CaptureWindow dispatches CaptureWorker, 62 lines substantive |
| `native/src/capture.cpp` | DwmGetDxSharedSurface capture pipeline | VERIFIED | Full pipeline: function pointer lookup from user32.dll, HWND validation (IsWindow), SEH wrapper (__try/__except), DwmGetDxSharedSurface -> OpenSharedResource -> staging CopyResource -> Map -> EncodeBgraToPng. 229 lines. |
| `native/src/capture.h` | CaptureWorker class declaration | VERIFIED | Napi::AsyncWorker subclass, ComPtr members, Promise deferred, 30 lines |
| `native/src/d3d_device.cpp` | D3D11 device singleton creation | VERIFIED | D3D11CreateDevice with BGRA_SUPPORT, ComPtr RAII, g_initialized guard for singleton pattern, 40 lines |
| `native/src/d3d_device.h` | D3D11 device singleton API | VERIFIED | InitializeD3D, GetD3DDevice, GetD3DContext, IsD3DAvailable exports, 10 lines |
| `native/src/png_encoder.cpp` | BGRA-to-RGBA swap and PNG encoding | VERIFIED | STB_IMAGE_WRITE_IMPLEMENTATION, BGRA-to-RGBA channel swap (dst[0]=src[2], dst[2]=src[0]), stbi_write_png_to_func, 34 lines |
| `native/src/png_encoder.h` | PNG encoder API | VERIFIED | EncodeBgraToPng signature, 7 lines |
| `native/src/common.h` | DWM_LOG macro (stderr only) | VERIFIED | fprintf(stderr, ...) macro, no printf/cout usage, 8 lines |
| `native/vendor/stb_image_write.h` | Vendored single-header PNG encoder | VERIFIED | 1724 lines, contains stbi_write_png |
| `src/capture/targets/dwm-capture.ts` | TypeScript wrapper with isDwmCaptureAvailable and captureWindowDwm | VERIFIED | Exports both functions, lazy addon loading with try/catch, null-on-failure semantics, 52 lines |
| `native/build/Release/dwm-capture.node` | Compiled binary | VERIFIED | File exists on disk |
| `package.json` | cmake-js, node-addon-api, node-gyp-build, build:native script | VERIFIED | All four entries present |
| `.gitignore` | native/build/ excluded | VERIFIED | Entry present |

### Key Link Verification

| From | To | Via | Status | Details |
|------|----|-----|--------|---------|
| addon.cpp | d3d_device.h | `#include "d3d_device.h"` + InitializeD3D() + IsD3DAvailable() + GetD3DDevice() + GetD3DContext() | WIRED | Calls all 4 exported functions |
| addon.cpp | capture.h | `#include "capture.h"` + `new CaptureWorker(...)` | WIRED | Creates and queues CaptureWorker |
| capture.cpp | d3d_device.h | `#include "d3d_device.h"` (header only, device passed via constructor) | WIRED | Device/context passed as ComPtr parameters |
| capture.cpp | png_encoder.h | `#include "png_encoder.h"` + `EncodeBgraToPng(...)` call at line 156 | WIRED | Called with mapped pixel data, result stored in pngDataOut |
| png_encoder.cpp | stb_image_write.h | `#define STB_IMAGE_WRITE_IMPLEMENTATION` + `#include "stb_image_write.h"` | WIRED | Implementation define activates the single-header library |
| dwm-capture.ts | dwm-capture.node | `require("../../../native/build/Release/dwm-capture.node")` | WIRED | Lazy-loaded at first call, result cached |
| CMakeLists.txt | src/capture.cpp | Listed in add_library source files | WIRED | Build system includes capture.cpp |

### Data-Flow Trace (Level 4)

| Artifact | Data Variable | Source | Produces Real Data | Status |
|----------|---------------|--------|--------------------|--------|
| capture.cpp | pngDataOut | DwmGetDxSharedSurface -> OpenSharedResource -> CopyResource -> Map -> EncodeBgraToPng | Yes (real D3D11 texture readback) | FLOWING |
| addon.cpp | CaptureWorker::pngData_ | Populated in Execute(), returned as Napi::Buffer in OnOK() | Yes (Buffer::Copy from vector) | FLOWING |
| dwm-capture.ts | return value | `await addon.captureWindow(hwnd)` | Yes (Promise resolves with Buffer from native) | FLOWING |

### Behavioral Spot-Checks

| Behavior | Command | Result | Status |
|----------|---------|--------|--------|
| Addon loads and exports correct API | `node -e "require('./native/...').isAvailable()"` | `{"isAvailable":true,"exports":["isAvailable","captureWindow"]}` | PASS |
| Invalid HWND rejects gracefully | `node -e "...captureWindow(99999).catch(...)"` | `REJECTED: Error: Invalid or destroyed HWND` | PASS |
| TS wrapper loads and reports availability | `npx tsx -e "import { isDwmCaptureAvailable } from '...'"` | `{"available":true,"hasCapture":true}` | PASS |
| No stdout pollution from C++ | All DWM_LOG output appears on stderr only | Confirmed: `fprintf(stderr, ...)` macro, no printf/cout in source | PASS |

### Requirements Coverage

| Requirement | Source Plan | Description | Status | Evidence |
|-------------|------------|-------------|--------|----------|
| DWM-01 | 05-01 | Native C++ NAPI addon compiles and produces loadable .node binary | SATISFIED | Binary at native/build/Release/dwm-capture.node loads successfully, exports isAvailable + captureWindow |
| DWM-02 | 05-02 | Addon captures window by HWND using DWM composition APIs (no PrintWindow/WM_PRINT) | SATISFIED | Uses DwmGetDxSharedSurface (reads DWM composition directly, no window messages sent) |
| DWM-03 | 05-02 | Captured frames returned as PNG buffers with correct RGBA pixel data | NEEDS HUMAN | Pipeline complete (BGRA-to-RGBA swap in png_encoder.cpp), but color correctness requires visual verification |
| DWM-04 | 05-03 | Capture does not cause visible flicker | NEEDS HUMAN | DwmGetDxSharedSurface by design does not send messages to target window, but visual confirmation needed |
| DWM-05 | 05-03 | Capture ignores overlapping windows (reads from DWM composition) | NEEDS HUMAN | DwmGetDxSharedSurface reads from DWM composition (inherently occlusion-immune), but visual confirmation needed |

### Anti-Patterns Found

| File | Line | Pattern | Severity | Impact |
|------|------|---------|----------|--------|
| dwm-capture.ts | 23 | Bare `require()` in ESM project instead of `createRequire()` | INFO | Works on Node 22+ (current runtime is v25.8.2) but may fail on Node 20 LTS. Phase 6 integration should use createRequire for broader compatibility. |

No TODOs, FIXMEs, placeholders, or stub patterns found in any phase 5 files.

### Human Verification Required

### 1. GDI App Capture Quality (DWM-02, DWM-03)

**Test:** Open Notepad with some text. Run:
```
npx tsx -e "import { Window } from 'node-screenshots'; import { captureWindowDwm } from './src/capture/targets/dwm-capture.ts'; import { writeFileSync } from 'fs'; const win = Window.all().find(w => w.title().includes('Notepad')); if (!win) { console.error('Open Notepad first!'); process.exit(1); } const buf = await captureWindowDwm(win.id()); if (!buf) { console.error('FAIL: returned null'); process.exit(1); } writeFileSync('test-capture.png', buf); console.log('Saved test-capture.png', buf.length, 'bytes');"
```
**Expected:** PNG shows Notepad with correct colors (red is red, not blue). Text is readable.
**Why human:** Visual color accuracy and content correctness cannot be verified programmatically.

### 2. Occlusion Immunity (DWM-05)

**Test:** Partially cover Notepad with another window. Run the same capture command.
**Expected:** Captured image shows only Notepad content with no bleed-through from overlapping window.
**Why human:** Occlusion behavior requires visual comparison of captured image vs screen state.

### 3. No Flicker (DWM-04)

**Test:** Watch the Notepad window carefully while running the capture command.
**Expected:** No visible flicker, flash, or rendering disruption in Notepad during capture.
**Why human:** Temporal visual behavior cannot be detected programmatically.

### Gaps Summary

No code-level gaps found. All artifacts exist, are substantive, are wired together, and data flows through the complete pipeline. The three remaining items (GDI capture quality, occlusion immunity, no flicker) are inherently visual/behavioral properties that the summaries claim pass but require human visual confirmation to fully verify.

The API pivot from WGC to DwmGetDxSharedSurface was intentional (user decision D-01, D-02 in CONTEXT.md) and is correctly reflected throughout the codebase. The C++ standard was appropriately downgraded from C++20 to C++17 since WinRT headers are no longer needed.

---

_Verified: 2026-04-12T23:45:00Z_
_Verifier: Claude (gsd-verifier)_