Upload folder using huggingface_hub

AGENTS.md

@@ -23,8 +23,9 @@ For tasks of **reboot** from a new codex session:
 3. Read doc/v4/PRD.md, doc/v4/Plan.md, doc/v4/Progress.md for SAM 2.1 integration (card + hand)
 4. Read doc/v5/PRD.md, doc/v5/Plan.md, doc/v5/Progress.md for the in-browser capture coach (distance + level gates)
 5. Read doc/v6/PRD.md, doc/v6/Plan.md, doc/v6/Progress.md for the mobile-native demo surface (`/m`)
-6. Assume this is a continuation of an existing project.
-7. Summarize your understanding of the current state and propose the next concrete step without writing code yet.
+6. Read doc/v10/PRD.md, doc/v10/Plan.md, doc/v10/Progress.md for multi-shot session median recommendations
+7. Assume this is a continuation of an existing project.
+8. Summarize your understanding of the current state and propose the next concrete step without writing code yet.
 
 ## Project Overview
 
@@ -242,6 +243,35 @@ in `web_demo/app.py`), never the full address, to keep PII out of bucket
 paths. Admin grouping/display and CSV export prefer `kol_email` and fall
 back to `kol_name` for legacy rows.
 
+### v10 multi-shot session median
+
+Repeat captures in the same browser session are linked by a client-generated
+UUID. The browser carries the previous server-returned session state; Python
+adds the current successful calibrated per-finger diameters and computes each
+median. The precise median is retained, while a half-up 0.1 mm value is used
+for `recommend_ring_size()`; exact midpoint ties prefer the smaller size. Raw
+shot fields remain unchanged. The visible result cards prefer the separate
+`session_recommendation` object. A single footer below the cards reads
+`Based on N measurements. (Please measure at least 3 times for best reliability)`
+
+Aggregation is partitioned by `handedness + finger + ring_model`; failed
+fingers are excluded and exact duplicate images are identified by SHA-256.
+Supabase is only an asynchronous audit trail and is never queried on the live
+recommendation path. Sessions expire after 30 minutes or when email/model/mode
+context changes. See `doc/v10/`.
+
+Additive columns on `measurements`:
+
+| Column | Notes |
+|---|---|
+| `session_id` | Browser-session UUID; nullable for legacy/non-session clients. |
+| `session_attempt_index` | Monotonic request count within the carried state. |
+| `image_sha256` | Exact duplicate detection and audit. |
+| `session_recommendation` | JSONB snapshot of precise medians, 0.1 mm decision diameters, sizes, counts, and spreads. |
+
+Existing `diameter_cm`, `per_finger`, and `overall_*` fields continue to mean
+the current raw shot, not the session median.
+
 ### v8 post-shipment feedback (`/feedback` + `feedback` table)
 
 A **separate** flow from the post-result rating above — different

CLAUDE.md

@@ -23,8 +23,9 @@ For tasks of **reboot** from a new codex session:
 3. Read doc/v4/PRD.md, doc/v4/Plan.md, doc/v4/Progress.md for SAM 2.1 integration (card + hand)
 4. Read doc/v5/PRD.md, doc/v5/Plan.md, doc/v5/Progress.md for the in-browser capture coach (distance + level gates)
 5. Read doc/v6/PRD.md, doc/v6/Plan.md, doc/v6/Progress.md for the mobile-native demo surface (`/m`)
-6. Assume this is a continuation of an existing project.
-7. Summarize your understanding of the current state and propose the next concrete step without writing code yet.
+6. Read doc/v10/PRD.md, doc/v10/Plan.md, doc/v10/Progress.md for multi-shot session median recommendations
+7. Assume this is a continuation of an existing project.
+8. Summarize your understanding of the current state and propose the next concrete step without writing code yet.
 
 ## Project Overview
 
@@ -242,6 +243,35 @@ in `web_demo/app.py`), never the full address, to keep PII out of bucket
 paths. Admin grouping/display and CSV export prefer `kol_email` and fall
 back to `kol_name` for legacy rows.
 
+### v10 multi-shot session median
+
+Repeat captures in the same browser session are linked by a client-generated
+UUID. The browser carries the previous server-returned session state; Python
+adds the current successful calibrated per-finger diameters and computes each
+median. The precise median is retained, while a half-up 0.1 mm value is used
+for `recommend_ring_size()`; exact midpoint ties prefer the smaller size. Raw
+shot fields remain unchanged. The visible result cards prefer the separate
+`session_recommendation` object. A single footer below the cards reads
+`Based on N measurements. (Please measure at least 3 times for best reliability)`
+
+Aggregation is partitioned by `handedness + finger + ring_model`; failed
+fingers are excluded and exact duplicate images are identified by SHA-256.
+Supabase is only an asynchronous audit trail and is never queried on the live
+recommendation path. Sessions expire after 30 minutes or when email/model/mode
+context changes. See `doc/v10/`.
+
+Additive columns on `measurements`:
+
+| Column | Notes |
+|---|---|
+| `session_id` | Browser-session UUID; nullable for legacy/non-session clients. |
+| `session_attempt_index` | Monotonic request count within the carried state. |
+| `image_sha256` | Exact duplicate detection and audit. |
+| `session_recommendation` | JSONB snapshot of precise medians, 0.1 mm decision diameters, sizes, counts, and spreads. |
+
+Existing `diameter_cm`, `per_finger`, and `overall_*` fields continue to mean
+the current raw shot, not the session median.
+
 ### v8 post-shipment feedback (`/feedback` + `feedback` table)
 
 A **separate** flow from the post-result rating above — different

measure_finger.py

@@ -289,8 +289,16 @@ def save_output(output: Dict[str, Any], output_path: str) -> None:
     # Ensure output directory exists
     Path(output_path).parent.mkdir(parents=True, exist_ok=True)
 
+    def _numpy_json_default(value: Any) -> Any:
+        """Normalize NumPy values emitted by multi-finger geometry helpers."""
+        if isinstance(value, np.ndarray):
+            return value.tolist()
+        if isinstance(value, np.generic):
+            return value.item()
+        raise TypeError(f"Object of type {type(value).__name__} is not JSON serializable")
+
     with open(output_path, "w") as f:
-        json.dump(output, f, indent=2)
+        json.dump(output, f, indent=2, default=_numpy_json_default)
 
 
 # Debug visualisations are for human inspection, so there's no reason to
@@ -1083,7 +1091,7 @@ def measure_finger(
 
     log_phase_summary(timings)
 
-    return create_output(
+    output = create_output(
         finger_diameter_cm=median_width_cm,
         confidence=confidence_breakdown['overall'],
         card_detected=card_detected,
@@ -1094,6 +1102,11 @@ def measure_finger(
         edge_method_used=edge_method_used,
         card_metrics=card_metrics,
     )
+    # Additive metadata used by the web session aggregator. Keeping it in the
+    # core result also makes CLI/debug JSON explicit about which physical hand
+    # was measured.
+    output["handedness"] = hand_data.get("handedness", "Unknown")
+    return output
 
 
 MULTI_FINGERS = ["index", "middle", "ring"]
@@ -1463,6 +1476,7 @@ def measure_multi_finger(
         r.pop("_internal", None)
 
     aggregated["scale_px_per_cm"] = round(px_per_cm, 2)
+    aggregated["handedness"] = hand_data.get("handedness", "Unknown")
     aggregated["quality_flags"] = {
         "card_detected": card_detected,
         "view_angle_ok": view_angle_ok,

script/deploy_hf.sh

@@ -5,11 +5,18 @@ set -euo pipefail
 REPO_ID="Feng-X/ring-sizer"
 IGNORE='[".venv/*", ".git/*", "__pycache__/*", "*.pyc", "output/*", "web_demo/uploads/*", "web_demo/results/*", "doc/*", ".claude/*", "input/*"]'
 
-cd "$(dirname "$0")/.."
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PYTHON_BIN="${REPO_ROOT}/.venv/bin/python"
 
-source .venv/bin/activate
+if [[ ! -x "${PYTHON_BIN}" ]]; then
+    echo "Deployment environment not found: ${PYTHON_BIN}" >&2
+    echo "Create it with: python3 -m venv .venv && .venv/bin/pip install -r requirements.txt" >&2
+    exit 1
+fi
 
-python -c "
+cd "${REPO_ROOT}"
+
+"${PYTHON_BIN}" -c "
 from huggingface_hub import HfApi
 HfApi().upload_folder(
     folder_path='.',

script/validate_knuckle.py

@@ -0,0 +1,237 @@
+"""Seat-vs-PIP-knuckle width validation over a folder of hand photos.
+
+For each image: run the real pipeline up through canonical rotation, then
+measure two bands on the chosen finger --
+  * SEAT    : current anatomical band  [PIP - seg , PIP]            (median)
+  * KNUCKLE : PIP-centered band         PIP +/- K_SEG*seg            (median + p90)
+-- map each to a ring size, and write
+  * an annotated overlay PNG so the seat vs knuckle lines can be eyeballed
+  * a row in results.csv
+
+No ground truth is required: this is a visual + tabular comparison to confirm
+the knuckle band detects the wider PIP joint on knuckle-dominant fingers.
+
+Usage:
+  python script/validate_knuckle.py [input_dir] [--finger index] [--limit N]
+"""
+import sys
+import csv
+import argparse
+from pathlib import Path
+
+import numpy as np
+import cv2
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from src.finger_segmentation import segment_hand, isolate_finger
+from src.geometry import (
+    estimate_finger_axis, localize_ring_zone_from_landmarks,
+    calculate_angle_from_vertical, rotate_image_precise, rotate_axis_data,
+    transform_points_rotation,
+)
+from src.edge_refinement import refine_edges_sobel
+from src.card_detection import compute_scale_factor
+from src.ring_size import recommend_ring_size
+from measure_finger import _sam_card_detect
+
+# --- locked method parameters (per agreed recommendation) ---
+K_SEG = 0.4                # knuckle band half-height in units of |DIP-PIP|
+SLOPE, INTERCEPT = 0.809353, 0.251506   # src/calibration.json (mask/classic)
+
+
+def _cal_mm(raw_px, px_per_cm):
+    raw_cm = raw_px / px_per_cm
+    return (SLOPE * raw_cm + INTERCEPT) * 10.0
+
+
+def _size(cal_mm):
+    rs = recommend_ring_size(cal_mm / 10.0)
+    return rs["best_match"] if rs else None
+
+
+def _band_widths_px(image, axis_data, zone, px_per_cm, landmarks, mask):
+    """Return (median_px, p90_px, n) of per-row mask widths over a band."""
+    m = refine_edges_sobel(
+        image=image, axis_data=axis_data, zone_data=zone,
+        scale_px_per_cm=px_per_cm, finger_landmarks=landmarks,
+        finger_mask=mask, mask_mode="mask_only",
+    )
+    ed = m["edge_data"]
+    vr = ed["valid_rows"]
+    w = (ed["right_edges"][vr] - ed["left_edges"][vr])
+    if w.size == 0:
+        return None, None, 0
+    # same MAD trim the production median uses, so seat matches the real number
+    med = np.median(w)
+    mad = np.median(np.abs(w - med))
+    keep = np.abs(w - med) <= 3 * mad if mad > 0 else np.ones_like(w, bool)
+    w = w[keep]
+    return float(np.median(w)), float(np.percentile(w, 90)), int(w.size)
+
+
+def _draw(img, landmarks, seat_c, seat_w, knk_c, knk_w, texts):
+    """Draw both width lines + landmarks on a copy, crop tight, return it."""
+    vis = img.copy()
+    t = max(2, img.shape[1] // 500)
+    pts = [seat_c, knk_c] + [tuple(p) for p in landmarks]
+
+    def hline(c, half, color):
+        cx, cy = float(c[0]), float(c[1])
+        a = (int(cx - half), int(cy)); b = (int(cx + half), int(cy))
+        cv2.line(vis, a, b, color, t)
+        cv2.circle(vis, a, t + 1, color, -1)
+        cv2.circle(vis, b, t + 1, color, -1)
+        pts.extend([a, b])
+
+    hline(seat_c, seat_w / 2, (0, 200, 0))      # green = seat
+    hline(knk_c, knk_w / 2, (0, 80, 255))       # orange = knuckle
+    for name, p in zip(["MCP", "PIP", "DIP", "TIP"], landmarks):
+        cv2.circle(vis, (int(p[0]), int(p[1])), t + 2, (255, 255, 0), -1)
+
+    xs = [p[0] for p in pts]; ys = [p[1] for p in pts]
+    pad = int(img.shape[1] * 0.12)
+    x0 = max(0, int(min(xs)) - pad); x1 = min(img.shape[1], int(max(xs)) + pad)
+    y0 = max(0, int(min(ys)) - pad); y1 = min(img.shape[0], int(max(ys)) + pad)
+    crop = vis[y0:y1, x0:x1].copy()
+
+    fs = crop.shape[1] / 700.0
+    for i, txt in enumerate(texts):
+        y = int(30 * fs) + int(i * 34 * fs)
+        cv2.putText(crop, txt, (int(10 * fs), y), cv2.FONT_HERSHEY_SIMPLEX,
+                    fs, (0, 0, 0), max(3, int(4 * fs)), cv2.LINE_AA)
+        cv2.putText(crop, txt, (int(10 * fs), y), cv2.FONT_HERSHEY_SIMPLEX,
+                    fs, (255, 255, 255), max(1, int(2 * fs)), cv2.LINE_AA)
+    return crop
+
+
+def process(path, finger, out_dir):
+    image = cv2.imread(str(path))
+    if image is None:
+        return {"name": path.stem, "fail_reason": "imread_failed"}
+
+    hand = segment_hand(image, finger=finger)
+    if hand is None:
+        return {"name": path.stem, "fail_reason": "hand_not_detected"}
+    img_can = hand.get("canonical_image", image)
+    raw_mask = hand.get("mask")
+
+    card = _sam_card_detect(img_can, hand, False, None)
+    if card is None:
+        return {"name": path.stem, "fail_reason": "card_not_detected"}
+    px_per_cm, _ = compute_scale_factor(card["corners"])
+
+    h, w = img_can.shape[:2]
+    fd = isolate_finger(hand, finger=finger, image_shape=(h, w))
+    if fd is None or fd.get("landmarks") is None:
+        return {"name": path.stem, "fail_reason": "finger_isolation_failed"}
+
+    axis = estimate_finger_axis(fd["landmarks"])
+    angle = calculate_angle_from_vertical(axis["direction"])
+    R = None
+    if abs(angle) >= 0.0:
+        img_can, R = rotate_image_precise(img_can, angle, (w / 2.0, h / 2.0))
+        axis = rotate_axis_data(axis, R)
+        lm = transform_points_rotation(fd["landmarks"], R)
+        raw_mask = cv2.warpAffine(raw_mask, R, (w, h), flags=cv2.INTER_NEAREST)
+    else:
+        lm = fd["landmarks"]
+
+    mcp, pip, dip, tip = lm
+    seg = float(np.linalg.norm(dip - pip))
+    direction = (pip - mcp) / np.linalg.norm(pip - mcp)
+
+    seat = localize_ring_zone_from_landmarks(lm, axis, zone_type="anatomical")
+    half = K_SEG * seg
+    knuckle = {
+        "start_point": (pip - direction * half).astype(np.float32),
+        "end_point": (pip + direction * half).astype(np.float32),
+        "center_point": pip.astype(np.float32),
+        "length": float(2 * half),
+        "localization_method": "pip_knuckle",
+    }
+
+    seat_med, _, seat_n = _band_widths_px(img_can, axis, seat, px_per_cm, lm, raw_mask)
+    knk_med, knk_p90, knk_n = _band_widths_px(img_can, axis, knuckle, px_per_cm, lm, raw_mask)
+    if seat_med is None or knk_med is None:
+        return {"name": path.stem, "fail_reason": "no_valid_rows"}
+
+    seat_cal = _cal_mm(seat_med, px_per_cm)
+    knk_cal = _cal_mm(knk_med, px_per_cm)
+    knk_p90_cal = _cal_mm(knk_p90, px_per_cm)
+    row = {
+        "name": path.stem,
+        "finger": finger,
+        "scale_px_per_cm": round(px_per_cm, 1),
+        "seat_cal_mm": round(seat_cal, 2),
+        "seat_size": _size(seat_cal),
+        "knuckle_med_cal_mm": round(knk_cal, 2),
+        "knuckle_size": _size(knk_cal),
+        "knuckle_p90_cal_mm": round(knk_p90_cal, 2),
+        "knuckle_p90_size": _size(knk_p90_cal),
+        "gap_mm": round(knk_cal - seat_cal, 2),
+        "size_up": int((_size(knk_cal) or 0) > (_size(seat_cal) or 0)),
+        "fail_reason": "",
+    }
+
+    texts = [
+        f"seat   {seat_cal:.1f}mm  size {row['seat_size']}",
+        f"knuckle {knk_cal:.1f}mm  size {row['knuckle_size']}  (gap {row['gap_mm']:+.1f}mm)",
+    ]
+    crop = _draw(img_can, lm, seat["center_point"], seat_med,
+                 pip, knk_med, texts)
+    cv2.imwrite(str(out_dir / f"{path.stem}__cmp.png"), crop)
+    return row
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("input_dir", nargs="?", default="input/kol_high_quality")
+    ap.add_argument("--finger", default="index")
+    ap.add_argument("--limit", type=int, default=0)
+    args = ap.parse_args()
+
+    in_dir = Path(args.input_dir)
+    out_dir = Path("output/knuckle_validation")
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    exts = {".jpg", ".jpeg", ".png"}
+    images = sorted(p for p in in_dir.iterdir() if p.suffix.lower() in exts)
+    if args.limit:
+        images = images[:args.limit]
+
+    fields = ["name", "finger", "scale_px_per_cm", "seat_cal_mm", "seat_size",
+              "knuckle_med_cal_mm", "knuckle_size", "knuckle_p90_cal_mm",
+              "knuckle_p90_size", "gap_mm", "size_up", "fail_reason"]
+    rows = []
+    for i, p in enumerate(images, 1):
+        try:
+            r = process(p, args.finger, out_dir)
+        except Exception as e:
+            r = {"name": p.stem, "fail_reason": f"error:{type(e).__name__}:{e}"}
+        rows.append({k: r.get(k, "") for k in fields})
+        print(f"[{i}/{len(images)}] {p.stem}: "
+              + (r["fail_reason"] if r.get("fail_reason")
+                 else f"seat={r['seat_size']} knuckle={r['knuckle_size']} gap={r['gap_mm']:+.1f}mm"),
+              flush=True)
+
+    csv_path = out_dir / "results.csv"
+    with open(csv_path, "w", newline="") as f:
+        wcsv = csv.DictWriter(f, fieldnames=fields)
+        wcsv.writeheader()
+        wcsv.writerows(rows)
+
+    ok = [r for r in rows if not r["fail_reason"]]
+    up = [r for r in ok if r["size_up"]]
+    print("\n==== summary ====")
+    print(f"processed {len(rows)}, ok {len(ok)}, failed {len(rows) - len(ok)}")
+    if ok:
+        gaps = [float(r["gap_mm"]) for r in ok]
+        print(f"knuckle wider in {sum(g > 0 for g in gaps)}/{len(ok)} images; "
+              f"mean gap {np.mean(gaps):+.2f}mm, max {max(gaps):+.2f}mm")
+        print(f"knuckle bumps the recommended size up in {len(up)}/{len(ok)} images")
+    print(f"overlays + results.csv -> {out_dir}")
+
+
+if __name__ == "__main__":
+    main()

src/ring_size.py

@@ -1,5 +1,6 @@
 """Ring size recommendation from calibrated finger width."""
 
+from decimal import Decimal
 from typing import Dict, List, Literal, Optional, Tuple
 
 # Ring model definitions: model name → {size: inner_diameter_mm}
@@ -44,9 +45,18 @@ def _get_sorted_sizes(ring_model: str) -> List[Tuple[int, float]]:
     return sorted(chart.items(), key=lambda x: x[1])
 
 
-def recommend_ring_size(diameter_cm: float, ring_model: str = DEFAULT_RING_MODEL) -> Optional[Dict]:
+def recommend_ring_size(
+    diameter_cm: float,
+    ring_model: str = DEFAULT_RING_MODEL,
+    *,
+    prefer_smaller_on_tie: bool = False,
+) -> Optional[Dict]:
     """Recommend ring size from calibrated finger outer diameter.
 
+    When ``prefer_smaller_on_tie`` is true, exact midpoint ties are compared
+    with decimal arithmetic and resolve to the smaller size. The default keeps
+    the legacy per-photo lookup behavior.
+
     Returns dict with:
         - best_match: nearest ring size (int)
         - best_match_inner_mm: inner diameter of best match
@@ -61,14 +71,27 @@ def recommend_ring_size(diameter_cm: float, ring_model: str = DEFAULT_RING_MODEL
         return None
 
     sorted_sizes = _get_sorted_sizes(ring_model)
+    if prefer_smaller_on_tie:
+        decision_mm = Decimal(str(diameter_cm)) * Decimal("10")
+
+        def distance_key(size_and_diameter: Tuple[int, float]):
+            size, inner_mm = size_and_diameter
+            return abs(Decimal(str(inner_mm)) - decision_mm), size
+    else:
+        def distance_key(size_and_diameter: Tuple[int, float]):
+            _, inner_mm = size_and_diameter
+            return abs(inner_mm - diameter_mm)
 
     # Find nearest size
-    best_size, best_inner = min(sorted_sizes, key=lambda x: abs(x[1] - diameter_mm))
+    # Session recommendations opt into a smaller-size exact-tie policy.
+    # Decimal distances keep binary-float noise from turning a mathematical
+    # tie into an upper-size result. Other callers retain the legacy lookup.
+    best_size, best_inner = min(sorted_sizes, key=distance_key)
 
     # Find second nearest size
     second_size, second_inner = min(
         (s for s in sorted_sizes if s[0] != best_size),
-        key=lambda x: abs(x[1] - diameter_mm),
+        key=distance_key,
     )
 
     range_min = min(best_size, second_size)

src/session_recommendation.py

@@ -0,0 +1,338 @@
+"""Session-level median recommendations for repeated web measurements.
+
+The computer-vision pipeline continues to produce one raw result per photo.
+This module accumulates the successful calibrated diameters returned by those
+results and derives a separate recommendation from their per-finger median.
+It is deliberately independent of Flask and Supabase so local/offline runs use
+the same logic as production.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import re
+import statistics
+import uuid
+from decimal import Decimal, ROUND_HALF_UP
+from typing import Any, Dict, Mapping, Optional, Tuple
+
+from src.ring_size import aggregate_ring_sizes, recommend_ring_size
+
+SESSION_STATE_VERSION = 1
+MAX_SESSION_SHOTS = 20
+MIN_STATE_DIAMETER_CM = 1.0
+MAX_STATE_DIAMETER_CM = 3.0
+
+FINGER_ORDER = ("index", "middle", "ring", "pinky")
+VALID_FINGERS = set(FINGER_ORDER)
+VALID_HANDEDNESS = {"Left", "Right", "Unknown"}
+_SHA256_RE = re.compile(r"^[0-9a-f]{64}$")
+
+
+def _size_decision_diameter_mm(median_cm: float) -> float:
+    """Quantize a session median to the supported 0.1 mm decision precision."""
+    median_mm = Decimal(str(median_cm)) * Decimal("10")
+    return float(median_mm.quantize(Decimal("0.1"), rounding=ROUND_HALF_UP))
+
+
+def image_sha256(data: bytes) -> str:
+    """Return a stable content fingerprint for duplicate-shot detection."""
+    return hashlib.sha256(data).hexdigest()
+
+
+def normalize_session_id(value: Any) -> Optional[str]:
+    """Return a canonical UUID string, or None for absent/malformed input."""
+    if not isinstance(value, str) or not value.strip():
+        return None
+    try:
+        return str(uuid.UUID(value.strip()))
+    except (ValueError, AttributeError):
+        return None
+
+
+def _empty_state(session_id: str, ring_model: str) -> Dict[str, Any]:
+    return {
+        "version": SESSION_STATE_VERSION,
+        "session_id": session_id,
+        "ring_model": ring_model,
+        "attempt_count": 0,
+        "shots": [],
+    }
+
+
+def _finite_diameter(value: Any) -> Optional[float]:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    diameter = float(value)
+    if not math.isfinite(diameter):
+        return None
+    if diameter < MIN_STATE_DIAMETER_CM or diameter > MAX_STATE_DIAMETER_CM:
+        return None
+    return round(diameter, 4)
+
+
+def _sanitize_state(
+    previous_state: Any,
+    *,
+    session_id: str,
+    ring_model: str,
+) -> Dict[str, Any]:
+    """Validate untrusted browser-returned state and enforce a small bound."""
+    fresh = _empty_state(session_id, ring_model)
+    if not isinstance(previous_state, Mapping):
+        return fresh
+    if previous_state.get("version") != SESSION_STATE_VERSION:
+        return fresh
+    if normalize_session_id(previous_state.get("session_id")) != session_id:
+        return fresh
+    if previous_state.get("ring_model") != ring_model:
+        return fresh
+
+    attempt_count = previous_state.get("attempt_count", 0)
+    if isinstance(attempt_count, bool) or not isinstance(attempt_count, int):
+        attempt_count = 0
+    fresh["attempt_count"] = max(0, min(attempt_count, 10_000))
+
+    raw_shots = previous_state.get("shots")
+    if not isinstance(raw_shots, list):
+        return fresh
+
+    shots = []
+    for raw_shot in raw_shots[-MAX_SESSION_SHOTS:]:
+        if not isinstance(raw_shot, Mapping):
+            continue
+        handedness = raw_shot.get("handedness")
+        if handedness not in VALID_HANDEDNESS:
+            continue
+        digest = raw_shot.get("image_sha256")
+        if not isinstance(digest, str) or not _SHA256_RE.fullmatch(digest):
+            continue
+        raw_per_finger = raw_shot.get("per_finger")
+        if not isinstance(raw_per_finger, Mapping):
+            continue
+        per_finger: Dict[str, float] = {}
+        for finger, value in raw_per_finger.items():
+            if finger not in VALID_FINGERS:
+                continue
+            diameter = _finite_diameter(value)
+            if diameter is not None:
+                per_finger[finger] = diameter
+        if not per_finger:
+            continue
+        shots.append({
+            "run_id": str(raw_shot.get("run_id") or "")[:64],
+            "image_sha256": digest,
+            "handedness": handedness,
+            "per_finger": per_finger,
+        })
+
+    fresh["shots"] = shots[-MAX_SESSION_SHOTS:]
+    return fresh
+
+
+def _result_handedness(result: Mapping[str, Any]) -> str:
+    handedness = result.get("handedness")
+    return handedness if handedness in VALID_HANDEDNESS else "Unknown"
+
+
+def _successful_current_samples(
+    result: Mapping[str, Any],
+    *,
+    mode: str,
+    finger_index: str,
+) -> Dict[str, float]:
+    samples: Dict[str, float] = {}
+    if mode == "multi":
+        per_finger = result.get("per_finger")
+        if not isinstance(per_finger, Mapping):
+            return samples
+        for finger in FINGER_ORDER:
+            item = per_finger.get(finger)
+            if not isinstance(item, Mapping) or item.get("status") != "ok":
+                continue
+            diameter = _finite_diameter(item.get("diameter_cm"))
+            if diameter is not None:
+                samples[finger] = diameter
+        return samples
+
+    if result.get("fail_reason") is not None:
+        return samples
+    finger = finger_index if finger_index in VALID_FINGERS else "index"
+    diameter = _finite_diameter(result.get("finger_outer_diameter_cm"))
+    if diameter is not None:
+        samples[finger] = diameter
+    return samples
+
+
+def _recommend_for_hand(
+    state: Mapping[str, Any],
+    *,
+    handedness: str,
+    ring_model: str,
+    current_result: Mapping[str, Any],
+    mode: str,
+    finger_index: str,
+    current_shot_included: bool,
+    duplicate_image: bool,
+) -> Optional[Dict[str, Any]]:
+    values: Dict[str, list] = {finger: [] for finger in FINGER_ORDER}
+    successful_shots = 0
+    for shot in state.get("shots", []):
+        if shot.get("handedness") != handedness:
+            continue
+        successful_shots += 1
+        for finger, diameter in shot.get("per_finger", {}).items():
+            if finger in values:
+                values[finger].append(float(diameter))
+
+    synthetic: Dict[str, Dict[str, Any]] = {}
+    stats: Dict[str, Dict[str, Any]] = {}
+    for finger in FINGER_ORDER:
+        finger_values = values[finger]
+        if not finger_values:
+            continue
+        # Inputs are stored to 4 decimal places in cm, so an even-sized median
+        # can contain one additional decimal place. Preserve that value for
+        # auditability, but quantize the value used for discrete size lookup to
+        # 0.1 mm. This avoids invisible hundredths of a millimetre flipping a
+        # recommendation while the UI displays the same one-decimal diameter.
+        median_cm = round(float(statistics.median(finger_values)), 5)
+        decision_diameter_mm = _size_decision_diameter_mm(median_cm)
+        spread_mm = round((max(finger_values) - min(finger_values)) * 10.0, 2)
+        ring_size = recommend_ring_size(
+            decision_diameter_mm / 10.0,
+            ring_model=ring_model,
+            prefer_smaller_on_tie=True,
+        )
+        synthetic[finger] = {
+            "finger_outer_diameter_cm": median_cm,
+            # Session confidence is intentionally not invented. Equal weights
+            # keep the legacy cross-finger aggregator deterministic without
+            # reusing the non-predictive per-shot confidence score.
+            "confidence": 1.0,
+            "ring_size": ring_size,
+            "fail_reason": None,
+        }
+        stats[finger] = {
+            "sample_count": len(finger_values),
+            "spread_mm": spread_mm,
+            "decision_diameter_mm": decision_diameter_mm,
+        }
+
+    if not synthetic:
+        return None
+
+    aggregated = aggregate_ring_sizes(synthetic)
+    per_finger = aggregated.get("per_finger", {})
+    for finger, finger_stats in stats.items():
+        if finger in per_finger:
+            # The equal weight above is only an internal tie-breaker for the
+            # legacy cross-finger aggregator, not a claim of 100% confidence.
+            per_finger[finger].pop("confidence", None)
+            per_finger[finger].update(finger_stats)
+
+    # Preserve a failed current-finger card when no earlier success exists,
+    # keeping first-shot rendering equivalent to the raw multi result.
+    if mode == "multi":
+        current_per_finger = current_result.get("per_finger")
+        if isinstance(current_per_finger, Mapping):
+            for finger in FINGER_ORDER:
+                current_item = current_per_finger.get(finger)
+                if finger not in per_finger and isinstance(current_item, Mapping):
+                    per_finger[finger] = dict(current_item)
+                    per_finger[finger]["sample_count"] = 0
+                    per_finger[finger]["spread_mm"] = None
+                    per_finger[finger]["decision_diameter_mm"] = None
+
+        aggregated["fingers_measured"] = len(per_finger)
+        aggregated["fingers_succeeded"] = sum(
+            item.get("status") == "ok" for item in per_finger.values()
+        )
+
+    recommendation: Dict[str, Any] = {
+        **aggregated,
+        "basis": "session_median",
+        "session_id": state["session_id"],
+        "attempt_index": state["attempt_count"],
+        "handedness": handedness,
+        "successful_shots": successful_shots,
+        "current_shot_included": current_shot_included,
+        "duplicate_image": duplicate_image,
+    }
+
+    if mode != "multi":
+        finger = finger_index if finger_index in VALID_FINGERS else "index"
+        finger_rec = per_finger.get(finger)
+        if finger_rec and finger_rec.get("status") == "ok":
+            recommendation["finger_index"] = finger
+            recommendation["finger_outer_diameter_cm"] = finger_rec["diameter_cm"]
+            recommendation["ring_size"] = synthetic[finger]["ring_size"]
+    return recommendation
+
+
+def update_session_recommendation(
+    previous_state: Any,
+    *,
+    session_id: str,
+    ring_model: str,
+    run_id: str,
+    image_digest: str,
+    result: Mapping[str, Any],
+    mode: str,
+    finger_index: str = "index",
+) -> Tuple[Dict[str, Any], Optional[Dict[str, Any]]]:
+    """Add one attempt and return `(updated_state, recommendation)`.
+
+    `result` must be the calibrated raw result for the current photo. The
+    returned recommendation is for the current detected hand only. A total
+    current-shot failure increments the attempt counter but returns no stale
+    recommendation to the UI.
+    """
+    canonical_id = normalize_session_id(session_id)
+    if canonical_id is None:
+        raise ValueError("session_id must be a valid UUID")
+    if not _SHA256_RE.fullmatch(image_digest or ""):
+        raise ValueError("image_digest must be a SHA-256 hex digest")
+
+    state = _sanitize_state(
+        previous_state,
+        session_id=canonical_id,
+        ring_model=ring_model,
+    )
+    state["attempt_count"] += 1
+
+    current_samples = _successful_current_samples(
+        result,
+        mode=mode,
+        finger_index=finger_index,
+    )
+    handedness = _result_handedness(result)
+    duplicate = any(
+        shot.get("image_sha256") == image_digest for shot in state["shots"]
+    )
+    included = bool(current_samples) and not duplicate
+    if included:
+        state["shots"].append({
+            "run_id": str(run_id or "")[:64],
+            "image_sha256": image_digest,
+            "handedness": handedness,
+            "per_finger": current_samples,
+        })
+        state["shots"] = state["shots"][-MAX_SESSION_SHOTS:]
+
+    # Do not surface an old recommendation on top of a total current failure.
+    if not current_samples:
+        return state, None
+
+    recommendation = _recommend_for_hand(
+        state,
+        handedness=handedness,
+        ring_model=ring_model,
+        current_result=result,
+        mode=mode,
+        finger_index=finger_index,
+        current_shot_included=included,
+        duplicate_image=duplicate,
+    )
+    return state, recommendation

tests/test_cli_output.py

@@ -0,0 +1,24 @@
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+import numpy as np
+
+from measure_finger import save_output
+
+
+class CliOutputTests(unittest.TestCase):
+    def test_save_output_normalizes_numpy_scalars_and_arrays(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            path = Path(tmp) / "result.json"
+            save_output(
+                {"scalar": np.float32(1.25), "array": np.array([1, 2], dtype=np.int32)},
+                str(path),
+            )
+            self.assertEqual(json.loads(path.read_text()), {"scalar": 1.25, "array": [1, 2]})
+
+
+if __name__ == "__main__":
+    unittest.main()
+

tests/test_measurement_session.js

@@ -0,0 +1,48 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const test = require("node:test");
+const vm = require("node:vm");
+
+const source = fs.readFileSync(
+  "web_demo/static/shared/measurement-session.js",
+  "utf8",
+);
+
+function loadHelper() {
+  const data = new Map();
+  let idCounter = 0;
+  const window = {
+    crypto: { randomUUID: () => `00000000-0000-4000-8000-${String(++idCounter).padStart(12, "0")}` },
+    sessionStorage: {
+      getItem: (key) => data.has(key) ? data.get(key) : null,
+      setItem: (key, value) => data.set(key, value),
+    },
+  };
+  vm.runInNewContext(source, { window, Date, JSON, Math, Number, String });
+  return window.MeasurementSession;
+}
+
+test("preserves returned state for an unchanged context", () => {
+  const helper = loadHelper();
+  const context = {
+    kol_email: "User@Example.com ", ring_model: "gen", mode: "multi",
+    finger_index: "index", source: "photo",
+  };
+  const first = helper.prepare(context);
+  const state = { session_id: first.session_id, attempt_count: 1, shots: [] };
+  helper.accept(context, { session_state: state });
+  assert.deepEqual(helper.prepare(context).session_state, state);
+});
+
+test("rotates the session when measurement context changes", () => {
+  const helper = loadHelper();
+  const base = {
+    kol_email: "user@example.com", ring_model: "gen", mode: "multi",
+    finger_index: "index", source: "photo",
+  };
+  const first = helper.prepare(base);
+  const second = helper.prepare({ ...base, ring_model: "air" });
+  assert.notEqual(second.session_id, first.session_id);
+  assert.equal(second.session_state, null);
+});
+

tests/test_session_evidence.js

@@ -0,0 +1,38 @@
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const test = require("node:test");
+const vm = require("node:vm");
+
+const source = fs.readFileSync(
+  "web_demo/static/shared/session-evidence.js",
+  "utf8",
+);
+
+function loadHelper() {
+  const window = {};
+  vm.runInNewContext(source, { window, Number, Object });
+  return window.SessionEvidence;
+}
+
+test("formats singular and recommended measurement guidance", () => {
+  const helper = loadHelper();
+  assert.equal(
+    helper.text({ successful_shots: 1 }),
+    "Based on 1 measurement. (Please measure at least 3 times for best reliability)",
+  );
+});
+
+test("uses the session shot count and keeps guidance after three", () => {
+  const helper = loadHelper();
+  assert.equal(
+    helper.text({ successful_shots: 3 }),
+    "Based on 3 measurements. (Please measure at least 3 times for best reliability)",
+  );
+});
+
+test("falls back to per-finger counts and hides empty evidence", () => {
+  const helper = loadHelper();
+  assert.equal(helper.text({ per_finger: { index: { sample_count: 2 } } }),
+    "Based on 2 measurements. (Please measure at least 3 times for best reliability)");
+  assert.equal(helper.text({ per_finger: {} }), "");
+});

tests/test_session_recommendation.py

@@ -0,0 +1,160 @@
+import unittest
+import uuid
+
+from src.session_recommendation import image_sha256, update_session_recommendation
+
+
+def multi_result(*, handedness="Right", index=1.80, middle=1.90, ring=1.70):
+    values = {"index": index, "middle": middle, "ring": ring}
+    per_finger = {}
+    for finger, value in values.items():
+        if value is None:
+            per_finger[finger] = {
+                "status": "failed",
+                "diameter_cm": None,
+                "best_match": None,
+                "range": None,
+                "fail_reason": "finger_isolation_failed",
+            }
+        else:
+            per_finger[finger] = {
+                "status": "ok",
+                "diameter_cm": value,
+                "best_match": 8,
+                "range": [7, 8],
+                "fail_reason": None,
+            }
+    return {
+        "fail_reason": None,
+        "handedness": handedness,
+        "per_finger": per_finger,
+        "fingers_measured": 3,
+        "fingers_succeeded": sum(v is not None for v in values.values()),
+    }
+
+
+class SessionRecommendationTests(unittest.TestCase):
+    def setUp(self):
+        self.session_id = str(uuid.uuid4())
+
+    def update(self, state, result, image, **kwargs):
+        return update_session_recommendation(
+            state,
+            session_id=self.session_id,
+            ring_model=kwargs.get("ring_model", "gen"),
+            run_id=kwargs.get("run_id", image),
+            image_digest=image_sha256(image.encode()),
+            result=result,
+            mode=kwargs.get("mode", "multi"),
+            finger_index=kwargs.get("finger_index", "index"),
+        )
+
+    def test_first_shot_matches_its_diameter(self):
+        state, rec = self.update(None, multi_result(index=1.80), "one")
+        self.assertEqual(state["attempt_count"], 1)
+        self.assertEqual(rec["per_finger"]["index"]["diameter_cm"], 1.80)
+        self.assertEqual(rec["per_finger"]["index"]["sample_count"], 1)
+
+    def test_even_and_odd_medians_are_computed_before_size_lookup(self):
+        state, _ = self.update(None, multi_result(index=1.70), "one")
+        state, rec = self.update(state, multi_result(index=1.90), "two")
+        self.assertEqual(rec["per_finger"]["index"]["diameter_cm"], 1.80)
+        self.assertEqual(rec["per_finger"]["index"]["sample_count"], 2)
+        state, rec = self.update(state, multi_result(index=1.80), "three")
+        self.assertEqual(rec["per_finger"]["index"]["diameter_cm"], 1.80)
+        self.assertEqual(rec["per_finger"]["index"]["sample_count"], 3)
+
+    def test_size_lookup_rounds_median_to_tenth_mm_and_prefers_smaller_tie(self):
+        state, _ = self.update(
+            None,
+            multi_result(index=1.7784),
+            "one",
+            ring_model="air",
+        )
+        _, rec = self.update(
+            state,
+            multi_result(index=1.7837),
+            "two",
+            ring_model="air",
+        )
+        index = rec["per_finger"]["index"]
+        self.assertEqual(index["diameter_cm"], 1.78105)
+        self.assertEqual(index["decision_diameter_mm"], 17.8)
+        self.assertEqual(index["best_match"], 7)
+
+    def test_nearby_medians_on_both_sides_share_the_same_air_decision(self):
+        _, above = self.update(
+            None,
+            multi_result(index=1.7807),
+            "above",
+            ring_model="air",
+        )
+        self.session_id = str(uuid.uuid4())
+        _, below = self.update(
+            None,
+            multi_result(index=1.7795),
+            "below",
+            ring_model="air",
+        )
+        for rec in (above, below):
+            index = rec["per_finger"]["index"]
+            self.assertEqual(index["decision_diameter_mm"], 17.8)
+            self.assertEqual(index["best_match"], 7)
+
+    def test_partial_failure_only_skips_that_finger(self):
+        state, rec = self.update(None, multi_result(index=1.80, middle=None), "one")
+        self.assertEqual(rec["per_finger"]["index"]["sample_count"], 1)
+        self.assertEqual(rec["per_finger"]["middle"]["status"], "failed")
+        self.assertEqual(rec["per_finger"]["middle"]["sample_count"], 0)
+
+    def test_duplicate_image_is_not_counted_twice(self):
+        state, _ = self.update(None, multi_result(index=1.80), "same")
+        state, rec = self.update(state, multi_result(index=1.80), "same")
+        self.assertEqual(state["attempt_count"], 2)
+        self.assertEqual(len(state["shots"]), 1)
+        self.assertTrue(rec["duplicate_image"])
+        self.assertEqual(rec["per_finger"]["index"]["sample_count"], 1)
+
+    def test_hands_are_partitioned(self):
+        state, _ = self.update(None, multi_result(handedness="Right", index=1.80), "right")
+        state, rec = self.update(state, multi_result(handedness="Left", index=2.00), "left")
+        self.assertEqual(rec["handedness"], "Left")
+        self.assertEqual(rec["per_finger"]["index"]["diameter_cm"], 2.00)
+        self.assertEqual(rec["per_finger"]["index"]["sample_count"], 1)
+
+    def test_total_failure_increments_attempt_without_stale_recommendation(self):
+        state, _ = self.update(None, multi_result(index=1.80), "one")
+        failed = {"fail_reason": "card_not_detected", "per_finger": {}}
+        state, rec = self.update(state, failed, "two")
+        self.assertEqual(state["attempt_count"], 2)
+        self.assertEqual(len(state["shots"]), 1)
+        self.assertIsNone(rec)
+
+    def test_single_mode_uses_same_aggregator(self):
+        first = {
+            "fail_reason": None,
+            "handedness": "Right",
+            "finger_outer_diameter_cm": 1.70,
+        }
+        second = {**first, "finger_outer_diameter_cm": 1.90}
+        state, _ = self.update(None, first, "one", mode="single")
+        _, rec = self.update(state, second, "two", mode="single")
+        self.assertEqual(rec["finger_outer_diameter_cm"], 1.80)
+        self.assertEqual(rec["per_finger"]["index"]["sample_count"], 2)
+
+    def test_mismatched_or_malformed_state_starts_fresh(self):
+        malformed = {
+            "version": 1,
+            "session_id": str(uuid.uuid4()),
+            "ring_model": "gen",
+            "attempt_count": 999,
+            "shots": [{"diameter_cm": "hacked"}],
+        }
+        state, rec = self.update(malformed, multi_result(index=1.80), "one")
+        self.assertEqual(state["attempt_count"], 1)
+        self.assertEqual(len(state["shots"]), 1)
+        self.assertEqual(rec["per_finger"]["index"]["sample_count"], 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_web_session_api.py

@@ -0,0 +1,120 @@
+import json
+import unittest
+import uuid
+from unittest.mock import patch
+
+from web_demo.app import app
+
+
+def raw_multi(index):
+    return {
+        "fail_reason": None,
+        "handedness": "Right",
+        "overall_best_size": 8,
+        "overall_range_min": 7,
+        "overall_range_max": 9,
+        "fingers_measured": 3,
+        "fingers_succeeded": 3,
+        "per_finger": {
+            "index": {
+                "status": "ok", "diameter_cm": index, "confidence": 0.61,
+                "best_match": 8, "range": [7, 8], "fail_reason": None,
+            },
+            "middle": {
+                "status": "ok", "diameter_cm": 1.90, "confidence": 0.62,
+                "best_match": 9, "range": [8, 9], "fail_reason": None,
+            },
+            "ring": {
+                "status": "ok", "diameter_cm": 1.70, "confidence": 0.60,
+                "best_match": 7, "range": [6, 7], "fail_reason": None,
+            },
+        },
+    }
+
+
+class WebSessionApiTests(unittest.TestCase):
+    def setUp(self):
+        app.config.update(TESTING=True)
+        self.client = app.test_client()
+        self.session_id = str(uuid.uuid4())
+
+    def post_default(self, state=None):
+        data = {
+            "kol_email": "user@example.com",
+            "ring_model": "gen",
+            "mode": "multi",
+            "session_id": self.session_id,
+        }
+        if state is not None:
+            data["session_state"] = json.dumps(state)
+        return self.client.post("/api/measure-default", data=data)
+
+    @patch("web_demo.app._save_json")
+    @patch("web_demo.app._persist_measurement_async")
+    @patch("web_demo.app.image_sha256", side_effect=["a" * 64, "b" * 64])
+    @patch("web_demo.app.measure_multi_finger")
+    def test_two_shots_return_median_and_persist_raw_plus_snapshot(
+        self, measure_mock, _hash_mock, persist_mock, _save_mock
+    ):
+        measure_mock.side_effect = [raw_multi(1.70), raw_multi(1.90)]
+
+        first_response = self.post_default()
+        self.assertEqual(first_response.status_code, 200)
+        first = first_response.get_json()
+        self.assertEqual(
+            first["session_recommendation"]["per_finger"]["index"]["diameter_cm"],
+            1.70,
+        )
+
+        second_response = self.post_default(first["session_state"])
+        self.assertEqual(second_response.status_code, 200)
+        second = second_response.get_json()
+        self.assertEqual(second["result"]["per_finger"]["index"]["diameter_cm"], 1.90)
+        self.assertEqual(
+            second["session_recommendation"]["per_finger"]["index"]["diameter_cm"],
+            1.80,
+        )
+        self.assertEqual(
+            second["session_recommendation"]["per_finger"]["index"]["sample_count"],
+            2,
+        )
+        self.assertEqual(
+            second["session_recommendation"]["per_finger"]["index"][
+                "decision_diameter_mm"
+            ],
+            18.0,
+        )
+
+        second_record = persist_mock.call_args_list[1].kwargs["record"]
+        self.assertEqual(second_record["per_finger"]["index"]["diameter_cm"], 1.90)
+        self.assertEqual(
+            second_record["session_recommendation"]["per_finger"]["index"]["diameter_cm"],
+            1.80,
+        )
+        self.assertEqual(
+            second_record["session_recommendation"]["per_finger"]["index"][
+                "decision_diameter_mm"
+            ],
+            18.0,
+        )
+        self.assertEqual(second_record["session_attempt_index"], 2)
+
+    @patch("web_demo.app._save_json")
+    @patch("web_demo.app._persist_measurement_async")
+    @patch("web_demo.app.measure_multi_finger", return_value=raw_multi(1.80))
+    def test_old_client_without_session_fields_keeps_single_shot_contract(
+        self, _measure_mock, _persist_mock, _save_mock
+    ):
+        response = self.client.post(
+            "/api/measure-default",
+            data={"kol_email": "user@example.com", "ring_model": "gen", "mode": "multi"},
+        )
+        self.assertEqual(response.status_code, 200)
+        body = response.get_json()
+        self.assertIsNone(body["session_state"])
+        self.assertIsNone(body["session_recommendation"])
+        self.assertEqual(body["result"]["per_finger"]["index"]["diameter_cm"], 1.80)
+
+
+if __name__ == "__main__":
+    unittest.main()

web_demo/app.py

@@ -33,6 +33,11 @@ from measure_finger import measure_finger, measure_multi_finger, apply_calibrati
 from src.logging_config import configure_logging
 from src.ring_size import recommend_ring_size, RING_MODELS, VALID_RING_MODELS, DEFAULT_RING_MODEL
 from src.ai_recommendation import ai_explain_recommendation
+from src.session_recommendation import (
+    image_sha256,
+    normalize_session_id,
+    update_session_recommendation,
+)
 from web_demo.supabase_client import (
     upload_file,
     upload_bytes,
@@ -90,6 +95,7 @@ _persist_executor = ThreadPoolExecutor(max_workers=2, thread_name_prefix="supa-p
 PHOTO_MAX_SIDE = 2048
 RESULT_MAX_SIDE = 1024
 STORE_JPEG_QUALITY = 80
+SESSION_STATE_MAX_BYTES = 50_000
 
 
 def _shrink_jpeg(image_path: Path, max_side: int) -> Optional[bytes]:
@@ -248,6 +254,25 @@ def _read_form_settings() -> Dict[str, Any]:
             except json.JSONDecodeError:
                 logger.warning("dropping malformed gate_telemetry payload")
 
+    # Session state is returned by this server and carried by the browser to
+    # the next measurement. It is still untrusted input: cap its size here and
+    # let src/session_recommendation.py validate every nested field.
+    session_state: Optional[Dict[str, Any]] = None
+    raw_session_state = request.form.get("session_state")
+    if raw_session_state:
+        if len(raw_session_state) > SESSION_STATE_MAX_BYTES:
+            logger.warning(
+                "dropping oversized session_state payload (%d bytes)",
+                len(raw_session_state),
+            )
+        else:
+            try:
+                parsed_state = json.loads(raw_session_state)
+                if isinstance(parsed_state, dict):
+                    session_state = parsed_state
+            except json.JSONDecodeError:
+                logger.warning("dropping malformed session_state payload")
+
     return {
         "finger_index": request.form.get("finger_index", "index"),
         "mode": request.form.get("mode", "single"),
@@ -258,9 +283,44 @@ def _read_form_settings() -> Dict[str, Any]:
         "ring_model": ring_model,
         "capture_method": capture_method,
         "gate_telemetry": gate_telemetry,
+        "session_id": normalize_session_id(request.form.get("session_id")),
+        "session_state": session_state,
     }
 
 
+def _apply_session_recommendation(
+    result: Dict[str, Any],
+    *,
+    session_id: Optional[str],
+    previous_state: Optional[Dict[str, Any]],
+    ring_model: str,
+    run_id: str,
+    image_digest: str,
+    mode: str,
+    finger_index: str = "index",
+) -> Tuple[Optional[Dict[str, Any]], Optional[Dict[str, Any]]]:
+    """Attach the median recommendation without changing raw shot fields."""
+    if session_id is None:
+        return None, None
+    try:
+        state, recommendation = update_session_recommendation(
+            previous_state,
+            session_id=session_id,
+            ring_model=ring_model,
+            run_id=run_id,
+            image_digest=image_digest,
+            result=result,
+            mode=mode,
+            finger_index=finger_index,
+        )
+    except (TypeError, ValueError) as exc:
+        logger.warning("session aggregation skipped for run %s: %s", run_id, exc)
+        return None, None
+    if recommendation is not None:
+        result["session_recommendation"] = recommendation
+    return state, recommendation
+
+
 # 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
@@ -338,6 +398,7 @@ def api_measure():
     upload_path = UPLOAD_DIR / upload_name
     upload_path.parent.mkdir(parents=True, exist_ok=True)
     file.save(upload_path)
+    image_digest = image_sha256(upload_path.read_bytes())
 
     image = cv2.imread(str(upload_path))
     if image is None:
@@ -354,6 +415,9 @@ def api_measure():
         upload_name=upload_name,
         base_name=base_name,
         run_id=run_id,
+        image_digest=image_digest,
+        session_id=settings["session_id"],
+        session_state=settings["session_state"],
     )
     if settings["mode"] == "multi":
         return _run_multi_measurement(**common_kwargs)
@@ -371,6 +435,7 @@ def api_measure_default():
 
     settings = _read_form_settings()
     base_name, run_id = _make_base_name(settings["kol_email"] or "sample")
+    image_digest = image_sha256(DEFAULT_SAMPLE_PATH.read_bytes())
 
     common_kwargs = dict(
         image=image,
@@ -381,6 +446,9 @@ def api_measure_default():
         gate_telemetry=settings["gate_telemetry"],
         base_name=base_name,
         run_id=run_id,
+        image_digest=image_digest,
+        session_id=settings["session_id"],
+        session_state=settings["session_state"],
     )
     if settings["mode"] == "multi":
         return _run_multi_measurement(**common_kwargs)
@@ -399,6 +467,9 @@ def _run_measurement(
     upload_name: str = "",
     base_name: str = "",
     run_id: str = "",
+    image_digest: str = "",
+    session_id: Optional[str] = None,
+    session_state: Optional[Dict[str, Any]] = None,
 ):
     result_png_name = f"{base_name}_result.png"
     result_png_path = RESULTS_DIR / result_png_name
@@ -429,6 +500,17 @@ def _run_measurement(
         result["gate_telemetry"] = gate_telemetry
     result = _numpy_safe(result)
 
+    updated_session_state, session_recommendation = _apply_session_recommendation(
+        result,
+        session_id=session_id,
+        previous_state=session_state,
+        ring_model=ring_model,
+        run_id=run_id,
+        image_digest=image_digest,
+        mode="single",
+        finger_index=finger_index,
+    )
+
     result_json_name = f"{base_name}_result.json"
     result_json_path = RESULTS_DIR / result_json_name
     _save_json(result_json_path, result)
@@ -440,6 +522,8 @@ def _run_measurement(
         "input_image_url": input_image_url,
         "result_json_url": f"/results/{result_json_name}",
         "run_id": run_id,
+        "session_state": updated_session_state,
+        "session_recommendation": session_recommendation,
     }
 
     # Persist to Supabase in the background — do not block the response on
@@ -465,6 +549,13 @@ def _run_measurement(
             "overall_range_max": ring_size.get("range_max"),
             "result_json": result,
             "fail_reason": result.get("fail_reason"),
+            "session_id": session_id,
+            "session_attempt_index": (
+                updated_session_state.get("attempt_count")
+                if updated_session_state else None
+            ),
+            "image_sha256": image_digest,
+            "session_recommendation": session_recommendation,
         },
     )
 
@@ -482,6 +573,9 @@ def _run_multi_measurement(
     upload_name: str = "",
     base_name: str = "",
     run_id: str = "",
+    image_digest: str = "",
+    session_id: Optional[str] = None,
+    session_state: Optional[Dict[str, Any]] = None,
 ):
     """Run multi-finger measurement pipeline."""
     result_png_name = f"{base_name}_result.png"
@@ -502,11 +596,23 @@ def _run_multi_measurement(
         result["gate_telemetry"] = gate_telemetry
     result = _numpy_safe(result)
 
+    updated_session_state, session_recommendation = _apply_session_recommendation(
+        result,
+        session_id=session_id,
+        previous_state=session_state,
+        ring_model=ring_model,
+        run_id=run_id,
+        image_digest=image_digest,
+        mode="multi",
+    )
+
     # Collect finger widths for AI recommendation
-    per_finger = result.get("per_finger", {})
+    recommendation_result = session_recommendation or result
+    recommendation_per_finger = recommendation_result.get("per_finger", {})
+    raw_per_finger = result.get("per_finger", {})
     finger_widths = {}
     for fn in ("index", "middle", "ring"):
-        pf = per_finger.get(fn, {})
+        pf = recommendation_per_finger.get(fn, {})
         if pf.get("status") == "ok" and pf.get("diameter_cm") is not None:
             finger_widths[fn] = pf["diameter_cm"]
         else:
@@ -514,12 +620,12 @@ def _run_multi_measurement(
 
     ai_reason = None
     ai_explain = request.form.get("ai_explain", "0") == "1"
-    if ai_explain and result.get("overall_best_size") is not None:
+    if ai_explain and recommendation_result.get("overall_best_size") is not None:
         ai_reason = ai_explain_recommendation(
             finger_widths,
-            recommended_size=result["overall_best_size"],
-            range_min=result["overall_range_min"],
-            range_max=result["overall_range_max"],
+            recommended_size=recommendation_result["overall_best_size"],
+            range_min=recommendation_result["overall_range_min"],
+            range_max=recommendation_result["overall_range_max"],
             ring_model=ring_model,
         )
     if ai_reason:
@@ -531,7 +637,7 @@ def _run_multi_measurement(
 
     # Compute overall confidence from per-finger data
     confidences = [
-        pf.get("confidence") for pf in per_finger.values()
+        pf.get("confidence") for pf in raw_per_finger.values()
         if pf.get("status") == "ok" and pf.get("confidence") is not None
     ]
     overall_confidence = min(confidences) if confidences else None
@@ -544,6 +650,8 @@ def _run_multi_measurement(
         "input_image_url": input_image_url,
         "result_json_url": f"/results/{result_json_name}",
         "run_id": run_id,
+        "session_state": updated_session_state,
+        "session_recommendation": session_recommendation,
     }
 
     # Persist to Supabase in the background.
@@ -561,10 +669,17 @@ def _run_multi_measurement(
             "overall_best_size": result.get("overall_best_size"),
             "overall_range_min": result.get("overall_range_min"),
             "overall_range_max": result.get("overall_range_max"),
-            "per_finger": per_finger,
+            "per_finger": raw_per_finger,
             "confidence": overall_confidence,
             "result_json": result,
             "fail_reason": result.get("fail_reason"),
+            "session_id": session_id,
+            "session_attempt_index": (
+                updated_session_state.get("attempt_count")
+                if updated_session_state else None
+            ),
+            "image_sha256": image_digest,
+            "session_recommendation": session_recommendation,
         },
     )
 
@@ -1071,10 +1186,20 @@ def api_admin_export_csv():
     output = io.StringIO()
     fieldnames = [
         "kol_email", "kol_name", "created_at", "mode", "ring_model",
+        "session_id", "session_attempt_index", "session_hand", "session_successful_shots",
         "overall_best_size", "overall_range_min", "overall_range_max",
         "index_size", "index_diameter", "index_confidence",
         "middle_size", "middle_diameter", "middle_confidence",
         "ring_size", "ring_diameter", "ring_confidence",
+        "session_index_size", "session_index_diameter",
+        "session_index_decision_mm", "session_index_samples",
+        "session_index_spread_mm",
+        "session_middle_size", "session_middle_diameter",
+        "session_middle_decision_mm", "session_middle_samples",
+        "session_middle_spread_mm",
+        "session_ring_size", "session_ring_diameter",
+        "session_ring_decision_mm", "session_ring_samples",
+        "session_ring_spread_mm",
         "confidence", "fail_reason", "ai_explanation",
         "ring_fit", "gt_best_finger", "gt_index_size", "gt_middle_size", "gt_ring_size", "gt_notes",
         "feedback_rating", "feedback_message",
@@ -1089,6 +1214,8 @@ def api_admin_export_csv():
             "created_at": row.get("created_at", ""),
             "mode": row.get("mode", ""),
             "ring_model": row.get("ring_model", ""),
+            "session_id": row.get("session_id", ""),
+            "session_attempt_index": row.get("session_attempt_index", ""),
             "overall_best_size": row.get("overall_best_size", ""),
             "overall_range_min": row.get("overall_range_min", ""),
             "overall_range_max": row.get("overall_range_max", ""),
@@ -1108,11 +1235,23 @@ def api_admin_export_csv():
             "id": row.get("id", ""),
         }
         pf = row.get("per_finger") or {}
+        session_rec = row.get("session_recommendation") or {}
+        session_pf = session_rec.get("per_finger") or {}
+        flat["session_hand"] = session_rec.get("handedness", "")
+        flat["session_successful_shots"] = session_rec.get("successful_shots", "")
         for finger in ("index", "middle", "ring"):
             fd = pf.get(finger, {})
             flat[f"{finger}_size"] = fd.get("best_match", "")
             flat[f"{finger}_diameter"] = fd.get("diameter_cm", "")
             flat[f"{finger}_confidence"] = fd.get("confidence", "")
+            session_fd = session_pf.get(finger, {})
+            flat[f"session_{finger}_size"] = session_fd.get("best_match", "")
+            flat[f"session_{finger}_diameter"] = session_fd.get("diameter_cm", "")
+            flat[f"session_{finger}_decision_mm"] = session_fd.get(
+                "decision_diameter_mm", ""
+            )
+            flat[f"session_{finger}_samples"] = session_fd.get("sample_count", "")
+            flat[f"session_{finger}_spread_mm"] = session_fd.get("spread_mm", "")
         writer.writerow(flat)
 
     return Response(

web_demo/static/app.js

@@ -189,7 +189,10 @@ const renderMultiResult = (result) => {
     html += `</div>`;
   }
   html += "</div>";
-  html += `<div class="finger-count">${result.fingers_succeeded}/${result.fingers_measured} fingers measured</div>`;
+  const evidenceText = window.SessionEvidence.text(result);
+  if (evidenceText) {
+    html += `<div class="finger-count">${evidenceText}</div>`;
+  }
   html += buildSizeRefTable();
 
   fingerBreakdown.innerHTML = html;
@@ -215,6 +218,10 @@ const renderSingleResult = (result) => {
   const fingerSelect = form.querySelector('[name="finger_index"]');
   const fingerName = fingerSelect ? fingerSelect.value : "finger";
   const capitalName = fingerName.charAt(0).toUpperCase() + fingerName.slice(1);
+  const evidenceText = window.SessionEvidence.text(result);
+  const evidence = evidenceText
+    ? `<div class="finger-count">${evidenceText}</div>`
+    : "";
   fingerBreakdown.innerHTML = `<div class="finger-cards">
     <div class="finger-card" style="border-top: 3px solid #00dddd;">
       <div class="finger-name">${capitalName}</div>
@@ -223,10 +230,10 @@ const renderSingleResult = (result) => {
       <div class="finger-range">${rs.range_min} – ${rs.range_max}</div>
       <div class="finger-width">${diamMm} mm</div>
     </div>
-  </div>` + buildSizeRefTable();
+  </div>${evidence}` + buildSizeRefTable();
 };
 
-const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
+const runMeasurement = async (endpoint, formData, inputUrlFallback = "", sessionContext = null) => {
   const startedAt = Date.now();
   const renderElapsed = () => {
     const secs = Math.floor((Date.now() - startedAt) / 1000);
@@ -258,6 +265,9 @@ const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
     }
 
     const data = await response.json();
+    if (sessionContext && window.MeasurementSession) {
+      window.MeasurementSession.accept(sessionContext, data);
+    }
     lastRunId = data.run_id || "";
     if (feedbackSection) {
       if (data.success && lastRunId) {
@@ -273,10 +283,11 @@ const runMeasurement = async (endpoint, formData, inputUrlFallback = "") => {
     showImage(inputPreview, inputFrame, data.input_image_url || inputUrlFallback);
     showImage(debugPreview, debugFrame, data.result_image_url);
 
+    const recommendation = data.session_recommendation || data.result;
     if (data.mode === "multi") {
-      renderMultiResult(data.result);
+      renderMultiResult(recommendation);
     } else {
-      renderSingleResult(data.result);
+      renderSingleResult(recommendation);
     }
 
     if (data.success) {
@@ -335,13 +346,26 @@ form.addEventListener("submit", async (event) => {
   formData.append("kol_email", settings.kol_email);
 
   const file = imageInput.files[0];
+  const sessionContext = {
+    kol_email: settings.kol_email,
+    ring_model: settings.ring_model,
+    mode: settings.mode,
+    finger_index: settings.finger_index,
+    source: file ? "photo" : "sample",
+  };
+  const measurementSession = window.MeasurementSession.prepare(sessionContext);
+  formData.append("session_id", measurementSession.session_id);
+  if (measurementSession.session_state) {
+    formData.append("session_state", JSON.stringify(measurementSession.session_state));
+  }
+
   if (file) {
     formData.append("image", file);
-    await runMeasurement("/api/measure", formData);
+    await runMeasurement("/api/measure", formData, "", sessionContext);
     return;
   }
 
-  await runMeasurement("/api/measure-default", formData, defaultSampleUrl);
+  await runMeasurement("/api/measure-default", formData, defaultSampleUrl, sessionContext);
 });
 
 if (defaultSampleUrl) {

web_demo/static/mobile/steps/confirm.js

@@ -92,14 +92,25 @@ export default {
       elapsedTimer = setInterval(renderTimer, 1000);
 
       try {
+        const sessionContext = {
+          kol_email: session.kolEmail,
+          ring_model: session.ringModel,
+          mode: "multi",
+          finger_index: "index",
+          source: "photo",
+        };
+        const measurementSession = window.MeasurementSession.prepare(sessionContext);
         const result = await postMeasure({
           blob: session.imageBlob,
           kol_email: session.kolEmail,
           ring_model: session.ringModel,
           gate_telemetry: session.gateTelemetry,
           capture_method: session.imageSource === "camera" ? "camera" : "upload",
+          session_id: measurementSession.session_id,
+          session_state: measurementSession.session_state,
         });
         clearTimerFn();
+        window.MeasurementSession.accept(sessionContext, result);
         session.result = result;
         nav.next();
       } catch (err) {

web_demo/static/mobile/steps/result.js

@@ -91,14 +91,13 @@ function renderRecommendation(payload, ringModel) {
     if (!pf) continue;
     cards += fingerCardHtml(fn, pf);
   }
-  const succeeded = (payload && payload.fingers_succeeded) ?? 0;
-  const total = (payload && payload.fingers_measured) ?? 0;
-  // Count below the cards so it reads as a footnote/summary on mobile;
-  // the cards themselves are large enough to communicate that this is
-  // a per-finger breakdown without a leading label.
+  const evidenceText = window.SessionEvidence.text(payload);
+  // Session evidence replaces the old "N/N fingers measured" footer. Failed
+  // fingers remain explicit in their own cards, while this line explains the
+  // strength of the recommendation and the target number of repeat captures.
   return `
     ${cards ? `<div class="finger-cards">${cards}</div>` : ""}
-    <div class="finger-count">${escape(`${succeeded}/${total} fingers measured`)}</div>
+    ${evidenceText ? `<div class="finger-count">${escape(evidenceText)}</div>` : ""}
     ${buildSizeRefTable(ringModel)}
   `;
 }
@@ -112,6 +111,7 @@ export default {
       return;
     }
     const payload = data.result || data;
+    const recommendation = data.session_recommendation || payload;
     const overlayUrl = data.result_image_url;
     const ringModel = session.ringModel || "gen";
 
@@ -174,13 +174,13 @@ export default {
         <div class="step-body">
           ${statusBanner}
           <div class="panel">
-            <h2 class="panel-title">Result Overlay</h2>
+            <h2 class="panel-title">Current Photo Overlay</h2>
             <div class="image-frame show">${overlayInner}</div>
           </div>
 
           <div class="panel">
             <h2 class="panel-title">Ring Size Recommendation</h2>
-            ${renderRecommendation(payload, ringModel)}
+            ${renderRecommendation(recommendation, ringModel)}
           </div>
 
           ${feedbackPanel}

web_demo/static/shared/measure-api.js

@@ -22,6 +22,8 @@ export async function postMeasure({
   blob,
   kol_email,
   gate_telemetry = null,
+  session_id = null,
+  session_state = null,
   ...overrides
 } = {}) {
   if (!blob) throw new Error("postMeasure: blob is required");
@@ -37,6 +39,12 @@ export async function postMeasure({
   formData.append("ring_model", settings.ring_model);
   formData.append("ai_explain", settings.ai_explain);
   formData.append("capture_method", settings.capture_method);
+  if (session_id) {
+    formData.append("session_id", session_id);
+  }
+  if (session_state) {
+    formData.append("session_state", JSON.stringify(session_state));
+  }
   if (gate_telemetry) {
     formData.append("gate_telemetry", JSON.stringify(gate_telemetry));
   }

web_demo/static/shared/measurement-session.js

@@ -0,0 +1,94 @@
+// Browser transport for v10 multi-shot measurement sessions.
+//
+// Python owns all measurement aggregation and ring-size decisions. This
+// helper only keeps the last server-returned state in sessionStorage and sends
+// it back with the next photo. State is per-tab, survives a refresh, and is
+// rotated when the measurement context changes or sits idle for 30 minutes.
+
+(function attachMeasurementSession(global) {
+  "use strict";
+
+  const STORAGE_KEY = "ring-sizer-measurement-session-v1";
+  const IDLE_TIMEOUT_MS = 30 * 60 * 1000;
+  let memoryRecord = null;
+
+  function newId() {
+    if (global.crypto && typeof global.crypto.randomUUID === "function") {
+      return global.crypto.randomUUID();
+    }
+    // RFC 4122 v4 fallback for older embedded browsers.
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+      const r = Math.floor(Math.random() * 16);
+      const v = c === "x" ? r : (r & 0x3) | 0x8;
+      return v.toString(16);
+    });
+  }
+
+  function contextKey(context) {
+    const normalized = {
+      kol_email: String(context && context.kol_email || "").trim().toLowerCase(),
+      ring_model: String(context && context.ring_model || "gen"),
+      mode: String(context && context.mode || "multi"),
+      finger_index: String(context && context.finger_index || "index"),
+      source: String(context && context.source || "photo"),
+    };
+    return JSON.stringify(normalized);
+  }
+
+  function load() {
+    try {
+      const raw = global.sessionStorage.getItem(STORAGE_KEY);
+      return raw ? JSON.parse(raw) : null;
+    } catch (_err) {
+      return memoryRecord;
+    }
+  }
+
+  function save(record) {
+    memoryRecord = record;
+    try {
+      global.sessionStorage.setItem(STORAGE_KEY, JSON.stringify(record));
+    } catch (_err) {
+      // Private browsing / embedded webviews may reject storage. The in-memory
+      // record still preserves the session for this page lifetime.
+    }
+  }
+
+  function prepare(context) {
+    const key = contextKey(context);
+    const now = Date.now();
+    let record = load();
+    const expired = !record || !Number.isFinite(record.updated_at)
+      || now - record.updated_at > IDLE_TIMEOUT_MS;
+    if (expired || record.context_key !== key || !record.session_id) {
+      record = {
+        context_key: key,
+        session_id: newId(),
+        session_state: null,
+        updated_at: now,
+      };
+      save(record);
+    }
+    return {
+      session_id: record.session_id,
+      session_state: record.session_state,
+    };
+  }
+
+  function accept(context, response) {
+    const prepared = prepare(context);
+    const returnedState = response && response.session_state;
+    if (!returnedState || returnedState.session_id !== prepared.session_id) {
+      return;
+    }
+    save({
+      context_key: contextKey(context),
+      session_id: prepared.session_id,
+      session_state: returnedState,
+      updated_at: Date.now(),
+    });
+  }
+
+  global.MeasurementSession = { prepare, accept };
+})(window);
+

web_demo/static/shared/session-evidence.js

@@ -0,0 +1,31 @@
+// Shared result-footer copy for multi-shot recommendations.
+// Kept separate from the renderers so desktop and mobile always make the
+// same claim about how many measurements support the recommendation.
+
+(function attachSessionEvidence(global) {
+  "use strict";
+
+  function measurementCount(payload) {
+    const successfulShots = Number(payload && payload.successful_shots);
+    if (Number.isInteger(successfulShots) && successfulShots > 0) {
+      return successfulShots;
+    }
+
+    const perFinger = payload && payload.per_finger;
+    if (!perFinger || typeof perFinger !== "object") return 0;
+    const counts = Object.values(perFinger)
+      .map((finger) => Number(finger && finger.sample_count))
+      .filter((count) => Number.isInteger(count) && count > 0);
+    return counts.length ? Math.max(...counts) : 0;
+  }
+
+  function text(payload) {
+    const count = measurementCount(payload);
+    if (!count) return "";
+    const noun = count === 1 ? "measurement" : "measurements";
+    return `Based on ${count} ${noun}. (Please measure at least 3 times for best reliability)`;
+  }
+
+  global.SessionEvidence = { measurementCount, text };
+})(window);
+

web_demo/templates/index.html

@@ -102,7 +102,7 @@
       </div>
 
       <div class="panel">
-        <h2>Result Overlay</h2>
+        <h2>Current Photo Overlay</h2>
         <div class="image-frame" id="debugFrame">
           <img id="debugPreview" alt="" />
           <p class="placeholder">Waiting for result</p>
@@ -165,6 +165,8 @@
   </footer>
 
   <script>window.DEFAULT_SAMPLE_URL = "{{ default_sample_url }}";</script>
+  <script src="/static/shared/measurement-session.js"></script>
+  <script src="/static/shared/session-evidence.js"></script>
   <script src="/static/app.js"></script>
 </body>
 </html>

web_demo/templates/mobile.html

@@ -30,6 +30,8 @@
   <script src="/static/preview/thresholds.js"></script>
   <script src="/static/preview/preview.js"></script>
   <script src="/static/preview/orientation.js"></script>
+  <script src="/static/shared/measurement-session.js"></script>
+  <script src="/static/shared/session-evidence.js"></script>
   <script type="module" src="/static/preview/hands.js"></script>
 
   <script type="module" src="/static/mobile/mobile.js"></script>