Skip to content

Mobile: indefinite phone-fit hold + configurable auto-restore#1532

Open
Jinwoo-H wants to merge 1 commit intomainfrom
Jinwoo-H/mobile-improvements-4
Open

Mobile: indefinite phone-fit hold + configurable auto-restore#1532
Jinwoo-H wants to merge 1 commit intomainfrom
Jinwoo-H/mobile-improvements-4

Conversation

@Jinwoo-H
Copy link
Copy Markdown
Contributor

@Jinwoo-H Jinwoo-H commented May 7, 2026

Why

When the mobile app leaves a terminal (tab swap, app background, lock screen), the PTY currently restores to desktop dims ~300ms later. For TUI apps like Claude Code and codex this fires an expensive reflow that disrupts the on-screen UI even though the user is coming right back. Users want the terminal to stay at phone size, with an explicit way back to desktop.

What

  • Default: indefinite hold. The phone-fit override and PTY dims stay put after the last mobile subscriber leaves. The 300ms debounced restore is gone.
  • Escape hatch: the existing desktop banner is widened to also show when a terminal is held with no active mobile driver, with copy/button adapted ("This terminal is held at phone size... Restore"). Click Restore → PTY snaps back to desktop dims.
  • Optional auto-restore: new mobileAutoRestoreFitMs setting on GlobalSettings (number | null). null = Indefinite. Finite values (clamped server-side to [5s, 60min]) schedule a wall-clock restore that long after the last unsubscribe.
  • Settable from both ends: dropdown in desktop Mobile preferences (Indefinite / 1m / 5m / 30m) and a per-host expandable picker in the mobile Settings screen. Mobile uses two new RPCs on the existing terminal.* namespace: terminal.getAutoRestoreFit and terminal.setAutoRestoreFit.

See docs/mobile-fit-hold.md for the full design (3-iteration design review).

Notable runtime semantics

  • reclaimTerminalForDesktop widened: handles both the active-subscriber path (existing) and the held-no-subscriber path (resolves restore target via the override's snapshotted baseline; applyLayout remains the sole writer of terminalFitOverrides).
  • Setting transitions: finite → null cancels every pending restore timer; null → finite does NOT retroactively schedule timers for already-held PTYs (the new value applies to the next unsubscribe).
  • Re-subscribe before a finite-window restore fires cancels the pending timer.

Tests

8 new tests in mobile-subscribe-integration.test.ts covering: indefinite hold, finite-delay auto-restore, re-subscribe-cancels, manual reclaim of held PTY, finite→null clears all timers, null→finite no retro-scheduling, and clamp behavior. Updated 2 mock stores (mobile-subscribe-integration, mobile-presence-lock) and 2 codex-accounts test fixtures for the new field. All 48 mobile-related tests pass; tc:node and tc:web clean.

Made with Orca 🐋

When the mobile app leaves a terminal, the PTY now stays at phone size
indefinitely by default instead of releasing back to desktop dims after
a 300ms debounce. This avoids expensive TUI reflows for apps like
Claude Code and codex when users tab away briefly. The desktop banner
becomes the explicit return path with a 'Restore' button, and a new
'mobileAutoRestoreFitMs' setting (settable from both desktop preferences
and the mobile app via terminal.setAutoRestoreFit / .getAutoRestoreFit
RPCs) lets users opt into a wall-clock auto-restore (1m / 5m / 30m).

See docs/mobile-fit-hold.md for the full design.

Co-authored-by: Orca <help@stably.ai>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant