feat: show version in help overlay

Inject version at build time via globalThis.__remobiVersion, display as
muted footer in the help overlay. Dev builds (from source checkout) show
git hash suffix e.g. v0.2.7-dev+abc1234, npm installs show clean version.

Detection uses src/index.ts presence (not published to npm) to distinguish
source checkout from npm install, avoiding false positives from user repos.

Author: connorads

build.ts

@@ -17,7 +17,10 @@ function findProjectRoot(): string {
 const PROJECT_ROOT = findProjectRoot()
 
 /** Bundle the overlay JS + CSS into strings */
-export async function bundleOverlay(config: RemobiConfig): Promise<{ js: string; css: string }> {
+export async function bundleOverlay(
+	config: RemobiConfig,
+	version: string,
+): Promise<{ js: string; css: string }> {
 	// Read CSS
 	const cssPath = resolve(PROJECT_ROOT, 'styles/base.css')
 	const css = readFileSync(cssPath, 'utf-8')
@@ -26,19 +29,21 @@ export async function bundleOverlay(config: RemobiConfig): Promise<{ js: string;
 	const prebuiltPath = resolve(PROJECT_ROOT, 'dist/overlay.iife.js')
 	if (existsSync(prebuiltPath)) {
 		const overlayJs = readFileSync(prebuiltPath, 'utf-8')
-		const js = `globalThis.__remobiConfig=${JSON.stringify(config)};${overlayJs}`
+		const js = `globalThis.__remobiVersion=${JSON.stringify(version)};globalThis.__remobiConfig=${JSON.stringify(config)};${overlayJs}`
 		return { js, css }
 	}
 
 	// Dev fallback: bundle from source via esbuild (requires src/ and esbuild)
 	const esbuild = await import('esbuild')
 
 	const configJson = JSON.stringify(config)
+	const versionJson = JSON.stringify(version)
 	const entryCode = `
 import { init, createHookRegistry } from './src/index.ts'
 const hooks = createHookRegistry()
 const config = ${configJson}
-;(function() { init(config, hooks) })()
+const version = ${versionJson}
+;(function() { init(config, hooks, version) })()
 `
 
 	const tmpEntry = resolve(PROJECT_ROOT, '.tmp-entry.ts')
@@ -132,16 +137,20 @@ export function injectOverlay(html: string, js: string, css: string, config: Rem
 }
 
 /** Full build pipeline: bundle → fetch ttyd HTML → inject → write output */
-export async function build(config: RemobiConfig, outputPath: string): Promise<void> {
-	const { js, css } = await bundleOverlay(config)
+export async function build(
+	config: RemobiConfig,
+	outputPath: string,
+	version: string,
+): Promise<void> {
+	const { js, css } = await bundleOverlay(config, version)
 	const baseHtml = await fetchTtydHtml()
 	const patched = injectOverlay(baseHtml, js, css, config)
 	writeFileSync(outputPath, patched)
 }
 
 /** Build from stdin HTML (pipe mode) */
-export async function injectFromStdin(config: RemobiConfig): Promise<string> {
-	const { js, css } = await bundleOverlay(config)
+export async function injectFromStdin(config: RemobiConfig, version: string): Promise<string> {
+	const { js, css } = await bundleOverlay(config, version)
 	const stdin = await readStdin()
 	if (stdin.trim().length === 0) {
 		throw new Error('remobi inject expects piped ttyd HTML on stdin')

cli.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { execSync } from 'node:child_process'
 import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
@@ -14,22 +15,45 @@ import { serve } from './src/serve'
 import type { RemobiConfig, RemobiConfigOverrides } from './src/types'
 import { readStdin } from './src/util/node-compat'
 
-// Walk up from module location to find package.json — works from both source and dist/
-function loadPackageVersion(): string {
+// Walk up from module location to find project root — works from both source and dist/
+function findProjectRoot(): string {
 	let dir = import.meta.dirname
 	for (let i = 0; i < 5; i++) {
-		try {
-			const content = readFileSync(resolve(dir, 'package.json'), 'utf-8')
-			// oxlint-disable-next-line typescript/consistent-type-assertions -- JSON.parse returns unknown
-			return (JSON.parse(content) as { version: string }).version
-		} catch {
-			dir = dirname(dir)
-		}
+		if (existsSync(resolve(dir, 'package.json'))) return dir
+		dir = dirname(dir)
+	}
+	return import.meta.dirname
+}
+
+function loadPackageVersion(root: string): string {
+	try {
+		const content = readFileSync(resolve(root, 'package.json'), 'utf-8')
+		// oxlint-disable-next-line typescript/consistent-type-assertions -- JSON.parse returns unknown
+		return (JSON.parse(content) as { version: string }).version
+	} catch {
+		return '0.0.0'
+	}
+}
+
+// Source checkout has src/index.ts (not published to npm per files array in package.json).
+// For dev builds, append git short hash so local vs npm is obvious.
+function resolveVersion(): string {
+	const root = findProjectRoot()
+	const pkgVersion = loadPackageVersion(root)
+	if (!existsSync(resolve(root, 'src/index.ts'))) return pkgVersion
+	try {
+		const hash = execSync('git rev-parse --short HEAD', {
+			cwd: root,
+			encoding: 'utf-8',
+			stdio: ['ignore', 'pipe', 'ignore'],
+		}).trim()
+		return `${pkgVersion}-dev+${hash}`
+	} catch {
+		return pkgVersion
 	}
-	return '0.0.0'
 }
 
-const VERSION: string = loadPackageVersion()
+const VERSION: string = resolveVersion()
 
 function usage(): void {
 	console.log(`remobi v${VERSION} — mobile-friendly terminal overlay for ttyd + tmux
@@ -212,7 +236,14 @@ async function main(): Promise<void> {
 	switch (command) {
 		case 'serve': {
 			const loaded = await loadConfig(configPath)
-			await serve(loaded.config, port, command_.length > 0 ? command_ : undefined, noSleep, host)
+			await serve(
+				loaded.config,
+				port,
+				command_.length > 0 ? command_ : undefined,
+				noSleep,
+				host,
+				VERSION,
+			)
 			break
 		}
 
@@ -233,7 +264,7 @@ async function main(): Promise<void> {
 			// Ensure output directory exists
 			mkdirSync(dirname(targetPath), { recursive: true })
 
-			await build(loaded.config, targetPath)
+			await build(loaded.config, targetPath, VERSION)
 			console.log(`Built: ${targetPath}`)
 			break
 		}
@@ -254,7 +285,7 @@ async function main(): Promise<void> {
 			}
 
 			ensureInjectInputMode('remobi inject')
-			const result = await injectFromStdin(loaded.config)
+			const result = await injectFromStdin(loaded.config, VERSION)
 			process.stdout.write(result)
 			break
 		}

src/controls/help.ts

@@ -55,7 +55,7 @@ function renderGestures(config: RemobiConfig): DocumentFragment {
 }
 
 /** Build the help overlay content as a DocumentFragment — no innerHTML */
-function buildHelpContent(config: RemobiConfig): DocumentFragment {
+function buildHelpContent(config: RemobiConfig, version?: string): DocumentFragment {
 	const topRightButtons: readonly ControlButton[] = [
 		{
 			id: 'font-size',
@@ -93,6 +93,10 @@ function buildHelpContent(config: RemobiConfig): DocumentFragment {
 		}
 	}
 
+	if (version !== undefined) {
+		frag.appendChild(el('p', { class: 'wt-help-version' }, `remobi v${version}`))
+	}
+
 	return frag
 }
 
@@ -107,9 +111,10 @@ export function createHelpOverlay(
 	term: XTerminal,
 	helpButton: HTMLButtonElement,
 	config: RemobiConfig,
+	version?: string,
 ): HelpOverlayResult {
 	const overlay = el('div', { id: 'wt-help' })
-	overlay.appendChild(buildHelpContent(config))
+	overlay.appendChild(buildHelpContent(config, version))
 
 	function open(): void {
 		overlay.style.display = 'block'

src/index.ts

@@ -49,6 +49,7 @@ function isMobile(): boolean {
 export function init(
 	config: RemobiConfig = defaultConfig,
 	hooks: HookRegistry = createHookRegistry(),
+	version?: string,
 ): void {
 	void waitForTerm()
 		.then(async (term) => {
@@ -195,7 +196,7 @@ export function init(
 
 				// Help overlay should never break core controls.
 				try {
-					const { element: helpOverlay } = createHelpOverlay(term, helpButton, config)
+					const { element: helpOverlay } = createHelpOverlay(term, helpButton, config, version)
 					document.body.appendChild(helpOverlay)
 				} catch (error) {
 					console.error('remobi: failed to initialise help overlay', error)

src/overlay-entry.ts

@@ -2,6 +2,8 @@ import { createHookRegistry, init } from './index'
 import type { RemobiConfig } from './types'
 
 declare const __remobiConfig: RemobiConfig
+declare const __remobiVersion: string | undefined
 const config = __remobiConfig
+const version = typeof __remobiVersion !== 'undefined' ? __remobiVersion : undefined
 const hooks = createHookRegistry()
-init(config, hooks)
+init(config, hooks, version)

src/serve.ts

@@ -199,9 +199,10 @@ export async function serve(
 	command: readonly string[] = DEFAULT_COMMAND,
 	noSleep = false,
 	host: string = DEFAULT_HOST,
+	version = 'unknown',
 ): Promise<void> {
 	console.log('remobi: building overlay...')
-	const { js, css } = await bundleOverlay(config)
+	const { js, css } = await bundleOverlay(config, version)
 
 	const internalPort = randomInternalPort()
 	const ttydArgs = buildTtydArgs(config, internalPort, command)

styles/base.css

@@ -247,6 +247,13 @@ body {
 	width: 30%;
 }
 
+#wt-help .wt-help-version {
+	text-align: center;
+	color: #6c7086;
+	font-size: 12px;
+	margin: 16px 0 0;
+}
+
 #wt-help .wt-help-close {
 	position: fixed;
 	top: 12px;

tests/integration.test.ts

@@ -150,6 +150,34 @@ describe('help overlay integration', () => {
 		expect(element.innerHTML).toContain('Gestures')
 	})
 
+	test('shows version when provided', () => {
+		const term = mockTerminal()
+		const { helpButton } = createFontControls(term, defaultConfig.font)
+		const { element } = createHelpOverlay(term, helpButton, defaultConfig, '1.2.3')
+
+		document.body.appendChild(element)
+
+		const versionEl = element.querySelector('.wt-help-version')
+		expect(versionEl).not.toBeNull()
+		expect(versionEl?.textContent).toBe('remobi v1.2.3')
+	})
+
+	test('shows dev version with hash', () => {
+		const term = mockTerminal()
+		const { helpButton } = createFontControls(term, defaultConfig.font)
+		const { element } = createHelpOverlay(term, helpButton, defaultConfig, '0.2.6-dev+abc1234')
+
+		expect(element.innerHTML).toContain('remobi v0.2.6-dev+abc1234')
+	})
+
+	test('omits version when not provided', () => {
+		const term = mockTerminal()
+		const { helpButton } = createFontControls(term, defaultConfig.font)
+		const { element } = createHelpOverlay(term, helpButton, defaultConfig)
+
+		expect(element.querySelector('.wt-help-version')).toBeNull()
+	})
+
 	test('renders configured button descriptions and no stale Claude section', () => {
 		const term = mockTerminal()
 		const { helpButton } = createFontControls(term, defaultConfig.font)

tests/playwright/smoke.spec.ts

@@ -25,4 +25,26 @@ test('remobi inject pipes ttyd HTML and produces patched output', async ({ reque
 
 	expect(stdout).toContain('<!DOCTYPE html>')
 	expect(stdout.indexOf('</head>')).toBeGreaterThan(-1)
+	expect(stdout).toContain('__remobiVersion')
+})
+
+test('help overlay shows version', async ({ page }) => {
+	await page.goto('/')
+	await page.waitForSelector('#wt-toolbar', { timeout: 10_000 })
+
+	// Open help via touchend (same pattern as touch.spec.ts — tap() can miss on mobile viewports)
+	const helpBtn = page.locator('#wt-font-controls button', { hasText: '?' })
+	await expect(helpBtn).toBeVisible()
+	await helpBtn.dispatchEvent('touchend', {
+		touches: [],
+		changedTouches: [],
+		targetTouches: [],
+	})
+
+	const overlay = page.locator('#wt-help')
+	await expect(overlay).toBeVisible()
+
+	const versionEl = page.locator('#wt-help .wt-help-version')
+	await expect(versionEl).toBeVisible()
+	await expect(versionEl).toContainText(/remobi v\d+\.\d+\.\d+/)
 })