uttrflow / uttrflow/uttrflow-swift
Add an app compatibility matrix: which insertion route, paste confirmation, caret and context each kind of app actually gives
- Dominant language
- Swift
- Stars
- 4
- Forks
- 17
- Avg merge
- 3h 32m
- Merged PRs (30d)
- 277
Description
## What is missing
Dictation, clipboard paste-back and AI suggestions all depend on how *other* apps publish text through Accessibility, take a synthetic ⌘V, and report a caret rectangle. What is known is scattered over seven documents, each measured separately and some of them contradicting each other:
- `Docs/insertion.md` and `Docs/input-paste-eligibility.md`: which apps refuse the Accessibility write.
- `Docs/context-accessibility.md`: which apps give a window title and a selection (a three-row table).
- `Docs/predict-ime.md`: which toolkits publish `AXTextInputMarkedRange`.
- `Docs/predict-reliability.md`: browser editors, apps built on a bundled browser engine, and cross-platform-toolkit IDEs that publish nothing.
- `Docs/predict-probe.md`: the surface capability table, still empty (#101).
- `Docs/input-synthetic-keystrokes.md`: what posted events contain, with no per-app results.
```
$ git grep -n -i "compatib" -- Docs README.md CONTRIBUTING.md
(no output)
```
There is no single place that says "in this kind of app, this is what works". Nor is there a way for a contributor to add a row by testing one app they already use.
## Proposal
A new `Docs/compatibility.md`: one table per app class, one row per app version tested, with no marketing claims, filled only from runs of the existing tools (`uttrflow-dev insert --via …`, `uttrflow-dev probe surface`, `uttrflow-dev probe ime`) and a short manual check.
| Column | Values | How it is measured |
|---|---|---|
| App, version, macOS version | text | About window |
| Class | browser (engine) / bundled-browser-engine app / native AppKit / cross-platform toolkit / terminal / office / remote or VM / game | by inspection |
| Field tested | e.g. single-line, multi-line, rich editor, spreadsheet cell, secure | by inspection |
| Focused field published | yes / no / only after `AXManualAccessibility` | `uttrflow-dev probe surface` |
| Accessibility write | lands / refused / reports success, changes nothing / lands late | `uttrflow-dev insert --via accessibility` |
| Paste | lands / ignored / other shortcut fires / forwarded elsewhere | `uttrflow-dev insert --via paste` |
| Paste confirmation | landed / not reported / gave up | same run's printout |
| Full route result | once / twice / nowhere | `uttrflow-dev insert` |
| Caret rectangle | right / wrong place / none | `uttrflow-dev probe surface` plus a look |
| Value and selection readable | yes / value only / no | `uttrflow-dev probe surface` |
| Marked text (IME) published | yes / no | `uttrflow-dev probe ime` |
| Typed completion | correct / wrong characters / nothing | accept a suggestion |
| Notes | line breaks, undo, RTL, anything surprising | |
Each cell that is not a measurement stays blank. "Unknown" is a valid answer; a guess is not.
## Acceptance criteria
- `Docs/compatibility.md` exists with the columns above, a short "how to add a row" section, and at least the rows the maintainers can fill from the existing docs, each linked to the document it came from.
- The seven documents above link to it and stop keeping their own partial tables, or say which column they feed.
- `Docs/README.md` lists it, and the per-class testing issues filed alongside this one link to it.
- The docs audit in `make verify` passes.
Contributor guide
Research direction
Start with Docs/insertion.md, Docs/input-paste-eligibility.md, Docs/context-accessibility.md, Docs/predict-ime.md, Docs/predict-reliability.md, Docs/predict-probe.md, and Docs/input-synthetic-keystrokes.md. Run the existing uttrflow-dev insert and probe commands while checking Docs/README.md and the make verify audit. Done means Docs/compatibility.md has the specified columns, measured rows and contribution instructions, with the seven source documents and README linked or updated as described.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- macos, swift
- Domain
- accessibility, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 68/100