feat(forwarding): let the PC own hold timing for scanning profiles

docs/physical-smoke-test.md

@@ -67,4 +67,4 @@ Verify three-column/four-row Movement layouts including Scroll up, Scroll down,
 
 ### Remote scanning
 
-With a compatible Windows or macOS PC, assign remote slots in PC settings and select Switchify scanning in Remote Forwarding. Start with one Select switch in automatic mode, then test three slots in manual mode. Check row escape, icon menus, scroll repetition, confirmed drag and shared colour/timing. Verify local mapped keys do nothing while Remote owns scanning, but PC Escape stops it. Check hold action labels on PC. Confirm cancellation, switch replacement, hold-to-stop, navigation away, backgrounding and disconnect never click on release and always release an active drag. Reload profiles after changing PC assignments/settings. Reconnect must require explicit Start. Use a disposable target application for real-input checks; keep these checks separate from automated tests.
+With a compatible Windows or macOS PC, assign remote slots in PC settings and select Switchify scanning in Remote Forwarding. Start with one Select switch in automatic mode, then test three slots in manual mode. Check row escape, icon menus, scroll repetition, confirmed drag and shared colour/timing. Verify local mapped keys do nothing while Remote owns scanning, but PC Escape stops it. Check hold action labels on PC. Confirm cancellation and switch replacement never click on release and keep the session running; confirm a hold longer than the Forwarding hold-to-stop still delivers its release and the PC offers hold actions; confirm no idle stop occurs while scanning waits; confirm navigation away, backgrounding and disconnect never click on release and always release an active drag. Changing PC assignments applies to a live session; reload profiles only to refresh the labels shown in Remote. Reconnect must require explicit Start. Use a disposable target application for real-input checks; keep these checks separate from automated tests.

docs/protocol-compatibility.md

@@ -39,4 +39,4 @@ Fake tests cover negotiation, backward compatibility, response bounds, serial po
 
 PCs may advertise `capabilities.switchScanning: true`. Only then request `switch.profile.list` with `{ "includeScanning": true }`; older PCs retain the empty-object request. The opt-in catalog adds kind `scanning`, ID `builtin.switchify-scanning`, a revision and up to eight stateful/unassigned switch labels. Older clients receive the unchanged catalog. Protocol v1, authentication and existing forwarding command payloads are unchanged.
 
-Scanning edges request acknowledgements. Cancelled events, replacement presses and hold-to-stop send session stop without an actionable release. A PC refusal stops forwarding and clears restoration intent. Scanning profiles are never automatically restored after reconnect. A fresh start receives a new session ID; PC profile revisions reject stale assignments.
+Scanning edges request acknowledgements. The PC owns hold timing for scanning profiles: Remote's hold-to-stop and 60-second idle stop apply to keyboard forwarding only, and a long hold still delivers its release. A cancelled press is withdrawn with a `switch.sync` that omits it, so the PC drops the gesture without selecting; a replacement press is withdrawn with a `switch.sync` and then sent as a fresh press, never as a release. A PC refusal stops forwarding and clears restoration intent. Scanning profiles are never automatically restored after reconnect. A fresh start receives a new session ID; the PC applies its current assignments at start and no longer rejects a stale profile revision, so labels in Remote may lag until profiles are reloaded.

src/app/(tabs)/settings.tsx

@@ -41,7 +41,7 @@ export default function SettingsScreen() {
       <View style={cardWidth}><SettingCard title="Typing mode" description="Choose whether text sends live or as a draft."><View style={{ flexDirection: 'row', gap: spacing.sm }}><ControlButton label="Live" selected={preferences.typingMode === 'live'} onPress={() => void preferencesStore.update({ typingMode: 'live' })} /><ControlButton label="Draft" selected={preferences.typingMode === 'draft'} onPress={() => void preferencesStore.update({ typingMode: 'draft' })} /></View></SettingCard></View>
       <View style={cardWidth}><SettingCard title="Default PC" description="Select the computer used for automatic connection.">{saved.length === 0 ? <EmptyState icon="computer" title="No saved PCs" body="Pair a PC before choosing a default." /> : <View style={{ gap: spacing.sm }}><ControlButton label="Most recently connected" selected={defaultId === null} onPress={() => void setDefault(null)} />{saved.map((pc) => <ControlButton key={pc.desktopId} label={pc.displayName} selected={defaultId === pc.desktopId} onPress={() => void setDefault(pc.desktopId)} />)}</View>}</SettingCard></View>
       <View style={cardWidth}><SettingCard title="Pointer controls" description="Capabilities reported by the connected computer.">{connection.kind === 'connected' && connection.profile ? <View><ListRow icon="speed" title="Pointer speed" description={`${connection.profile.capabilities.pointerSpeed.scalePercent}%`} /><ListRow icon="repeat" title="Movement repeat" description={connection.profile.capabilities.mouseRepeat.enabled ? 'On' : 'Off'} /><ListRow icon="desktop-windows" title="Displays" description={`${connection.profile.capabilities.displayNavigation.displayCount}`} /></View> : <EmptyState icon="link" title="Connect a PC" body="Supported pointer controls are provided by the connected computer." />}</SettingCard></View>
-      {Platform.OS === 'android' ? <View style={cardWidth}><SettingCard title="Forwarding hold to stop" description="How long a physical switch must be held."><SelectorField label="Hold to stop" options={[3_000, 5_000, 8_000].map((milliseconds) => ({ key: milliseconds, label: `${milliseconds / 1000} seconds` }))} selectedKey={preferences.forwardingHoldToStopMs} onSelect={(forwardingHoldToStopMs) => preferencesStore.update({ forwardingHoldToStopMs })} /></SettingCard></View> : null}
+      {Platform.OS === 'android' ? <View style={cardWidth}><SettingCard title="Forwarding hold to stop" description="How long a physical switch must be held to stop keyboard forwarding. Switchify scanning uses the PC's hold limit instead."><SelectorField label="Hold to stop" options={[3_000, 5_000, 8_000].map((milliseconds) => ({ key: milliseconds, label: `${milliseconds / 1000} seconds` }))} selectedKey={preferences.forwardingHoldToStopMs} onSelect={(forwardingHoldToStopMs) => preferencesStore.update({ forwardingHoldToStopMs })} /></SettingCard></View> : null}
       <View style={cardWidth}><Card><PrivacyPolicyLink /><DiagnosticsLink /></Card></View>
     </View>
   </Screen>;

src/forwarding/ForwardingController.test.ts

@@ -17,7 +17,7 @@ const catalog: ProtocolResponse = { kind: 'switchProfileCatalog', id: 'catalog',
 describe('ForwardingController', () => {
   const generic = ['switch.profile.list', 'switch.session.start', 'switch.edge', 'switch.sync', 'switch.session.stop'];
   const fakeTimers = () => ({ interval: jest.fn(() => 1 as never), timeout: jest.fn(() => 2 as never), clear: jest.fn() });
-  it.each(['cancelled', 'held', 'replaced'])('stops scanning without sending a selecting release when %s', async (reason) => {
+  it.each(['cancelled', 'held', 'replaced'])('keeps a scanning session alive and never selects on its own when %s', async (reason) => {
     const bridge = new FakeBridge();
     const scanCatalog: ProtocolResponse = { kind: 'switchProfileCatalog', id: 'catalog', catalog: { catalogRevision: 1, profiles: [{ id: 'builtin.switchify-scanning', version: 1, name: 'Switchify scanning', kind: 'scanning', bindings: [{ switchId: 1, label: 'Select', behavior: 'stateful' }] }] } };
     const connection = { request: jest.fn(async () => scanCatalog), send: jest.fn(async () => true) };
@@ -30,10 +30,42 @@ describe('ForwardingController', () => {
     for (let i = 0; i < 10; i++) await Promise.resolve();
     bridge.emit({ type: 'switchEdge', generation: 41, sequence: 2, keyCode: 20, down: reason === 'replaced', downTimeMs: reason === 'replaced' ? 1 : 0, eventTimeMs: reason === 'held' ? 5000 : 20, cancelled: reason === 'cancelled' });
     for (let i = 0; i < 20; i++) await Promise.resolve();
-    expect(controller.snapshot().phase).toBe('idle');
-    expect(connection.send).toHaveBeenCalledWith('switch.edge', expect.objectContaining({ state: 'down' }), 'ack');
-    expect(connection.send).not.toHaveBeenCalledWith('switch.edge', expect.objectContaining({ state: 'up' }), expect.anything());
-    expect(connection.send).toHaveBeenCalledWith('switch.session.stop', expect.anything());
+    expect(controller.snapshot().phase).toBe('active');
+    expect(connection.send).not.toHaveBeenCalledWith('switch.session.stop', expect.anything());
+    const edges = (connection.send as jest.Mock).mock.calls.filter(([command]) => command === 'switch.edge').map(([, payload]) => payload.state);
+    if (reason === 'cancelled') {
+      // Withdrawn with a sync so the PC drops the gesture without selecting.
+      expect(edges).toEqual(['down']);
+      const syncs = (connection.send as jest.Mock).mock.calls.filter(([command]) => command === 'switch.sync').map(([, payload]) => payload.pressedSwitchIds);
+      expect(syncs.at(-1)).toEqual([]);
+      expect(controller.snapshot().mappings.find((mapping) => mapping.keyCode === 20)?.pressed).toBe(false);
+    } else if (reason === 'held') {
+      // The PC owns hold timing, so a long hold still delivers its release.
+      expect(edges).toEqual(['down', 'up']);
+    } else {
+      // A replacement withdraws the old press with a sync, then presses again;
+      // the PC never receives a release it could act on.
+      expect(edges).toEqual(['down', 'down']);
+      const calls = (connection.send as jest.Mock).mock.calls.filter(([command]) => command === 'switch.sync' || command === 'switch.edge');
+      const withdraw = calls.findIndex(([command, payload]) => command === 'switch.sync' && Array.isArray(payload?.pressedSwitchIds) && payload.pressedSwitchIds.length === 0 && payload.sequence > 2);
+      expect(withdraw).toBeGreaterThan(0);
+      expect(calls[withdraw + 1]?.[0]).toBe('switch.edge');
+      expect(calls[withdraw + 1]?.[1]?.state).toBe('down');
+    }
+    expect(scanCatalog).toBeTruthy();
+    await controller.cleanup();
+  });
+  it('does not arm the idle stop for scanning profiles', async () => {
+    const bridge = new FakeBridge();
+    const scanCatalog: ProtocolResponse = { kind: 'switchProfileCatalog', id: 'catalog', catalog: { catalogRevision: 1, profiles: [{ id: 'builtin.switchify-scanning', version: 1, name: 'Switchify scanning', kind: 'scanning', bindings: [{ switchId: 1, label: 'Select', behavior: 'stateful' }] } ] } };
+    const connection = { request: jest.fn(async () => scanCatalog), send: jest.fn(async () => true) };
+    const pc = profile(generic, ['switch.edge']); pc.capabilities.switchScanning = true;
+    const timers = fakeTimers();
+    const controller = new ForwardingController(connection, bridge, pc, 5000, timers, () => 'session');
+    await controller.loadProfiles(); await controller.start();
+    bridge.emit({ type: 'switchEdge', generation: 41, sequence: 1, keyCode: 20, down: true, downTimeMs: 0, eventTimeMs: 0, cancelled: false });
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+    expect(timers.timeout).not.toHaveBeenCalled();
     await controller.cleanup();
   });
   it.each(['stop', 'sync'])('preserves queued edge semantics across delayed acknowledgement and %s', async (scenario) => {

src/forwarding/ForwardingController.ts

@@ -153,20 +153,30 @@ export class ForwardingController {
     if (!mapping) return;
     this.#resetIdle();
     const duration = Math.max(0, event.eventTimeMs - event.downTimeMs);
-    if (this.selectedProfile()?.kind === 'scanning' && (event.cancelled || (!event.down && duration >= this.holdToStopMs))) {
-      void this.stop(event.cancelled ? 'Switch input cancelled. Start forwarding again.' : 'Forwarding stopped after the switch was held.', true);
+    // Scanning profiles leave hold limits to the PC, which owns the hold-action
+    // timing and its own emergency hold. A cancelled press is withdrawn with a
+    // sync so the PC drops the gesture without selecting, and the session
+    // continues; nothing here ends a scanning session on the user's behalf.
+    const scanning = this.selectedProfile()?.kind === 'scanning';
+    if (scanning && event.cancelled) {
+      this.#set({ mappings: this.#state.mappings.map((item) => item.keyCode === event.keyCode ? { ...item, pressed: false, downTimeMs: null } : item) });
+      const attempt = this.#attempt; const held = this.#heldIds();
+      void this.#enqueue(() => this.#syncNow(held, attempt));
       return;
     }
     const replacement = event.down && mapping.pressed && mapping.downTimeMs !== event.downTimeMs;
-    if (replacement && this.selectedProfile()?.kind === 'scanning') { void this.stop('A switch press was replaced. Start forwarding again.', true); return; }
+    // For scanning, a replacement's missing release must never reach the PC as
+    // an up edge, which would select. Withdraw it with a sync first.
+    const withdrawn = replacement && scanning ? this.#heldIds().filter((id) => id !== mapping.switchId) : null;
     this.#set({ mappings: this.#state.mappings.map((item) => item.keyCode === event.keyCode ? { ...item, pressed: event.down, downTimeMs: event.down ? event.downTimeMs : null } : item) });
     const attempt = this.#attempt;
     void this.#enqueue(async () => {
       if (attempt !== this.#attempt || this.#state.phase !== 'active') return;
-      if (replacement) await this.#edge(mapping.switchId, false);
+      if (withdrawn) await this.#syncNow(withdrawn, attempt);
+      else if (replacement) await this.#edge(mapping.switchId, false);
       if (attempt !== this.#attempt || this.#state.phase !== 'active') return;
       await this.#edge(mapping.switchId, event.down);
-      if (!event.down && !event.cancelled && duration >= this.holdToStopMs) void this.stop('Forwarding stopped after the switch was held.', true);
+      if (!scanning && !event.down && !event.cancelled && duration >= this.holdToStopMs) void this.stop('Forwarding stopped after the switch was held.', true);
     });
   }
 
@@ -194,7 +204,9 @@ export class ForwardingController {
     } else await this.connection.send('switch.session.stop', { sessionId: this.#sessionId, sequence: this.#sequence });
   }
 
-  #resetIdle(): void { if (this.#idle) this.timers.clear(this.#idle); this.#idle = this.timers.timeout(() => { void this.stop('Forwarding stopped after 60 seconds without switch activity.', true); }, 60_000); }
+  // A scanning user may watch the PC screen for a long time between presses,
+  // so the idle stop applies to keyboard forwarding only.
+  #resetIdle(): void { if (this.#idle) this.timers.clear(this.#idle); this.#idle = null; if (this.selectedProfile()?.kind === 'scanning') return; this.#idle = this.timers.timeout(() => { void this.stop('Forwarding stopped after 60 seconds without switch activity.', true); }, 60_000); }
   #clearTimers(): void { if (this.#sync) this.timers.clear(this.#sync); if (this.#idle) this.timers.clear(this.#idle); this.#sync = null; this.#idle = null; }
   #enqueue<T>(operation: () => Promise<T>): Promise<T> { this.#pending++; const next = this.#queue.then(operation, operation).finally(() => { this.#pending--; }); this.#queue = next.then(() => undefined, () => undefined); return next; }
   #set(patch: Partial<ForwardingState>): void { this.#state = { ...this.#state, ...patch }; this.#listeners.forEach((listener) => listener()); }