fix: prevent synthesised click from closing overlays opened by touch

Move onTap's touchFired guard from per-element to module-level scope.
After any touchend, all onTap click handlers are suppressed for 400ms,
preventing the browser's synthesised click from hitting newly-visible
overlays at the same coordinates.

Removes drawer's justOpened guard — now redundant.

Author: connorads

src/drawer/drawer.ts

@@ -42,7 +42,6 @@ export function createDrawer(
 	drawer.appendChild(grid)
 
 	let drawerOpen = false
-	let justOpened = false
 
 	for (const buttonDef of buttons) {
 		const button = el('button')
@@ -95,14 +94,6 @@ export function createDrawer(
 		backdrop.style.display = 'block'
 		drawer.classList.add('open')
 		drawerOpen = true
-		// Guard against synthesised click on backdrop. When onTap fires on
-		// touchend (no preventDefault), the browser synthesises mousedown/click
-		// ~4ms later at the same coordinates. By then the backdrop is visible
-		// and intercepts the click, immediately closing the drawer.
-		justOpened = true
-		setTimeout(() => {
-			justOpened = false
-		}, 300)
 	}
 
 	function close(): void {
@@ -115,20 +106,6 @@ export function createDrawer(
 		return drawerOpen
 	}
 
-	// Backdrop dismisses drawer. The click listener ignores the first click
-	// after open() to avoid synthesised click from the triggering touch.
-	// touchend is never synthesised, so it always works immediately.
-	backdrop.addEventListener(
-		'click',
-		(e: Event) => {
-			if (justOpened) {
-				justOpened = false
-				e.stopImmediatePropagation()
-			}
-		},
-		{ capture: true },
-	)
-
 	onTap(backdrop, () => {
 		const kbWasOpen = isKeyboardOpen()
 		haptic()

src/util/tap.ts

@@ -1,23 +1,48 @@
 /**
  * Register a tap handler that works on both touch and non-touch devices.
  *
- * iOS Safari can fail to synthesise `click` after touch events on dynamically
- * created elements. This listens for `touchend` (fires on finger lift — correct
- * button press-then-release UX) and `click` (fallback for mouse/keyboard).
- * A guard prevents double-fire when both events occur.
+ * ## Why module-level touchFired (not per-element)
+ *
+ * On touch devices, after touchend fires, the browser synthesises a click
+ * ~4ms later at the same coordinates. When a touchend handler opens an
+ * overlay (higher z-index) at those coordinates, the synthesised click
+ * hit-tests against the overlay instead of the original button — closing
+ * it immediately. A per-element guard only prevents double-fire on the
+ * SAME element; module-level state prevents cross-element synthesised clicks.
+ *
+ * ## Why not preventDefault() on touchend
+ *
+ * The W3C Touch Events spec says preventDefault() on touchend suppresses
+ * synthesised mouse events — the "correct" solution. But it was removed
+ * (d40fa46) because without synthesised mousedown, focus stays on the
+ * terminal textarea and Android re-shows the keyboard when toolbar buttons
+ * are pressed. Restoring it would require blur() + reworking keyboard state
+ * preservation (isKeyboardOpen/conditionalFocus) across 13 call sites.
+ *
+ * ## Why not Pointer Events (pointerup)
+ *
+ * preventDefault() on pointerup does NOT suppress compatibility mouse
+ * events per the Pointer Events spec. The browser still synthesises
+ * mousedown/mouseup/click from the underlying touch events.
  */
-export function onTap(element: HTMLElement, handler: (e: Event) => void): void {
-	let touchFired = false
 
+let touchFired = false
+let touchGuardTimer: ReturnType<typeof setTimeout> | null = null
+
+export function onTap(element: HTMLElement, handler: (e: Event) => void): void {
 	element.addEventListener('touchend', (e: TouchEvent) => {
 		// No preventDefault — allow the browser to synthesise mousedown/click,
 		// which transfers focus to the button and away from the terminal textarea.
 		// Without this, Android re-shows the keyboard when buttons are pressed.
-		// The touchFired guard below prevents the handler from double-firing.
+		// The module-level touchFired guard below prevents the handler from
+		// double-firing on this element AND prevents cross-element synthesised
+		// clicks from closing overlays that just opened at the same coordinates.
 		touchFired = true
 		handler(e)
-		setTimeout(() => {
+		if (touchGuardTimer !== null) clearTimeout(touchGuardTimer)
+		touchGuardTimer = setTimeout(() => {
 			touchFired = false
+			touchGuardTimer = null
 		}, 400)
 	})
 
@@ -26,3 +51,12 @@ export function onTap(element: HTMLElement, handler: (e: Event) => void): void {
 		handler(e)
 	})
 }
+
+/** Reset module-level touch guard state — test-only. */
+export function _resetTouchGuard(): void {
+	touchFired = false
+	if (touchGuardTimer !== null) {
+		clearTimeout(touchGuardTimer)
+		touchGuardTimer = null
+	}
+}

tests/integration.test.ts

@@ -8,6 +8,7 @@ import { createHelpOverlay } from '../src/controls/help'
 import { createDrawer } from '../src/drawer/drawer'
 import { createHookRegistry } from '../src/hooks/registry'
 import { createToolbar } from '../src/toolbar/toolbar'
+import { _resetTouchGuard } from '../src/util/tap'
 import { mockTerminal } from './fixtures'
 
 beforeEach(() => {
@@ -138,6 +139,10 @@ describe('font controls integration', () => {
 })
 
 describe('help overlay integration', () => {
+	beforeEach(() => {
+		_resetTouchGuard()
+	})
+
 	test('creates help overlay', () => {
 		const term = mockTerminal()
 		const { helpButton } = createFontControls(term, defaultConfig.font)
@@ -178,6 +183,28 @@ describe('help overlay integration', () => {
 		expect(element.querySelector('.wt-help-version')).toBeNull()
 	})
 
+	test('synthesised click after touchend does not immediately close overlay', () => {
+		const term = mockTerminal()
+		const { element: fontControls, helpButton } = createFontControls(term, defaultConfig.font)
+		const { element: overlay } = createHelpOverlay(term, helpButton, defaultConfig)
+
+		document.body.appendChild(fontControls)
+		document.body.appendChild(overlay)
+
+		// Simulate touch on ? button — touchend opens the overlay
+		helpButton.dispatchEvent(new Event('touchend', { bubbles: true }))
+		expect(overlay.style.display).toBe('block')
+
+		// Browser synthesises click ~4ms later. On a real device the overlay
+		// (higher z-index) now covers the ? button area, so hit-testing targets
+		// the overlay element itself. Simulate this by dispatching click on the
+		// overlay with target === overlay.
+		overlay.dispatchEvent(new Event('click', { bubbles: true }))
+
+		// Overlay should still be open — the synthesised click must be ignored
+		expect(overlay.style.display).toBe('block')
+	})
+
 	test('renders configured button descriptions and no stale Claude section', () => {
 		const term = mockTerminal()
 		const { helpButton } = createFontControls(term, defaultConfig.font)

tests/playwright/touch.spec.ts

@@ -93,9 +93,8 @@ test('drawer open → close → re-open cycle', async ({ page }) => {
 test('synthesised click from tap() hits backdrop (regression guard)', async ({ page }) => {
 	// Proves the mechanism that caused the open-then-close bug still exists:
 	// after touchend opens the drawer, synthesised mousedown/click land on the
-	// backdrop. The justOpened guard in drawer.ts must block these.
-	// Listen at document level (capture phase) because the fix uses
-	// stopImmediatePropagation on the backdrop element.
+	// backdrop. The module-level touch guard in tap.ts suppresses the onTap
+	// click handler, so the drawer stays open despite the click reaching it.
 	await page.evaluate(() => {
 		const w = window as unknown as { __backdropClicks: { isTrusted: boolean }[] }
 		w.__backdropClicks = []

tests/tap.test.ts

@@ -1,7 +1,11 @@
-import { describe, expect, test, vi } from 'vitest'
-import { onTap } from '../src/util/tap'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+import { _resetTouchGuard, onTap } from '../src/util/tap'
 
 describe('onTap', () => {
+	beforeEach(() => {
+		_resetTouchGuard()
+	})
+
 	test('fires handler on click', () => {
 		const element = document.createElement('button')
 		const handler = vi.fn()
@@ -50,4 +54,37 @@ describe('onTap', () => {
 
 		vi.useRealTimers()
 	})
+
+	test('touchend on element A suppresses click on element B', () => {
+		const a = document.createElement('button')
+		const b = document.createElement('button')
+		const handlerA = vi.fn()
+		const handlerB = vi.fn()
+		onTap(a, handlerA)
+		onTap(b, handlerB)
+
+		a.dispatchEvent(new TouchEvent('touchend'))
+		b.dispatchEvent(new Event('click'))
+
+		expect(handlerA).toHaveBeenCalledOnce()
+		expect(handlerB).not.toHaveBeenCalled()
+	})
+
+	test('cross-element click works after guard timeout', () => {
+		vi.useFakeTimers()
+		const a = document.createElement('button')
+		const b = document.createElement('button')
+		const handlerA = vi.fn()
+		const handlerB = vi.fn()
+		onTap(a, handlerA)
+		onTap(b, handlerB)
+
+		a.dispatchEvent(new TouchEvent('touchend'))
+		vi.advanceTimersByTime(400)
+		b.dispatchEvent(new Event('click'))
+
+		expect(handlerB).toHaveBeenCalledOnce()
+
+		vi.useRealTimers()
+	})
 })