Upload folder using huggingface_hub

.gitignore

@@ -38,3 +38,10 @@ input/*.heic
 .DS_Store
 Thumbs.db
 
+# Claude Code session metadata
+.claude/
+
+# Local TLS certs (mkcert) — private key MUST NOT be committed.
+web_demo/certs/
+*.pem
+

script/analyze_hand_span.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Hand-span ratio distribution analysis for the web-preview distance gate.
+
+For each image in `input/kol_total` ∪ `input/kol_success`:
+  1. Run MediaPipe Hands once on the original frame; compute
+     hand_span_ratio = ||landmark[5] - landmark[17]|| / min(W, H).
+  2. Run the full measurement pipeline once (cached) to get the authoritative
+     fail_reason. This is the only way to cleanly separate `card_too_small`
+     from other failure modes (`hand_not_detected`, `card_not_parallel`, etc.).
+  3. Bucket ratios by fail_reason and print percentile stats so we can pick
+     the preview "close enough" threshold (target: P10 of the success bucket
+     to be conservative for small-handed users).
+"""
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import cv2
+import mediapipe as mp
+import numpy as np
+from mediapipe.tasks import python as mp_python
+from mediapipe.tasks.python import vision as mp_vision
+
+# Landmarks for the palm-MCP span (index MCP and pinky MCP).
+LM_INDEX_MCP = 5
+LM_PINKY_MCP = 17
+
+IMG_EXTS = {".jpg", ".jpeg", ".png"}
+
+# Reuse the same MediaPipe Tasks model the pipeline already downloads.
+MODEL_PATH = (
+    Path(__file__).resolve().parent.parent / ".model" / "hand_landmarker.task"
+)
+
+_detector = None
+
+
+def _get_detector():
+    global _detector
+    if _detector is None:
+        if not MODEL_PATH.exists():
+            raise FileNotFoundError(
+                f"hand_landmarker.task missing at {MODEL_PATH} — run measure_finger.py once to trigger the auto-download."
+            )
+        opts = mp_vision.HandLandmarkerOptions(
+            base_options=mp_python.BaseOptions(model_asset_path=str(MODEL_PATH)),
+            num_hands=1,
+            min_hand_detection_confidence=0.3,
+            min_tracking_confidence=0.3,
+        )
+        _detector = mp_vision.HandLandmarker.create_from_options(opts)
+    return _detector
+
+
+def hand_span_ratio(image_path: Path):
+    """Return (ratio, h, w, detected). Try 4 rotations like the pipeline does;
+    the ratio is rotation-invariant so we just take whichever rotation detects
+    a hand with highest confidence."""
+    img = cv2.imread(str(image_path))
+    if img is None:
+        return None, None, None, False
+    h0, w0 = img.shape[:2]
+
+    rotations = [
+        (img, 0),
+        (cv2.rotate(img, cv2.ROTATE_90_CLOCKWISE), 1),
+        (cv2.rotate(img, cv2.ROTATE_90_COUNTERCLOCKWISE), 3),
+        (cv2.rotate(img, cv2.ROTATE_180), 2),
+    ]
+
+    detector = _get_detector()
+    best_score = -1.0
+    best_lm = None
+    best_hw = None
+
+    for rotated, _code in rotations:
+        rgb = cv2.cvtColor(rotated, cv2.COLOR_BGR2RGB)
+        rgb = np.ascontiguousarray(rgb)
+        mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=rgb)
+        res = detector.detect(mp_image)
+        if not res.hand_landmarks:
+            continue
+        score = res.handedness[0][0].score if res.handedness else 0.0
+        if score > best_score:
+            best_score = score
+            best_lm = res.hand_landmarks[0]
+            best_hw = rotated.shape[:2]
+
+    if best_lm is None:
+        return None, h0, w0, False
+
+    rh, rw = best_hw
+    p5 = np.array([best_lm[LM_INDEX_MCP].x * rw, best_lm[LM_INDEX_MCP].y * rh])
+    p17 = np.array([best_lm[LM_PINKY_MCP].x * rw, best_lm[LM_PINKY_MCP].y * rh])
+    span_px = float(np.linalg.norm(p5 - p17))
+    short_side = min(rh, rw)  # rotation-invariant
+    return span_px / short_side, h0, w0, True
+
+
+def measure_fail_reason(image_path: Path, cache_dir: Path, base: Path) -> dict:
+    """Run measure_finger.py once (cached) and return its result dict."""
+    out_json = cache_dir / f"{image_path.stem}.json"
+    if not out_json.exists():
+        cmd = [
+            sys.executable, "measure_finger.py",
+            "--input", str(image_path),
+            "--output", str(out_json),
+            "--finger-index", "index",
+            "--card-method", "sam",
+            "--no-calibration",
+        ]
+        try:
+            subprocess.run(
+                cmd, capture_output=True, text=True, timeout=180, cwd=base,
+            )
+        except subprocess.TimeoutExpired:
+            return {"fail_reason": "timeout"}
+    if out_json.exists():
+        with open(out_json) as f:
+            return json.load(f)
+    return {"fail_reason": "no_output"}
+
+
+def percentiles(values, ps=(10, 25, 50, 75, 90)):
+    if not values:
+        return {p: None for p in ps}
+    arr = np.array(values)
+    return {p: float(np.percentile(arr, p)) for p in ps}
+
+
+def main():
+    base = Path(__file__).resolve().parent.parent
+    os.chdir(base)
+
+    # Union of kol_total and kol_success, dedup by filename.
+    by_name = {}
+    for d in ("kol_total", "kol_success"):
+        folder = base / "input" / d
+        if not folder.is_dir():
+            continue
+        for p in folder.iterdir():
+            if p.suffix.lower() in IMG_EXTS:
+                by_name.setdefault(p.name, p)
+    images = sorted(by_name.values(), key=lambda p: p.name)
+    print(f"Found {len(images)} unique images across kol_total ∪ kol_success")
+
+    cache_dir = base / "output" / "hand_span_analysis"
+    cache_dir.mkdir(parents=True, exist_ok=True)
+
+    results = []
+    for i, img_path in enumerate(images, 1):
+        print(f"[{i}/{len(images)}] {img_path.name}", end=" ", flush=True)
+
+        ratio, h, w, detected = hand_span_ratio(img_path)
+        meas = measure_fail_reason(img_path, cache_dir, base)
+        fail = meas.get("fail_reason")
+
+        results.append({
+            "image": img_path.name,
+            "h": h, "w": w,
+            "hand_detected_mediapipe": detected,
+            "hand_span_ratio": ratio,
+            "fail_reason": fail,
+            "scale_px_per_cm": meas.get("scale_px_per_cm"),
+        })
+        print(f"ratio={ratio if ratio is None else f'{ratio:.3f}'} fail={fail}")
+
+    out_json = cache_dir / "hand_span_results.json"
+    with open(out_json, "w") as f:
+        json.dump(results, f, indent=2)
+    print(f"\nSaved {out_json}")
+
+    # Bucket by fail_reason.
+    buckets: dict[str, list[float]] = {}
+    for r in results:
+        if r["hand_span_ratio"] is None:
+            key = "_mediapipe_no_hand"
+        else:
+            key = r["fail_reason"] or "success"
+            buckets.setdefault(key, []).append(r["hand_span_ratio"])
+
+    print("\n=== hand_span_ratio distribution by fail_reason ===")
+    print(f"{'bucket':<30} {'n':>4}  {'P10':>6} {'P25':>6} {'P50':>6} {'P75':>6} {'P90':>6}  mean")
+    for key in sorted(buckets, key=lambda k: (-len(buckets[k]), k)):
+        vals = buckets[key]
+        ps = percentiles(vals)
+        mean = float(np.mean(vals))
+        line = (
+            f"{key:<30} {len(vals):>4}  "
+            f"{ps[10]:.3f}  {ps[25]:.3f}  {ps[50]:.3f}  {ps[75]:.3f}  {ps[90]:.3f}   {mean:.3f}"
+        )
+        print(line)
+
+    no_hand = sum(1 for r in results if not r["hand_detected_mediapipe"])
+    print(f"\nMediaPipe failed to detect a hand on {no_hand}/{len(results)} images.")
+
+    # Threshold suggestion.
+    success = buckets.get("success", [])
+    too_small = buckets.get("card_too_small", [])
+    if success:
+        p10_success = float(np.percentile(success, 10))
+        print(f"\nSuggested preview gate: hand_span_ratio >= {p10_success:.3f}")
+        print(f"  (P10 of success cohort, conservative for small-handed users)")
+        if too_small:
+            below = sum(1 for v in too_small if v < p10_success)
+            print(f"  {below}/{len(too_small)} card_too_small samples fall below this gate.")
+            above = sum(1 for v in success if v >= p10_success)
+            print(f"  {above}/{len(success)} success samples pass this gate (= 90% by construction).")
+
+
+if __name__ == "__main__":
+    main()

web_demo/app.py

@@ -22,7 +22,7 @@ from typing import Any, Dict, List, Optional, Tuple
 
 import cv2
 import numpy as np
-from flask import Flask, Response, jsonify, render_template, request, send_from_directory
+from flask import Flask, Response, jsonify, redirect, render_template, request, send_from_directory
 from werkzeug.utils import secure_filename
 
 ROOT_DIR = Path(__file__).resolve().parents[1]
@@ -55,6 +55,8 @@ DEFAULT_SAMPLE_URL = "/static/examples/default_sample.jpg"
 ALLOWED_EXTENSIONS = {".jpg", ".jpeg", ".png"}
 DEMO_EDGE_METHOD = "mask"
 DEMO_CARD_METHOD = "sam"
+VALID_CAPTURE_METHODS = {"upload", "camera"}
+DEFAULT_CAPTURE_METHOD = "upload"
 
 app = Flask(__name__)
 
@@ -145,25 +147,79 @@ def _save_json(path: Path, data: Dict[str, Any]) -> None:
         json.dump(data, f, indent=2, ensure_ascii=False)
 
 
-def _read_form_settings() -> Dict[str, str]:
+def _read_form_settings() -> Dict[str, Any]:
     """Parse the measurement-request form fields shared by /api/measure and
     /api/measure-default."""
     ring_model = request.form.get("ring_model", DEFAULT_RING_MODEL)
     if ring_model not in VALID_RING_MODELS:
         ring_model = DEFAULT_RING_MODEL
+    capture_method = request.form.get("capture_method", DEFAULT_CAPTURE_METHOD)
+    if capture_method not in VALID_CAPTURE_METHODS:
+        capture_method = DEFAULT_CAPTURE_METHOD
+
+    # gate_telemetry is a JSON-encoded blob from the v5 capture coach. Schema
+    # is intentionally fluid — server stamps it into result_json verbatim so
+    # frontend can evolve the payload without server changes. Hard-cap the
+    # raw size at 10 KB so a malicious client can't pad result_json (and
+    # Supabase rows) with arbitrary bytes; the legitimate payload is on the
+    # order of a few hundred bytes.
+    gate_telemetry: Optional[Dict[str, Any]] = None
+    raw = request.form.get("gate_telemetry")
+    if raw:
+        if len(raw) > 10_000:
+            logger.warning("dropping oversized gate_telemetry payload (%d bytes)", len(raw))
+        else:
+            try:
+                parsed = json.loads(raw)
+                if isinstance(parsed, dict):
+                    gate_telemetry = parsed
+            except json.JSONDecodeError:
+                logger.warning("dropping malformed gate_telemetry payload")
+
     return {
         "finger_index": request.form.get("finger_index", "index"),
         "mode": request.form.get("mode", "single"),
         "kol_name": request.form.get("kol_name", "").strip(),
         "ring_model": ring_model,
+        "capture_method": capture_method,
+        "gate_telemetry": gate_telemetry,
     }
 
 
+# Coarse UA sniff — only used to decide which surface (`index.html` vs
+# `mobile.html`) to render at `/`. We deliberately use a simple regex
+# rather than a UA-parsing library: false negatives just mean a phone
+# user sees the desktop page, which they can recover from with the
+# `?desktop=1` override; false positives are harmless because the
+# desktop user just sees the mobile page (and can use `?desktop=1`
+# from there). Not worth a heavy dependency.
+_MOBILE_UA_RE = re.compile(
+    r"iphone|ipod|android.+mobile|blackberry|iemobile|opera mini|windows phone",
+    re.IGNORECASE,
+)
+
+
+def _is_mobile_ua(user_agent_str: str) -> bool:
+    return bool(user_agent_str and _MOBILE_UA_RE.search(user_agent_str))
+
+
 @app.route("/")
 def index():
+    # Phone visitors get auto-redirected to the mobile flow unless they
+    # opt out with `?desktop=1`. The override lets the dev demo from a
+    # phone in desktop mode and lets us share desktop links that hold
+    # up regardless of the recipient's device.
+    force_desktop = request.args.get("desktop") is not None
+    if not force_desktop and _is_mobile_ua(request.headers.get("User-Agent", "")):
+        return redirect("/m", code=302)
     return render_template("index.html", default_sample_url=DEFAULT_SAMPLE_URL, dev_mode=False)
 
 
+@app.route("/m")
+def index_mobile():
+    return render_template("mobile.html")
+
+
 @app.route("/dev")
 @app.route("/debug")
 def index_dev():
@@ -209,6 +265,8 @@ def api_measure():
         input_image_url=f"/uploads/{upload_name}",
         ring_model=settings["ring_model"],
         kol_name=settings["kol_name"],
+        capture_method=settings["capture_method"],
+        gate_telemetry=settings["gate_telemetry"],
         upload_path=upload_path,
         upload_name=upload_name,
         base_name=base_name,
@@ -236,6 +294,8 @@ def api_measure_default():
         input_image_url=DEFAULT_SAMPLE_URL,
         ring_model=settings["ring_model"],
         kol_name=settings["kol_name"],
+        capture_method=settings["capture_method"],
+        gate_telemetry=settings["gate_telemetry"],
         base_name=base_name,
         run_id=run_id,
     )
@@ -250,6 +310,8 @@ def _run_measurement(
     input_image_url: str,
     ring_model: str = DEFAULT_RING_MODEL,
     kol_name: str = "",
+    capture_method: str = DEFAULT_CAPTURE_METHOD,
+    gate_telemetry: Optional[Dict[str, Any]] = None,
     upload_path: Optional[Path] = None,
     upload_name: str = "",
     base_name: str = "",
@@ -279,6 +341,9 @@ def _run_measurement(
         if rec:
             result["ring_size"] = rec
 
+    result["capture_method"] = capture_method
+    if gate_telemetry is not None:
+        result["gate_telemetry"] = gate_telemetry
     result = _numpy_safe(result)
 
     result_json_name = f"{base_name}_result.json"
@@ -325,6 +390,8 @@ def _run_multi_measurement(
     input_image_url: str,
     ring_model: str = DEFAULT_RING_MODEL,
     kol_name: str = "",
+    capture_method: str = DEFAULT_CAPTURE_METHOD,
+    gate_telemetry: Optional[Dict[str, Any]] = None,
     upload_path: Optional[Path] = None,
     upload_name: str = "",
     base_name: str = "",
@@ -344,6 +411,9 @@ def _run_multi_measurement(
         ring_model=ring_model,
     )
 
+    result["capture_method"] = capture_method
+    if gate_telemetry is not None:
+        result["gate_telemetry"] = gate_telemetry
     result = _numpy_safe(result)
 
     # Collect finger widths for AI recommendation
@@ -744,4 +814,11 @@ def api_admin_export_csv():
 
 
 if __name__ == "__main__":
-    app.run(host="0.0.0.0", port=8000, debug=True)
+    # Local-dev HTTPS via mkcert: set RING_DEV_TLS_CERT and RING_DEV_TLS_KEY
+    # to enable HTTPS on the dev server (required for getUserMedia on a
+    # phone over LAN). HF Space deploys leave these unset and serve HTTP
+    # behind HF's platform-level TLS terminator.
+    cert = os.environ.get("RING_DEV_TLS_CERT")
+    key = os.environ.get("RING_DEV_TLS_KEY")
+    ssl_context = (cert, key) if cert and key else None
+    app.run(host="0.0.0.0", port=8000, debug=True, ssl_context=ssl_context)

web_demo/static/mobile/mobile.css

@@ -0,0 +1,843 @@
+/* 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. */
+
+@import url("../shared/tokens.css");
+
+* {
+  box-sizing: border-box;
+}
+
+[hidden] {
+  display: none !important;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+  width: 100%;
+  height: 100%;
+  background: var(--bg-1);
+  color: var(--ink);
+  font-family: "Iowan Old Style", "Palatino", "Book Antiqua", "Times New Roman", serif;
+  -webkit-font-smoothing: antialiased;
+  overflow: hidden;
+}
+
+#mobileRoot {
+  width: 100%;
+  /* Cascade order: each later rule overrides on browsers supporting
+     that unit. Old browsers stop at vh; modern iOS Safari reaches
+     dvh which tracks URL-bar transitions, so per-step footers stay
+     visible. */
+  height: 100vh;
+  height: 100svh;
+  height: 100dvh;
+}
+
+/* --- Step base layout -------------------------------------------- */
+
+.step {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  padding: max(16px, env(safe-area-inset-top, 0px)) 20px
+    max(16px, env(safe-area-inset-bottom, 0px));
+  background:
+    radial-gradient(circle at 10% 10%, var(--bg-3), transparent 55%),
+    radial-gradient(circle at 90% 0%, var(--bg-2), transparent 55%),
+    linear-gradient(140deg, var(--bg-1), #fff8f2 60%, #f0e2d8 100%);
+}
+
+.step-head {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin-bottom: 12px;
+  min-height: 40px;
+  flex: 0 0 auto;
+}
+
+.step-back {
+  width: 40px;
+  height: 40px;
+  flex: 0 0 40px;
+  border: 1px solid var(--border);
+  border-radius: 50%;
+  background: white;
+  color: var(--ink);
+  font-size: 22px;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.step-back:active {
+  background: var(--sand);
+}
+
+.step-body {
+  flex: 1 1 auto;
+  overflow-y: auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+.step-foot {
+  flex: 0 0 auto;
+  padding-top: 14px;
+}
+
+/* Secondary action under a primary button — text-link weight so it
+   reads as an "escape hatch" rather than an equally-weighted choice.
+   Padding is sized to clear the WCAG 2.5.5 / Apple HIG ~44px minimum
+   touch target. */
+.step-link {
+  display: block;
+  width: 100%;
+  margin-top: 8px;
+  padding: 12px 16px;
+  background: transparent;
+  border: none;
+  border-radius: 8px;
+  color: var(--ink-soft);
+  font-size: 0.95rem;
+  font-weight: 500;
+  text-decoration: underline;
+  text-underline-offset: 3px;
+  cursor: pointer;
+}
+
+.step-link:hover {
+  color: var(--ink);
+}
+
+.step-link:focus-visible {
+  color: var(--ink);
+  outline: 2px solid var(--accent);
+  outline-offset: 2px;
+}
+
+.guide-upload-error {
+  margin: 8px 4px 0;
+  font-size: 0.85rem;
+  color: var(--accent);
+  text-align: center;
+}
+
+/* --- Typography (matches desktop hero/panel) --------------------- */
+
+.hero-eyebrow {
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  font-size: 0.75rem;
+  font-weight: 600;
+  color: var(--accent-dark);
+  margin: 0 0 24px;
+}
+
+.hero-headline {
+  font-family: "Futura", "Gill Sans", "Optima", "Trebuchet MS", sans-serif;
+  font-size: clamp(2rem, 8vw, 2.4rem);
+  letter-spacing: 0.02em;
+  line-height: 1.15;
+  margin: 0 0 28px;
+  color: var(--ink);
+}
+
+.hero-sub {
+  font-size: 1.05rem;
+  line-height: 1.7;
+  color: var(--ink-soft);
+  margin: 0;
+  max-width: 36ch;
+}
+
+/* Step 1 leans into a softly centered hero: vertically nudge the copy
+   toward the middle so the eye lands on the headline, not the very
+   top of the page. */
+.step-intro .step-body {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+}
+
+/* --- Panel (matches desktop .hero-card / .panel) ----------------- */
+
+.panel {
+  background: rgba(255, 255, 255, 0.78);
+  border: 1px solid var(--border);
+  border-radius: 20px;
+  padding: 22px;
+  box-shadow: 0 18px 40px rgba(43, 31, 31, 0.08);
+  -webkit-backdrop-filter: blur(6px);
+  backdrop-filter: blur(6px);
+  margin-bottom: 16px;
+}
+
+.panel:last-child {
+  margin-bottom: 0;
+}
+
+.panel-title {
+  font-family: "Futura", "Gill Sans", "Optima", "Trebuchet MS", sans-serif;
+  font-size: 1.4rem;
+  margin: 0 0 14px;
+  color: var(--ink);
+}
+
+/* --- Form controls (matches desktop) ----------------------------- */
+
+.controls {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.controls label {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  font-size: 0.9rem;
+  color: var(--ink-soft);
+}
+
+.controls input[type="text"],
+.controls select {
+  /* Lock both controls to the same height. iOS Safari's native
+     <select> renders at a slightly shorter intrinsic height than
+     <input>, so identical padding alone doesn't match — an explicit
+     height (with box-sizing: border-box, set globally) does. */
+  height: 48px;
+  width: 100%;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 0 14px;
+  /* iOS auto-zoom guard — must be ≥ 16px. */
+  font-size: 1rem;
+  line-height: 1.4;
+  background: white;
+  color: var(--ink);
+}
+
+/* Strip the native <select> chrome (Safari's tiny up/down chevrons,
+   inset shadows, etc.) so the visual treatment matches the text
+   input. We restore a single chevron via a background-image so the
+   dropdown affordance is still visible. */
+.controls select {
+  -webkit-appearance: none;
+  -moz-appearance: none;
+  appearance: none;
+  padding-right: 40px;
+  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 8' fill='none' stroke='%234b3d3d' stroke-width='1.6' stroke-linecap='round' stroke-linejoin='round'><polyline points='1,2 6,7 11,2'/></svg>");
+  background-repeat: no-repeat;
+  background-position: right 14px center;
+  background-size: 12px 8px;
+}
+
+.form-error {
+  margin: 12px 0 0;
+  font-size: 0.85rem;
+  color: var(--accent);
+  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 {
+  margin: 0;
+  padding: 14px 18px 14px 32px;
+  list-style: disc;
+  background: rgba(191, 58, 43, 0.06);
+  border-left: 3px solid rgba(191, 58, 43, 0.55);
+  border-radius: 8px;
+  font-size: 0.9rem;
+  color: var(--ink-soft);
+  line-height: 1.55;
+}
+
+.capture-tips li + li {
+  margin-top: 6px;
+}
+
+.capture-tips strong {
+  color: var(--ink);
+}
+
+/* "Like this" sample below the tips on the guide step. Same rounded
+   image-frame chrome as the confirm preview / result overlay so the
+   visual treatment is consistent across the three places we show a
+   photo. */
+.guide-example {
+  margin: 16px 0 0;
+  padding: 0;
+}
+
+.guide-example img {
+  width: 100%;
+  height: auto;
+  display: block;
+  border-radius: 14px;
+  background: #f6efea;
+  box-shadow: 0 6px 18px var(--shadow);
+}
+
+.guide-example figcaption {
+  margin-bottom: 8px;
+  font-size: 0.85rem;
+  color: var(--ink-soft);
+  text-align: center;
+  font-style: italic;
+}
+
+/* --- Primary button --------------------------------------------- */
+
+.primary {
+  width: 100%;
+  border: none;
+  border-radius: 14px;
+  padding: 14px 16px;
+  font-size: 1rem;
+  font-weight: 600;
+  color: white;
+  background: linear-gradient(120deg, var(--accent), #e25f4f);
+  box-shadow: 0 12px 30px var(--shadow);
+  cursor: pointer;
+}
+
+.primary:active {
+  transform: translateY(1px);
+}
+
+.primary:disabled {
+  /* Distinct solid color rather than an opacity fade. Opacity makes
+     a disabled button look like a "weak" version of the live one,
+     which is visually noisy on top of a busy video preview. A solid
+     warm beige-gray with no shadow reads unambiguously as inactive
+     while staying inside the cream palette. */
+  background: #a89e8f;
+  box-shadow: none;
+  cursor: not-allowed;
+}
+
+/* --- Image frame (matches desktop input/result image panels) ---- */
+
+.image-frame {
+  position: relative;
+  border-radius: 16px;
+  overflow: hidden;
+  background: #f6efea;
+  min-height: 180px;
+  display: grid;
+  place-items: center;
+}
+
+.image-frame img {
+  width: 100%;
+  height: auto;
+  display: none;
+}
+
+.image-frame.show img {
+  display: block;
+}
+
+/* --- Confirm step status text ----------------------------------- */
+
+/* Lives in the step-foot (not the panel) so it's always visible —
+   tall photos can push panel content out of the visible step-body
+   area, which would otherwise hide the live "Measuring… Xs" timer. */
+.confirm-status {
+  margin: 0 0 10px;
+  font-size: 0.95rem;
+  color: var(--ink-soft);
+  text-align: center;
+  /* Keep the timer line single-line so the layout doesn't jump as the
+     seconds counter ticks; the message is short by design. */
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.confirm-status.error {
+  color: var(--accent);
+  font-weight: 600;
+  /* Errors can be longer than the live timer; allow wrapping there. */
+  white-space: normal;
+}
+
+/* --- Step 4 — Capture stage (full-bleed camera) ----------------- */
+
+.step-capture {
+  --capture-url-bar-inset: 0px;
+  --capture-bottom-inset: max(
+    28px,
+    calc(var(--capture-url-bar-inset) + env(safe-area-inset-bottom, 0px) + 16px)
+  );
+  position: relative;
+  padding: 0;
+  background: #000;
+}
+
+.capture-video {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  background: #000;
+}
+
+.capture-back,
+.capture-flash {
+  position: absolute;
+  top: max(12px, env(safe-area-inset-top, 12px));
+  width: 40px;
+  height: 40px;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: rgba(0, 0, 0, 0.45);
+  color: #fff;
+  font-size: 22px;
+  cursor: pointer;
+  z-index: 2;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  -webkit-backdrop-filter: blur(8px);
+  backdrop-filter: blur(8px);
+  transition: background 0.15s ease, color 0.15s ease;
+}
+
+.capture-back {
+  left: 12px;
+}
+
+.capture-flash {
+  right: 12px;
+  font-size: 18px;
+}
+
+.capture-back:hover,
+.capture-back:focus-visible,
+.capture-flash:hover,
+.capture-flash:focus-visible {
+  background: rgba(0, 0, 0, 0.65);
+}
+
+.capture-flash[aria-pressed="true"] {
+  background: #fff8d4;
+  color: #8a5b0a;
+}
+
+.capture-chips {
+  position: absolute;
+  bottom: calc(var(--capture-bottom-inset) + 64px);
+  left: 16px;
+  right: 16px;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  justify-content: center;
+  z-index: 2;
+}
+
+.capture-status {
+  position: absolute;
+  bottom: calc(var(--capture-bottom-inset) + 110px);
+  left: 16px;
+  right: 16px;
+  margin: 0;
+  text-align: center;
+  font-size: 0.85rem;
+  color: rgba(255, 255, 255, 0.85);
+  text-shadow: 0 1px 4px rgba(0, 0, 0, 0.6);
+  z-index: 2;
+}
+
+.capture-status.error {
+  color: #ffd5d0;
+  font-weight: 600;
+}
+
+.capture-controls {
+  position: absolute;
+  bottom: var(--capture-bottom-inset);
+  left: 16px;
+  right: 16px;
+  z-index: 2;
+}
+
+.capture-controls .capture-shutter {
+  width: 100%;
+}
+
+/* --- Status chips (distance / level) ---------------------------- */
+
+.status-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 4px 10px;
+  border-radius: 999px;
+  font-size: 0.82rem;
+  font-weight: 600;
+  border: 1px solid transparent;
+  background: rgba(255, 255, 255, 0.85);
+  color: var(--ink-soft);
+}
+
+.status-chip .chip-dot {
+  display: inline-block;
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: currentColor;
+  opacity: 0.8;
+}
+
+.status-chip.pending {
+  color: var(--ink-soft);
+  border-color: var(--border);
+}
+
+.status-chip.skipped {
+  color: var(--ink-soft);
+  border-color: var(--border);
+  opacity: 0.6;
+}
+
+.status-chip.red {
+  color: #b1271b;
+  background: #fde7e3;
+  border-color: rgba(177, 39, 27, 0.4);
+}
+
+.status-chip.amber {
+  color: #8a5b0a;
+  background: #fbeed1;
+  border-color: rgba(138, 91, 10, 0.4);
+}
+
+.status-chip.green {
+  color: #1f6b34;
+  background: #d8f1de;
+  border-color: rgba(31, 107, 52, 0.4);
+}
+
+/* --- Bubble level (capture stage) ------------------------------- */
+/* iPhone-style two-cross level. A static white cross marks the center
+   target; a second cross of the same shape drifts toward the high side
+   of the device. When the device is in tolerance the moving cross snaps
+   to the center and turns green (the two crosses visually merge). When
+   out of tolerance it floats out, clamped to a max radius, in red. The
+   ±5° tolerance ring is decorative — it gives the user a sense of how
+   far "in tolerance" is — and stays neutral white. */
+
+.capture-level-bubble {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 128px;
+  height: 128px;
+  transform: translate(-50%, -50%);
+  pointer-events: none;
+  z-index: 2;
+  --neutral-color: rgba(255, 255, 255, 0.85);
+  --indicator-color: rgba(255, 255, 255, 0.85);
+  filter: drop-shadow(0 1px 2px rgba(0, 0, 0, 0.55));
+}
+
+.capture-level-bubble[data-state="green"] {
+  --indicator-color: #6ce39a;
+}
+
+.capture-level-bubble[data-state="red"] {
+  --indicator-color: #ff8a7e;
+}
+
+/* Tolerance ring + center crosshair stay neutral so only the moving
+   cross signals state (per design feedback). */
+.capture-level-bubble .bubble-tolerance {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 38px;
+  height: 38px;
+  border-radius: 50%;
+  transform: translate(-50%, -50%);
+  border: 1.5px solid var(--neutral-color);
+  opacity: 0.85;
+}
+
+.capture-level-bubble .bubble-crosshair-h,
+.capture-level-bubble .bubble-crosshair-v {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  background: var(--neutral-color);
+  opacity: 0.6;
+}
+
+.capture-level-bubble .bubble-crosshair-h {
+  width: 14px;
+  height: 1.5px;
+  transform: translate(-50%, -50%);
+}
+
+.capture-level-bubble .bubble-crosshair-v {
+  width: 1.5px;
+  height: 14px;
+  transform: translate(-50%, -50%);
+}
+
+/* Moving cross. The wrapper is the element JS translates every tick;
+   the two arms inside form the cross relative to the wrapper's origin. */
+.capture-level-bubble .bubble-indicator {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  width: 14px;
+  height: 14px;
+  transform: translate(-50%, -50%);
+  /* Linear transform transition smooths the 100 ms detection tick;
+     also gives the snap-to-center on green a brief settle motion. */
+  transition: transform 0.08s linear;
+}
+
+.capture-level-bubble .bubble-indicator-h,
+.capture-level-bubble .bubble-indicator-v {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  background: var(--indicator-color);
+  transition: background 0.18s ease;
+}
+
+.capture-level-bubble .bubble-indicator-h {
+  width: 18px;
+  height: 2px;
+  transform: translate(-50%, -50%);
+}
+
+.capture-level-bubble .bubble-indicator-v {
+  width: 2px;
+  height: 18px;
+  transform: translate(-50%, -50%);
+}
+
+.capture-level-bubble[data-state="pending"] .bubble-indicator {
+  opacity: 0;
+}
+
+/* --- Step 6 — Result -------------------------------------------- */
+
+/* Top-of-result feedback banner. Mirrors the desktop's status text
+   semantically (single line of feedback after measurement) but is
+   visually a small panel-shaped card so it reads as a result rather
+   than form chrome. Color-coded: green = success, red = failure. */
+.result-status {
+  margin: 0 0 16px;
+  padding: 14px 16px;
+  border-radius: 14px;
+  background: white;
+  border: 1px solid var(--border);
+  border-left: 4px solid var(--ink-soft);
+  box-shadow: 0 6px 18px var(--shadow);
+}
+
+.result-status p {
+  margin: 0;
+  font-size: 0.95rem;
+  font-weight: 600;
+  line-height: 1.5;
+}
+
+.result-status-success {
+  background: #e8f4ec;
+  border-color: rgba(31, 107, 52, 0.4);
+  border-left-color: #1f6b34;
+}
+
+.result-status-success p {
+  color: #1f6b34;
+}
+
+.result-status-error {
+  background: #fde7e3;
+  border-color: rgba(177, 39, 27, 0.4);
+  border-left-color: var(--accent);
+}
+
+.result-status-error p {
+  color: #b1271b;
+}
+
+/* Three finger cards stacked vertically (instead of the desktop's
+   3-column grid) — narrower mobile width fits a single column more
+   comfortably without shrinking the size number. */
+.finger-cards {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  margin-bottom: 12px;
+}
+
+.finger-card {
+  background: var(--sand);
+  border-radius: 10px;
+  padding: 14px 16px 16px;
+  text-align: center;
+  box-shadow: 0 1px 4px var(--shadow);
+}
+
+.finger-card .finger-name {
+  font-weight: 600;
+  font-size: 0.95rem;
+  margin-bottom: 6px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--ink);
+}
+
+.finger-card .finger-size-label {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--ink-soft);
+  margin-top: 4px;
+}
+
+.finger-card .finger-size {
+  font-size: 2rem;
+  font-weight: 700;
+  color: var(--accent);
+  line-height: 1.1;
+  margin: 2px 0;
+}
+
+.finger-card .finger-range {
+  font-size: 0.9rem;
+  color: var(--ink-soft);
+}
+
+.finger-card .finger-width {
+  font-size: 0.85rem;
+  color: var(--ink-soft);
+  margin-top: 4px;
+}
+
+.finger-card-failed {
+  opacity: 0.85;
+}
+
+.finger-card .finger-failed {
+  font-size: 1rem;
+  font-weight: 600;
+  color: #721c24;
+  margin: 8px 0 4px;
+}
+
+.finger-card .finger-fail-reason {
+  font-size: 0.78rem;
+  color: var(--ink-soft);
+  word-break: break-word;
+}
+
+.finger-count {
+  text-align: center;
+  font-size: 0.85rem;
+  color: var(--ink-soft);
+  margin-bottom: 12px;
+}
+
+/* --- Size reference table (mirrors desktop) --------------------- */
+
+.size-ref-table {
+  margin-top: 14px;
+  padding-top: 12px;
+  border-top: 1px solid var(--border);
+}
+
+.size-ref-title {
+  font-family: "Futura", "Gill Sans", "Optima", "Trebuchet MS", sans-serif;
+  font-size: 1rem;
+  margin: 0 0 8px;
+  color: var(--ink);
+  /* Center the model-label heading so it lines up with the centered
+     SIZE / Inner ⌀ (mm) columns below — same alignment story as
+     the desktop. */
+  /*text-align: center;*/
+}
+
+.size-ref-table table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.9rem;
+}
+
+.size-ref-table th,
+.size-ref-table td {
+  padding: 8px 10px;
+  /* Match the desktop alignment — both headers and values are
+     centered, which is more comfortable to scan when the columns
+     are short numeric values. */
+  text-align: center;
+  border-bottom: 1px solid var(--border);
+}
+
+.size-ref-table th {
+  font-weight: 600;
+  color: var(--ink-soft);
+  font-size: 0.8rem;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+.size-ref-table tbody tr:nth-child(even) {
+  background: rgba(245, 241, 231, 0.5);
+}

web_demo/static/mobile/mobile.js

@@ -0,0 +1,35 @@
+// Mobile flow entrypoint. Registers six steps that mirror the
+// desktop page broken into discrete screens:
+//
+//   1. intro    — value prop (desktop hero copy)
+//   2. form     — name + ring model (desktop hero-card top)
+//   3. guide    — photo tips + "like this" sample, opens the camera
+//   4. capture  — fullscreen camera coach
+//   5. confirm  — preview the captured image, fire measurement
+//   6. result   — overlay image + ring-size cards + size reference
+//
+// Cross-step state lives in `session.js` so back-navigation preserves
+// what the user has already entered. Step 3 also exposes an "Upload
+// from photos" escape hatch that skips the capture step and hands the
+// picked file straight to confirm — same downstream path as a camera
+// capture, just with `imageSource = "upload"`.
+
+import { registerStep, setOrder, start } from "./steps.js";
+import intro from "./steps/intro.js";
+import form from "./steps/form.js";
+import guide from "./steps/guide.js";
+import capture from "./steps/capture.js";
+import confirm from "./steps/confirm.js";
+import result from "./steps/result.js";
+
+registerStep("intro", intro);
+registerStep("form", form);
+registerStep("guide", guide);
+registerStep("capture", capture);
+registerStep("confirm", confirm);
+registerStep("result", result);
+
+setOrder(["intro", "form", "guide", "capture", "confirm", "result"]);
+
+const root = document.getElementById("mobileRoot");
+if (root) start(root);

web_demo/static/mobile/session.js

@@ -0,0 +1,46 @@
+// Shared state that persists across step transitions.
+//
+// `goTo(name, data)` would force every step to re-thread the full
+// payload to the next; with six steps and a back-nav that needs to
+// remember what was already entered, an implicit session module is
+// simpler. Lifecycle is bounded by the page (cleared on `reset()`,
+// invoked by the result step's "Measure again" button to ensure the
+// next run starts fresh).
+
+export const session = {
+  kolName: "",
+  ringModel: "gen",
+  // Either an uploaded File or a Blob captured from the camera step.
+  imageBlob: null,
+  // Object URL pointing at imageBlob — created by whichever step
+  // produced the blob, revoked by reset() to avoid leaks.
+  imageUrl: "",
+  // Source of the blob, used by confirm.js to label the preview.
+  imageSource: "", // "upload" | "camera"
+  // Capture-coach telemetry snapshot. Forwarded to /api/measure with
+  // the camera path; null for the upload path.
+  gateTelemetry: null,
+  // /api/measure response payload, populated by confirm.js before
+  // navigating to the result step.
+  result: null,
+};
+
+// Wipe just the photo + result — used by "Measure again" so the user
+// keeps their entered name + ring model on the next capture without
+// re-typing. A full reset isn't a separate function: a page refresh
+// 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.
+    }
+  }
+  session.imageBlob = null;
+  session.imageUrl = "";
+  session.imageSource = "";
+  session.gateTelemetry = null;
+  session.result = null;
+}

web_demo/static/mobile/steps.js

@@ -0,0 +1,74 @@
+// Tiny linear step controller for the mobile flow.
+//
+// Each step registers a `mount(container)` function that paints itself
+// into the supplied DOM container, plus an optional `unmount()` for
+// cleanup (e.g. tearing down a camera stream when leaving the capture
+// step). The controller maintains an index into a fixed step order and
+// exposes `next()` / `back()` / `goTo(name)` for transitions.
+//
+// Deliberately minimal: no transitions, no history-API integration, no
+// deep-linking. Five linear steps with back/forward — anything fancier
+// can be added when the UX calls for it.
+
+const stepRegistry = new Map();
+let order = [];
+let currentIndex = -1;
+let currentStep = null;
+let rootContainer = null;
+
+export function registerStep(name, step) {
+  if (typeof step.mount !== "function") {
+    throw new Error(`Step "${name}" must define mount(container)`);
+  }
+  stepRegistry.set(name, step);
+}
+
+export function setOrder(names) {
+  for (const name of names) {
+    if (!stepRegistry.has(name)) {
+      throw new Error(`Step "${name}" is not registered`);
+    }
+  }
+  order = [...names];
+}
+
+export function start(container) {
+  rootContainer = container;
+  if (!order.length) throw new Error("setOrder() must be called before start()");
+  goTo(order[0]);
+}
+
+// `data` is an optional payload handed to the destination step's
+// mount() — used by the capture step to forward the measurement result
+// to the result step. Steps that don't need data can ignore the third
+// argument; steps that need persistent state should still maintain it
+// themselves (the controller doesn't survive a hard reload).
+export function goTo(name, data) {
+  const idx = order.indexOf(name);
+  if (idx === -1) throw new Error(`Step "${name}" is not in the active order`);
+  if (currentStep && typeof currentStep.unmount === "function") {
+    try {
+      currentStep.unmount();
+    } catch (err) {
+      console.error(`Step "${order[currentIndex]}" unmount failed:`, err);
+    }
+  }
+  rootContainer.innerHTML = "";
+  currentIndex = idx;
+  currentStep = stepRegistry.get(name);
+  // Pass a small `nav` API down so steps don't need to import this
+  // module — keeps each step file standalone and easy to test.
+  const nav = {
+    next: (payload) => {
+      if (currentIndex < order.length - 1) goTo(order[currentIndex + 1], payload);
+    },
+    back: (payload) => {
+      if (currentIndex > 0) goTo(order[currentIndex - 1], payload);
+    },
+    goTo,
+    isFirst: () => currentIndex === 0,
+    isLast: () => currentIndex === order.length - 1,
+    progress: () => ({ index: currentIndex, total: order.length }),
+  };
+  currentStep.mount(rootContainer, nav, data);
+}

web_demo/static/mobile/steps/capture.js

@@ -0,0 +1,498 @@
+// Step 4 — Live camera + capture coach.
+//
+// Drives the existing `static/preview/*` modules (camera lifecycle,
+// MediaPipe Hands, DeviceOrientation, torch) inside the step
+// lifecycle: mount() opens the camera and starts the gate loop,
+// unmount() tears everything down. On shutter, captures a frame and
+// hands the blob to the confirm step (step 5) — the actual
+// /api/measure POST happens there.
+//
+// Most of the gate-loop logic mirrors the desktop implementation in
+// `web_demo/static/app.js` (anti-jitter counters, telemetry shape,
+// MediaPipe-not-loaded fallback). The desktop and mobile copies will
+// converge into a shared module in a later phase once the mobile flow
+// is validated end-to-end.
+
+import { session } from "../session.js";
+
+const LEVEL_NO_DATA_TIMEOUT_MS = 2000;
+
+let detectionTimer = null;
+let consecutiveDistanceGreen = 0;
+let consecutiveLevelGreen = 0;
+let mediaPipeReady = false;
+let orientationStatus = "unsupported";
+let latestOrientation = null;
+let levelStartedAtMs = null;
+let levelMarkedSkipped = false;
+let gateTelemetry = createTelemetry();
+let videoEl = null;
+let distanceChip = null;
+let levelChip = null;
+let levelBubble = null;
+let levelDot = null;
+let shutterBtn = null;
+let flashBtn = null;
+let statusEl = null;
+
+function createTelemetry() {
+  return {
+    started_at_ms: null,
+    distance_first_green_ms: null,
+    distance_green_frames: 0,
+    distance_red_frames: 0,
+    distance_amber_frames: 0,
+    distance_no_hand_frames: 0,
+    level_first_green_ms: null,
+    level_green_frames: 0,
+    level_red_frames: 0,
+    level_amber_frames: 0,
+    level_no_data_frames: 0,
+    orientation_status: "unsupported",
+    threshold_used: null,
+  };
+}
+
+function setChip(chipEl, state, label) {
+  if (!chipEl) return;
+  chipEl.className = `status-chip ${state}`;
+  const labelEl = chipEl.querySelector(".chip-label");
+  if (labelEl) labelEl.textContent = label;
+}
+
+function setStatus(text, isError = false) {
+  if (!statusEl) return;
+  statusEl.textContent = text || "";
+  statusEl.classList.toggle("error", !!isError);
+}
+
+function evaluateDistance(T) {
+  // Mobile collapses the desktop's 5-band gauge (red / amber /
+  // green / amber / red) to a strict 3-state read: too far / OK /
+  // too close. The amber soft-zone is gone — clearer single-action
+  // feedback at the cost of fewer intermediate hints.
+  const minRatio = T.HAND_SPAN_RATIO_MIN ?? 0.28;
+  const maxRatio = T.HAND_SPAN_RATIO_MAX ?? 0.55;
+
+  let result = null;
+  try {
+    result = window.HandsDetector ? window.HandsDetector.detect(videoEl) : null;
+  } catch (err) {
+    return { state: "skipped", label: "Detection error", isGreen: false };
+  }
+  const ratio = result ? result.ratio : null;
+  if (ratio === null) {
+    return { state: "red", label: "Hand not detected", isGreen: false };
+  }
+  if (ratio < minRatio) {
+    return { state: "red", label: "Move closer", isGreen: false };
+  }
+  if (ratio > maxRatio) {
+    return { state: "red", label: "Pull back", isGreen: false };
+  }
+  return { state: "green", label: "Distance OK", isGreen: true };
+}
+
+function evaluateLevel(T) {
+  if (orientationStatus !== "granted") {
+    return { included: false, state: "skipped", label: "" };
+  }
+  if (!latestOrientation) {
+    if (levelStartedAtMs !== null && Date.now() - levelStartedAtMs > LEVEL_NO_DATA_TIMEOUT_MS) {
+      return { included: false, state: "skipped", label: "Level: no sensor" };
+    }
+    return { included: true, state: "pending", label: "Level: detecting…", isGreen: false };
+  }
+  // Same red/green collapse as the distance gate — drop the desktop's
+  // amber "Hold steady" middle band. Tighter ±5° green threshold (set
+  // in thresholds.js) gets the user closer to a clean top-down shot.
+  const beta = Math.abs(latestOrientation.beta);
+  const gamma = Math.abs(latestOrientation.gamma);
+  const bmax = T.LEVEL_BETA_MAX_DEG ?? 5;
+  const gmax = T.LEVEL_GAMMA_MAX_DEG ?? 5;
+  if (beta < bmax && gamma < gmax) {
+    return { included: true, state: "green", label: "Level OK", isGreen: true };
+  }
+  return { included: true, state: "red", label: "Camera not level", isGreen: false };
+}
+
+// Bubble-level visualization. Dot moves toward the *high* side of the
+// device (matches a real spirit level): tilting the right edge down
+// (γ > 0) leaves the left edge high, so the dot drifts left. Saturates
+// at ±15° so wild tilts don't fly off the rim. Color states are derived
+// from raw degrees independent of the gate's anti-jitter counter — the
+// bubble is purely visual feedback; the gate still owns shutter unlock.
+function updateLevelBubble(lvl, T) {
+  if (!levelBubble || !levelDot) return;
+  if (!lvl.included) {
+    levelBubble.hidden = true;
+    return;
+  }
+  levelBubble.hidden = false;
+  // Belt-and-braces guard: orientation.js already filters non-finite
+  // readings, but treat anything we can't read as pending so a bad
+  // sample never propagates into the CSS transform as NaN.
+  if (
+    lvl.state === "pending" ||
+    !latestOrientation ||
+    !Number.isFinite(latestOrientation.beta) ||
+    !Number.isFinite(latestOrientation.gamma)
+  ) {
+    levelBubble.dataset.state = "pending";
+    levelDot.style.transform = "translate(-50%, -50%)";
+    return;
+  }
+  // Two-state behavior:
+  //   green → indicator snaps to the center cross, so the user sees a
+  //           single merged cross flash green when they're in tolerance.
+  //   red   → indicator floats out toward the high side of the device,
+  //           clamped to a max radius so wild tilts don't fly off-canvas.
+  if (lvl.isGreen) {
+    levelDot.style.transform = "translate(-50%, -50%)";
+    levelBubble.dataset.state = "green";
+    return;
+  }
+  const SATURATION_DEG = 15;
+  const MAX_RADIUS_PX = 52;
+  const clamp = (v) => Math.max(-1, Math.min(1, v / SATURATION_DEG));
+  const dx = -clamp(latestOrientation.gamma) * MAX_RADIUS_PX;
+  const dy = -clamp(latestOrientation.beta) * MAX_RADIUS_PX;
+  levelDot.style.transform = `translate(calc(-50% + ${dx}px), calc(-50% + ${dy}px))`;
+  levelBubble.dataset.state = "red";
+}
+
+function runDetectionTick() {
+  if (!videoEl || videoEl.paused || videoEl.readyState < 2) return;
+  const T = window.PreviewThresholds || {};
+  const requiredFrames = T.GATE_CONSECUTIVE_FRAMES ?? 3;
+
+  const dist = evaluateDistance(T);
+  setChip(distanceChip, dist.state, dist.label);
+  if (dist.isGreen) {
+    consecutiveDistanceGreen++;
+    gateTelemetry.distance_green_frames++;
+    if (
+      consecutiveDistanceGreen === requiredFrames &&
+      gateTelemetry.distance_first_green_ms === null &&
+      gateTelemetry.started_at_ms !== null
+    ) {
+      gateTelemetry.distance_first_green_ms = Date.now() - gateTelemetry.started_at_ms;
+    }
+  } else {
+    consecutiveDistanceGreen = 0;
+    if (dist.state === "red") gateTelemetry.distance_red_frames++;
+    else if (dist.state === "amber") gateTelemetry.distance_amber_frames++;
+    else gateTelemetry.distance_no_hand_frames++;
+  }
+
+  const lvl = evaluateLevel(T);
+  updateLevelBubble(lvl, T);
+  if (lvl.included) {
+    if (levelChip) {
+      levelChip.hidden = false;
+      setChip(levelChip, lvl.state, lvl.label);
+    }
+    if (lvl.isGreen) {
+      consecutiveLevelGreen++;
+      gateTelemetry.level_green_frames++;
+      if (
+        consecutiveLevelGreen === requiredFrames &&
+        gateTelemetry.level_first_green_ms === null &&
+        gateTelemetry.started_at_ms !== null
+      ) {
+        gateTelemetry.level_first_green_ms = Date.now() - gateTelemetry.started_at_ms;
+      }
+    } else {
+      consecutiveLevelGreen = 0;
+      if (lvl.state === "red") gateTelemetry.level_red_frames++;
+      else if (lvl.state === "amber") gateTelemetry.level_amber_frames++;
+      else gateTelemetry.level_no_data_frames++;
+    }
+  } else if (lvl.state === "skipped" && lvl.label) {
+    if (levelChip && !levelMarkedSkipped) {
+      levelChip.hidden = false;
+      setChip(levelChip, "skipped", lvl.label);
+      levelMarkedSkipped = true;
+    }
+  } else if (levelChip) {
+    levelChip.hidden = true;
+  }
+
+  const distancePass = consecutiveDistanceGreen >= requiredFrames;
+  const levelPass = !lvl.included || consecutiveLevelGreen >= requiredFrames;
+  if (shutterBtn) shutterBtn.disabled = !(distancePass && levelPass);
+}
+
+function abandonGate(distanceLabel) {
+  if (window.OrientationDetector) window.OrientationDetector.stop();
+  if (levelChip) levelChip.hidden = true;
+  if (levelBubble) {
+    levelBubble.hidden = true;
+    levelBubble.dataset.state = "pending";
+    if (levelDot) levelDot.style.transform = "translate(-50%, -50%)";
+  }
+  setChip(distanceChip, "skipped", distanceLabel);
+  if (shutterBtn) shutterBtn.disabled = false;
+}
+
+async function startGateLoop() {
+  gateTelemetry = createTelemetry();
+  gateTelemetry.started_at_ms = Date.now();
+  gateTelemetry.threshold_used =
+    (window.PreviewThresholds && window.PreviewThresholds.HAND_SPAN_RATIO_MIN) || null;
+  gateTelemetry.orientation_status = orientationStatus;
+  consecutiveDistanceGreen = 0;
+  consecutiveLevelGreen = 0;
+  latestOrientation = null;
+  levelStartedAtMs = Date.now();
+  levelMarkedSkipped = false;
+  mediaPipeReady = false;
+  if (shutterBtn) shutterBtn.disabled = true;
+  setChip(distanceChip, "pending", "Distance: starting…");
+
+  if (orientationStatus === "granted" && window.OrientationDetector) {
+    if (levelChip) {
+      levelChip.hidden = false;
+      setChip(levelChip, "pending", "Level: starting…");
+    }
+    if (levelBubble) {
+      levelBubble.hidden = false;
+      levelBubble.dataset.state = "pending";
+      if (levelDot) levelDot.style.transform = "translate(-50%, -50%)";
+    }
+    window.OrientationDetector.start((data) => {
+      latestOrientation = data;
+    });
+  } else {
+    if (levelChip) levelChip.hidden = true;
+    if (levelBubble) {
+      levelBubble.hidden = true;
+      levelBubble.dataset.state = "pending";
+      if (levelDot) levelDot.style.transform = "translate(-50%, -50%)";
+    }
+  }
+
+  if (!window.HandsDetector) {
+    abandonGate("Hands module didn't load");
+    return;
+  }
+  try {
+    await window.HandsDetector.init();
+    mediaPipeReady = true;
+  } catch (err) {
+    console.warn("MediaPipe init failed; distance gate disabled", err);
+    const detail = err && err.message ? String(err.message).slice(0, 60) : "init failed";
+    abandonGate(`Distance check off: ${detail}`);
+    return;
+  }
+  detectionTimer = setInterval(runDetectionTick, 100);
+}
+
+function stopGateLoop() {
+  if (detectionTimer) {
+    clearInterval(detectionTimer);
+    detectionTimer = null;
+  }
+  if (window.OrientationDetector) window.OrientationDetector.stop();
+  consecutiveDistanceGreen = 0;
+  consecutiveLevelGreen = 0;
+  latestOrientation = null;
+}
+
+// Same pattern as desktop: stage anchored to top:0/bottom:0 with the
+// URL-bar height pushed into a CSS variable so the bottom controls
+// stay above iOS Safari's URL bar without leaving a gap below.
+function syncCaptureInsets(stageEl) {
+  const layoutH = window.innerHeight;
+  const vv = window.visualViewport;
+  const visualH = vv ? vv.height : layoutH;
+  const offsetTop = vv ? vv.offsetTop : 0;
+  const urlBarH = Math.max(0, layoutH - visualH - offsetTop);
+  stageEl.style.setProperty("--capture-url-bar-inset", `${urlBarH}px`);
+}
+
+async function refreshFlash() {
+  if (!flashBtn || !window.CapturePreview) return;
+  if (!window.CapturePreview.isTorchSupported()) {
+    flashBtn.hidden = true;
+    return;
+  }
+  flashBtn.hidden = false;
+  flashBtn.setAttribute("aria-pressed", "true");
+  flashBtn.setAttribute("aria-label", "Turn flash off");
+  try {
+    await window.CapturePreview.setTorch(true);
+  } catch (err) {
+    flashBtn.setAttribute("aria-pressed", "false");
+    flashBtn.setAttribute("aria-label", "Turn flash on");
+  }
+}
+
+async function toggleFlash() {
+  if (!flashBtn || !window.CapturePreview) return;
+  const wasOn = flashBtn.getAttribute("aria-pressed") === "true";
+  const next = !wasOn;
+  flashBtn.setAttribute("aria-pressed", next ? "true" : "false");
+  flashBtn.setAttribute("aria-label", next ? "Turn flash off" : "Turn flash on");
+  try {
+    await window.CapturePreview.setTorch(next);
+  } catch (err) {
+    flashBtn.setAttribute("aria-pressed", wasOn ? "true" : "false");
+    flashBtn.setAttribute("aria-label", wasOn ? "Turn flash off" : "Turn flash on");
+    setStatus("Could not toggle flash on this device.", true);
+  }
+}
+
+async function shoot(nav) {
+  if (!shutterBtn || !window.CapturePreview) return;
+  shutterBtn.disabled = true;
+  setStatus("Capturing…");
+  let blob;
+  try {
+    blob = await window.CapturePreview.captureFrame(videoEl);
+  } catch (err) {
+    setStatus(`Capture failed: ${err.message || err}`, true);
+    shutterBtn.disabled = false;
+    return;
+  }
+  // Hand the captured frame off to the confirm step. The /api/measure
+  // POST happens there so the user can review the photo (and the
+  // measuring timer has its own dedicated screen).
+  if (session.imageUrl && session.imageUrl.startsWith("blob:")) {
+    URL.revokeObjectURL(session.imageUrl);
+  }
+  session.imageBlob = blob;
+  session.imageUrl = URL.createObjectURL(blob);
+  session.imageSource = "camera";
+  session.gateTelemetry = {
+    ...gateTelemetry,
+    captured_at_ms: gateTelemetry.started_at_ms ? Date.now() - gateTelemetry.started_at_ms : null,
+    media_pipe_ready: mediaPipeReady,
+    capture_width: videoEl.videoWidth || null,
+    capture_height: videoEl.videoHeight || null,
+    surface: "mobile",
+  };
+
+  stopGateLoop();
+  window.CapturePreview.stop();
+  nav.next();
+}
+
+export default {
+  mount(container, nav) {
+    container.innerHTML = `
+      <section class="step step-capture">
+        <video id="captureVideo" class="capture-video" autoplay playsinline muted></video>
+
+        <button type="button" class="capture-back" aria-label="Back">←</button>
+        <button type="button" class="capture-flash" hidden aria-label="Turn flash on" aria-pressed="false">
+          <svg viewBox="0 0 24 24" width="20" height="20" aria-hidden="true">
+            <path d="M13 2 L4 14 L11 14 L9 22 L20 9 L13 9 Z" fill="currentColor" />
+          </svg>
+        </button>
+
+        <div class="capture-level-bubble" id="captureLevelBubble" data-state="pending" hidden aria-hidden="true">
+          <div class="bubble-tolerance"></div>
+          <div class="bubble-crosshair-h"></div>
+          <div class="bubble-crosshair-v"></div>
+          <div class="bubble-indicator" id="captureLevelDot">
+            <div class="bubble-indicator-h"></div>
+            <div class="bubble-indicator-v"></div>
+          </div>
+        </div>
+
+        <div class="capture-chips">
+          <div class="status-chip pending" id="captureDistanceChip">
+            <span class="chip-dot" aria-hidden="true"></span>
+            <span class="chip-label">Distance: starting…</span>
+          </div>
+          <div class="status-chip pending" id="captureLevelChip" hidden>
+            <span class="chip-dot" aria-hidden="true"></span>
+            <span class="chip-label">Level: starting…</span>
+          </div>
+        </div>
+
+        <p class="capture-status" id="captureStatus">Requesting camera…</p>
+
+        <div class="capture-controls">
+          <button id="captureShutterBtn" type="button" class="primary capture-shutter" disabled>
+            Take Photo
+          </button>
+        </div>
+      </section>
+    `;
+
+    const stage = container.querySelector(".step-capture");
+    videoEl = container.querySelector("#captureVideo");
+    distanceChip = container.querySelector("#captureDistanceChip");
+    levelChip = container.querySelector("#captureLevelChip");
+    levelBubble = container.querySelector("#captureLevelBubble");
+    levelDot = container.querySelector("#captureLevelDot");
+    shutterBtn = container.querySelector("#captureShutterBtn");
+    flashBtn = container.querySelector(".capture-flash");
+    statusEl = container.querySelector("#captureStatus");
+
+    container.querySelector(".capture-back").addEventListener("click", () => {
+      // Tear-down happens in unmount() when the step controller swaps
+      // us out; just trigger the back transition.
+      nav.back();
+    });
+    shutterBtn.addEventListener("click", () => shoot(nav));
+    flashBtn.addEventListener("click", toggleFlash);
+
+    // URL-bar inset sync. Same pattern as v5 capture stage.
+    const sync = () => syncCaptureInsets(stage);
+    sync();
+    requestAnimationFrame(sync);
+    if (window.visualViewport) {
+      window.visualViewport.addEventListener("resize", sync);
+      window.visualViewport.addEventListener("scroll", sync);
+    }
+    // Stash the listener on the stage so unmount() can detach it.
+    stage._syncInsetsListener = sync;
+
+    (async () => {
+      // Orientation permission must be requested in response to the
+      // user gesture that triggered this step (the prep step's "Open
+      // camera" button click bubbles into this navigation, so we are
+      // still inside the gesture's task).
+      if (window.OrientationDetector) {
+        try {
+          orientationStatus = await window.OrientationDetector.requestPermission();
+        } catch (err) {
+          orientationStatus = "denied";
+        }
+      } else {
+        orientationStatus = "unsupported";
+      }
+
+      try {
+        await window.CapturePreview.start(videoEl);
+      } catch (err) {
+        setStatus(`Camera unavailable: ${err.message || err}`, true);
+        return;
+      }
+      setStatus("Keep the camera parallel to the table, at the right distance from your hand.");
+      await refreshFlash();
+      await startGateLoop();
+    })();
+  },
+
+  unmount() {
+    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);
+    }
+    videoEl = null;
+    distanceChip = null;
+    levelChip = null;
+    levelBubble = null;
+    levelDot = null;
+    shutterBtn = null;
+    flashBtn = null;
+    statusEl = null;
+  },
+};

web_demo/static/mobile/steps/confirm.js

@@ -0,0 +1,117 @@
+// Step 5 — Confirm the photo + run measurement.
+//
+// Receives `session.imageBlob` from either the upload step (step 3,
+// file picked) or the capture step (step 4, camera shutter). Shows
+// the photo so the user can decide whether to keep it, then on
+// "Start Measurement" POSTs to /api/measure and shows a live
+// elapsed-time counter — the algorithm can take 20-30 s and silence
+// during that wait is the worst UX. When the response arrives, we
+// store it on `session.result` and advance to the result step.
+
+import { session } from "../session.js";
+import { postMeasure } from "../../shared/measure-api.js";
+
+let elapsedTimer = null;
+
+function clearTimerFn() {
+  if (elapsedTimer) {
+    clearInterval(elapsedTimer);
+    elapsedTimer = null;
+  }
+}
+
+export default {
+  mount(container, nav) {
+    if (!session.imageBlob) {
+      // Defensive: someone reached this step without an image.
+      // Send them back to the photo guide rather than leaving them
+      // staring at an empty preview.
+      nav.goTo("guide");
+      return;
+    }
+
+    const sourceLabel =
+      session.imageSource === "camera" ? "Captured Photo" : "Uploaded Photo";
+
+    container.innerHTML = `
+      <section class="step step-confirm">
+        <header class="step-head">
+          <button type="button" class="step-back" aria-label="Back">←</button>
+        </header>
+        <div class="step-body">
+          <div class="panel">
+            <p class="hero-eyebrow">Step 3 of 4</p>
+            <h2 class="panel-title">${sourceLabel}</h2>
+            <div class="image-frame show">
+              <img id="confirmPreview" alt="Photo to measure" />
+            </div>
+          </div>
+        </div>
+        <footer class="step-foot">
+          <!-- Status sits in the footer (which never scrolls) so the
+               live "Measuring…" feedback stays visible even when the
+               photo is tall enough to push the rest of the panel
+               content off-screen. Empty before the user taps Start
+               Measurement — no pre-measurement placeholder. -->
+          <p class="confirm-status" id="confirmStatus" hidden></p>
+          <button id="confirmStartBtn" type="button" class="primary">
+            Start Measurement
+          </button>
+        </footer>
+      </section>
+    `;
+
+    const previewImg = container.querySelector("#confirmPreview");
+    const statusEl = container.querySelector("#confirmStatus");
+    const startBtn = container.querySelector("#confirmStartBtn");
+
+    previewImg.src = session.imageUrl;
+
+    container.querySelector(".step-back").addEventListener("click", () => {
+      // Sending the user back to the photo-guide step is the sanest
+      // default. The capture step would re-open the camera and
+      // discard the photo we just captured, which is hardly ever
+      // what the user wants.
+      nav.goTo("guide");
+    });
+
+    startBtn.addEventListener("click", async () => {
+      startBtn.disabled = true;
+      statusEl.hidden = false;
+
+      // Live elapsed-time counter — copy mirrors the desktop's
+      // setStatus(`Measuring… Done in under a minute. (${secs}s)`)
+      // so both surfaces show identical feedback during the wait.
+      const startedAt = Date.now();
+      const renderTimer = () => {
+        const secs = Math.floor((Date.now() - startedAt) / 1000);
+        statusEl.textContent = `Measuring… Done in under a minute. (${secs}s)`;
+        statusEl.classList.remove("error");
+      };
+      renderTimer();
+      elapsedTimer = setInterval(renderTimer, 1000);
+
+      try {
+        const result = await postMeasure({
+          blob: session.imageBlob,
+          kol_name: session.kolName,
+          ring_model: session.ringModel,
+          gate_telemetry: session.gateTelemetry,
+          capture_method: session.imageSource === "camera" ? "camera" : "upload",
+        });
+        clearTimerFn();
+        session.result = result;
+        nav.next();
+      } catch (err) {
+        clearTimerFn();
+        statusEl.textContent = `Measurement failed: ${err.message || err}`;
+        statusEl.classList.add("error");
+        startBtn.disabled = false;
+      }
+    });
+  },
+
+  unmount() {
+    clearTimerFn();
+  },
+};

web_demo/static/mobile/steps/form.js

@@ -0,0 +1,68 @@
+// Step 2 — Name / ID + Ring Model.
+// Mirrors the desktop hero-card's top "controls" block.
+// Persists answers in session so back-nav preserves them.
+
+import { session } from "../session.js";
+
+export default {
+  mount(container, nav) {
+    container.innerHTML = `
+      <section class="step step-form">
+        <header class="step-head">
+          <button type="button" class="step-back" aria-label="Back">←</button>
+        </header>
+        <div class="step-body">
+          <div class="panel">
+            <p class="hero-eyebrow">Step 1 of 4</p>
+            <h2 class="panel-title">Select Ring Model</h2>
+            <div class="controls">
+              <label>
+                <span>Ring Model</span>
+                <select id="formRingModel">
+                  <option value="gen">Gen1/Gen2</option>
+                  <option value="air">Air</option>
+                </select>
+              </label>
+              <label>
+                <span>Name / ID</span>
+                <input
+                  type="text"
+                  id="formKolName"
+                  placeholder="e.g. Your Name"
+                  autocomplete="name"
+                />
+              </label>
+            </div>
+            <p class="form-error" id="formError" hidden></p>
+          </div>
+        </div>
+        <footer class="step-foot">
+          <button type="button" class="primary step-next">Continue</button>
+        </footer>
+      </section>
+    `;
+
+    const nameInput = container.querySelector("#formKolName");
+    const modelSelect = container.querySelector("#formRingModel");
+    const errorEl = container.querySelector("#formError");
+
+    // Pre-fill from session — back-nav from upload/camera should not
+    // ask the user to retype.
+    nameInput.value = session.kolName || "";
+    modelSelect.value = session.ringModel || "gen";
+
+    container.querySelector(".step-back").addEventListener("click", nav.back);
+    container.querySelector(".step-next").addEventListener("click", () => {
+      const name = nameInput.value.trim();
+      if (!name) {
+        errorEl.textContent = "Please enter a name or ID before continuing.";
+        errorEl.hidden = false;
+        nameInput.focus();
+        return;
+      }
+      session.kolName = name;
+      session.ringModel = modelSelect.value;
+      nav.next();
+    });
+  },
+};

web_demo/static/mobile/steps/guide.js

@@ -0,0 +1,100 @@
+// Step 3 — Photo guide.
+//
+// Shows the same five-bullet tips list the desktop displays, plus the
+// pre-bundled sample photo as a concrete "like this" example so the
+// user knows exactly what they're aiming for. Two actions at the
+// bottom: a primary "Open Camera" (preferred path — feeds the live
+// capture coach with level + distance gates) and a secondary ghost
+// link "Upload from photos" for users with a usable shot already in
+// the camera roll. Upload bypasses the capture step entirely and
+// hands the file straight to the confirm step.
+
+import { session, resetForRetake } from "../session.js";
+
+export default {
+  mount(container, nav) {
+    container.innerHTML = `
+      <section class="step step-guide">
+        <header class="step-head">
+          <button type="button" class="step-back" aria-label="Back">←</button>
+        </header>
+        <div class="step-body">
+          <div class="panel">
+            <p class="hero-eyebrow">Step 2 of 4</p>
+            <h2 class="panel-title">Photo Guidance</h2>
+
+            <ul class="capture-tips">
+              <li>Place a card of <strong>standard credit card size</strong> beside your hand.</li>
+              <li>Hold phone <strong>directly above hand</strong>, parallel to table.</li>
+              <li><strong>Spread your fingers naturally</strong>.</li>
+              <li><strong>Use plain white background</strong>, a sheet of paper works great.</li>
+              <li><strong>Turn on your phone's flash</strong>, it sharpens finger edges.</li>
+            </ul>
+
+            <figure class="guide-example">
+              <figcaption>Like this — hand flat, card beside it.</figcaption>
+              <img
+                src="/static/examples/default_sample.jpg"
+                alt="Example photo: hand flat with a credit card placed beside it"
+              />
+            </figure>
+          </div>
+        </div>
+        <footer class="step-foot">
+          <button type="button" class="primary step-next">Open Camera</button>
+          <button type="button" class="step-link guide-upload">Upload from photos</button>
+          <p class="guide-upload-error" id="guideUploadError" hidden role="alert"></p>
+          <input
+            type="file"
+            id="guideFileInput"
+            class="guide-file-input"
+            accept="image/*"
+            hidden
+          />
+        </footer>
+      </section>
+    `;
+
+    container.querySelector(".step-back").addEventListener("click", nav.back);
+    container.querySelector(".step-next").addEventListener("click", nav.next);
+
+    const fileInput = container.querySelector("#guideFileInput");
+    const errorEl = container.querySelector("#guideUploadError");
+    const showUploadError = (msg) => {
+      if (!errorEl) return;
+      errorEl.textContent = msg;
+      errorEl.hidden = false;
+    };
+    const clearUploadError = () => {
+      if (!errorEl) return;
+      errorEl.hidden = true;
+      errorEl.textContent = "";
+    };
+    container.querySelector(".guide-upload").addEventListener("click", () => {
+      clearUploadError();
+      // Reset value so picking the same file twice still fires `change`.
+      fileInput.value = "";
+      fileInput.click();
+    });
+    fileInput.addEventListener("change", (ev) => {
+      const file = ev.target.files && ev.target.files[0];
+      if (!file) return;
+      // `accept="image/*"` is a hint, not enforcement — Android's "Files"
+      // picker lets users pick anything. Validate at source so the
+      // downstream confirm/measure steps don't render a broken image
+      // or POST garbage and surface a backend 4xx.
+      if (!file.type.startsWith("image/") || file.size === 0) {
+        showUploadError("Please pick an image file (JPG or PNG).");
+        return;
+      }
+      // Drop any prior session image (camera capture or earlier upload)
+      // so the confirm step sees a clean slate.
+      resetForRetake();
+      session.imageBlob = file;
+      session.imageUrl = URL.createObjectURL(file);
+      session.imageSource = "upload";
+      // Skip the capture step — uploads bypass the live coach by design.
+      nav.goTo("confirm");
+    });
+  },
+};

web_demo/static/mobile/steps/intro.js

@@ -0,0 +1,24 @@
+// Step 1 — Intro / value prop.
+// Mirrors the desktop hero copy: red eyebrow, large display headline,
+// muted sub-line. No panel — this lives directly on the gradient
+// background, same as the desktop column-left treatment.
+
+export default {
+  mount(container, nav) {
+    container.innerHTML = `
+      <section class="step step-intro">
+        <div class="step-body">
+          <p class="hero-eyebrow">Femometer Smart Ring Sizer</p>
+          <h1 class="hero-headline">Upload a photo to quickly measure ring size</h1>
+          <p class="hero-sub">
+            Using a card of standard credit card size for scale reference.
+          </p>
+        </div>
+        <footer class="step-foot">
+          <button type="button" class="primary step-next">Get Started</button>
+        </footer>
+      </section>
+    `;
+    container.querySelector(".step-next").addEventListener("click", nav.next);
+  },
+};

web_demo/static/mobile/steps/result.js

@@ -0,0 +1,171 @@
+// Step 6 — Result.
+//
+// Mirrors the desktop result section: a "Result Overlay" panel
+// showing the algorithm's annotated image, then a "Ring Size
+// Recommendation" panel with one card per measured finger and the
+// ring-size reference table at the bottom. Reads
+// `session.result` (the /api/measure response) and `session.ringModel`.
+
+import { session, resetForRetake } from "../session.js";
+import { formatFailReason } from "../../shared/fail-reasons.js";
+
+const FINGER_LABEL = {
+  index: "Index (Recommended)",
+  middle: "Middle",
+  ring: "Ring",
+};
+const FINGER_COLOR = {
+  index: "#00dddd",
+  middle: "#00cc44",
+  ring: "#dd44dd",
+};
+const RING_MODEL_LABELS = { gen: "Gen1/Gen2", air: "Air" };
+const RING_SIZE_TABLES = {
+  gen: { 6: 16.9, 7: 17.7, 8: 18.6, 9: 19.4, 10: 20.3, 11: 21.1, 12: 21.9, 13: 22.7 },
+  air: { 6: 16.6, 7: 17.4, 8: 18.2, 9: 19.0, 10: 19.9, 11: 20.7, 12: 21.5, 13: 22.3 },
+};
+
+function escape(s) {
+  return String(s == null ? "" : s)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}
+
+function fingerCardHtml(fn, pf) {
+  const label = FINGER_LABEL[fn] || fn;
+  const color = FINGER_COLOR[fn] || "#888";
+  if (pf.status !== "ok") {
+    return `
+      <div class="finger-card finger-card-failed" style="border-top: 3px solid ${color};">
+        <div class="finger-name">${escape(label)}</div>
+        <div class="finger-failed">Failed</div>
+        <div class="finger-fail-reason">${escape(pf.fail_reason || "unknown")}</div>
+      </div>
+    `;
+  }
+  const widthMm = pf.diameter_cm ? (pf.diameter_cm * 10).toFixed(1) : "—";
+  const range = pf.range ? `${pf.range[0]} – ${pf.range[1]}` : "";
+  return `
+    <div class="finger-card" style="border-top: 3px solid ${color};">
+      <div class="finger-name">${escape(label)}</div>
+      <div class="finger-size-label">Size</div>
+      <div class="finger-size">${escape(pf.best_match)}</div>
+      ${range ? `<div class="finger-range">Range: ${escape(range)}</div>` : ""}
+      <div class="finger-width">Width: ${escape(widthMm)} mm</div>
+    </div>
+  `;
+}
+
+function buildSizeRefTable(ringModel) {
+  const sizeTable = RING_SIZE_TABLES[ringModel] || RING_SIZE_TABLES.gen;
+  const modelLabel = RING_MODEL_LABELS[ringModel] || ringModel;
+  const rows = Object.entries(sizeTable)
+    .map(([size, mm]) => `<tr><td>${size}</td><td>${mm.toFixed(1)}</td></tr>`)
+    .join("");
+  return `
+    <div class="size-ref-table">
+      <h3 class="size-ref-title">Size Reference (${escape(modelLabel)})</h3>
+      <table>
+        <thead><tr><th>Size</th><th>Inner ⌀ (mm)</th></tr></thead>
+        <tbody>${rows}</tbody>
+      </table>
+    </div>
+  `;
+}
+
+function renderRecommendation(payload, ringModel) {
+  // The status banner above this panel already explains the failure
+  // case (using the friendly desktop copy via formatFailReason), so
+  // we don't repeat a "Measurement Failed" hero here. Just render
+  // whatever finger data made it back, the count, and the size
+  // reference — useful even when nothing measured.
+  const perFinger = (payload && payload.per_finger) || {};
+  let cards = "";
+  for (const fn of ["index", "middle", "ring"]) {
+    const pf = perFinger[fn];
+    if (!pf) continue;
+    cards += fingerCardHtml(fn, pf);
+  }
+  const succeeded = (payload && payload.fingers_succeeded) ?? 0;
+  const total = (payload && payload.fingers_measured) ?? 0;
+  // Count above the cards (not below) so the user reads
+  // "X/Y fingers measured" first and immediately understands the
+  // cards are a per-finger breakdown rather than a single result.
+  return `
+    <div class="finger-count">${escape(`${succeeded}/${total} fingers measured`)}</div>
+    ${cards ? `<div class="finger-cards">${cards}</div>` : ""}
+    ${buildSizeRefTable(ringModel)}
+  `;
+}
+
+export default {
+  mount(container, nav) {
+    const data = session.result;
+    if (!data) {
+      // Defensive — nothing to show, kick back to start.
+      nav.goTo("intro");
+      return;
+    }
+    const payload = data.result || data;
+    const overlayUrl = data.result_image_url;
+    const ringModel = session.ringModel || "gen";
+
+    // Same success/error rule the desktop uses (web_demo/app.py
+    // sets `data.success = result.fail_reason is None`). Status copy
+    // is sourced from shared/fail-reasons.js so the mobile and
+    // desktop surfaces stay in sync.
+    const succeeded = !!data.success && payload && payload.per_finger;
+    const statusBanner = succeeded
+      ? `
+        <div class="result-status result-status-success">
+          <p>Measurement complete.</p>
+        </div>
+      `
+      : `
+        <div class="result-status result-status-error">
+          <p>${escape(formatFailReason(payload && payload.fail_reason))}</p>
+        </div>
+      `;
+
+    container.innerHTML = `
+      <section class="step step-result">
+        <div class="step-body">
+          ${statusBanner}
+          ${
+            overlayUrl
+              ? `
+                <div class="panel">
+                  <h2 class="panel-title">Result Overlay</h2>
+                  <div class="image-frame show">
+                    <img src="${escape(overlayUrl)}" alt="Measurement overlay" />
+                  </div>
+                </div>
+              `
+              : ""
+          }
+
+          <div class="panel">
+            <h2 class="panel-title">Ring Size Recommendation</h2>
+            ${renderRecommendation(payload, ringModel)}
+          </div>
+        </div>
+        <footer class="step-foot">
+          <button type="button" class="primary step-retake">Measure Again</button>
+        </footer>
+      </section>
+    `;
+
+    // "Measure again" returns to the photo-guide step so the user can
+    // pick between Open Camera and Upload from photos — the upload
+    // entry was added after this button originally jumped straight to
+    // the camera. Form fields (Name / Ring Model) are preserved; only
+    // the photo + result + telemetry are wiped. Users who want a full
+    // reset (e.g. handing the phone to a different person) can
+    // refresh the page.
+    container.querySelector(".step-retake").addEventListener("click", () => {
+      resetForRetake();
+      nav.goTo("guide");
+    });
+  },
+};

web_demo/static/preview/hands.js

@@ -0,0 +1,90 @@
+// v5 Phase 2 — in-browser MediaPipe Hands for the distance gate.
+//
+// Loaded as `<script type="module">` so we can `import` directly from the
+// jsdelivr CDN. The module attaches the public API to window.HandsDetector
+// so the classic-script app.js can call it.
+//
+// CDN choice: jsdelivr-mirrored npm package (default for Phase 2). Future
+// productization on Shopify may require self-hosting under
+// `web_demo/static/vendor/mediapipe/` to satisfy strict CSP — see doc/v5/PRD.md
+// "Risks and open questions".
+
+// Pinned to a real published version (0.10.22 from an earlier draft did not
+// exist on jsdelivr; latest at the time of pinning was 0.10.35). Bump only
+// after re-validating that the entrypoint and `/wasm/` subpath both 200.
+import {
+  HandLandmarker,
+  FilesetResolver,
+} from "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.35/vision_bundle.mjs";
+
+// Same hand-landmarker model the Python pipeline uses (see
+// src/finger_segmentation.py:55). Hosting it on Google's CDN keeps the
+// frontend / backend symmetric and avoids us redistributing the weights.
+const MODEL_URL =
+  "https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/1/hand_landmarker.task";
+const WASM_URL =
+  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@0.10.35/wasm";
+
+// MediaPipe landmark indices for the palm-MCP span — matches
+// LM_INDEX_MCP / LM_PINKY_MCP in script/analyze_hand_span.py.
+const LM_INDEX_MCP = 5;
+const LM_PINKY_MCP = 17;
+
+let landmarker = null;
+let initPromise = null;
+
+async function init() {
+  if (landmarker) return landmarker;
+  if (initPromise) return initPromise;
+  initPromise = (async () => {
+    const fileset = await FilesetResolver.forVisionTasks(WASM_URL);
+    landmarker = await HandLandmarker.createFromOptions(fileset, {
+      baseOptions: {
+        modelAssetPath: MODEL_URL,
+        delegate: "GPU",
+      },
+      runningMode: "VIDEO",
+      numHands: 1,
+      minHandDetectionConfidence: 0.3,
+      minTrackingConfidence: 0.3,
+    });
+    return landmarker;
+  })();
+  try {
+    return await initPromise;
+  } catch (err) {
+    initPromise = null;
+    throw err;
+  }
+}
+
+// Run a single detection on the current `<video>` frame. Returns
+// `{ratio, span_px}` if a hand is detected, `null` otherwise. The ratio is
+// computed against `min(videoWidth, videoHeight)` so it's invariant to
+// portrait vs landscape framing.
+function detect(videoEl) {
+  if (!landmarker) return null;
+  if (!videoEl || videoEl.readyState < 2) return null;
+  const w = videoEl.videoWidth;
+  const h = videoEl.videoHeight;
+  if (!w || !h) return null;
+
+  const result = landmarker.detectForVideo(videoEl, performance.now());
+  if (!result || !result.landmarks || result.landmarks.length === 0) {
+    return null;
+  }
+  const lm = result.landmarks[0];
+  const p5 = lm[LM_INDEX_MCP];
+  const p17 = lm[LM_PINKY_MCP];
+  if (!p5 || !p17) return null;
+
+  // Landmark coords from MediaPipe Tasks are normalized [0,1] over the
+  // image dimensions, so multiplying by w/h gets pixel coords.
+  const dx = (p5.x - p17.x) * w;
+  const dy = (p5.y - p17.y) * h;
+  const span_px = Math.sqrt(dx * dx + dy * dy);
+  const ratio = span_px / Math.min(w, h);
+  return { ratio, span_px };
+}
+
+window.HandsDetector = { init, detect };

web_demo/static/preview/orientation.js

@@ -0,0 +1,77 @@
+// v5 Phase 3 — DeviceOrientationEvent for the level gate.
+//
+// Encapsulates the iOS 13+ requestPermission() dance, falls back gracefully
+// where the API is missing, and exposes a callback-based stream of
+// {beta, gamma} readings. Loaded as a non-module IIFE attached to window so
+// the classic-script app.js can call it directly (matching preview.js).
+//
+// Permission semantics:
+//   "granted"     — events should fire; caller can attach the listener
+//   "denied"      — user explicitly declined; respect that and skip the gate
+//   "unsupported" — browser doesn't expose DeviceOrientationEvent at all
+//
+// The desktop case (DeviceOrientationEvent exists but no sensor) is reported
+// as "granted" — events will fire but with null beta/gamma. Caller is
+// responsible for treating "no data after some time" as "skipped" and
+// excluding the level signal from the gate.
+
+window.OrientationDetector = (function () {
+  let activeHandler = null;
+  let receivedAny = false;
+
+  async function requestPermission() {
+    if (typeof DeviceOrientationEvent === "undefined") {
+      return "unsupported";
+    }
+    // Non-iOS browsers do not require an explicit grant — they fire events
+    // immediately when an attached listener is present (subject to policy).
+    if (typeof DeviceOrientationEvent.requestPermission !== "function") {
+      return "granted";
+    }
+    try {
+      const result = await DeviceOrientationEvent.requestPermission();
+      return result; // "granted" | "denied"
+    } catch (err) {
+      // Spec says the rejection is permanent for this origin within the
+      // session — same observable behaviour as a denial, so map to that.
+      return "denied";
+    }
+  }
+
+  function start(callback) {
+    stop();
+    receivedAny = false;
+    activeHandler = function (event) {
+      // Desktop browsers fire `deviceorientation` with null beta/gamma
+      // (the API exists, the sensor doesn't). Drop those silently — the
+      // caller's no-data-after-timeout logic decides whether to skip.
+      // Also drop non-finite (NaN/Infinity) readings — rare but observed
+      // on misbehaving sensors; would otherwise propagate into the gate
+      // and CSS `calc()` as NaN, which silently freezes the indicator.
+      if (
+        event.beta === null ||
+        event.gamma === null ||
+        !Number.isFinite(event.beta) ||
+        !Number.isFinite(event.gamma)
+      ) {
+        return;
+      }
+      receivedAny = true;
+      callback({ beta: event.beta, gamma: event.gamma });
+    };
+    window.addEventListener("deviceorientation", activeHandler);
+  }
+
+  function stop() {
+    if (activeHandler) {
+      window.removeEventListener("deviceorientation", activeHandler);
+      activeHandler = null;
+    }
+  }
+
+  function hasReceivedData() {
+    return receivedAny;
+  }
+
+  return { requestPermission, start, stop, hasReceivedData };
+})();

web_demo/static/preview/preview.js

@@ -0,0 +1,127 @@
+// v5 Phase 1 — camera lifecycle + frame capture.
+// No gates yet; that's Phase 2-4. This module owns the MediaStream and
+// exposes start/stop/captureFrame so app.js can wire UI events to it.
+//
+// Loaded as a non-module IIFE attached to window so it can coexist with
+// the existing app.js (which is also non-module). Convert both to ES
+// modules later if v5 adds a bundler.
+
+window.CapturePreview = (function () {
+  let activeStream = null;
+  let activeVideo = null;
+
+  function isSupported() {
+    // getUserMedia requires a secure context (HTTPS or localhost). On HTTP
+    // LAN IPs, Chrome leaves navigator.mediaDevices undefined; Safari
+    // exposes the namespace but getUserMedia() rejects. Check secure
+    // context up-front so the "Use Camera" button stays hidden in
+    // insecure-test setups instead of opening a doomed flow.
+    return !!(
+      window.isSecureContext &&
+      navigator.mediaDevices &&
+      typeof navigator.mediaDevices.getUserMedia === "function"
+    );
+  }
+
+  async function start(videoEl) {
+    if (!window.isSecureContext) {
+      throw new Error(
+        "Camera requires HTTPS. Open the deployed (Hugging Face) URL, or set up HTTPS locally — http://<LAN-IP> won't work."
+      );
+    }
+    if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
+      throw new Error("This browser does not expose getUserMedia.");
+    }
+    stop();
+    // facingMode 'environment' = rear camera. 'ideal' (not 'exact') so
+    // desktop laptops without a rear camera still open the front cam
+    // rather than rejecting outright.
+    //
+    // Width/height are also `ideal` hints — the UA picks the closest
+    // mode the camera actually supports. We ask for 4K because the
+    // kol_success training set is ~3024×4032 native iPhone captures and
+    // sub-1080 frames noticeably soften the finger boundary. Modern
+    // iPhones and high-end Android phones honor 3840×2160; lesser
+    // hardware quietly negotiates down (typically to 1920×1080), which
+    // is still our previous baseline. No outright rejection.
+    const stream = await navigator.mediaDevices.getUserMedia({
+      video: {
+        facingMode: { ideal: "environment" },
+        width: { ideal: 3840 },
+        height: { ideal: 2160 },
+      },
+      audio: false,
+    });
+    videoEl.srcObject = stream;
+    // iOS Safari needs muted + playsinline (set as HTML attrs) to autoplay.
+    await videoEl.play();
+    activeStream = stream;
+    activeVideo = videoEl;
+    return stream;
+  }
+
+  function stop() {
+    if (activeStream) {
+      activeStream.getTracks().forEach((t) => t.stop());
+      activeStream = null;
+    }
+    if (activeVideo) {
+      activeVideo.srcObject = null;
+      activeVideo = null;
+    }
+  }
+
+  function getActiveVideoTrack() {
+    if (!activeStream) return null;
+    const tracks = activeStream.getVideoTracks();
+    return tracks.length ? tracks[0] : null;
+  }
+
+  // Torch (camera flash) support is Chromium-on-Android only — iOS
+  // Safari/WebKit does not expose `torch` in MediaTrackCapabilities, and
+  // most front cameras lack an LED even on Android. Callers must hide
+  // the flash UI when this returns false.
+  function isTorchSupported() {
+    const track = getActiveVideoTrack();
+    if (!track || typeof track.getCapabilities !== "function") return false;
+    let caps;
+    try {
+      caps = track.getCapabilities();
+    } catch (err) {
+      return false;
+    }
+    return !!(caps && caps.torch);
+  }
+
+  async function setTorch(on) {
+    const track = getActiveVideoTrack();
+    if (!track) throw new Error("No active video track");
+    await track.applyConstraints({ advanced: [{ torch: !!on }] });
+  }
+
+  // Draw the current video frame to an offscreen canvas at native sensor
+  // resolution and encode as a JPEG Blob suitable for FormData submission.
+  // The server's existing /api/measure path accepts this with no changes.
+  async function captureFrame(videoEl, mimeType, quality) {
+    const w = videoEl.videoWidth;
+    const h = videoEl.videoHeight;
+    if (!w || !h) {
+      throw new Error("Video stream has no dimensions yet");
+    }
+    const canvas = document.createElement("canvas");
+    canvas.width = w;
+    canvas.height = h;
+    const ctx = canvas.getContext("2d");
+    ctx.drawImage(videoEl, 0, 0, w, h);
+    return new Promise((resolve, reject) => {
+      canvas.toBlob(
+        (blob) =>
+          blob ? resolve(blob) : reject(new Error("toBlob returned null")),
+        mimeType || "image/jpeg",
+        typeof quality === "number" ? quality : 0.92,
+      );
+    });
+  }
+
+  return { isSupported, start, stop, captureFrame, isTorchSupported, setTorch };
+})();

web_demo/static/preview/thresholds.js

@@ -0,0 +1,58 @@
+// v5 capture-coach gate thresholds.
+// Source of truth: doc/v5/PRD.md and script/analyze_hand_span.py results
+// (72-image kol corpus, 2026-05-06 fit).
+//
+// Loaded as a non-module IIFE attached to window so both hands.js (module)
+// and app.js (classic) can read the same constants. Convert to ES module
+// when v5 introduces a bundler.
+
+window.PreviewThresholds = (function () {
+  // Distance: ‖landmark[5] - landmark[17]‖ / min(videoWidth, videoHeight).
+  // Originally 0.239 (P10 of the success cohort) — narrowed to 0.3 on
+  // 2026-05-07 after user feedback that the previous bound accepted
+  // too many "still a bit far" frames as green.
+  const HAND_SPAN_RATIO_MIN = 0.3;
+
+  // Soft amber threshold (desktop only — mobile collapsed to red/green
+  // on the same date). Between 80% of the hard threshold and the
+  // threshold itself, the desktop UI shows "almost there".
+  const HAND_SPAN_RATIO_AMBER = HAND_SPAN_RATIO_MIN * 0.8;
+
+  // Upper distance bound. MediaPipe still returns landmarks when the hand
+  // partially clips the frame, so without an upper threshold the gate
+  // reads "Distance OK" even when the camera is too close — at which
+  // point there is no room left for the credit card and lens distortion
+  // biases the edge measurement. Tightened from 0.55 → 0.5 on
+  // 2026-05-07 alongside the lower-bound bump; pending a P90 sweep of
+  // the success cohort via analyze_hand_span.py.
+  const HAND_SPAN_RATIO_MAX = 0.5;
+  const HAND_SPAN_RATIO_MAX_AMBER = HAND_SPAN_RATIO_MAX * 0.88;
+
+  // Level: DeviceOrientationEvent beta (front-back) and gamma (left-right) in
+  // degrees. Tightened from 10° to 5° on 2026-05-07 — the previous
+  // bound matched the card_not_parallel hard gate but felt too lax in
+  // practice; ±5° gets the user closer to a clean top-down shot.
+  const LEVEL_BETA_MAX_DEG = 5;
+  const LEVEL_GAMMA_MAX_DEG = 5;
+
+  // Brightness: mean luminance (0–255) of a 64×64 downsample of the preview
+  // frame, computed as 0.299R + 0.587G + 0.114B. Below 60 is visibly
+  // underexposed and likely to fail edge detection.
+  const BRIGHTNESS_MIN_MEAN_LUM = 60;
+
+  // Anti-jitter: number of consecutive frames a signal must hold green
+  // before the gate counts it as passing. Prevents the shutter from flashing
+  // on/off as the user wobbles between threshold and threshold-epsilon.
+  const GATE_CONSECUTIVE_FRAMES = 3;
+
+  return {
+    HAND_SPAN_RATIO_MIN,
+    HAND_SPAN_RATIO_AMBER,
+    HAND_SPAN_RATIO_MAX,
+    HAND_SPAN_RATIO_MAX_AMBER,
+    LEVEL_BETA_MAX_DEG,
+    LEVEL_GAMMA_MAX_DEG,
+    BRIGHTNESS_MIN_MEAN_LUM,
+    GATE_CONSECUTIVE_FRAMES,
+  };
+})();

web_demo/static/shared/fail-reasons.js

@@ -0,0 +1,72 @@
+// Friendly status messages for /api/measure failures.
+//
+// Currently consumed by the mobile result step. The desktop
+// `static/app.js` keeps an inline duplicate of this map until the
+// Phase 4 desktop refactor migrates it to import from here. Until
+// then, edits to copy must land in BOTH places — that's tracked in
+// doc/v6/Progress.md.
+
+export const FAIL_REASON_MESSAGES = {
+  card_not_detected:
+    "Card not detected. A card of standard credit card dimensions (85.6 × 54 mm) is required as a scale reference to measure your finger width. Place the card beside your hand on a plain white background (e.g. a sheet of paper), and turn on your phone's flash.",
+  card_not_parallel:
+    "Card scale calibration failed. Keep your phone parallel to the card. Use a card of standard credit card dimensions (85.6 × 54 mm) as the reference.",
+  card_near_edge:
+    "Card appears cropped. Place the entire card within the photo frame.",
+  card_too_small:
+    "Card looks too small in the photo. Move your phone closer to the table so the card takes up a larger portion of the frame, then retake.",
+  hand_not_detected:
+    "Hand not detected. Place your hand flat on a plain white background (e.g. a sheet of paper), and spread your fingers naturally.",
+  finger_isolation_failed:
+    "Could not isolate the selected finger. Keep one target finger extended and separated.",
+  finger_not_fully_visible:
+    "Finger is partially out of frame. Move hand to center of photo.",
+  finger_mask_too_small:
+    "Finger region is too small. Move closer and use a higher-resolution photo.",
+  fingers_too_close:
+    "Fingers are too close together. Spread your fingers apart naturally.",
+  contour_extraction_failed:
+    "Finger contour extraction failed. Improve lighting and reduce background clutter.",
+  axis_estimation_failed:
+    "Finger axis estimation failed. Keep the finger straight and fully visible.",
+  zone_localization_failed:
+    "Ring zone localization failed. Keep more of the finger base visible.",
+  width_measurement_failed:
+    "Width measurement failed. Retake with phone parallel to the table and steady focus.",
+  sobel_edge_refinement_failed:
+    "Edge refinement failed. Turn on flash or use stronger, even lighting.",
+  width_unreasonable:
+    "Measured width is out of range. Retake with the phone parallel to the table.",
+  disagreement_with_contour:
+    "Edge methods disagree too much. Retake with cleaner edges and more even lighting.",
+  all_fingers_failed:
+    "Could not measure any fingers. Ensure hand is flat with fingers spread and well-lit.",
+  image_too_blurry:
+    "Photo is blurry. Hold your phone steady or use a tripod.",
+  image_underexposed:
+    "Photo is too dark. Turn on flash or improve lighting.",
+  image_overexposed:
+    "Photo is too bright. Avoid direct sunlight or strong overhead light.",
+  image_low_contrast:
+    "Photo has low contrast. Use a different background color.",
+  image_resolution_too_low:
+    "Photo resolution is too low. Use the rear camera at full resolution.",
+  image_quality_low_lighting:
+    "Lighting is uneven. Turn on flash and shoot from directly above.",
+};
+
+export function formatFailReason(failReason) {
+  if (!failReason) {
+    return "Measurement failed.";
+  }
+  if (failReason.startsWith("quality_score_low_")) {
+    return "Low edge quality detected. Turn on flash and retake.";
+  }
+  if (failReason.startsWith("consistency_low_")) {
+    return "Edge detection was inconsistent. Keep phone parallel to table and retry.";
+  }
+  return (
+    FAIL_REASON_MESSAGES[failReason] ||
+    "Measurement failed. Please retake the photo and try again."
+  );
+}

web_demo/static/shared/measure-api.js

@@ -0,0 +1,53 @@
+// POST a captured frame to /api/measure. Returns the parsed response
+// JSON unchanged so callers can render the same shape the desktop UI
+// already understands.
+//
+// Currently consumed only by the mobile capture step. Phase 4 of the
+// v6 plan migrates the desktop submit handler to this helper too;
+// until then `web_demo/static/app.js` keeps its inline fetch call.
+
+const DEFAULTS = {
+  finger_index: "index",
+  mode: "multi",
+  edge_method: "mask",
+  ring_model: "gen",
+  // Server reads "1" as truthy; anything else (including "on", "0",
+  // "") is treated as off. Mobile flow does not surface the AI toggle,
+  // so default off — opt-in lives on the desktop dev page.
+  ai_explain: "0",
+  capture_method: "camera",
+};
+
+export async function postMeasure({
+  blob,
+  kol_name,
+  gate_telemetry = null,
+  ...overrides
+} = {}) {
+  if (!blob) throw new Error("postMeasure: blob is required");
+  if (!kol_name) throw new Error("postMeasure: kol_name is required");
+
+  const settings = { ...DEFAULTS, ...overrides };
+  const formData = new FormData();
+  formData.append("image", blob, "capture.jpg");
+  formData.append("kol_name", kol_name);
+  formData.append("finger_index", settings.finger_index);
+  formData.append("mode", settings.mode);
+  formData.append("edge_method", settings.edge_method);
+  formData.append("ring_model", settings.ring_model);
+  formData.append("ai_explain", settings.ai_explain);
+  formData.append("capture_method", settings.capture_method);
+  if (gate_telemetry) {
+    formData.append("gate_telemetry", JSON.stringify(gate_telemetry));
+  }
+
+  const response = await fetch("/api/measure", {
+    method: "POST",
+    body: formData,
+  });
+  if (!response.ok) {
+    const text = await response.text().catch(() => "");
+    throw new Error(`Measurement request failed (${response.status}): ${text.slice(0, 120)}`);
+  }
+  return response.json();
+}

web_demo/static/shared/tokens.css

@@ -0,0 +1,16 @@
+/* Design tokens shared by the desktop (`styles.css`) and mobile
+   (`mobile/mobile.css`) surfaces. Keep this file colors-and-radii only —
+   no layout, no per-component rules — so both surfaces can evolve
+   independently while staying visually coherent. */
+:root {
+  --bg-1: #f5f1e7;
+  --bg-2: #eedad5;
+  --bg-3: #e7efe8;
+  --ink: #2b1f1f;
+  --ink-soft: #4b3d3d;
+  --accent: #bf3a2b;
+  --accent-dark: #8f2b22;
+  --sand: #f9f4ec;
+  --shadow: rgba(34, 26, 26, 0.12);
+  --border: rgba(45, 33, 33, 0.18);
+}

web_demo/static/styles.css

@@ -1,20 +1,20 @@
-:root {
-  --bg-1: #f5f1e7;
-  --bg-2: #eedad5;
-  --bg-3: #e7efe8;
-  --ink: #2b1f1f;
-  --ink-soft: #4b3d3d;
-  --accent: #bf3a2b;
-  --accent-dark: #8f2b22;
-  --sand: #f9f4ec;
-  --shadow: rgba(34, 26, 26, 0.12);
-  --border: rgba(45, 33, 33, 0.18);
-}
+/* Design tokens (CSS variables) live in shared/tokens.css so the mobile
+   surface can pick up the same palette. CSS @import must be the first
+   rule in a stylesheet, so it goes above everything else here. */
+@import url("./shared/tokens.css");
 
 * {
   box-sizing: border-box;
 }
 
+/* Force the HTML `hidden` attribute to win over class-level display rules.
+   The user-agent `[hidden]` rule is `display: none` at attribute specificity
+   (0,0,1,0), which loses to any class rule. We use `!important` because that's
+   the only way to beat author-level display declarations across the codebase. */
+[hidden] {
+  display: none !important;
+}
+
 body {
   margin: 0;
   min-height: 100vh;
@@ -140,7 +140,7 @@ body {
   background: rgba(191, 58, 43, 0.06);
   border-left: 3px solid rgba(191, 58, 43, 0.55);
   border-radius: 8px;
-  font-size: 0.85rem;
+  font-size: 1.0rem;
   color: var(--ink-soft);
   line-height: 1.5;
 }
@@ -173,7 +173,11 @@ select,
   border: 1px solid var(--border);
   border-radius: 12px;
   padding: 10px 12px;
-  font-size: 0.95rem;
+  /* iOS Safari auto-zooms the page when an input's computed font-size
+     is below 16px. The zoom doesn't always restore cleanly when the
+     keyboard dismisses, leaving the layout viewport offset. 16px
+     (= 1rem at default html font-size) keeps Safari hands-off. */
+  font-size: 1rem;
   background: white;
   color: var(--ink);
   width: 100%;
@@ -197,6 +201,13 @@ select,
   box-shadow: 0 12px 24px rgba(191, 58, 43, 0.25);
 }
 
+.primary:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+  transform: none;
+  box-shadow: none;
+}
+
 .status {
   margin-top: 12px;
   font-size: 0.9rem;

web_demo/templates/mobile.html

@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+  <meta name="theme-color" content="#f5f1e7" />
+  <title>Ring Size · Mobile</title>
+  <link rel="stylesheet" href="/static/mobile/mobile.css" />
+</head>
+<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).
+  -->
+  <main id="mobileRoot"></main>
+
+  <!-- Capture-coach modules. Loaded up front so they're ready by the
+       time the user reaches the capture step (step 4). They register
+       on window.* so the mobile capture step can reach them via
+       window.HandsDetector / CapturePreview / OrientationDetector. -->
+  <script src="/static/preview/thresholds.js"></script>
+  <script src="/static/preview/preview.js"></script>
+  <script src="/static/preview/orientation.js"></script>
+  <script type="module" src="/static/preview/hands.js"></script>
+
+  <script type="module" src="/static/mobile/mobile.js"></script>
+</body>
+</html>