Document after-selection scan preferences

docs/point-scan.md

@@ -6,7 +6,7 @@ Point scan ports the Android line-only and grid-then-line techniques to Switchif
 
 Open **Settings → Switches** to add named keyboard switches and assign normal and hold actions. There is no on/off control: scanning is armed whenever the saved switches cover the current mode (Select for automatic scanning; Select, Next and Previous for manual) and the environment allows it. The runtime re-arms after a save, after key learning, after Escape, when a mobile session ends, and retries a failed key reservation every two seconds. Fresh installs have no assignments; old point-scan keys migrate once. See [switch assignments](switches.md). Scanning arms at startup, so assigned keys are reserved from launch.
 
-Focus the intended application and press Select to start. Line mode chooses X, then Y, and opens an action menu. Grid mode chooses a row, then a cell, before the same line sequence. Selecting happens on switch release; holding any switch freezes the position and repeat keydowns do not select again. The scan resets after a menu click or completed drag and waits for the next Select. Movement wraps at the selected region's edges. Automatic movement stops after three full passes of the current phase without a selection; the scan resets and waits for the next Select. Manual steps never trigger this limit, and each Select starts a fresh count for the next phase. Android's five speeds are 45, 75, 120, 180, and 270 logical units per second, with delayed ticks capped at 250 ms.
+Focus the intended application and press Select to start. Line mode chooses X, then Y, and opens an action menu. Grid mode chooses a row, then a cell, before the same line sequence. Selecting happens on switch release; holding any switch freezes the position and repeat keydowns do not select again. The scan resets after a menu click or completed drag and waits for the next Select, unless After a selection is set to Keep scanning for point scanning; the next scan then starts by itself. See [After a selection](scanner-architecture.md#after-a-selection). Movement wraps at the selected region's edges. Automatic movement stops after three full passes of the current phase without a selection; the scan resets and waits for the next Select. Manual steps never trigger this limit, and each Select starts a fresh count for the next phase. Android's five speeds are 45, 75, 120, 180, and 270 logical units per second, with delayed ticks capped at 250 ms.
 
 The scan uses the monitor under the pointer when it starts. Windows uses native physical coordinates and display scaling; macOS uses Core Graphics display units and converts overlay rectangles to AppKit coordinates. A monitor geometry change cancels scanning. Native overlay strips are topmost, click-through, and nonactivating. The pointer moves only when a menu action executes.
 
@@ -40,9 +40,9 @@ Physical validation should include forward/reverse escape with a real switch, pa
 
 ## Actions at a point
 
-Choosing a point opens a native grid beside its marker. The rows are Left click / Right click / Double click; Scroll / Drag / More; New point / Close menu. The shared tree navigator handles row/item selection and row escape. The menu uses the current automatic/manual mode and block interval. After three automatic passes, it retains the target and shows Select to resume. That Select resumes scanning without executing an action.
+Choosing a point opens a native grid beside its marker. The rows are Left click / Right click / Double click; Scroll / Drag / More; New point / Close menu. The shared tree navigator handles row/item selection and row escape. The menu uses the current automatic/manual mode and block interval. After three automatic passes, it retains the target and shows Select to resume. That Select resumes scanning without executing an action. After a scroll or media item the menu stays on that item and keeps scanning; After a selection and Start again from change this for menus.
 
-Scroll offers Up / Down, Left / Right, and Back to actions. Each selection moves the pointer to the target and sends three wheel steps; the selected direction remains available. Back restores the main menu's Scroll item. Choose another point immediately restarts the configured technique on the original display. Clicks and completed drags return to armed idle.
+Scroll offers Up / Down, Left / Right, and Back to actions. Each selection moves the pointer to the target and sends three wheel steps; the selected direction remains available. Back restores the main menu's Scroll item. Choose another point immediately restarts the configured technique on the original display. Clicks and completed drags return to armed idle, unless After a selection is set to Keep scanning for point scanning.
 
 Drag retains the source and scans a destination on the same display without holding a button. The confirmation menu offers Drag here and New destination, with Cancel drag and Close menu in its final row. Cancel drag returns to the source menu. Confirmation moves to the source, presses the left button, interpolates to the destination over 300 ms on runtime ticks, and releases. No blocking sleep is used. Ordinary selections cannot issue another action during execution. Failed releases stay owned and cleanup retries before rearming and on disabled ticks.
 

docs/qwerty-keyboard.md

@@ -4,7 +4,7 @@ Switchify has its own UK English keyboard on Windows and macOS. It uses the save
 
 Select **Keyboard** in the action menu, or assign **Open keyboard** to a switch press or hold action in Settings → Switches. The switch opens the keyboard from idle, point scanning, menus, pauses and drags. Opening releases owned input and preserves the existing foreground focus without clicking. The keyboard does not take focus or accept mouse clicks.
 
-Scan a row, select it, then scan and select a key. The escape slot returns to rows. After typing, scanning starts again at the first row. Existing automatic/manual movement, speed, pause, reverse and inactivity suspension apply. The keyboard stays open after Space, Backspace, Enter and Tab. **Close** returns to point scanning.
+Scan a row, select it, then scan and select a key. The escape slot returns to rows. After typing, scanning starts again at the beginning: the first row, or the last when the direction is reverse. After a selection and Start again from, under Scanning settings, can make it wait for Select or continue from the key just typed; see [After a selection](scanner-architecture.md#after-a-selection). Existing automatic/manual movement, speed, pause, reverse and inactivity suspension apply. The keyboard stays open after Space, Backspace, Enter and Tab. **Close** returns to point scanning.
 
 Pages:
 
@@ -25,7 +25,7 @@ Use synthetic text in Notepad and a browser on Windows, and TextEdit and a brows
 1. Open Keyboard from the menu and an assigned switch while idle, scanning, paused and dragging. Verify no click or focus change occurs and owned input is released.
 2. Type lowercase letters, uppercase letters with Shift/Caps, and UK punctuation including £, @ and double quotes. Test Space, Backspace, Enter and Tab.
 3. Test Ctrl+A/C/V on Windows and Command+A/C/V on macOS. Cycle once/locked/off, including Shift with another modifier, and confirm no modifier remains physically held between selections.
-4. Visit every page. Verify row/key highlighting, reverse movement, row escape, suspension/resume, returning to the first row after a key and Close.
+4. Visit every page. Verify row/key highlighting, reverse movement, row escape, suspension/resume, returning to the beginning after a key and Close. Set Start again from to Where I selected and After a selection to Wait for Select for the keyboard, with automatic scanning; verify the highlight stays on the typed key, waits for Select, and returns to the beginning after a suggestion.
 5. Move the keyboard between the top and bottom. Check a scaled display and a secondary display, including negative coordinates. Verify the keyboard fits the work area and never activates its native windows.
 6. Switch foreground apps and verify the keyboard remains open with cleared modifiers and predictions. Disconnect remote scanning, change display configuration and close Switchify; verify overlays disappear and owned input is released.
 

docs/scanner-architecture.md

@@ -71,6 +71,45 @@ if any area is manual. Pass limit zero means unlimited; grouped and linear item
 scanning share the same navigator and execution revision. Keyboard skipping of
 unavailable predictions counts automatic wraps but never manual passes.
 
+### After a selection
+
+Two preferences decide how scanning continues after a selection that does something, such as typing a key, clicking or scrolling. Each has a shared value and an optional value for each area.
+
+| Preference | Values | Meaning |
+|---|---|---|
+| `nextScan` | `standard`, `automatic`, `wait` | Whether scanning moves on by itself or waits for Select |
+| `startFrom` | `standard`, `beginning`, `selection` | Whether scanning starts from the beginning or from the item selected |
+
+`standard` is what each scanner did before the preferences existed, and is the default:
+
+| Scanner | `nextScan` | `startFrom` |
+|---|---|---|
+| Point scanning | Waits after a click, including an auto-selected one, a closing command or a drag | Always the beginning; the preference is ignored |
+| Menus | Moves on after a scroll or media item | The item selected |
+| Keyboard | Moves on after a key or suggestion | The beginning |
+| Mouse panel | Moves on after an action | The beginning |
+
+The beginning is the first row or item, or the last when the initial direction is reverse.
+
+Rules that hold whatever is chosen:
+
+- Selections that only navigate start from the beginning of what they open. These are opening a menu, page or panel, the position items, Back from the position items, Close, and the keyboard's modifier and Caps keys.
+- Back in a menu returns to the item that opened it.
+- The menu's mode and display items start a new point scan. The menu's speed, Pause and Reverse items stay where they are and do not follow the preferences.
+- The mouse panel's Speed, Monitor and Drag keys are actions and follow both preferences.
+- A failed action and a pause at the pass limit resume from where they always did.
+- A chosen suggestion returns to the beginning, because its row is replaced.
+- `wait` has no effect in an area that is not automatic, except that point scanning always waits unless `automatic` is chosen.
+- A point scan that starts by itself still stops at the pass limit.
+
+A point scan that started by itself takes up whichever window is in front until a switch is used in it, because the click before it may have brought another window forward. From then on, a change of window ends the scan as usual. While such a scan has no window in front, it holds still for up to a second, then ends as usual.
+
+`keyboardWaitAfterTyping`, saved by earlier versions, still makes the keyboard wait. It applies only while the keyboard has no `nextScan` of its own and the shared value is `standard`. Settings no longer offers or changes it; the saved value is kept.
+
+A value that is not recognised is dropped on its own when the file is read, and the other scan settings are kept.
+
+`ItemScanner::continue_after_selection` applies both preferences for item scanners. `Workflow::used` decides what follows a used point.
+
 The existing configure API cancels a running scan and waits for Select. Native
 frames carry effective colour and thickness; individual renderers do not resolve
 settings. Point line/grid geometry and movement speed remain separate controls.