uttrflow / uttrflow/uttrflow-swift
Onboarding's first-dictation copy says "one key", "in this window" and "hold", whatever the shortcut and activation mode
- Dominant language
- Swift
- Stars
- 4
- Forks
- 17
- Avg merge
- 3h 32m
- Merged PRs (30d)
- 277
Description
## What happens
Three sentences in onboarding describe the first dictation in ways that do not match what the user has in front of them (`Sources/UttrflowUX/OnboardingPresenter.swift`):
1. **Welcome** (`:128-131`): "Hold one key, say what you mean, and Uttrflow writes it into whatever app you're in". The default shortcut is ⌥Space (`ShortcutSet.default`, `Sources/UttrflowCore/Keyboard/ShortcutSet.swift:17-22`), two keys, and the last page draws it as two keycaps.
2. **You're all set** (`:222-227`): subtitle "Try it right now, in this window or any other." The onboarding window has no text field (`Sources/Uttrflow/Onboarding/OnboardingView.swift` draws text, keycaps, notes and buttons only), so a dictation "in this window" has nowhere to land.
3. **You're all set** body "Hold it, talk, let go." and **You're set, with one catch** body "Hold the shortcut, talk, let go — then paste." (`:225`, `:239`) always say hold, whatever `Settings.hotkeyActivation` is. Onboarding already reads settings at draw time (`OnboardingFlow.page`), and the main window chooses "Hold" or "Press" from the same setting (`Sources/UttrflowUX/MainDictationPresentation.swift:392-393`, `Sources/UttrflowUX/HomePresentation.swift:358-364`). Onboarding can be reopened after the setting was changed (the speech model repair path opens it).
## Why it matters
This page is the whole guide to the first dictation. A new user who takes "in this window" literally holds the shortcut over the onboarding window, talks, and sees nothing typed, which is the worst possible first result. The same misunderstanding is what #505 fixes on Home.
## How to reproduce
Read the strings above, or finish onboarding and try the suggested dictation without moving to another app.
## Acceptance criteria
- The welcome body does not say "one key" (for example "Press a shortcut, say what you mean…").
- The ready subtitle points at another app, for example "Click into any text field — a note, an email, a chat — and try it." Keep it one sentence.
- The ready and pastes-manually bodies say "Press" rather than "Hold", and drop "let go", when `hotkeyActivation` is `.pressToToggle`. `OnboardingPresenter.page(for:hotkey:)` will need the activation as well as the binding.
- Tests in `Tests/UttrflowUXTests/OnboardingPresenterTests.swift` cover both activation modes on the two last-page endings that show keycaps.
## Where to start
- `Sources/UttrflowUX/OnboardingPresenter.swift:121-134` and `:215-247`; `OnboardingFlow.page` at `Sources/UttrflowUX/OnboardingFlow.swift:109-111` passes the settings in.
- Run `make verify` (export `DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer` first) and read CONTRIBUTING.md.
**Size:** S, about 1–2 hours.
Contributor guide
Research direction
Start with Sources/UttrflowUX/OnboardingPresenter.swift at the welcome and final-page strings, then trace OnboardingFlow.page in OnboardingFlow.swift to see how settings reach the presenter. Read Tests/UttrflowUXTests/OnboardingPresenterTests.swift and run its tests; done means both activation modes have coverage and the onboarding copy matches the shortcut, destination, and activation behavior, with make verify passing.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- swift
- Domain
- desktop, testing
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100