Create slim PrivateVoice2 handoff package

Ariver

2026-07-02 abb469859662c285fac758c042812e0da943728f

 CODEGRAPH.md

@@ -3,20 +3,22 @@
## Project

- Product: Wails v3 / Go desktop dictation app.
- Git root: `/Users/ar/Projects/PrivateVoice2/03-O`.
- Source root: `/Users/ar/Projects/PrivateVoice2/03-O/C1.source/privatevoice.src`.
- Current branch purpose: Round 6 Cantonese language version real-user test package based on `v2.2.0-build20260702.0303`.
- Protected macOS behavior: existing macOS App Store / local DMG build lines are not changed by this branch.
- Protected behavior: existing macOS App Store, local DMG, Monterey compatibility, Windows preview, model download safety, and paste/clipboard protection must not be changed without a scoped task and QA plan.

## Core Entrypoints

- `privatevoice.src/main.go`: process startup, data migration, logger, single-instance guard.
- `privatevoice.src/app.go`: Wails app wiring, settings window, tray, recorder, hotkey loop, ASR init, paste orchestration.
- `privatevoice.src/embed.go`: embeds frontend assets and app/tray icons.
- `C1.source/privatevoice.src/main.go`: process startup, data migration, logger, single-instance guard.
- `C1.source/privatevoice.src/app.go`: Wails app wiring, settings window, tray, recorder, hotkey loop, ASR init, paste orchestration.
- `C1.source/privatevoice.src/embed.go`: embeds frontend assets and app/tray icons.

## Language And Model Registry

- `privatevoice.src/internal/model/profile.go`: model and language IDs, model profile shape, install status types.
- `privatevoice.src/internal/model/registry.go`: language profile order, model profiles, language profiles, and normalization.
- `privatevoice.src/internal/modelselection/selection.go`: resolves current language and model, including manual-model fallback.
- `C1.source/privatevoice.src/internal/model/profile.go`: model and language IDs, model profile shape, install status types.
- `C1.source/privatevoice.src/internal/model/registry.go`: language profile order, model profiles, language profiles, and normalization.
- `C1.source/privatevoice.src/internal/modelselection/selection.go`: resolves current language and model, including manual-model fallback.
- Round 6 Cantonese path:
  - Language ID: `yue-HK`, displayed as `粤语`.
  - Default model: `sensevoice-yue-2025-09-09`.
@@ -25,23 +27,20 @@

## Platform Modules

- Audio: `privatevoice.src/internal/audio/recorder.go`
  - Uses `github.com/gen2brain/malgo`.
  - Cross-platform capture target: 16 kHz, 16-bit, mono.
- Audio: `C1.source/privatevoice.src/internal/audio/recorder.go`
- Hotkey:
  - macOS: `privatevoice.src/internal/hotkey/hotkey_darwin.go`
  - Windows: `privatevoice.src/internal/hotkey/hotkey_windows.go`
  - macOS: `C1.source/privatevoice.src/internal/hotkey/hotkey_darwin.go`
  - Windows: `C1.source/privatevoice.src/internal/hotkey/hotkey_windows.go`
- Text input:
  - macOS: `privatevoice.src/internal/input/paste_darwin.go`
  - Windows: `privatevoice.src/internal/input/paste_windows.go`
  - macOS: `C1.source/privatevoice.src/internal/input/paste_darwin.go`
  - Windows: `C1.source/privatevoice.src/internal/input/paste_windows.go`
- ASR engine:
  - macOS: `privatevoice.src/internal/engine/engine_darwin.go`
  - Windows: `privatevoice.src/internal/engine/engine_windows.go`
  - Linux: `privatevoice.src/internal/engine/engine_linux.go`
  - SenseVoice profiles may set `Profile.LanguageParam`; Cantonese uses `yue`.
  - macOS: `C1.source/privatevoice.src/internal/engine/engine_darwin.go`
  - Windows: `C1.source/privatevoice.src/internal/engine/engine_windows.go`
  - Linux: `C1.source/privatevoice.src/internal/engine/engine_linux.go`
- Overlay:
  - macOS: `privatevoice.src/internal/overlay/overlay_darwin.go`
  - Windows: `privatevoice.src/internal/overlay/overlay_windows.go`
  - macOS: `C1.source/privatevoice.src/internal/overlay/overlay_darwin.go`
  - Windows: `C1.source/privatevoice.src/internal/overlay/overlay_windows.go`

## Windows Preview Scope

@@ -49,31 +48,21 @@
- Non-SenseVoice models remain visible in settings but are disabled through `model.IsModelSupportedInCurrentBuild`.
- Windows unsupported reason: `windows_preview_unsupported`.
- Windows overlay remains native Win32/GDI+, with a larger translucent spectrum-style capsule indicator for recording states.
- Build script: `privatevoice.src/scripts/build-windows-preview.sh`.
- Evidence verifier: `privatevoice.src/scripts/verify-windows-qa-evidence.sh`.
- Runtime package includes:
  - `PrivateVoice Dictation.exe`
  - `onnxruntime.dll`
  - `sherpa-onnx-c-api.dll`
  - `sherpa-onnx-cxx-api.dll`
  - `RUN-WINDOWS-QA.cmd`
  - `QA-WINDOWS-PREVIEW.ps1`
  - `README-WINDOWS-PREVIEW.txt`
- Build script: `C1.source/privatevoice.src/scripts/build-windows-preview.sh`.
- Evidence verifier: `C1.source/privatevoice.src/scripts/verify-windows-qa-evidence.sh`.

## macOS Local Package Scope
## macOS Package Scope

- Local DMG script: `privatevoice.src/scripts/build-local-macos.sh`.
- Universal DMG script: `privatevoice.src/scripts/build-local-macos-universal.sh`.
- Local macOS package set for this branch:
  - `arm64` DMG for Apple Silicon.
  - `x86_64` DMG for Intel Mac.
  - `universal` DMG for Intel + Apple Silicon.
- Mainline macOS local packages keep `LSMinimumSystemVersion=14.0` and the default Qwen3-capable dependency line.
- Monterey-compatible packages remain a separate build line through `privatevoice.src/scripts/build-local-macos-monterey.sh`.
- Local DMG script: `C1.source/privatevoice.src/scripts/build-local-macos.sh`.
- Universal DMG script: `C1.source/privatevoice.src/scripts/build-local-macos-universal.sh`.
- Monterey compatibility script: `C1.source/privatevoice.src/scripts/build-local-macos-monterey.sh`.
- Developer ID / notarization script: `C1.source/privatevoice.src/scripts/build-release-macos.sh`.
- Mainline macOS local packages keep `LSMinimumSystemVersion=14.0`.
- Monterey-compatible packages remain a separate build line.

## Standard Verification Commands

Run from `privatevoice.src`:
Run from `C1.source/privatevoice.src`:

```bash
npm --prefix frontend run build
@@ -88,8 +77,7 @@

## Known Gaps

- Windows runtime QA must still be performed on Windows 10/11 hardware.
- Run `RUN-WINDOWS-QA.cmd` from the extracted preview package to collect WebView2/audio preflight, startup, engine, recording, recognition, paste, and Notepad target text evidence.
- After evidence is returned, run `verify-windows-qa-evidence.sh` and require `WINDOWS_QA_EVIDENCE_PASS` before claiming the goal complete.
- The Windows preview zip is unsigned and not an installer.
- SmartScreen / Defender prompts are expected for local testing.
- Windows runtime QA must still be performed on Windows 10/11 hardware before calling Windows stable.
- macOS 2.2.0 real-user test DMGs are locally signed and not notarized.
- Monterey compatibility was not revalidated for the 2.2.0 package set.
- Independent-site sales still need Developer ID release packaging, download page, authorization/activation, update strategy, support path, release manifest, and rollback policy.