uttrflow / uttrflow/uttrflow-swift

Onboarding's last page draws letter, digit and F-key shortcuts as "Key 2", "Key 18", "Key 96"

Open Beginner friendly
#682 0 comments 0 reactions 0 assignees View on GitHub
area:general bug good first issue P2
Dominant language
Swift
Stars
4
Forks
17
Avg merge
3h 32m
Merged PRs (30d)
277

Description

## What happens

Onboarding's last page draws the dictation shortcut as keycaps with its own key-name table:

```swift
// Sources/UttrflowUX/OnboardingPresenter.swift:429-437
private static let names: [UInt16: String] = [
36: "Return", 48: "Tab", 49: "Space", 51: "Delete", 53: "Escape",
]
private static func name(for keyCode: UInt16) -> String {
names[keyCode] ?? "Key \(keyCode)"
}
```

Settings draws the same shortcut with `SettingsShortcut.keycaps(for:)`, whose table names every letter, digit, punctuation key, F-key, arrow and keypad key (`Sources/UttrflowUX/SettingsShortcut.swift:52-76`). `OnboardingKeys.of` already calls `SettingsShortcut` for held modifiers and for the modifier caps (`OnboardingPresenter.swift:423-427`), just not for the key.

So a shortcut such as ⌥D, ⌃⌘1 or ⌥F5 is shown on "You're all set" as ⌥ **Key 2**, ⌃ ⌘ **Key 18**, ⌥ **Key 96**, while Settings shows D, 1 and F5. The page reads settings at draw time (`OnboardingFlow.page`, `Sources/UttrflowUX/OnboardingFlow.swift:109-111`), so this shows whenever onboarding is reopened after the shortcut was changed (for example by the speech model repair path, `AppDelegate.repairSpeechModel`).

## Why it matters

The last onboarding page exists to teach the one key combination the user needs. "Key 2" teaches nothing, and the two windows disagree about the same shortcut.

## How to reproduce

`OnboardingKeys.of(HotkeyBinding(keyCode: 2, modifiers: [.option]))` returns `["⌥", "Key 2"]`; `SettingsShortcut.keycaps(for:)` on the same binding returns `["⌥", "D"]`.

## Acceptance criteria

- `OnboardingKeys.of` returns exactly `SettingsShortcut.keycaps(for:)` for every binding, and the private `names` table is deleted.
- A test in `Tests/UttrflowUXTests/OnboardingPresenterTests.swift` checks a letter, a digit and an F-key shortcut on the ready page against `SettingsShortcut.keycaps(for:)`.
- Existing onboarding tests for ⌥Space and for Fn still pass.

## Where to start

- `Sources/UttrflowUX/OnboardingPresenter.swift:418-437`.
- Run `make verify` (export `DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer` first) and read CONTRIBUTING.md.

**Size:** XS, under an hour.

Contributor guide

Open the contributing guide

Research direction

Start in Sources/UttrflowUX/OnboardingPresenter.swift:418-437 and compare OnboardingKeys.of with SettingsShortcut.keycaps(for:). Add the requested coverage in Tests/UttrflowUXTests/OnboardingPresenterTests.swift for a letter, digit and F-key, while preserving the existing Space and Fn tests. Run make verify with DEVELOPER_DIR set, and done means both paths return matching keycaps without the private names table.

Written by the indexing model from the issue text.

Assessment

Tech stack
swift
Domain
desktop
Issue type
Bug
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
92/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.