fix(#53+#54): page.tsx SPACE-hold PTT delegates to warm-stream hook

Final wiring of the warm-stream/pre-roll engine (#53/#54). The SPACE-hold
push-to-talk path no longer cold-starts its own getUserMedia +
MediaRecorder per press; it delegates to streamingVoice.beginPushToTalk()
/ endPushToTalk(). The hook keeps the OS mic warm and prepends an 800ms
pre-roll, so the first word ('Sir.') is always at the head of one valid
webm blob (head-clip #53 eliminated) and capture begins instantly (no
multi-second start delay #54). All prior semantics preserved: e.repeat/
modifier/shouldSuppressSpace guards, recording/busy gate (+ new
spaceHoldPttInFlightRef re-entrancy guard), spaceHoldOwnsRec /
setSpaceHoldActive, bot-TTS interrupt, voicePhase UX, busy ownership left
to send() (avoids silent turn-drop), maybeResumeLive/userPrefersLive,
mic_permission_denied banner, sub-threshold tap = clean no-op, no
double-submit. On-screen PTT button left on legacy path (separate
handler, out of reported scope — tracked for follow-up).

tsc clean; build green; pytest 233 passed (+7 new
test_space_hold_ptt_delegation.py).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

frontend/src/app/page.tsx

@@ -1306,6 +1306,93 @@ export default function Page() {
   }
   function stopRecording() { mediaRecorderRef.current?.stop(); }
 
+  // #53 (head-clip) / #54 (PTT start latency) — the SPACE-hold path now
+  // DELEGATES to useStreamingVoice's warm-stream + pre-roll API instead of
+  // cold-starting its own getUserMedia + MediaRecorder per press. The hook
+  // keeps the OS mic hot and a rolling 800ms pre-roll, so the first word
+  // ("Sir." that previously transcribed as "S A R") is always at the head of
+  // the blob and there is no multi-second per-press start delay.
+  //
+  // Why delegation (not "prepend pre-roll blobs to page.tsx's recorder"):
+  // splicing slices from two independent MediaRecorder streams produces a
+  // corrupt webm container. The hook owns the single recorder that captured
+  // BOTH the pre-roll and the held utterance, so only it can assemble a valid
+  // blob. `endPushToTalk()` already runs the exact Sarvam submit+retry path
+  // and, on success, delivers the transcript via the hook's onFinalTranscript
+  // callback — which page.tsx wires (see useStreamingVoice config above) to
+  // `voiceSubmitRef.current` → `send()`, i.e. the IDENTICAL downstream path a
+  // successful /api/transcribe result used in recorder.onstop. We therefore
+  // MUST NOT re-submit the returned string here (that would double-fire); the
+  // returned value is used only to distinguish a deliberate hold from a
+  // sub-threshold tap (null) for clean state reset.
+  const spaceHoldPttInFlightRef = useRef<boolean>(false);
+  async function startSpaceHoldPTT() {
+    // Re-entrancy guard: a second SPACE keydown while a delegated PTT capture
+    // (or its in-flight transcription) is still resolving must be ignored,
+    // mirroring the original recordingRef/busyRef "don't start twice" intent.
+    if (spaceHoldPttInFlightRef.current) return;
+    spaceHoldPttInFlightRef.current = true;
+    // Preserve recorder.onstop / startRecording semantics: silence any prior
+    // bot TTS the instant the user starts talking (KI-222 FIX 1 / V3 FIX 2).
+    try { interruptBotAudio("ptt-start"); } catch { /* ignore */ }
+    // STT-in-flight UX: the original path flipped voicePhase to "transcribing"
+    // while Sarvam ran. endPushToTalk() runs that same Sarvam call internally,
+    // so set the phase here. NOTE: we deliberately do NOT setBusy(true) — the
+    // hook's onFinalTranscript → voiceSubmitRef → send() owns busy, and send()
+    // early-returns if busy is already true (would silently drop the turn).
+    setVoicePhase("transcribing"); // KI-038 — STT in flight on PTT
+    try {
+      streamingVoice.beginPushToTalk();
+    } catch (e) {
+      // beginPushToTalk itself is non-throwing by contract, but stay defensive
+      // and route any unexpected failure to the same red banner the cold path
+      // used. Warm-stream / permission failures surface via the hook's
+      // onVoiceError → setVoiceErrorBanner (mic_permission_denied) already.
+      console.error(e);
+      spaceHoldPttInFlightRef.current = false;
+      setVoicePhase(null);
+      setSpaceHoldActive(false);
+      setVoiceErrorBanner({ type: "mic_permission_denied", ts: Date.now() });
+    }
+  }
+  async function stopSpaceHoldPTT() {
+    if (!spaceHoldPttInFlightRef.current) return;
+    // KI-028 — resume Live ONLY if the user's persistent preference is still
+    // "on" (matches the original recorder.onstop maybeResumeLive semantics).
+    const maybeResumeLive = () => { if (userPrefersLive) live.setLive(true); };
+    try {
+      // endPushToTalk(): on a deliberate hold it transcribes (pre-roll + held
+      // utterance) AND delivers via onFinalTranscript → voiceSubmitRef →
+      // send() — the EXACT downstream path the old recorder.onstop success
+      // branch used. On a sub-threshold tap / empty capture it resolves to
+      // null and submits nothing. All transport / Sarvam failures surface via
+      // the hook's onVoiceError (transcribe_failed banner) — never silent.
+      const text = await streamingVoice.endPushToTalk();
+      if (text === null) {
+        // Sub-threshold tap or nothing captured: clean no-op. No empty submit;
+        // just clear the cosmetic "transcribing" phase we set on keydown.
+        setVoicePhase(null);
+        maybeResumeLive();
+      } else {
+        // Deliberate hold: the hook has ALREADY pushed `text` through
+        // onFinalTranscript → send(). send() owns busy + flips voicePhase to
+        // "thinking" and clears both in its own finally, so we must NOT reset
+        // voicePhase here (that would stomp send()'s "thinking") and must NOT
+        // re-submit. Just resume Live per the user's preference.
+        maybeResumeLive();
+      }
+    } catch (e) {
+      // endPushToTalk's internal Sarvam path swallows its own errors and
+      // surfaces them via onVoiceError; reaching here means an unexpected
+      // throw. Reset cosmetic state so the UI doesn't stick in "transcribing".
+      console.error(e);
+      setVoicePhase(null);
+      maybeResumeLive();
+    } finally {
+      spaceHoldPttInFlightRef.current = false;
+    }
+  }
+
   // KI-258 — Hold-SPACE-to-talk. Fixes from KI-257 first ship:
   //   (a) textarea ALWAYS had focus → isInputFocused() was always true →
   //       SPACE never fired. Fix: allow SPACE-hold when the textarea is
@@ -1314,14 +1401,20 @@ export default function Page() {
   //       handlers mid-press, splitting keydown/keyup across closures
   //       with stale values. Fix: read all state via refs; deps reduced
   //       to [voiceMasterOn] so handlers bind once.
+  // #53/#54 — these refs now point at the DELEGATED SPACE-hold handlers
+  // (startSpaceHoldPTT / stopSpaceHoldPTT), which route through the hook's
+  // warm-stream + pre-roll API. The on-screen Push-to-talk *button* still
+  // uses startRecording/stopRecording directly (separate onClick handler,
+  // intentionally untouched — it does not share this code path), so the
+  // legacy recorder path is preserved for that control.
   const startRecordingRef = useRef<(() => Promise<void>) | null>(null);
-  const stopRecordingRef = useRef<(() => void) | null>(null);
+  const stopRecordingRef = useRef<(() => Promise<void>) | null>(null);
   const recordingRef = useRef<boolean>(recording);
   const busyRef = useRef<boolean>(busy);
   const spaceHoldOwnsRecRef = useRef<boolean>(false);
   useEffect(() => {
-    startRecordingRef.current = startRecording;
-    stopRecordingRef.current = stopRecording;
+    startRecordingRef.current = startSpaceHoldPTT;
+    stopRecordingRef.current = stopSpaceHoldPTT;
     recordingRef.current = recording;
     busyRef.current = busy;
   });
@@ -1368,7 +1461,13 @@ export default function Page() {
       spaceHoldOwnsRecRef.current = false;
       setSpaceHoldActive(false);
       const sp = stopRecordingRef.current;
-      if (sp && recordingRef.current) sp();
+      // Original guard was `recordingRef.current` (the legacy `recording`
+      // state). The delegated path doesn't drive `recording` (the hook owns
+      // capture state), so gate on the delegated in-flight flag instead — the
+      // exact equivalent of "a capture this keydown started is still active".
+      // Still resolve a deliberate hold even on a sub-threshold tap:
+      // stopSpaceHoldPTT is a clean no-op when nothing is in flight.
+      if (sp && spaceHoldPttInFlightRef.current) void sp();
     };
     window.addEventListener("keydown", onKeyDown);
     window.addEventListener("keyup", onKeyUp);

tests/test_space_hold_ptt_delegation.py

@@ -0,0 +1,239 @@
+"""Regression test for #53 (PTT head-clip) + #54 (PTT start latency) —
+the page.tsx SPACE-hold DELEGATION wiring — 2026-05-18.
+
+WHY A SEPARATE TEST FROM test_ptt_preroll_warm_stream.py
+-----------------------------------------------------------------------------
+test_ptt_preroll_warm_stream.py pins the *hook's* pure pre-roll + hold-gate
+logic (PreRollRing / evaluateHoldGate in useStreamingVoice.ts) and the
+backend STT head-survival contract. It does NOT pin the remaining surface:
+that page.tsx's SPACE-hold path actually DELEGATES to that hook instead of
+cold-starting its own getUserMedia + MediaRecorder per press. Naive prepending
+of the hook's pre-roll blobs onto page.tsx's *separate* recorder chunks would
+produce a corrupt webm (two independent MediaRecorder streams); the only
+correct fix is delegation. This file pins that delegation + every
+non-negotiable semantic it must preserve.
+
+WHY A SOURCE-ASSERTION TEST (no JS runner)
+-----------------------------------------------------------------------------
+This repo has NO JS/React test harness — frontend/package.json has no `test`
+script, no jest/vitest, and `tests/` is a pure pytest (Python) suite. The
+SPACE-hold delegation is browser DOM event wiring inside a React client
+component; it cannot be exercised from Python, and standing up a
+jest/RTL/jsdom toolchain would be a large out-of-scope change to shared
+frontend tooling. The existing sibling test (test_ptt_preroll_warm_stream.py)
+explicitly acknowledges this same constraint ("There is no JS test runner in
+this repo, so the two contracts are pinned at the layers a Python test can
+reach honestly") and pins frontend contracts via source assertions. This file
+follows that established repo idiom: it asserts the structural wiring
+contract in the SHIPPED page.tsx so a future refactor that silently
+re-introduces the per-press cold start (or drops a preserved semantic) fails
+CI loudly.
+
+Run:
+    cd /Users/rohitsar/Developer/Insurance\\ Sales\\ Bot
+    PYTHONPATH=$PWD .venv/bin/python -m pytest \
+        tests/test_space_hold_ptt_delegation.py -v
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+import pytest
+
+REPO = Path(__file__).resolve().parents[1]
+PAGE = REPO / "frontend" / "src" / "app" / "page.tsx"
+
+
+@pytest.fixture(scope="module")
+def src() -> str:
+    return PAGE.read_text()
+
+
+def _strip_comments(code: str) -> str:
+    """Drop // line-comment content (and blank-after-strip lines) so negative
+    assertions ("must NOT call send()/setBusy(true)") match only real CODE,
+    not the explanatory comments that legitimately *name* the avoided trap."""
+    out = []
+    for line in code.splitlines():
+        # Remove an inline/standalone // comment. No string literal in the
+        # delegated handlers contains "//", so a plain split is safe here.
+        if "//" in line:
+            line = line[: line.index("//")]
+        if line.strip():
+            out.append(line)
+    return "\n".join(out)
+
+
+def _slice(src: str, start_marker: str, end_marker: str) -> str:
+    """Return the source between (and including) two anchor substrings.
+    Asserts both anchors exist exactly once so the test fails loudly if the
+    region is renamed rather than silently asserting against the wrong code.
+    """
+    assert src.count(start_marker) == 1, f"anchor not unique: {start_marker!r}"
+    assert src.count(end_marker) == 1, f"anchor not unique: {end_marker!r}"
+    i = src.index(start_marker)
+    j = src.index(end_marker, i) + len(end_marker)
+    assert j > i, f"end anchor precedes start anchor: {end_marker!r}"
+    return src[i:j]
+
+
+def test_space_handler_refs_point_at_delegated_funcs(src: str):
+    """The SPACE keydown/keyup refs must be wired to the DELEGATED handlers
+    (startSpaceHoldPTT / stopSpaceHoldPTT), NOT the legacy per-press
+    cold-start startRecording/stopRecording. This is the core #53/#54 fix."""
+    assert "startRecordingRef.current = startSpaceHoldPTT;" in src, (
+        "SPACE keydown ref no longer points at the delegated handler — the "
+        "per-press getUserMedia cold start (head-clip #53 + latency #54) may "
+        "have been re-introduced."
+    )
+    assert "stopRecordingRef.current = stopSpaceHoldPTT;" in src
+    # The legacy refs must NOT be re-bound to the cold-start path.
+    assert "startRecordingRef.current = startRecording;" not in src
+    assert "stopRecordingRef.current = stopRecording;" not in src
+
+
+def test_delegated_start_calls_hook_beginPushToTalk(src: str):
+    """startSpaceHoldPTT must engage the hook's warm-stream PTT, never spin
+    its own getUserMedia / MediaRecorder."""
+    fn = _slice(
+        src,
+        "async function startSpaceHoldPTT() {",
+        "async function stopSpaceHoldPTT() {",
+    )
+    assert "streamingVoice.beginPushToTalk()" in fn, (
+        "startSpaceHoldPTT does not delegate to the hook's beginPushToTalk"
+    )
+    # No independent capture device may be opened on the delegated path.
+    assert "getUserMedia" not in fn, "delegated start must not cold-start a mic"
+    assert "new MediaRecorder" not in fn, (
+        "delegated start must not create its own recorder (corrupt-webm trap)"
+    )
+
+
+def test_delegated_stop_calls_hook_endPushToTalk_and_does_not_resubmit(src: str):
+    """stopSpaceHoldPTT must finalize via the hook's endPushToTalk().
+
+    The hook ALREADY delivers a deliberate-hold transcript via
+    onFinalTranscript -> voiceSubmitRef -> send() (the exact downstream path
+    the old recorder.onstop success branch used). Re-feeding the returned
+    string into send() here would double-submit, so the delegated stop must
+    NOT call send()/voiceSubmitRef itself."""
+    fn = _slice(
+        src,
+        "async function stopSpaceHoldPTT() {",
+        "  // #53/#54 — these refs now point at the DELEGATED SPACE-hold",
+    )
+    assert "await streamingVoice.endPushToTalk()" in fn
+    # No re-submission on the delegated stop path (hook already submitted).
+    # Check against CODE only — the comments legitimately name send() while
+    # explaining WHY we must not call it.
+    code = _strip_comments(fn)
+    assert "send(" not in code, (
+        "delegated stop re-submits the transcript — double-fire; the hook's "
+        "onFinalTranscript already routed it through send()"
+    )
+    assert "voiceSubmitRef" not in code
+
+
+def test_sub_threshold_tap_is_clean_noop(src: str):
+    """endPushToTalk() resolves null on a sub-threshold tap / empty capture.
+    The delegated stop must treat null as a clean no-op (no empty submit,
+    cosmetic state reset) — a non-negotiable semantic."""
+    fn = _slice(
+        src,
+        "async function stopSpaceHoldPTT() {",
+        "  // #53/#54 — these refs now point at the DELEGATED SPACE-hold",
+    )
+    assert "text === null" in fn, (
+        "delegated stop does not branch on the null (tap) result — a "
+        "sub-threshold tap may submit empty / leave state stuck"
+    )
+    # On the null branch the cosmetic phase set on keydown is cleared.
+    assert "setVoicePhase(null)" in fn
+
+
+def test_preserved_semantics_present_on_delegated_path(src: str):
+    """Enumerate the non-negotiable semantics the original SPACE path had and
+    assert each survives on the delegated path."""
+    start = _slice(
+        src,
+        "async function startSpaceHoldPTT() {",
+        "async function stopSpaceHoldPTT() {",
+    )
+    stop = _slice(
+        src,
+        "async function stopSpaceHoldPTT() {",
+        "  // #53/#54 — these refs now point at the DELEGATED SPACE-hold",
+    )
+
+    # interruptBotAudio("ptt-start") — silence prior bot TTS the instant the
+    # user starts talking (was startRecording's first action).
+    assert 'interruptBotAudio("ptt-start")' in start
+
+    # voicePhase "transcribing" UX while STT is in flight (was recorder.onstop).
+    assert 'setVoicePhase("transcribing")' in start
+
+    # busy is NOT force-set true before delegating — send() (invoked by the
+    # hook) owns busy and early-returns if busy is already true. Setting it
+    # here would silently drop the turn. Pin that this trap is avoided
+    # (CODE only; the comment legitimately names setBusy(true)).
+    assert "setBusy(true)" not in _strip_comments(start), (
+        "delegated start sets busy=true before send() runs — send() will "
+        "early-return on `busy` and the spoken turn is silently dropped"
+    )
+
+    # maybeResumeLive with the userPrefersLive gate (KI-028) survives.
+    assert "userPrefersLive" in stop and "live.setLive(true)" in stop
+
+    # mic_permission_denied banner surfacing is still reachable on the
+    # delegated start (defensive path) — matches the cold path's catch.
+    assert 'setVoiceErrorBanner({ type: "mic_permission_denied"' in start
+
+    # Re-entrancy guard equivalent to the old recordingRef/busyRef
+    # "don't start twice" intent.
+    assert "spaceHoldPttInFlightRef" in start
+
+
+def test_keydown_keyup_guards_unchanged(src: str):
+    """e.repeat / modifier guards, shouldSuppressSpace(), spaceHoldOwnsRecRef
+    ownership tracking, setSpaceHoldActive, and preventDefault must all remain
+    on the SPACE handlers (non-negotiable: a refactor must not nuke a
+    legitimately-typed space in the textarea)."""
+    handlers = _slice(
+        src,
+        "const onKeyDown = (e: KeyboardEvent) => {",
+        "window.addEventListener(\"keydown\", onKeyDown);",
+    )
+    # e.repeat + all modifier guards.
+    assert "if (e.repeat) return;" in handlers
+    assert "e.metaKey || e.ctrlKey || e.altKey || e.shiftKey" in handlers
+    # textarea guard still gates SPACE-hold.
+    assert "if (shouldSuppressSpace()) return;" in handlers
+    # ownership tracking + visual state both directions.
+    assert "spaceHoldOwnsRecRef.current = true;" in handlers
+    assert "spaceHoldOwnsRecRef.current = false;" in handlers
+    assert "setSpaceHoldActive(true);" in handlers
+    assert "setSpaceHoldActive(false);" in handlers
+    # the "did THIS keydown own the press" guard before stopping.
+    assert "if (!spaceHoldOwnsRecRef.current) return;" in handlers
+    # preventDefault on both keydown + keyup (stop a stray typed space).
+    assert handlers.count("e.preventDefault();") >= 2
+    # busy still blocks a fresh SPACE-hold start (turn in flight) and the
+    # delegated in-flight flag gates the stop call.
+    assert "if (recordingRef.current || busyRef.current) return;" in handlers
+    assert "spaceHoldPttInFlightRef.current) void sp();" in handlers
+
+
+def test_onscreen_button_path_left_intact(src: str):
+    """The on-screen Push-to-talk *button* uses a separate onClick handler
+    (startRecording/stopRecording) and does NOT share the SPACE code path, so
+    per the task it must be left untouched. Assert the legacy recorder
+    functions still exist and the button still uses them."""
+    assert "async function startRecording() {" in src
+    assert "function stopRecording() {" in src
+    # Button onClick still toggles the legacy recorder path.
+    assert re.search(
+        r"onClick=\{recording \? stopRecording : startRecording\}", src
+    ), "on-screen Push-to-talk button onClick wiring changed unexpectedly"