Learn dictionary entries from the user's corrections, reviewed on device (#37)

[dinooo13]

Stacked on #54 (feature/36-polish-hotkey): it reuses #54's OnDeviceLanguageModel wrapper. The base is #54's branch, so the diff shows only this feature.

What

After a paste, Pladder watches the field it pasted into and proposes a dictionary rule for a word the user fixes by hand.

1. AppModel.handle(.inserted) passes the pasted text to CorrectionLearner.pasted, but only with the Accessibility grant. That handler runs after the coordinator has emitted inserted.
2. AXPasteObserver (PladderSystem) runs on its own run-loop thread and finds the paste just before the caret, trying it with and without the trailing space. It reads a window of the paste plus a margin on each read, never the whole field. It reads on every AXValueChanged and stops after 60 s, when focus leaves, when the app deactivates or when the element is destroyed.
3. CorrectionDiff (Core, pure) aligns the window as it was when the paste was found against the last reading that still holds it. The alignment is a token LCS with punctuation as token boundaries. A pair has one or two words per side and must lie wholly inside the paste. Case-only changes, insertions, deletions and rewrites yield nothing.
4. Pairs already in the dictionary or dismissed earlier are dropped. PhoneticGate then drops pairs that do not sound alike: it passes a pair on a Soundex match or an edit distance of at most 2, and requires distance 1 for keys of 3 characters or fewer. Only the survivors go to FoundationModelsCorrectionReviewer (PladderRefine, on On-device LLM polish on a second hotkey via Apple Foundation Models #36's OnDeviceLanguageModel), which returns a guided yes/no with one plain-text fallback.
5. Each yes becomes a menu line, Learned “Claud” → “Claude”?, with an Add / Dismiss submenu. There are at most three lines, newest first. Add merges the pair into settings.dictionary, overwriting a rule with the same from. Dismiss records the pair in ~/Library/Application Support/Pladder/dismissed-corrections.json.

Menu, not a toast. The overlay is click-through and never becomes key by construction, and the Menu Bar style shows no pill at all. A proposal that arrives a minute later should wait rather than interrupt. The menu bar glyph is unchanged, as decided.

Dismissed pairs in their own file, not in Settings. Every settings assignment is compared, saved and rebuilds the pipeline, and SettingsStore moves an undecodable file aside, so a bug in this feature could cost the user their dictionary. The separate file can only cost itself.

The feature has no setting. Without Accessibility or Apple Intelligence nothing is watched and nothing is shown.

Critical path (in place of a benchmark)

No code between recordingStopped and inserted changes:

git diff feature/36-polish-hotkey -- Sources/PladderCore/DictationCoordinator.swift Sources/PladderCore/Processors Sources/PladderSystem/PasteboardOutput.swift

The diff is empty. The plan's four private removals in CustomWordCorrector.swift were not made either (see deviations). The one hook is a defer in AppModel.handle(.inserted), which runs on the main actor after the event that ends the measured window, and it only spawns a detached task. For completeness, the integration build of #36, #37 and #38 benches within noise of main (see #55).

Tests

swift build, swift build -c release and swift test pass. Core: 272 tests in 0.54 s. System: 16. Refine: 13. The other targets are unchanged. 54 new tests:

• CorrectionDiffTests (23): substitution, phrase to word and word to phrase, punctuation boundary, punctuation-changing hunk dropped, apostrophes and hyphens, case-only change, insertions and deletions, three-word spans, rewrites (four hunks and more than 50 %), margin edits ignored, a change reaching into the margin ignored, a one-word paste anchored by its margin, a one-word paste into an empty field, long tokens, control characters, the last anchored reading (chat send), a reading without the anchor skipped, an undone fix, no readings, an unchanged field, the trailing-space variant, text order.
• PhoneticGateTests (7): Soundex, distance 2, Friday/Monday, umlaut/ß, phrases without spaces, the short-key guard, unrelated words.
• CorrectionLearnerTests (12, in-memory fakes for the observer and the model): accept, reject, gate before review, dismissed, already in the dictionary, observer nil, model unavailable (observer never called), reviewer error drops only that pair, two pastes independent, cap of 3, the sentence the reviewer sees, the 400-character cut.
• DismissedCorrectionsTests (4): round trip, case-insensitive matching, missing file, unreadable file left in place.
• AXPasteObserverTests (5): returns nil in under 100 ms without the grant (the grant is stubbed, so the test never reads the live field), plus the window arithmetic and the margin/paste/margin split.
• CorrectionReviewPromptTests (3): the yes/no parser and the prompt. Nothing calls the model.

Deviations from the plan

1. CustomWordCorrector.swift is untouched. PhoneticGate has its own 25-line Soundex. That file sits on the release-to-paste path, and a feature that runs after the paste should leave it alone.
2. PasteObservation carries before / after, the window's margins as they were when the paste was found, and the diff aligns the whole window. This anchors a one- or two-word paste on the text around it; under the plan's rule it could never reach 60 % coverage. It also separates a correction of the dictation from the user editing their own text next to it. A hunk touching the margin is ignored.
3. Anchor and rewrite rules adjusted for short pastes. Coverage is floor(0.6 × words) of the window, and readings with no words (an emptied field) are always skipped. The rewrite threshold is max(2, 50 %) of the paste's tokens, and "more than 3 hunks" counts substitutions inside the paste.
4. CorrectionLearner is a Sendable final class, not an actor. It has no mutable state. pasted returns its detached Task, so tests await it instead of polling.
5. Reviewer errors are thrown, not turned into false. The learner drops the pair and logs the reason. The outcome is the same and the log is more useful.
6. The observer finds the focused element via AXFocusedApplication, then that app's AXFocusedUIElement, rather than the system-wide focused element. This gives the pid even when Chromium has not built its tree yet. AXManualAccessibility is set once per pid when the first read finds no text field.
7. The window end follows the field's length (windowEnd + Δcount), capped at twice the window plus 1024.
8. AXPasteObserver.init(isTrusted:) is injectable so the test never depends on the harness's real grant. A harness started from a trusted terminal is itself trusted and would otherwise watch the developer's live field.
9. AXThread.finish does not wait for the run loop. A thread cancelled before main runs never publishes one, and the first test run hung on exactly that. GlobalHotkeyMonitor.TapThread has the same latent bug but was left alone: it lives for the app's life and is out of scope.
10. German menu line: „%1$@“ → „%2$@“ ins Wörterbuch?, with Hinzufügen and Verwerfen.
11. Not dependent on On-device LLM polish on a second hotkey via Apple Foundation Models #36's drain behaviour. The reviewer uses the wrapper's timeout (10 s) and nothing else. A stuck drain would only stall that paste's background task.

Manual test recipe

• Build and install: ./scripts/bundle.sh --install. This quits the running Pladder, so pick a moment.
• Check that Apple Intelligence is on (System Settings › Apple Intelligence & Siri). Without it the feature is absent by design.
• TextEdit. In a new document, dictate "I tried Claud in Claude Code today", or any sentence with a name the engine misspells. Fix the misspelled word by hand. Either wait up to 60 s or click into another window. Open the menu bar menu: it should show Learned “Claud” → “Claude”? with Add / Dismiss. Click Add. Dictate the sentence again: the word should come out corrected. The Dictionary tab should show the new row.
• Browser. In Safari, then Chrome if available, open data:text/html,<textarea rows=6 cols=60></textarea> or a GitHub comment box, and repeat the steps. In Chrome the first dictation after launch may show no proposal, because the accessibility tree is switched on during that first watch. The second should show one.
• Negative. Dictate, then reword the sentence: there should be no proposal. Dictate, fix a word and click Dismiss: the pair should appear in ~/Library/Application Support/Pladder/dismissed-corrections.json and should not be proposed after the next identical correction.
• Send. In Slack, Messages or a Claude web chat, dictate, fix a word and press Return within a second. The proposal should still appear, because the reading taken before the field emptied is used.
• Terminal. Dictate into a shell or Claude Code and fix a word. There should be no proposal and nothing in the log beyond no anchor or "not a text field". This is expected: v1 learns nothing in terminals or TUIs.
• Log. Run /usr/bin/log show --last 30m --style compact --predicate 'subsystem == "de.dinooo13.pladder" AND category == "learning"'. The release-to-paste lines (category == "timing") should look as before.
• Do one German dictation and correction, so the German menu line is seen once.

Open questions

1. Discoverability. The proposal is a menu line only, as decided. Revisit after a week of use if the lines go unseen.
2. Terminals. Nothing is learned in terminals or TUIs. There is no AX path to a TUI's input line, and the docs say so.
3. Case-only changes stay excluded, as the issue says. "github" → "GitHub" would be a useful rule; a follow-up could allow a case change when the capital is not at position 0.

Review notes

• A review call and a polish call share the one system model, which serialises requests. A polish dictation that lands while a review is running waits for it, usually under a second. Reviews run about a minute after a paste, so this is rare. It is left as it is.
• Once On-device LLM polish on a second hotkey via Apple Foundation Models (#36) #54 merges, retarget this PR to main.

Closes #37

🤖 Generated with Claude Code

[dinooo13]

Live test found three bugs, fixed on this branch

1. The reviewer said no to everything (a689be8). A hand fix went through the diff and the gate, and the model then rejected it every time, "Claud" → "Claude" included, so nothing was ever proposed. The model is now asked whether CORRECTED is a name, brand, product, place or technical term, as two guided fields of which the first decides. Against the real model on 16 labelled pairs the old prompt scored 6/16 (every answer "no") and the new one 15/16 on two runs. The one miss, cat → dog, is dropped by the phonetic gate first.
2. Safari: "no focused application" (848a895 on the integration branch, from this branch). The system-wide AXFocusedApplication came back empty with Safari frontmost. The watcher now falls back to NSWorkspace.frontmostApplication.
3. Safari: the watch ended 100 ms after the paste (055b8c2). WebKit posts AXFocusedUIElementChanged after a paste with a new object for the same textarea. The watch now ends only when its element reports that it lost focus. Notification names (no user text) are now logged.

Live results (integration build, own settings file)

• TextEdit: "…every message with platter." fixed by hand to "Pladder". The menu showed Learned “platter” → “Pladder”?. Add wrote {"from":"platter","to":"Pladder","matchCase":false}, and the next dictation of the same sentence came out "Pladder".
• Safari textarea: "built with Swift2i and chips on GitHub" fixed to "SwiftUI … ships". Both were proposed. "Swift2i" → "SwiftUI" is right; "chips" → "ships" is a false positive (the model took "ships" for a term). Dismiss removed the line and wrote the pair to dismissed-corrections.json next to the settings file.
• Release-to-paste lines were unchanged throughout (0.16 to 0.23 s).

Known limit: when an ordinary word is fixed into another ordinary word that the model reads as a term in context (chips → ships "on GitHub"), the pair is still proposed. Dismiss handles it, and the pair is never proposed again. Rejecting every pair whose misheard side is a real word would also block the main case, since recognisers turn names into real words ("platter" for Pladder).