From 7c2ff742a43d666ffd0ef83a47f4a21966434719 Mon Sep 17 00:00:00 2001 From: adybag14-cyber <252811164+adybag14-cyber@users.noreply.github.com> Date: Tue, 19 May 2026 12:48:35 -0700 Subject: [PATCH] fix(tui): termux-gate scrollback preservation, touch-friendly defaults Adds a Termux runtime detection helper and gates three TUI defaults on it: - Skip the startup scrollback clear on Termux so users can review/copy earlier output after reopening the app. Desktop keeps the existing \x1b[2J\x1b[H\x1b[3J slate (AlternateScreen takes over there anyway). - Default INLINE_MODE on under Termux: primary-buffer rendering makes long-thread review and copy/paste much less fragile when users background/foreground the app. Override with HERMES_TUI_INLINE=0/1. - Default mouse tracking off under Termux so touch selection isn't intercepted by terminal mouse protocols. Explicit override via HERMES_TUI_MOUSE_TRACKING=0/1; legacy HERMES_TUI_DISABLE_MOUSE still works on desktop. Detection is purely env-based (TERMUX_VERSION or PREFIX path) with an explicit opt-out HERMES_TUI_TERMUX_MODE=0 for debugging. Non-Termux platforms keep every existing default. Co-authored-by: adybag14-cyber <252811164+adybag14-cyber@users.noreply.github.com> --- ui-tui/src/__tests__/termux.test.ts | 35 +++++++++++++++++++++++ ui-tui/src/config/env.ts | 43 ++++++++++++++++++++++++++--- ui-tui/src/entry.tsx | 14 ++++++---- ui-tui/src/lib/termux.ts | 29 +++++++++++++++++++ 4 files changed, 112 insertions(+), 9 deletions(-) create mode 100644 ui-tui/src/__tests__/termux.test.ts create mode 100644 ui-tui/src/lib/termux.ts diff --git a/ui-tui/src/__tests__/termux.test.ts b/ui-tui/src/__tests__/termux.test.ts new file mode 100644 index 00000000000..2fe0573d5aa --- /dev/null +++ b/ui-tui/src/__tests__/termux.test.ts @@ -0,0 +1,35 @@ +import { describe, expect, it } from 'vitest' + +import { isTermuxEnv, isTermuxTuiMode } from '../lib/termux.js' + +describe('isTermuxEnv', () => { + it('detects TERMUX_VERSION marker', () => { + expect(isTermuxEnv({ TERMUX_VERSION: '0.118.0' } as NodeJS.ProcessEnv)).toBe(true) + }) + + it('detects Termux PREFIX path marker', () => { + expect( + isTermuxEnv({ PREFIX: '/data/data/com.termux/files/usr' } as NodeJS.ProcessEnv) + ).toBe(true) + }) + + it('returns false for generic Linux envs', () => { + expect(isTermuxEnv({ PREFIX: '/usr' } as NodeJS.ProcessEnv)).toBe(false) + }) +}) + +describe('isTermuxTuiMode', () => { + it('defaults to true inside Termux', () => { + expect(isTermuxTuiMode({ TERMUX_VERSION: '0.118.0' } as NodeJS.ProcessEnv)).toBe(true) + }) + + it('allows explicit opt-out override', () => { + expect( + isTermuxTuiMode({ TERMUX_VERSION: '0.118.0', HERMES_TUI_TERMUX_MODE: '0' } as NodeJS.ProcessEnv) + ).toBe(false) + }) + + it('stays false outside Termux even if override is set', () => { + expect(isTermuxTuiMode({ HERMES_TUI_TERMUX_MODE: '1', PREFIX: '/usr' } as NodeJS.ProcessEnv)).toBe(false) + }) +}) diff --git a/ui-tui/src/config/env.ts b/ui-tui/src/config/env.ts index 8e9dde92fde..35cc6878279 100644 --- a/ui-tui/src/config/env.ts +++ b/ui-tui/src/config/env.ts @@ -1,16 +1,51 @@ +import { isTermuxTuiMode } from '../lib/termux.js' + const truthy = (v?: string) => /^(?:1|true|yes|on)$/i.test((v ?? '').trim()) +const falsy = (v?: string) => /^(?:0|false|no|off)$/i.test((v ?? '').trim()) + +const parseToggle = (v?: string): boolean | null => { + const raw = (v ?? '').trim() + + if (!raw) { + return null + } + + if (truthy(raw)) { + return true + } + + if (falsy(raw)) { + return false + } + + return null +} + +export const TERMUX_TUI_MODE = isTermuxTuiMode() export const STARTUP_RESUME_ID = (process.env.HERMES_TUI_RESUME ?? '').trim() export const STARTUP_QUERY = (process.env.HERMES_TUI_QUERY ?? '').trim() export const STARTUP_IMAGE = (process.env.HERMES_TUI_IMAGE ?? '').trim() -export const MOUSE_TRACKING = !truthy(process.env.HERMES_TUI_DISABLE_MOUSE) + +const mouseTrackingOverride = parseToggle(process.env.HERMES_TUI_MOUSE_TRACKING) +const mouseTrackingDisabledLegacy = truthy(process.env.HERMES_TUI_DISABLE_MOUSE) +// Mobile selection UX: on Termux default mouse tracking OFF so touch selection +// is less likely to be intercepted by terminal mouse protocols. Desktop keeps +// prior behavior unless explicitly overridden. +export const MOUSE_TRACKING = + mouseTrackingOverride ?? (TERMUX_TUI_MODE ? false : !mouseTrackingDisabledLegacy) + export const NO_CONFIRM_DESTRUCTIVE = truthy(process.env.HERMES_TUI_NO_CONFIRM) +const inlineOverride = parseToggle(process.env.HERMES_TUI_INLINE) + // Skip AlternateScreen — TUI renders into the primary buffer so the host // terminal's native scrollback captures whatever scrolls off the top. -// Experiment gate: lets us measure native scroll vs our virtualization on -// the same pipeline. -export const INLINE_MODE = truthy(process.env.HERMES_TUI_INLINE) +// +// On Termux we default this on: users often background/foreground the app, +// and primary-buffer rendering makes long-thread review and copy/paste much +// less fragile. Override explicitly with HERMES_TUI_INLINE=0/1. +export const INLINE_MODE = inlineOverride ?? TERMUX_TUI_MODE // Live FPS counter overlay, fed by ink's onFrame (real render rate, not a // synthetic timer). diff --git a/ui-tui/src/entry.tsx b/ui-tui/src/entry.tsx index bfd56fa19d6..690caf0cc95 100644 --- a/ui-tui/src/entry.tsx +++ b/ui-tui/src/entry.tsx @@ -5,6 +5,7 @@ import './lib/forceTruecolor.js' import type { FrameEvent } from '@hermes/ink' +import { TERMUX_TUI_MODE } from './config/env.js' import { GatewayClient } from './gatewayClient.js' import { setupGracefulExit } from './lib/gracefulExit.js' import { formatBytes, type HeapDumpResult, performHeapDump } from './lib/memory.js' @@ -21,11 +22,14 @@ if (!process.stdin.isTTY) { // terminal tab can still have mouse/focus/paste modes enabled. resetTerminalModes() -// Clear visible screen + scrollback buffer. Without this, tmux may retain -// stale TUI output in its scrollback buffer from the previous session, -// which is visible when the user scrolls up or briefly before AlternateScreen -// takes over on restart. See entry.tsx → AlternateScreen flow. -process.stdout.write('\x1b[2J\x1b[H\x1b[3J') +// Desktop terminals benefit from a clean startup slate because the TUI usually +// runs in AlternateScreen. On Termux we keep prior output intact so users can +// review/copy earlier assistant replies after reopening the app. +if (TERMUX_TUI_MODE) { + process.stdout.write('\n') +} else { + process.stdout.write('\x1b[2J\x1b[H\x1b[3J') +} const gw = new GatewayClient() diff --git a/ui-tui/src/lib/termux.ts b/ui-tui/src/lib/termux.ts new file mode 100644 index 00000000000..20328b8e678 --- /dev/null +++ b/ui-tui/src/lib/termux.ts @@ -0,0 +1,29 @@ +const TERMUX_PREFIX = '/data/data/com.termux/files/usr' + +const truthy = (value?: string) => /^(?:1|true|yes|on)$/i.test(String(value ?? '').trim()) + +export const isTermuxEnv = (env: NodeJS.ProcessEnv = process.env): boolean => { + const prefix = String(env.PREFIX ?? '') + + return Boolean(env.TERMUX_VERSION) || prefix.includes(TERMUX_PREFIX) +} + +/** + * Return true when Hermes should enable Termux-focused TUI defaults. + * + * Defaults to on in Termux, with an explicit opt-out for debugging: + * HERMES_TUI_TERMUX_MODE=0 + */ +export const isTermuxTuiMode = (env: NodeJS.ProcessEnv = process.env): boolean => { + if (!isTermuxEnv(env)) { + return false + } + + const override = String(env.HERMES_TUI_TERMUX_MODE ?? '').trim().toLowerCase() + + if (override) { + return truthy(override) + } + + return true +}