uttrflow / uttrflow/uttrflow-swift

Test one desktop app built on a bundled browser engine and report a compatibility row

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

Description

## What this is

One row for the compatibility matrix (#599), measured in a chat, notes or code-editor app that bundles its own browser engine. Uttrflow's dictation, clipboard paste and AI suggestions all depend on how other apps publish text, and the only way to know what a given app does is to try it. No code changes are needed, just one app you already use.

Test the main composer or editor. Run the probe twice: once as is, and once with a screen reader turned on and then off again, because these apps publish their fields only after an assistive app asks (#605). Note whether the result changes.

Please say in a comment which app you are taking, so two people do not test the same one. Another app of the same class is a separate row, and welcome on this issue too.

## Where to start

- **Read first:** `CONTRIBUTING.md` for building, and the compatibility matrix issue (MATRIX) for the table you are filling.
- **Build the tool:** `swift build -c release --product uttrflow-dev`.
- **Grant Accessibility:** System Settings › Privacy & Security › Accessibility, add `.build/release/uttrflow-dev`. Accessibility is granted per binary, so the app's own grant does not cover it.
- **Test data:** use invented text only, such as `the quick brown fox` or `support@example.com`. No real names, addresses or messages.

## What to run, in one field of one app

1. Click into the field before each countdown ends.
2. `uttrflow-dev probe surface --seconds 30`: note whether a focused field, value, caret rectangle and text style are reported.
3. `uttrflow-dev insert --via accessibility "one two three four five six seven"`: did it land, get refused, report success and change nothing, or land a moment later?
4. `uttrflow-dev insert --via paste "one two three four five six seven"`: did it land? What did the tool print about confirmation?
5. `uttrflow-dev insert "one two three four five six seven"` (the full route): did the words appear once, twice, or not at all?
6. If you use AI suggestions: accept one suggestion and describe exactly what arrived and where the ghost was drawn.
7. `uttrflow-dev probe ime` while composing with an input method, if you use one.

## What to report

Paste this filled in as a comment, or open a PR adding the row to `Docs/compatibility.md`:

```
App / version:
macOS version / Mac:
Keyboard layout / input source:
Field tested:
Focused field published:
Accessibility write:
Paste:
Paste confirmation:
Full route result:
Caret rectangle:
Value and selection readable:
Marked text published:
Typed completion:
Notes:
```

**Size:** about an hour for one app. One app per comment is plenty, and partial rows are welcome; leave a cell blank rather than guessing.

`make verify` only matters if you open a PR against the doc.

Contributor guide

Open the contributing guide

Research direction

Read CONTRIBUTING.md and the compatibility matrix issue, then build with `swift build -c release --product uttrflow-dev` and grant Accessibility to the binary. Choose one chat, notes, or code-editor app and run the listed probe and insert commands with invented text, including the screen-reader comparison. Done means reporting the completed compatibility fields in a comment or adding the row to `Docs/compatibility.md`.

Written by the indexing model from the issue text.

Assessment

Tech stack
macos, swift
Domain
accessibility, documentation, testing
Issue type
Documentation
Difficulty
2/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
90/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.