fix(mobile): coalesce keyboard viewport settling

[Lint111]

Reopening this as the first of the three from #173, rebased onto current master (fa1700d, after #227 landed). Same fix as the original #194, with a stronger test — details below.

Summary

Coalesce the burst of mobile visualViewport resize events into one final xterm layout and PTY resize after the software-keyboard animation settles.

The bug

Keyboard open and close used separate fixed 150 ms and 100 ms timers. Mobile browsers report several intermediate viewport heights during the OS animation, so each step armed its own timer and refit xterm against a transient height. The visible symptom is repeated reflow while the keyboard slides up, with the terminal briefly laid out against a size that is already stale.

To see it: on a phone (or a touch-emulated viewport), focus the terminal so the keyboard animates in. Each intermediate viewport height triggers its own fit; the measurement below counts three for a three-step animation.

What changed

• one 80 ms settle timer, reset on every viewport resize, instead of per-event fixed timers
• the open/close request to return the terminal to the bottom is preserved across reschedules
• the existing fit, padding correction, helper synchronisation and resize transport run only once the viewport goes quiet
• pending settlement is cancelled during handler cleanup

Only src/web/public/mobile-handlers.js changes. That file has had no commits on master since this branch point, so the rebase was clean.

Test

test/mobile/keyboard.test.ts gains two cases:

1. refits once for a burst of keyboard viewport steps — drives the public onKeyboardShow three times in quick succession and asserts exactly one refit.

   On master this fails with expected 3 to be 1: one refit per viewport step. With the change it is 1. That is the behavioural difference stated as a number rather than an absent-method error.

2. coalesces keyboard animation frames into one final terminal fit — the finer-grained version, asserting nothing fires before the settle window and exactly one fit/resize/scroll-restore fires after.

Both needed a harness fix to be meaningful at all: the suite never selects a session, so initTerminal() never runs and app.terminal / app.fitAddon are both null. _scheduleViewportSettle returns early on a falsy terminal, so as written the assertions never reached the code they claimed to cover — they errored on Cannot read properties of null. The tests now install the minimum surface the settle callback touches and restore it afterwards.

Validation

• npm run test:ci — 4033 passed, 0 failed
• test/mobile/keyboard.test.ts — both new cases pass; 8 failures remain, all pre-existing on unmodified master (same null-initialisation limit of the headless harness, unrelated to this change). I verified the identical 8 fail on a clean origin/master checkout.
• tsc --noEmit, npm run lint, npm run check:frontend-syntax, prettier --check — all clean

Worth noting test/mobile/** is excluded from CI (config/vitest.ci.config.ts), so CI will not exercise the new tests. They are reproducible locally with:

npx vitest run --config config/vitest.config.ts test/mobile/keyboard.test.ts -t "refits once for a burst"

Scope

No change to resize arbitration, mobile terminal controls, input handling, session replay, or frame capture. Two commits: the fix, then the test-harness repair.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Ark0N]

Thanks @Lint111, good fix and a much stronger test than the original #194.

Manual testing on an iPhone hit one regression before merge: closing the keyboard corrupted the terminal view (duplicated prompts, tmux dot-filler rows). Root cause: scheduling the settle from handleViewportResize on every viewport event arms fit + PTY-resize work even when the show/hide state machine never engaged. Keyboard detection can miss a fine-grained OS animation entirely (each step under the 150px threshold, with the baseline chasing the animation down), while MobileDetection.updateAppHeight() still shrinks --app-height, so the settle fitted xterm against a mid-animation container with no keyboard CSS compensation and resized the PTY to transient dims (58 -> 10 -> 50 rows in my repro). That SIGWINCH thrash is what garbles the transcript. Master is unaffected on that path because it never resized the PTY from handleViewportResize at all.

I pushed 1f164bc to your branch (maintainer edit): only a real show/hide transition arms the settle work; handleViewportResize now calls _deferViewportSettle(), which pushes a pending settle back and is otherwise a no-op. Your coalescing behavior is preserved (one fit per transition, after the viewport goes quiet), your two tests pass unchanged, and a third test pins the new gate. Verified with a faked-visualViewport harness driving the real handler in both animation profiles, plus on-device on an iPhone: corruption gone, single clean refit on open and close.

The baseline-chasing detection flaw itself (sub-150px steps never flip keyboardVisible) predates this PR and is worth a follow-up of its own.

Merging, thanks again!