From 3ed785c33ee8cd509a46e546dfce67177b1148b9 Mon Sep 17 00:00:00 2001
From: Julian Cuni <julian.cuni@microservices.al>
Date: Sun, 21 Jun 2026 15:03:01 +0200
Subject: [PATCH] feat(booth): open the pay/exit modal on a hardware scan
 regardless of focus
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A barcode/QR scanner is an HID "keyboard wedge" — it types the id + Enter into
whatever holds focus. Previously that only worked while the ticket <input> was
focused; a scan with focus elsewhere (or nowhere) went nowhere.

New useScanner hook (apps/web/src/lib/use-scanner.ts): a document-level keydown
listener that detects the scanner's FAST keystroke burst ended by Enter and opens
the pay/exit modal via setActiveTicket — regardless of focus. A gap > 50ms resets
the buffer, so human-paced typing with nothing focused never registers as a scan
(min length 3 guards stray Enters). Keystrokes into an input/textarea/select/
contenteditable are ignored, so the manual ticket field still works by hand. The
hook is paused while a modal is already open — a scan must not abandon an
in-progress payment; the operator finishes/closes, then scans the next car.

Verified at runtime (Playwright): a fast burst with focus on BODY opens the modal;
a second scan while the modal is open is ignored; slow (120ms) human typing does
NOT open it; the manual input submit still opens it. build+lint 14/14.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V
---
 apps/web/src/BoothScreen.tsx    |  6 +++
 apps/web/src/lib/use-scanner.ts | 78 +++++++++++++++++++++++++++++++++
 wiki/concepts/booth-console.md  |  8 ++++
 wiki/log.md                     | 10 +++++
 4 files changed, 102 insertions(+)
 create mode 100644 apps/web/src/lib/use-scanner.ts

diff --git a/apps/web/src/BoothScreen.tsx b/apps/web/src/BoothScreen.tsx
index 7fa2a2f..e8f9314 100644
--- a/apps/web/src/BoothScreen.tsx
+++ b/apps/web/src/BoothScreen.tsx
@@ -5,6 +5,7 @@ import { fetchEvents, fetchOccupancy, type LedgerEvent, type Occupancy } from ".
 import { qk } from "./lib/query.js";
 import { useLiveStore } from "./lib/live-store.js";
 import { useShift } from "./lib/use-shift.js";
+import { useScanner } from "./lib/use-scanner.js";
 import { Panel } from "./ui/Panel.js";
 import { StatusDot } from "./ui/StatusDot.js";
 import { BoothPayModal } from "./BoothPayModal.js";
@@ -132,6 +133,11 @@ export function BoothScreen() {
   // The ledger event open in the read-only detail modal (null = closed).
   const [detailEvent, setDetailEvent] = useState<LedgerEvent | null>(null);
 
+  // A hardware scan opens the pay/exit modal regardless of focus (the operator needn't
+  // click the ticket field first). Paused while a modal is already up — a scan must not
+  // abandon an in-progress payment (the operator finishes/closes, then scans the next).
+  useScanner({ onScan: setActiveTicket, paused: activeTicket != null || detailEvent != null });
+
   // Live-feed filters: free-text search, event category, and direction/source.
   const [feedSearch, setFeedSearch] = useState("");
   const [feedType, setFeedType] = useState<FeedCat | "">("");
diff --git a/apps/web/src/lib/use-scanner.ts b/apps/web/src/lib/use-scanner.ts
new file mode 100644
index 0000000..0c931b9
--- /dev/null
+++ b/apps/web/src/lib/use-scanner.ts
@@ -0,0 +1,78 @@
+import { useEffect, useRef } from "react";
+
+// Global hardware-scanner capture (HID "keyboard wedge"). A barcode/QR scanner types
+// the code as a fast keystroke burst followed by Enter — like a keyboard, but far
+// faster than a human. This hook listens at the DOCUMENT level so a scan fires the
+// callback no matter what's focused (or if nothing is), unlike a single <input> that
+// only catches scans while it holds focus. See wiki/concepts/booth-console.md.
+//
+// It does NOT hijack manual typing: keystrokes into an <input>/<textarea>/editable
+// element are left to that field (the booth's ticket input still works by hand). The
+// burst heuristic — chars arriving faster than a human could type, ended by Enter —
+// is what distinguishes a scan from a person pressing keys with nothing focused.
+
+/** Tuning. A scanner emits keystrokes ~1–20ms apart; a human is ≥80–100ms. */
+const MAX_INTERKEY_MS = 50; // a gap longer than this resets the buffer (not one scan)
+const MIN_LENGTH = 3; // ignore stray single Enter presses / very short bursts
+
+interface ScannerOptions {
+  /** Called with the scanned code (trimmed) when a burst completes with Enter. */
+  onScan: (code: string) => void;
+  /** When true, scans are ignored (e.g. a modal is already open — don't interrupt an
+   *  in-progress payment). The listener stays attached; it just no-ops. */
+  paused?: boolean;
+}
+
+/** Capture hardware-scanner input globally. The callback fires on the Enter that ends a
+ *  fast keystroke burst, regardless of focus. Editable-field keystrokes are ignored so
+ *  manual typing is unaffected. */
+export function useScanner({ onScan, paused = false }: ScannerOptions): void {
+  // Keep the latest callback + paused flag in refs so the effect's listener never goes
+  // stale and we don't re-attach on every render.
+  const onScanRef = useRef(onScan);
+  const pausedRef = useRef(paused);
+  onScanRef.current = onScan;
+  pausedRef.current = paused;
+
+  useEffect(() => {
+    let buffer = "";
+    let lastTime = 0;
+
+    function isEditableTarget(el: EventTarget | null): boolean {
+      if (!(el instanceof HTMLElement)) return false;
+      const tag = el.tagName;
+      return tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT" || el.isContentEditable;
+    }
+
+    function onKeyDown(e: KeyboardEvent) {
+      // Let the focused field (and its form) handle its own keystrokes — the manual
+      // ticket input submits via its form's onSubmit; we only cover the un-focused case.
+      if (isEditableTarget(e.target)) return;
+
+      const now = e.timeStamp || performance.now();
+      const gap = now - lastTime;
+      lastTime = now;
+
+      if (e.key === "Enter") {
+        const code = buffer.trim();
+        buffer = "";
+        // Only a fast-burst code of reasonable length counts as a scan; a lone Enter or
+        // a slowly-assembled string (a person mashing keys) is ignored.
+        if (code.length >= MIN_LENGTH && !pausedRef.current) {
+          e.preventDefault();
+          onScanRef.current(code);
+        }
+        return;
+      }
+
+      // A gap too long means a new (human-paced) sequence — start the buffer over.
+      if (gap > MAX_INTERKEY_MS) buffer = "";
+
+      // Accumulate printable single characters (scanner codes: digits + SUB-/SUBSESS-…).
+      if (e.key.length === 1) buffer += e.key;
+    }
+
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, []);
+}
diff --git a/wiki/concepts/booth-console.md b/wiki/concepts/booth-console.md
index 90c257f..f6dc252 100644
--- a/wiki/concepts/booth-console.md
+++ b/wiki/concepts/booth-console.md
@@ -68,6 +68,14 @@ a right column with the **live event ticker**. Submitting/clicking a ticket open
 modal** (entry/duration/total, tender, voucher checkbox, entry/exit snapshots). All live-refreshed via
 the WS.
 
+> **Focus-independent scan capture (2026-06-21).** A scan now opens the pay/exit modal **regardless of
+> focus** — the operator needn't click the ticket field first. A document-level listener (`useScanner`,
+> `apps/web/src/lib/use-scanner.ts`) detects the HID scanner's fast keystroke BURST ended by Enter (a
+> gap > 50ms resets the buffer, so human-paced typing with nothing focused never triggers it) and fires
+> the same `setActiveTicket`. It ignores keystrokes into an `<input>/<textarea>/select/contenteditable`
+> so the manual ticket field still works by hand. It is **paused while a modal is already open** — a
+> scan must not abandon an in-progress payment; the operator finishes/closes, then scans the next car.
+
 ### Explainable activity log (2026-06-19)
 The ticker used to flag an **anomaly** with no explanation — a red row with just an id, "nobody knows
 what happened." Now every event is **self-describing and clickable**:
diff --git a/wiki/log.md b/wiki/log.md
index 661029a..4f36305 100644
--- a/wiki/log.md
+++ b/wiki/log.md
@@ -1299,3 +1299,13 @@ viewport like /booth: a fixed title+filters, then a two-pane area (shift list |
 pane scrolls independently (min-h-0/flex-1 + overflow-y-auto) instead of the whole page growing.
 Verified at runtime (Playwright): /shift redirects, rows open the detail modal, layout fills height,
 booth still works (0 console errors). build+lint 14/14.
+
+## [2026-06-21] feat | Booth: focus-independent hardware-scan capture
+A scan now opens the /booth pay/exit modal no matter what's focused (or if nothing is) — the operator
+needn't click the ticket field first. New useScanner hook (apps/web/src/lib/use-scanner.ts): a
+document-level keydown listener that detects the HID scanner's fast keystroke burst ended by Enter (gap
+> 50ms resets the buffer, so human-paced typing never triggers it; min length 3) and fires
+setActiveTicket. Ignores keystrokes into editable fields so the manual ticket input is unaffected;
+paused while a modal is open so a scan can't abandon an in-progress payment. Verified at runtime
+(Playwright): scan with focus on BODY opens the modal; second scan while open is ignored; slow typing
+doesn't trigger; manual form submit still works. build+lint 14/14. See [[booth-console]].