uttrflow / uttrflow/uttrflow-swift

Add an app compatibility matrix: which insertion route, paste confirmation, caret and context each kind of app actually gives

Open
#599 1 comment 0 reactions 0 assignees View on GitHub
area:general documentation help wanted P2
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.