Upload folder using huggingface_hub

AGENTS.md

@@ -21,8 +21,10 @@ For tasks of **reboot** from a new codex session:
 1. Read doc/v0/PRD.md, doc/v0/Plan.md, doc/v0/Progress.md for baseline implementation
 2. Read doc/v1/PRD.md, doc/v1/Plan.md, doc/v1/Progress.md for edge refinement (v1)
 3. Read doc/v4/PRD.md, doc/v4/Plan.md, doc/v4/Progress.md for SAM 2.1 integration (card + hand)
-4. Assume this is a continuation of an existing project.
-5. Summarize your understanding of the current state and propose the next concrete step without writing code yet.
+4. Read doc/v5/PRD.md, doc/v5/Plan.md, doc/v5/Progress.md for the in-browser capture coach (distance + level gates)
+5. Read doc/v6/PRD.md, doc/v6/Plan.md, doc/v6/Progress.md for the mobile-native demo surface (`/m`)
+6. Assume this is a continuation of an existing project.
+7. Summarize your understanding of the current state and propose the next concrete step without writing code yet.
 
 ## Project Overview
 
@@ -175,6 +177,23 @@ For outer fingers the ROI is shrunk and rotation is centered on the proximal pha
 ### Environment flags
 
 - `RING_DISABLE_SUPABASE=1` — opt out of Supabase persistence for local dev runs (the web demo otherwise persists each measurement off the request thread).
+- `RING_DEV_TLS_CERT` / `RING_DEV_TLS_KEY` — paths to a local mkcert pair. When both are set, `web_demo/app.py` runs Flask under HTTPS on `0.0.0.0:8000` so a phone on the same LAN can hit the dev server (`getUserMedia` requires a secure context). Unset on HF Space deploys (TLS terminates upstream).
+
+---
+
+## Web demo surfaces
+
+`web_demo/app.py` serves two front-end shells off the same Flask app:
+
+| Route | Template | Notes |
+|---|---|---|
+| `/` (desktop UA) | `templates/index.html` | Original single-page form + result demo. |
+| `/` (mobile UA) | 302 → `/m` | Coarse UA regex (`iphone|ipod|android.+mobile|...`); `?desktop=1` overrides. |
+| `/m` | `templates/mobile.html` | v6 paginated six-step flow (intro → form → guide → capture → confirm → result). |
+| `/dev`, `/debug` | `templates/index.html` | Desktop with `dev_mode=True` (AI-explanation toggle visible). |
+| `/admin` | `templates/admin.html` | Token-gated KOL dashboard. |
+
+`/api/measure` is the single contract both surfaces speak. Any algorithm change in `measure_finger.py` improves both surfaces with zero front-end work. See `doc/v5/` for the in-browser capture coach (distance + level gates) and `doc/v6/` for the mobile flow.
 
 ---
 

CLAUDE.md

@@ -21,8 +21,10 @@ For tasks of **reboot** from a new codex session:
 1. Read doc/v0/PRD.md, doc/v0/Plan.md, doc/v0/Progress.md for baseline implementation
 2. Read doc/v1/PRD.md, doc/v1/Plan.md, doc/v1/Progress.md for edge refinement (v1)
 3. Read doc/v4/PRD.md, doc/v4/Plan.md, doc/v4/Progress.md for SAM 2.1 integration (card + hand)
-4. Assume this is a continuation of an existing project.
-5. Summarize your understanding of the current state and propose the next concrete step without writing code yet.
+4. Read doc/v5/PRD.md, doc/v5/Plan.md, doc/v5/Progress.md for the in-browser capture coach (distance + level gates)
+5. Read doc/v6/PRD.md, doc/v6/Plan.md, doc/v6/Progress.md for the mobile-native demo surface (`/m`)
+6. Assume this is a continuation of an existing project.
+7. Summarize your understanding of the current state and propose the next concrete step without writing code yet.
 
 ## Project Overview
 
@@ -175,6 +177,23 @@ For outer fingers the ROI is shrunk and rotation is centered on the proximal pha
 ### Environment flags
 
 - `RING_DISABLE_SUPABASE=1` — opt out of Supabase persistence for local dev runs (the web demo otherwise persists each measurement off the request thread).
+- `RING_DEV_TLS_CERT` / `RING_DEV_TLS_KEY` — paths to a local mkcert pair. When both are set, `web_demo/app.py` runs Flask under HTTPS on `0.0.0.0:8000` so a phone on the same LAN can hit the dev server (`getUserMedia` requires a secure context). Unset on HF Space deploys (TLS terminates upstream).
+
+---
+
+## Web demo surfaces
+
+`web_demo/app.py` serves two front-end shells off the same Flask app:
+
+| Route | Template | Notes |
+|---|---|---|
+| `/` (desktop UA) | `templates/index.html` | Original single-page form + result demo. |
+| `/` (mobile UA) | 302 → `/m` | Coarse UA regex (`iphone|ipod|android.+mobile|...`); `?desktop=1` overrides. |
+| `/m` | `templates/mobile.html` | v6 paginated six-step flow (intro → form → guide → capture → confirm → result). |
+| `/dev`, `/debug` | `templates/index.html` | Desktop with `dev_mode=True` (AI-explanation toggle visible). |
+| `/admin` | `templates/admin.html` | Token-gated KOL dashboard. |
+
+`/api/measure` is the single contract both surfaces speak. Any algorithm change in `measure_finger.py` improves both surfaces with zero front-end work. See `doc/v5/` for the in-browser capture coach (distance + level gates) and `doc/v6/` for the mobile flow.
 
 ---
 

measure_finger.py

@@ -39,6 +39,7 @@ from src.confidence import (
 )
 from src.debug_observer import draw_comprehensive_edge_overlay, draw_hand_skeleton
 from src.visualization import draw_card_overlay
+from src.viz_constants import Color
 from src.ring_size import recommend_ring_size, aggregate_ring_sizes, VALID_RING_MODELS, DEFAULT_RING_MODEL
 from src.image_quality import (
     check_card_in_frame,
@@ -328,8 +329,9 @@ def _overlay_sam_masks(
 ) -> np.ndarray:
     """Tint the SAM hand and card masks onto a debug image.
 
-    Hand mask is rendered in cyan, card mask in green. Both are drawn as
-    semi-transparent fills plus a solid contour so the pixel-accurate SAM
+    Both the hand and the card are rendered in Color.CONTOUR (the shared
+    default object-outline color, distinct from the per-finger band colors)
+    as semi-transparent fills plus a solid contour so the pixel-accurate SAM
     silhouettes remain visible underneath downstream finger/edge overlays.
 
     If ``rotation_matrix`` is supplied (because the caller applied a precise
@@ -363,23 +365,14 @@ def _overlay_sam_masks(
     hand_u8 = _prepare(hand_mask)
     card_u8 = _prepare(card_mask)
 
-    # Semi-transparent fills
-    if hand_u8 is not None:
-        tint = np.zeros_like(out)
-        tint[hand_u8 > 0] = (255, 255, 0)  # cyan in BGR
-        out = cv2.addWeighted(out, 1.0, tint, 0.18, 0)
-    if card_u8 is not None:
-        tint = np.zeros_like(out)
-        tint[card_u8 > 0] = (0, 255, 0)    # green in BGR
-        out = cv2.addWeighted(out, 1.0, tint, 0.22, 0)
-
-    # Solid contours to emphasize the SAM-derived silhouette
+    # Solid contours only — no tinted fill, so the underlying photo stays
+    # at full brightness inside the SAM silhouettes.
     if hand_u8 is not None:
         contours, _ = cv2.findContours(hand_u8, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
-        cv2.drawContours(out, contours, -1, (255, 255, 0), 2, cv2.LINE_AA)
+        cv2.drawContours(out, contours, -1, Color.CONTOUR, 2, cv2.LINE_AA)
     if card_u8 is not None:
         contours, _ = cv2.findContours(card_u8, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
-        cv2.drawContours(out, contours, -1, (0, 255, 0), 2, cv2.LINE_AA)
+        cv2.drawContours(out, contours, -1, Color.CONTOUR, 2, cv2.LINE_AA)
 
     return out
 
@@ -1500,10 +1493,13 @@ def _draw_multi_finger_debug(
     from src.visualization import draw_card_overlay
     from src.viz_constants import Color
 
+    # BGR values matched to the mobile result-card top-border colors in
+    # web_demo/static/mobile/steps/result.js so each band on the overlay
+    # visually links to its card: index #00dddd, middle #3b82f6, ring #dd44dd.
     FINGER_COLORS = {
-        "index": (255, 255, 0),    # Cyan (BGR)
-        "middle": (0, 255, 0),     # Green
-        "ring": (255, 0, 255),     # Magenta
+        "index": (221, 221, 0),    # cyan
+        "middle": (246, 130, 59),  # blue
+        "ring": (221, 68, 221),    # magenta
     }
 
     vis = image_canonical.copy()
@@ -1581,14 +1577,18 @@ def _draw_multi_finger_debug(
                 left_can = to_canonical(np.array([lx, gy])).astype(np.int32)
                 right_can = to_canonical(np.array([rx, gy])).astype(np.int32)
 
-                # Edge dots (small, using finger color)
-                cv2.circle(vis, tuple(left_can), 2, Color.BLUE, -1)
-                cv2.circle(vis, tuple(right_can), 2, Color.MAGENTA, -1)
+                # Edge dots in the per-finger color so left/right boundaries
+                # match the band lines and the result card.
+                cv2.circle(vis, tuple(left_can), 2, color, -1)
+                cv2.circle(vis, tuple(right_can), 2, color, -1)
 
-                # Width measurement lines (every Nth row)
+                # Width measurement lines (every Nth row) in the per-finger
+                # color so the band visually matches its result card. Drawn
+                # at thickness 2 so they read as boldly as the dot-stacked
+                # left/right boundary bars rather than fading into the skin.
                 if count % line_spacing == 0:
                     cv2.line(vis, tuple(left_can), tuple(right_can),
-                             Color.GREEN, 1, cv2.LINE_AA)
+                             color, 2, cv2.LINE_AA)
                 count += 1
 
     _save_debug_visualization(result_png_path, vis)

src/debug_observer.py

@@ -187,11 +187,12 @@ def draw_hand_skeleton(image: np.ndarray, landmarks: np.ndarray) -> np.ndarray:
     """
     overlay = image.copy()
 
-    # Draw connections
+    # Draw connections in the shared CONTOUR color so the skeleton matches
+    # the hand silhouette and stays distinct from the per-finger band colors.
     for idx1, idx2 in HAND_CONNECTIONS:
         pt1 = (int(landmarks[idx1, 0]), int(landmarks[idx1, 1]))
         pt2 = (int(landmarks[idx2, 0]), int(landmarks[idx2, 1]))
-        cv2.line(overlay, pt1, pt2, Color.CYAN, Size.LINE_THICK, cv2.LINE_AA)
+        cv2.line(overlay, pt1, pt2, Color.CONTOUR, Size.LINE_THICK, cv2.LINE_AA)
 
     # Draw landmarks on top
     for i, (x, y) in enumerate(landmarks):

src/visualization.py

@@ -138,14 +138,7 @@ def draw_card_overlay(
     corners = np.asarray(card_result["corners"], dtype=np.int32)
     params = get_scaled_font_params(image.shape[0])
 
-    # Semi-transparent fill inside the corner quadrilateral. Avoids the
-    # visual clutter of drawing the raw SAM mask (which often has stray
-    # blobs outside the real card boundary).
-    tint = np.zeros_like(image)
-    cv2.fillConvexPoly(tint, corners, Color.CARD)
-    cv2.addWeighted(image, 1.0, tint, 0.22, 0, dst=image)
-
-    # Draw quadrilateral
+    # Draw quadrilateral (no tinted fill — keeps the card photo unobscured).
     cv2.polylines(image, [corners], isClosed=True, color=Color.CARD,
                   thickness=params["contour_thickness"])
 

src/viz_constants.py

@@ -100,9 +100,13 @@ class Color:
     # Semantic Colors (what they represent in the system)
     # ========================================================================
 
-    # Object colors
-    CARD = GREEN            # Credit card outline
-    FINGER = MAGENTA        # Finger contour
+    # Object colors. CONTOUR is the shared default for tracing detected
+    # objects (card, hand silhouette, finger contour). Kept distinct from the
+    # per-finger ring-zone band colors (cyan/green/magenta) so the structural
+    # outlines don't compete with the measurement bands.
+    CONTOUR = GREEN         # Default object contour
+    CARD = CONTOUR          # Credit card outline
+    FINGER = CONTOUR        # Finger contour
 
     # Axis/geometry colors
     AXIS_PALM = CYAN        # Palm-side axis endpoint

web_demo/static/mobile/mobile.css

@@ -1,9 +1,9 @@
 /* Mobile flow stylesheet. Pulls design tokens from shared/tokens.css
    so the palette matches the desktop. Visual treatments here mirror
-   the desktop's hero copy, hero-card panel, file-drop, capture-tips,
-   primary button, image-frame, finger-cards, and size-ref-table —
-   the mobile flow is the desktop page paginated, not a different
-   visual identity. */
+   the desktop's hero copy, hero-card panel, capture-tips, primary
+   button, image-frame, finger-cards, and size-ref-table — the mobile
+   flow is the desktop page paginated, not a different visual
+   identity. */
 
 @import url("../shared/tokens.css");
 
@@ -247,47 +247,7 @@ body {
   font-weight: 600;
 }
 
-/* --- File drop + camera trigger + tips (matches desktop) -------- */
-
-.file-drop {
-  display: flex;
-  flex-direction: column;
-  gap: 6px;
-  padding: 22px;
-  border: 1.5px dashed var(--accent);
-  border-radius: 18px;
-  background: var(--sand);
-  cursor: pointer;
-  margin-bottom: 12px;
-}
-
-.file-drop input {
-  display: none;
-}
-
-.file-title {
-  font-size: 1.05rem;
-  font-weight: 600;
-  color: var(--ink);
-}
-
-.file-hint {
-  font-size: 0.9rem;
-  color: var(--ink-soft);
-}
-
-.camera-trigger {
-  width: 100%;
-  margin-bottom: 14px;
-  padding: 12px 14px;
-  font-size: 0.95rem;
-  font-weight: 600;
-  color: var(--accent-dark);
-  background: rgba(255, 255, 255, 0.85);
-  border: 1px dashed var(--accent);
-  border-radius: 14px;
-  cursor: pointer;
-}
+/* --- Capture tips (matches desktop) ----------------------------- */
 
 .capture-tips {
   margin: 0;

web_demo/static/mobile/session.js

@@ -31,12 +31,7 @@ export const session = {
 // reloads this module and reinitializes `session` to the defaults.
 export function resetForRetake() {
   if (session.imageUrl && session.imageUrl.startsWith("blob:")) {
-    try {
-      URL.revokeObjectURL(session.imageUrl);
-    } catch (err) {
-      // URL.revokeObjectURL never throws on a valid blob URL; this is
-      // pure defensive guarding for malformed values.
-    }
+    URL.revokeObjectURL(session.imageUrl);
   }
   session.imageBlob = null;
   session.imageUrl = "";

web_demo/static/mobile/steps/capture.js

@@ -34,6 +34,12 @@ let levelDot = null;
 let shutterBtn = null;
 let flashBtn = null;
 let statusEl = null;
+let viewportListener = null;
+// Bumped on every mount; the async startup IIFE compares its captured
+// generation to this after each await to detect that unmount has fired
+// while it was suspended. Without this, a quick Back tap can let the
+// IIFE start a setInterval *after* unmount has run, leaking it forever.
+let mountGeneration = 0;
 
 function createTelemetry() {
   return {
@@ -447,10 +453,10 @@ export default {
     if (window.visualViewport) {
       window.visualViewport.addEventListener("resize", sync);
       window.visualViewport.addEventListener("scroll", sync);
+      viewportListener = sync;
     }
-    // Stash the listener on the stage so unmount() can detach it.
-    stage._syncInsetsListener = sync;
 
+    const generation = ++mountGeneration;
     (async () => {
       // Orientation permission must be requested in response to the
       // user gesture that triggered this step (the prep step's "Open
@@ -465,6 +471,10 @@ export default {
       } else {
         orientationStatus = "unsupported";
       }
+      // Bail if unmount fired while we were suspended — without this
+      // we'd start the camera and gate-loop interval on a step that
+      // has already torn down, leaking both.
+      if (generation !== mountGeneration) return;
 
       try {
         await window.CapturePreview.start(videoEl);
@@ -472,20 +482,33 @@ export default {
         setStatus(`Camera unavailable: ${err.message || err}`, true);
         return;
       }
+      if (generation !== mountGeneration) {
+        window.CapturePreview.stop();
+        return;
+      }
       setStatus("Get both green to unlock the shutter — hold level, at the right distance.");
       await refreshFlash();
+      if (generation !== mountGeneration) {
+        window.CapturePreview.stop();
+        return;
+      }
       await startGateLoop();
+      if (generation !== mountGeneration) {
+        stopGateLoop();
+        window.CapturePreview.stop();
+      }
     })();
   },
 
   unmount() {
+    mountGeneration++;
     stopGateLoop();
     if (window.CapturePreview) window.CapturePreview.stop();
-    const stage = document.querySelector(".step-capture");
-    if (stage && window.visualViewport && stage._syncInsetsListener) {
-      window.visualViewport.removeEventListener("resize", stage._syncInsetsListener);
-      window.visualViewport.removeEventListener("scroll", stage._syncInsetsListener);
+    if (viewportListener && window.visualViewport) {
+      window.visualViewport.removeEventListener("resize", viewportListener);
+      window.visualViewport.removeEventListener("scroll", viewportListener);
     }
+    viewportListener = null;
     videoEl = null;
     distanceChip = null;
     levelChip = null;

web_demo/static/mobile/steps/result.js

@@ -16,7 +16,7 @@ const FINGER_LABEL = {
 };
 const FINGER_COLOR = {
   index: "#00dddd",
-  middle: "#00cc44",
+  middle: "#3b82f6",
   ring: "#dd44dd",
 };
 const RING_MODEL_LABELS = { gen: "Gen1/Gen2", air: "Air" };

web_demo/templates/mobile.html

@@ -10,10 +10,9 @@
 <body>
   <!--
     Step controller paints into this single root container — each step
-    fully owns the visible viewport, no nested scrolling. Phase 1 is
-    Next/Back navigation between five placeholder steps; later phases
-    fill them in with real content (intro copy, position guide,
-    camera capture, results).
+    fully owns the visible viewport, no nested scrolling. The six steps
+    (intro / form / guide / capture / confirm / result) live under
+    static/mobile/steps/ and are wired up in mobile.js.
   -->
   <main id="mobileRoot"></main>