How dwell works

Dwell is how you activate a cell or zone: look at it until progress completes, then look away (or at another cell). There is no click unless you ask for one.

1. Gaze lands on a cell or zone.
2. Scan grace waits until you are stably on-target (default 100 ms; Settings → Dwell).
3. Activation is a sequence of step times in milliseconds. Progress fills through each step. The last step repeats while gaze holds.
4. The cell fires when dwell ends and blink grace expires (look away, or look at another cell). Blink grace pauses progress; look-away does not start another fill until grace expires.
5. The cell’s actions then run in order (Send, Command, mouse, page nav, …). See Actions.

<Phase> cells: the first dwell activation enters phase 0; each later activation advances (last wraps to first). The current phase’s actions run when dwell ends. actionLoop="true" keeps dispatching until you dwell the cell again (stopAllActionLoops stops every loop).

Rapid vs standard

Two sequences share scan grace:

Sequence	Used for
Rapid	Send, composer typing, modifiers, mapping keys (backspace, space, enter, …), compose.backspace / compose.deleteWord
Standard	Settings, navigation, mouse, AHK, Run, assist toggles, composer word chips, quitApp, editor / preview

Both live under Settings → Dwell (Slow / Normal / Fast / Custom). Per-cell XML can override scanGrace, dwellGrace, and activation.

Likely keys

Likely keys (Settings → Dwell, under Rapid) pulls the dwell target toward the next character you probably want, and shortens that key’s rapid steps. After t, h is easier to land than g or j. After a finished word, Space is easier than the letters beside it. The pull learns from what you type on every keyboard. 0 turns it off.

The gaze marker stays on the measured point. The center of a key always wins, and Shift, Backspace, Enter, and the other non-character keys keep their real bounds. A per-cell activation sequence keeps the times written in the layout.

Pause dwell

Pause dwell on the drawer, or the Sleep chip, suspends dwell everywhere except suspendExempt unlock targets (the Main chip also resumes). A dim screen border leaves a gap at those targets. Suspend and resume hold 500 ms before a new dwell can start.

toggleDwellSuspend, suspendDwell, and resumeDwell are different commands, not aliases of each other.

Overlap

When pages overlap, the topmost page’s grid is opaque: gaze and paint do not fall through. Shell zones (dock chips) still win over everything. A cell on a buried grid does not come forward when dwelled; only the unoccluded part hit-tests.

Progress shape (radial, pie, fill directions) is Settings → Dwell.