# Phase 03.2: Integrate into Official Beyond Driver Package - Context

**Gathered:** 2026-03-22
**Status:** Ready for planning

<domain>
## Phase Boundary

Driver builds and deploys as part of the official Bigscreen Beyond driver package (`bigscreenbeyond`) instead of a standalone `beyond_proximity` sidecar. The DLL slots into the existing Steam-distributed Beyond driver directory alongside resources, icons, and companion tools. No new features — just repackaging the existing driver into the correct home.

</domain>

<decisions>
## Implementation Decisions

### Integration model
- Modify the existing `bigscreenbeyond` driver manifest — change `resourceOnly: false`, `alwaysActivate: true`, `hmd_presence: ["35BD.0101"]`
- DLL output renamed to `driver_bigscreenbeyond.dll` (matches manifest `name` field convention: `driver_{name}.dll`)
- CMake project name stays `beyond_proximity` internally — only the output artifact name changes
- Existing `resources/` directory (icons, `driver.vrresources`) left untouched — our DLL just adds to the package

### Build & deploy workflow
- CMake build output mirrors bigscreenbeyond layout locally: `build/driver/bigscreenbeyond/bin/win64/driver_bigscreenbeyond.dll`
- Deploy script (PowerShell) copies DLL + manifest to the Steam-installed Beyond driver directory
- Deploy target on this system: `C:\Program Files (x86)\Steam\steamapps\common\Bigscreen Beyond Driver`
- Deploy scope: DLL + manifest only — don't touch resources, BeyondHID.exe, eyetracking, or anything else
- `beyond_prox_ctl.exe` stays in build output as dev tool only, not deployed to production path

### Sidecar transition
- One-time manual `vrpathreg removedriver` for the standalone `beyond_proximity` sidecar — done by agent during execution, not in a reusable script
- Remove `driver/beyond_proximity/` directory from repo (git history preserves old files)
- New driver package assets live in `driver/bigscreenbeyond/` (manifest only — resources stay in the installed package, not in the repo)

### Verification
- Verification script confirms `beyond_proximity` is NOT registered in SteamVR driver paths
- Verification script confirms `bigscreenbeyond` driver loads from the Steam install path
- Existing functionality checks: HMD property write (proximity on/off), HID access, icons still display

### Claude's Discretion
- Deploy script implementation details (elevation mechanism, error handling)
- CMake variable naming for the new output paths
- Whether `driver/bigscreenbeyond/` in the repo contains just the manifest or also a stub resources/ directory
- Verification script structure (extend existing vs new script)

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Current driver code
- `CMakeLists.txt` — Build configuration, output paths, DLL naming (lines 8-9 define DRIVER_NAME/TARGET_NAME)
- `src/driver/device_provider.cpp` — DeviceProvider with HMD property write, named pipe, HID init
- `src/driver/hmd_driver_factory.cpp` — HmdDriverFactory entry point

### Driver manifests
- `driver/beyond_proximity/driver.vrdrivermanifest` — Current sidecar manifest (to be replaced)
- `code_samples/Bigscreen Beyond Driver/driver.vrdrivermanifest` — Official Beyond manifest (reference for target format)
- `code_samples/Bigscreen Beyond Driver/resources/driver.vrresources` — Icon resource mapping (uses `{bigscreenbeyond}` path prefix)

### ETDriver precedent (nested sub-driver pattern — NOT using this, but useful reference)
- `code_samples/Bigscreen Beyond Driver/bin/eyetracking/ETDriver/driver.vrdrivermanifest` — Shows alwaysActivate=true sub-driver pattern

### Existing verification
- `scripts/verify_driver.ps1` — Current verification pattern to extend

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `CMakeLists.txt` — Already outputs to driver package structure; needs path/name changes
- `scripts/verify_driver.ps1` — Existing numbered-check verification pattern to extend
- `driver/beyond_proximity/driver.vrdrivermanifest` — Starting point for new manifest (update fields)

### Established Patterns
- CMake post-build copy command copies driver assets (manifest, resources) to build output
- PowerShell verification scripts with atomic numbered checks
- DriverLog for all driver-side logging

### Integration Points
- `CMakeLists.txt` lines 8-9: `DRIVER_NAME` and `TARGET_NAME` variables control output DLL name and directory structure
- `CMakeLists.txt` lines 25-31: Output directory configuration — change to `bigscreenbeyond`
- `CMakeLists.txt` lines 55-59: Post-build copy command — update source path from `beyond_proximity` to `bigscreenbeyond`
- SteamVR driver path registry (`vrpathreg`) — needs old sidecar removed, bigscreenbeyond already registered by Steam

</code_context>

<specifics>
## Specific Ideas

- The Steam-installed Beyond driver at `C:\Program Files (x86)\Steam\steamapps\common\Bigscreen Beyond Driver` is already registered with SteamVR — no need to `vrpathreg adddriver` for bigscreenbeyond, just place files there
- The `{bigscreenbeyond}` path prefix in `driver.vrresources` is resolved by SteamVR based on the driver's registered path — icons will continue working as long as the manifest name stays `bigscreenbeyond`
- Deploy script needs elevation to write to Program Files — consider `Start-Process -Verb RunAs` or requiring admin terminal

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope

</deferred>

---

*Phase: 03.2-integrate-into-official-beyond-driver-package*
*Context gathered: 2026-03-22*