fix: webcam stream actually fires + JS auto-arms record toggle

Root cause: gradio 4.44.1's gr.Image(streaming=True) only dispatches
.stream() events while the user is actively "recording" (Webcam.svelte
gates take_picture on `recording=true`). We had hidden the record
toggle via CSS, so the stream never started and _stash_frame never ran.

Fixes:
- Inject JS that polls for the (hidden) record button and clicks it
once per mount, flipping recording=true so frames flow.
- .stream() now wires to a hidden gr.Number sink — outputs=[] silently
disables the handler in 4.44.1.
- landmark_classifier: retry on transient HF download failure instead
of caching the failure forever, log full exception text + token state,
and fall back to anonymous fetch when the token call 404s.
- app.py: configure root logging so signbridge.* messages reach stdout.

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

app.py

@@ -7,11 +7,17 @@ Gradio interface it builds. Keep this file thin — real UI lives in
 
 from __future__ import annotations
 
+import logging
 import os
 
 from dotenv import load_dotenv
 
-from signbridge.space import build_demo
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+)
+
+from signbridge.space import build_demo  # noqa: E402
 
 
 def main() -> None:

signbridge/recognizer/landmark_classifier.py

@@ -44,12 +44,35 @@ def _resolve_weight(local_override: str | None, filename: str) -> Path | None:
     except ImportError:
         logger.warning("huggingface_hub missing; cannot fetch %s.", filename)
         return None
-    try:
-        local = hf_hub_download(repo_id=_HF_REPO, filename=filename, repo_type="model")
-        return Path(local)
-    except Exception as exc:  # noqa: BLE001 — HF Hub can fail for many reasons
-        logger.warning("hf_hub_download(%s) failed: %s", filename, type(exc).__name__)
-        return None
+    token = os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACE_HUB_TOKEN") or None
+    logger.info(
+        "hf_hub_download(%s) attempt: repo=%s token_len=%d",
+        filename, _HF_REPO, len(token) if token else 0,
+    )
+    # First attempt: with explicit token (if set). If that fails with
+    # auth-flavoured RepositoryNotFoundError, retry anonymously — public
+    # repos work without auth, and a stale/invalid token can poison even
+    # public reads.
+    last_exc: Exception | None = None
+    for attempt_token in (token, None):
+        try:
+            local = hf_hub_download(
+                repo_id=_HF_REPO,
+                filename=filename,
+                repo_type="model",
+                token=attempt_token,
+            )
+            logger.info("hf_hub_download(%s) ok via %s", filename, "token" if attempt_token else "anonymous")
+            return Path(local)
+        except Exception as exc:  # noqa: BLE001 — many failure modes
+            last_exc = exc
+            logger.warning(
+                "hf_hub_download(%s) failed (token=%s): %s — %s",
+                filename, "yes" if attempt_token else "no", type(exc).__name__, str(exc)[:300],
+            )
+            if attempt_token is None:
+                break  # already tried anonymously
+    return None
 
 _lock = threading.Lock()
 _state: dict[str, object] = {"loaded": False, "landmarker": None, "mlp": None, "classes": None}
@@ -66,7 +89,11 @@ def _normalize_landmarks(coords3: np.ndarray) -> np.ndarray:
 
 
 def _ensure_loaded() -> bool:
-    """Lazy-load MediaPipe + MLP. Returns True if both ready."""
+    """Lazy-load MediaPipe + MLP. Returns True if both ready.
+
+    Transient failures (HF Hub blip, momentary network) are NOT cached
+    so the next call retries. Only deps-missing (ImportError) is fatal
+    and cached, since it can't fix itself at runtime."""
     if _state["loaded"]:
         return _state["landmarker"] is not None and _state["mlp"] is not None
     with _lock:
@@ -75,13 +102,11 @@ def _ensure_loaded() -> bool:
 
         mlp_path = _resolve_weight(_MLP_LOCAL_OVERRIDE, _MLP_FILENAME)
         if mlp_path is None:
-            logger.info("MLP weights unavailable; landmark classifier disabled.")
-            _state["loaded"] = True
+            logger.warning("MLP weights download failed; will retry on next call.")
             return False
         hand_path = _resolve_weight(_HAND_LOCAL_OVERRIDE, _HAND_FILENAME)
         if hand_path is None:
-            logger.info("hand_landmarker.task unavailable; landmark classifier disabled.")
-            _state["loaded"] = True
+            logger.warning("hand_landmarker.task download failed; will retry on next call.")
             return False
 
         try:
@@ -91,7 +116,7 @@ def _ensure_loaded() -> bool:
             import torch.nn as nn  # type: ignore[import-not-found]
         except ImportError as exc:
             logger.warning("landmark classifier deps missing (%s); disabled.", exc)
-            _state["loaded"] = True
+            _state["loaded"] = True  # cache: deps won't appear at runtime
             return False
 
         opts = vision.HandLandmarkerOptions(

signbridge/space.py

@@ -82,11 +82,8 @@ class _SessionState:
     last_audio_path: str | None = None
 
 
-# Single-user demo: one global latest-frame variable instead of a
-# session-keyed dict. The previous session-keyed approach failed because
-# adding `gr.Request` to a stream-handler signature appears to silently
-# kill the handler in gradio 4.44.1 (TypeError swallowed by the queue
-# worker). No request injection here = no failure surface.
+# Single-user demo: one global latest-frame variable populated by the
+# .stream() handler. The Take-image button reads from here.
 _latest_frame: np.ndarray | None = None
 _frame_lock = threading.Lock()
 _stash_count = 0
@@ -96,6 +93,26 @@ def _new_session() -> _SessionState:
     return _SessionState()
 
 
+def _stash_frame(frame: np.ndarray | None) -> int:
+    """Webcam .stream() callback. Fires every ~500ms (gradio's internal
+    setInterval in Webcam.svelte) once `recording=true`. Writes the
+    latest live frame to the global cache. Returns _stash_count so we
+    can wire a real (hidden) output — empty outputs=[] silently
+    disables the handler in gradio 4.44.1."""
+    global _latest_frame, _stash_count
+    if frame is None:
+        return _stash_count
+    with _frame_lock:
+        _latest_frame = frame
+        _stash_count += 1
+        if _stash_count == 1 or _stash_count % 30 == 0:
+            print(
+                f"[stash] fired #{_stash_count} shape={frame.shape}",
+                flush=True,
+            )
+    return _stash_count
+
+
 def _format_history(signs: list[str]) -> str:
     if not signs:
         return "_(no signs captured yet — try signing the letter A and pressing Capture)_"
@@ -146,44 +163,26 @@ def _shared_extractor() -> LandmarkExtractor:
         return _extractor_singleton
 
 
-def _stash_frame(frame: np.ndarray | None) -> None:
-    """Webcam .change() callback — writes every live frame to the global
-    `_latest_frame`. Bare signature (no gr.Request, no extra params) so
-    gradio's signature inspection can't fail."""
-    global _latest_frame, _stash_count
-    if frame is None:
-        return
-    with _frame_lock:
-        _latest_frame = frame
-        _stash_count += 1
-        # Log every ~30 frames (~1/sec at 30 fps webcam) so HF run logs
-        # confirm the handler is actually firing.
-        if _stash_count == 1 or _stash_count % 30 == 0:
-            logger.info(
-                "_stash_frame fired %d times; last shape=%s dtype=%s",
-                _stash_count, frame.shape, frame.dtype,
-            )
-
-
 def _capture_sign(state: _SessionState) -> tuple[str, str, _SessionState]:
-    """Take-image button handler. Reads the latest live frame from the
-    global cache, runs recognition, appends to history."""
+    """Take-image button handler. Reads the latest streamed frame from
+    the global cache, runs recognition, appends to history."""
     with _frame_lock:
         frame = _latest_frame
-
-    logger.info(
-        "_capture_sign: frame_present=%s, stash_count=%d",
-        frame is not None, _stash_count,
+    print(
+        f"[capture] stash_count={_stash_count} frame_present={frame is not None}",
+        flush=True,
     )
 
     if frame is None:
         return (
-            "_no frame yet — make sure the camera preview is live and try again_",
+            "_no frame yet — wait a moment for the camera to start streaming, then try again_",
             _format_history(state.sign_history),
             state,
         )
 
     token, confidence = _recognize(frame)
+    print(f"[capture] recognised token={token!r} conf={confidence:.2f}", flush=True)
+
     if not token or confidence < 0.5:
         return (
             "_couldn't recognise that one — try centering the gesture and a plain background_",
@@ -265,12 +264,52 @@ _WEBCAM_BUTTON_LABEL_CSS = """
     font-size: 13px;
     color: #1e1b4b;
 }
+/* Snapshot tab uses streaming + a custom Take-image button. We hide
+   gradio's built-in controls so the user only sees the live preview
+   and our button. A small JS snippet auto-clicks the (hidden) record
+   toggle once after permission is granted, which makes Webcam.svelte
+   start dispatching the .stream() event every 500ms. The
+   "Click to Access Webcam" placeholder is a separate DOM node and
+   stays visible — browsers require a user gesture for getUserMedia(). */
+.signbridge-webcam-snapshot .source-selection,
+.signbridge-webcam-snapshot .controls,
+.signbridge-webcam-snapshot .button-wrap {
+    display: none !important;
+}
+"""
+
+
+# JS injected at app load. Runs in the browser. Polls for gradio's
+# hidden record button inside our snapshot webcam and clicks it once
+# per mount, which flips Webcam.svelte's `recording=true` and starts
+# the .stream() frame loop. Without this, .stream() never fires —
+# gradio gates frame dispatch on the record toggle.
+_AUTO_ARM_STREAM_JS = """
+() => {
+    const SELECTOR = '.signbridge-webcam-snapshot .button-wrap > button';
+    const tick = () => {
+        document.querySelectorAll(SELECTOR).forEach((btn) => {
+            if (btn.dataset.signbridgeArmed) return;
+            // Only arm a freshly-mounted (not-yet-recording) button.
+            const titleDiv = btn.querySelector('div[title]');
+            if (titleDiv && titleDiv.title === 'start recording') {
+                btn.click();
+                btn.dataset.signbridgeArmed = '1';
+                console.log('[signbridge] auto-armed webcam stream');
+            }
+        });
+    };
+    setInterval(tick, 500);
+}
 """
 
 
 def build_demo() -> gr.Blocks:
     with gr.Blocks(
-        title="SignBridge", theme=gr.themes.Soft(), css=_WEBCAM_BUTTON_LABEL_CSS
+        title="SignBridge",
+        theme=gr.themes.Soft(),
+        css=_WEBCAM_BUTTON_LABEL_CSS,
+        js=_AUTO_ARM_STREAM_JS,
     ) as demo:
         gr.Markdown(
             "# 🤟 SignBridge — real-time ASL → English speech\n"
@@ -294,25 +333,27 @@ def build_demo() -> gr.Blocks:
                         gr.HTML(
                             '<div class="signbridge-webcam-help">'
                             '<b>How it works:</b> '
-                            '<b>1.</b> click the webcam once to grant access · '
+                            '<b>1.</b> click the preview once to grant camera access · '
                             '<b>2.</b> sign a letter (A–Z) · '
                             '<b>3.</b> click <b>📸 Take image</b> — recognition is automatic · '
                             '<b>4.</b> repeat for the next letter, then press <b>🔊 Speak</b>.'
                             "</div>"
                         )
+                        # streaming=True keeps the live preview running
+                        # continuously. _AUTO_ARM_STREAM_JS clicks the
+                        # hidden record button after permission grant
+                        # so Webcam.svelte starts dispatching frames
+                        # via the .stream() event (gated on
+                        # `recording=true`). We hide the record/stop
+                        # controls via CSS so the user only sees a
+                        # clean preview + our Take-image button.
                         webcam = gr.Image(
                             sources=["webcam"],
-                            # streaming=True keeps the live preview running
-                            # after the one-time permission grant, so the
-                            # user never sees the access-prompt screen
-                            # again. Frames are stashed in session state via
-                            # the .stream() handler, and the Take-image
-                            # button reads from there.
                             streaming=True,
                             label="Sign here",
                             height=420,
                             type="numpy",
-                            elem_classes=["signbridge-webcam"],
+                            elem_classes=["signbridge-webcam", "signbridge-webcam-snapshot"],
                         )
                         with gr.Row():
                             capture_btn = gr.Button(
@@ -341,13 +382,13 @@ def build_demo() -> gr.Blocks:
                             "Spell out a word letter-by-letter, then press Speak."
                         )
 
-                # Use .change() (not .stream()) — it fires on every value
-                # change which, for a streaming webcam, is every frame.
-                # outputs=[] is required (None doesn't wire the event).
-                webcam.change(
+                # Hidden Number sink for the .stream() handler — empty
+                # outputs=[] silently disables it in gradio 4.44.1.
+                _stash_sink = gr.Number(value=0, visible=False)
+                webcam.stream(
                     fn=_stash_frame,
                     inputs=[webcam],
-                    outputs=[],
+                    outputs=[_stash_sink],
                     show_progress="hidden",
                 )
                 capture_btn.click(