GroqDictate — Product Behavior Specification

# GroqDictate — Product Behavior Specification

## 0. Product Intent

GroqDictate is a macOS menu bar dictation tool that should feel like a **single global shortcut**, not a traditional app.

Core loop:
1. Press **Right ⌘** to start recording.
2. Press **Right ⌘** again to stop and transcribe.
3. Transcript is pasted into the app the user is currently working in.

Design priorities:
- **Minimalism**: no dock/app-switcher presence during normal use.
- **Speed**: low start latency and low stop→paste latency.
- **Predictability**: focus, keyboard handling, and errors behave consistently.
- **Polish**: no raw backend noise in UI, clear next actions.

---

## 1. UX Principles

1. **User intent beats implementation convenience**.
   - If user changes app while recording/processing, paste should follow user’s latest context.
2. **Settings flow and dictation flow are independent**.
   - Returning from Settings should not corrupt dictation target behavior.
3. **Cancel is immediate when system allows it**.
   - Esc should dismiss active dictation states whenever event capture is available.
4. **Errors are actionable, not technical dumps**.
   - Show concise friendly messages; keep raw details for logs.
5. **Accessory app constraints are acknowledged explicitly**.
   - Some keyboard behavior is OS-limited (permissions, Secure Input).

---

## 2. Implementation Principles & Code Ownership

Implementation is split by responsibility:
- `Sources/App/` — app lifecycle orchestration and state transitions
- `Sources/Core/` — constants, shared strings, config/keychain primitives
- `Sources/Services/` — system integrations (audio, hotkeys, focus, networking)
- `Sources/UI/` — panel + settings rendering and view-local behavior

Rules:
1. `App` coordinates state; it does not render complex UI directly.
2. `Services` own side-effecting integrations; they do not decide UX copy.
3. `UI` renders state; it does not own business transition logic.
4. `Core` remains dependency-light and free of app lifecycle side effects.

---

## 3. App Mode & Surface Area

- App activation policy: `.accessory` (LSUIElement-style behavior).
- Primary UI surfaces:
  1. Menu bar item
  2. Floating non-activating panel (recording/processing/errors)
  3. Settings window
- No persistent main window.

---

## 4. First Launch & Onboarding

### 4.1 First launch without API key
- Show Settings window as onboarding.
- API key field is focused and ready for paste.
- Cmd+V, Cmd+C, Cmd+X, Cmd+A must work in text fields.

### 4.2 Validation on save
- API key cannot be empty.
- API key must start with `gsk_`.
- On valid save, persist:
  - API key in Keychain
  - model/mic/gain in UserDefaults

### 4.3 Closing without save
- X closes Settings, no save.
- App remains in menu bar.
- Next launch reopens onboarding until valid key exists.

---

## 5. Settings Behavior

### 5.1 Opening
Settings can be opened via:
- menu bar item
- Cmd+,
- relaunch while idle

### 5.2 Focus behavior
- On open: capture `settingsReturnApp` (last non-GroqDictate frontmost app at open time).
- On close (Done or X): reactivate `settingsReturnApp` when possible.
- Settings focus lifecycle is independent from dictation target lifecycle.

### 5.3 Single settings context
- Opening Settings repeatedly should not create user-confusing duplicate settings contexts.

---

## 6. Permissions Model

### 6.1 Microphone
- Requested after successful onboarding save.
- If denied/restricted: recording cannot start; user gets actionable message and deep-link to microphone privacy pane.

### 6.2 Accessibility / event capture
- App attempts privileged global event capture for reliable key handling.
- If unavailable, fallback behavior remains usable for core flow where system permits.

### 6.3 System constraints
- Under Secure Input or missing permissions, global key interception can be reduced or unavailable.
- App must fail gracefully with clear user-facing guidance, not silent failure.

---

## 7. Keyboard Interaction Contract

### 7.1 Right ⌘
- Idle → Start recording
- Recording → Stop and transcribe
- Processing → ignored
- Error state → executes error-specific action (retry/new/settings/etc.)

### 7.2 Esc
- Recording → cancel and dismiss
- Processing → cancel UI state and ignore late callback
- Error → dismiss and cleanup
- Idle → pass through

Esc is **best-effort global cancel** subject to macOS event-capture limitations.

---

## 8. Dictation Focus Model (Authoritative)

GroqDictate maintains two independent focus references:
1. `settingsReturnApp` — used only for settings close behavior.
2. `dictationTargetApp` — used only for paste/cancel return behavior.

### 8.1 Dictation target policy (dynamic)
- On recording start, initialize `dictationTargetApp` to current non-self frontmost app.
- While recording/processing, update `dictationTargetApp` whenever user activates another non-self app.
- Reopen events must not accidentally overwrite target with GroqDictate itself.

Result: transcript pastes into the app the user is most recently working in.

### 8.2 Failure tolerance
- If target app terminates before paste, app must not crash.
- Transcript remains in clipboard; app falls back safely.

---

## 9. Floating Panel Specification

### 9.1 Window behavior
- `NSPanel` non-activating
- floating level
- joins all Spaces
- does not steal key focus from user app
- excluded from standard window cycling/exposé contexts where appropriate

### 9.2 Lifecycle
- Created once and reused.
- `show()` repositions and orders front.
- `dismiss()` resets visual state and hides (no destroy/recreate cycle).

### 9.3 Visual states
1. Recording
   - top: live waveform
   - bottom-left: recording label
   - bottom-right: esc hint
2. Processing
   - top: shimmer animation
   - bottom-left: transcribing label
   - bottom-right: esc hint
3. Error
   - top: concise friendly message
   - bottom-left: context action if available
   - bottom-right: esc dismiss hint

No raw JSON or backend payload text is shown verbatim.

---

## 10. Recording & Audio Pipeline

- Audio format: 16kHz, mono, 16-bit PCM WAV.
- Input gain applied in callback path.
- Optional specific mic selection supported.
- Temp file location: `$TMPDIR`.
- On stop: finalize WAV, trim leading/trailing silence, then apply FLAC compression threshold.
- Interior pauses are preserved.
- Cleanup policy:
  - success: cleanup
  - cancel: cleanup
  - dismiss error: cleanup
  - retryable error: preserve last file for retry

---

## 11. Transcription Network Behavior

- Endpoint: `POST /openai/v1/audio/transcriptions`
- Session tuned with explicit request/resource timeouts.
- Warm connection strategy at startup for first-request latency reduction.
- Retry policy for transient transport failures (timeout/connection-loss class).

---

## 12. Error Handling Policy

### 12.1 Sources of error
- transport/network failures
- HTTP status errors
- empty/invalid transcription body
- local read/write/audio failures

### 12.2 Groq status coverage (minimum)
- 400 bad request
- 401 unauthorized
- 403 forbidden (including account/org restrictions)
- 404 not found
- 413 payload too large
- 422 unprocessable
- 424 failed dependency
- 429 rate limit
- 498 capacity exceeded
- 500/502/503 server errors

### 12.3 UI mapping requirements
- Every error state must map to:
  - concise top-line message
  - optional action (`retry`, `new`, `settings`)
  - Esc dismiss behavior

### 12.4 Message extraction
When response body includes structured error JSON, prefer:
1. `error.message` (sanitized)
2. fallback to status-based friendly text
3. never display full raw payloads directly in panel

### 12.5 Retry categories
- Retryable: timeout, transient network, 429, 500/502/503, temporary capacity issues
- New recording required: too large (413)
- Settings-required: invalid auth/config (401 and relevant config failures)

---

## 13. Reopen / Relaunch / Quit

### 13.1 Reopen while idle
- Open Settings.

### 13.2 Reopen while recording/processing/error panel visible
- Do not disrupt active dictation state.
- Bring panel to user attention (non-destructive behavior).
- Preserve dictation target intent.

### 13.3 Quit and relaunch
- With saved key: app initializes ready state.
- Without saved key: onboarding settings reappears.

---

## 14. Menu Bar

Menu includes:
- informational shortcut hints
- Settings… (Cmd+,)
- Quit (Cmd+Q)

Menu interactions must not destabilize active dictation state.

---

## 15. Performance & Perceived Speed

Targets:
- fast panel appearance after trigger
- low stop→paste latency
- no unnecessary blocking operations on main thread in critical interaction path

Perceived performance:
- processing animation should feel responsive but not jittery
- state transitions should be immediate and visually coherent

---

## 16. Reliability Constraints & Non-Goals

### 16.1 Explicit constraints
- Global key capture is limited by macOS permissions and Secure Input contexts.
- App must communicate these limits clearly.

### 16.2 Non-goals (for now)
- full long-audio chunking pipeline
- complex background job orchestration
- broad multi-window UI surface

---

## 17. Acceptance Criteria (Release Gate)

A build is releasable only if:
1. Focus/paste target behavior matches dynamic-target policy across app/space switching.
2. Esc cancel behavior is correct where event capture is available, and graceful where unavailable.
3. Error UI is clean/actionable, including 403 restricted-account scenarios.
4. Success/cancel/retry flows do not leak temp files or crash under repeated usage.
5. Reopen/relaunch behavior does not corrupt active dictation state.
6. Module boundaries remain intact (`App`, `Core`, `Services`, `UI`) with no ownership leakage.

---

## 18. Source of Truth Relationship

- This file defines expected product behavior.
- `QA.md` is the executable verification plan for this behavior.
- If behavior changes, update **both** spec and QA together in the same revision.