---
phase: 05-native-addon-and-dwm-capture
plan: 01
subsystem: native-addon
tags: [native, cpp, napi, d3d11, build-toolchain]
dependency_graph:
  requires: []
  provides: [native-addon-binary, d3d11-device-singleton, png-encoder, cmake-build-pipeline]
  affects: [05-02-PLAN, 05-03-PLAN]
tech_stack:
  added: [cmake-js@8.0.0, node-addon-api@8.7.0, node-gyp-build@4.8.4, stb_image_write]
  patterns: [NAPI-module-init, D3D11-singleton, ComPtr-RAII, stderr-only-logging]
key_files:
  created:
    - native/CMakeLists.txt
    - native/src/addon.cpp
    - native/src/d3d_device.cpp
    - native/src/d3d_device.h
    - native/src/common.h
    - native/src/png_encoder.cpp
    - native/src/png_encoder.h
    - native/vendor/stb_image_write.h
  modified:
    - package.json
    - .gitignore
decisions:
  - Used C++20 standard (not C++17) for WinRT coroutine header compatibility
  - NAPI version 8 with exceptions disabled (NAPI error handling instead)
  - D3D11 device created at addon load as module-level singleton
  - All logging via stderr DWM_LOG macro to protect MCP JSON-RPC stdout
metrics:
  duration_seconds: 259
  completed: "2026-04-13T05:13:41Z"
  tasks_completed: 2
  tasks_total: 2
  files_created: 8
  files_modified: 2
---

# Phase 05 Plan 01: Native Addon Scaffold Summary

Native C++ NAPI addon with cmake-js build pipeline, D3D11 device singleton, and stb_image_write PNG encoder -- compiles on C++20, loads into Node.js, exports isAvailable() returning true on Windows 11.

## What Was Done

### Task 1: Native addon scaffold -- CMakeLists.txt, package.json deps, directory structure
- Created `native/CMakeLists.txt` with C++20, WinRT, D3D11/DXGI/DWM linking, NAPI v8
- Added cmake-js, node-addon-api, node-gyp-build to package.json
- Added `build:native` script
- Commit: `2cedde2`

### Task 2: C++ source files -- addon.cpp, d3d_device, png_encoder, common.h, stb vendor
- Created addon.cpp with NAPI module init exporting `isAvailable()` and `captureWindow()` placeholder
- Created D3D11 device singleton with ComPtr RAII (d3d_device.cpp/h)
- Created BGRA-to-RGBA PNG encoder using vendored stb_image_write (png_encoder.cpp/h)
- Created common.h with stderr-only DWM_LOG macro
- Vendored stb_image_write.h (1724 lines)
- Added native/build/ to .gitignore
- Commit: `d315780`

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] CMake not installed on system**
- **Found during:** Task 2 (build step)
- **Issue:** `cmake-js compile` failed with "CMake is not installed"
- **Fix:** Installed CMake 4.3.1 via `winget install Kitware.CMake`
- **Files modified:** None (system-level install)

## Verification Results

- `npx cmake-js compile -d native` completes without errors
- `node -e "require('./native/build/Release/dwm-capture.node')"` loads successfully
- `isAvailable()` returns `true` (D3D11 feature level 0xB000 = 11.0)
- `captureWindow()` export present (placeholder rejects with Plan 05-02 message)
- D3D11 device created once at addon load (singleton pattern confirmed)
- All C++ logging goes to stderr via DWM_LOG macro
- No printf/std::cout in native source files

## Known Stubs

| Stub | File | Line | Reason | Resolved By |
|------|------|------|--------|-------------|
| captureWindow placeholder | native/src/addon.cpp | 13-17 | Returns rejected promise; real implementation in Plan 05-02 | 05-02-PLAN |

## Threat Flags

None -- no new security surface beyond what the plan's threat model covers.

## Self-Check: PASSED

All 8 created files exist. Both commit hashes (2cedde2, d315780) verified in git log.