66 lines
4.0 KiB
Markdown
66 lines
4.0 KiB
Markdown
# Native macOS POC Results
|
|
|
|
> This document records capability evidence, not the production product specification.
|
|
> Canonical direction is defined by [`../../CONTEXT.md`](../../CONTEXT.md),
|
|
> [`../product/mastermind-product-brief.md`](../product/mastermind-product-brief.md), and
|
|
> [`../architecture/native-mastermind.md`](../architecture/native-mastermind.md).
|
|
|
|
## Implemented
|
|
|
|
- SwiftPM-based macOS POC under `native/MastermindPOC`.
|
|
- AppKit lifecycle with a menu bar status item.
|
|
- Transparent non-activating overlay window with hide/show and click-through controls.
|
|
- Overlay window uses `NSWindowSharingType.none` and ScreenCaptureKit filtering excludes the current process windows from app-owned capture.
|
|
- ScreenCaptureKit screen stream proof with frame counters.
|
|
- ScreenCaptureKit system audio proof with best-effort PCM extraction to 16 kHz mono signed 16-bit little-endian frames.
|
|
- AVAudioEngine microphone proof with 16 kHz mono signed 16-bit little-endian frames.
|
|
- Separate microphone and system audio counters in the overlay.
|
|
- Compact HUD controls for Settings, Hide, and Quit.
|
|
- Draggable overlay title area.
|
|
- Settings panel with persisted overlay background opacity.
|
|
- Swift unit tests for status labels, PCM frame metadata, PCM S16LE encoding, and separate audio counters.
|
|
- App bundle build script at `native/MastermindPOC/scripts/build-app.sh`.
|
|
|
|
## Verified Automatically
|
|
|
|
- `swift test` passes for `MastermindPOCCore`.
|
|
- `swift build --product MastermindPOC` compiles the native executable.
|
|
- `native/MastermindPOC/scripts/build-app.sh` produces `native/MastermindPOC/build/MastermindPOC.app`.
|
|
- Existing Electron local provider tests pass when run outside the managed sandbox restrictions.
|
|
|
|
## Manual Verification Needed
|
|
|
|
- Launch `native/MastermindPOC/build/MastermindPOC.app`.
|
|
- Confirm the menu bar item is visible while the app runs.
|
|
- Confirm the overlay appears locally and can be hidden.
|
|
- Confirm the overlay can be dragged by its top title bar.
|
|
- Confirm the overlay Settings button opens the settings panel.
|
|
- Confirm the opacity slider changes only the HUD background opacity and persists across relaunches.
|
|
- Confirm the overlay Quit button exits the app.
|
|
- Confirm click-through lets pointer events pass to apps underneath.
|
|
- Grant Screen Recording permission when macOS prompts, then restart the POC if needed.
|
|
- Start `Screen + System Audio` and confirm screen frame and system PCM counters increase.
|
|
- Start `Microphone` and confirm microphone PCM counters increase while speaking.
|
|
- Confirm `Pause All Capture` stops screen, system audio, and microphone updates.
|
|
- Confirm app-owned screen capture does not include the Mastermind overlay.
|
|
|
|
## Boundary
|
|
|
|
This POC is not a stealth or anti-detection system. It shows a menu bar item while running, requests normal macOS permissions, and only excludes its own overlay from the context it captures for itself.
|
|
|
|
## Role in production migration
|
|
|
|
`native/MastermindPOC` proves that AppKit windowing, ScreenCaptureKit screen and system-audio capture, AVAudioEngine microphone capture, current-process exclusion, and 16 kHz PCM conversion are viable.
|
|
|
|
Production development moves to `native/Mastermind`. Validated capability code may be ported behind production boundaries, but the POC is not renamed into the product and is retired after parity checks pass.
|
|
|
|
The production design intentionally differs from the POC:
|
|
|
|
- the Companion Island is hidden at launch and anchored to the primary display's top center;
|
|
- enabled Collectors start continuously after onboarding instead of through manual start menu items;
|
|
- the Menu Bar Item uses a stable glyph with detailed states inside its menu;
|
|
- screen, microphone, and system-audio states are simultaneous per-Collector states rather than one `TrustStatus`;
|
|
- settings and management live inside the expanded Companion Island;
|
|
- screen context follows the active display rather than always selecting the main display;
|
|
- the Context Graph, Local Provider, local ASR client, retention, encryption, Context Receipts, and Activity Log are production requirements not implemented by the POC.
|