feat(fe): always-on spin+power hero on shot detail

A player reads two things: what spin and how hard. The widget carrying
both waited for a replay, so the page opened on debug numbers instead.
It now leads the page whenever the shot has a shotnet block, with a
plain-English gloss and a POWER_TIERS label beside the m/s figure.
Gate: pytest 160 passed + 7 skipped, 3 runs; demo 14 shots checked by
hand (hero, caveat, downgrade badge, suspect box, mobile quickbar).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

app/static/app.js

@@ -289,6 +289,25 @@ const AND_RESIM_DEFAULT_ON = false;
 // trusted range is [1, 8] m/s, hence a ceiling of 8.0.
 const AND_V0_MIN = 0.5, AND_V0_MAX = 8.0;
 
+// How hard the shot was, in words: soft < 2.5 <= medium <= 4.5 < hard, on
+// the model's CUE V0 in m/s. These are DISPLAY LABELS ONLY -- the m/s
+// number is always printed beside the tier, so nothing is lost by rounding
+// a shot into a word. The thresholds sit inside the trusted band
+// AND_V0_MIN..AND_V0_MAX above and are meant to be re-tuned once there is a
+// feel for real footage; this table is the single place to do it.
+const POWER_TIERS = [
+  { max: 2.5, inclusive: false, label: "soft" },
+  { max: 4.5, inclusive: true, label: "medium" },
+  { max: Infinity, inclusive: true, label: "hard" },
+];
+
+/** The power tier of a cue V0 in m/s. */
+function powerTier(v0Cue) {
+  const t = POWER_TIERS.find(
+    (x) => (x.inclusive ? v0Cue <= x.max : v0Cue < x.max));
+  return (t || POWER_TIERS[POWER_TIERS.length - 1]).label;
+}
+
 const ANV = {
   videoId: null,
   timer: null,
@@ -944,6 +963,24 @@ const fmtTs = (s) => (s === null || s === undefined ? "—"
 
 const CONF_LABEL = { low: "low", medium: "medium", high: "high" };
 
+/** Write the confidence badge into `el` -- the shot list cell and the
+    detail hero share this one builder, so the two places cannot drift.
+
+    The rank shown is the DISPLAYED one, which has already passed the
+    detection-density valve. When the valve downgraded it, the badge keeps
+    the ↓ marker and says what by: a rank that drops without explanation
+    reads as "the model is bad". */
+function fillConfBadge(el, sn) {
+  el.className = `anv-badge anv-badge-${sn.confidence}`;
+  el.textContent = CONF_LABEL[sn.confidence] || sn.confidence;
+  el.removeAttribute("title");
+  if (sn.confidence_raw && sn.confidence_raw !== sn.confidence) {
+    el.title = `downgraded from ${CONF_LABEL[sn.confidence_raw]} -- `
+      + `detection density ${(sn.det_density || 0).toFixed(2)}/frame`;
+    el.textContent += " ↓";
+  }
+}
+
 /** The shot table, filling in GRADUALLY. Numbers are shown exactly as the
     server sent them; V0, phi and spin prefer the model column, falling back
     to the analytic one labelled "bi" (ball) because they are different
@@ -1049,14 +1086,7 @@ function renderAnvShots(body) {
       } else if (i === 5) {                 // the confidence badge
         if (sn) {
           const b = document.createElement("span");
-          b.className = `anv-badge anv-badge-${sn.confidence}`;
-          b.textContent = CONF_LABEL[sn.confidence] || sn.confidence;
-          if (sn.confidence_raw && sn.confidence_raw !== sn.confidence) {
-            b.title = `downgraded from ${CONF_LABEL[sn.confidence_raw]} -- `
-              + `detection density `
-              + `${(sn.det_density || 0).toFixed(2)}/frame`;
-            b.textContent += " ↓";
-          }
+          fillConfBadge(b, sn);
           td.appendChild(b);
         } else {
           td.textContent = s.spin_confidence
@@ -1213,8 +1243,8 @@ function renderAnvDetail() {
   const warn = $("#and-warnings");
   const line = $("#and-resim");
   const btn = $("#and-replay");
-  $("#and-shotviz").classList.add("hidden");  // shown once replay starts
   if (!res.metrics) {
+    hideAndHero();
     tbl.innerHTML = "";
     warn.innerHTML = "";
     line.classList.add("hidden");
@@ -1230,7 +1260,10 @@ function renderAnvDetail() {
     syncQbAnalyzer();
     return;
   }
+  fillAndHero(res);
   const hasSn = fillAnMetrics(tbl, res, { flags: true });
+  // ruled 1 of the schema docstring: model numbers on screen ALWAYS carry
+  // the sim-only caveat, which now sits directly under the hero
   $("#and-caveat").classList.toggle("hidden", !hasSn);
   fillAnWarnings(warn, res);
 
@@ -1310,8 +1343,11 @@ function fillAndShotviz(sn) {
     dot.setAttribute("cx", 50 - sn.a * 46);
     dot.setAttribute("cy", 50 - sn.b * 46);
   }
+  // the tier first, because it is the part a player reads; the m/s
+  // number rides along so the word never hides a measurement, and "(cue)"
+  // keeps it apart from the analytic BALL speed
   $("#and-power-val").textContent =
-    `${sn.v0_cue_mps.toFixed(2)} m/s (cue V0)`;
+    `${powerTier(sn.v0_cue_mps)} -- ${sn.v0_cue_mps.toFixed(2)} m/s (cue)`;
   $("#and-spin-cap").textContent =
     `${sn.spin_vert} + ${sn.spin_side} (a=${sn.a.toFixed(2)}, `
     + `b=${sn.b.toFixed(2)})`;
@@ -1320,6 +1356,60 @@ function fillAndShotviz(sn) {
   return true;
 }
 
+// The plain-English gloss under the big spin label. It is derived from the
+// SAME two class fields the label uses, never from raw a/b, so the sentence
+// can never contradict the label above it.
+const SPIN_VERT_WORDS = {
+  follow: "hit above centre",
+  stun: "hit at centre height",
+  draw: "hit below centre",
+};
+const SPIN_SIDE_WORDS = { "side-L": "left side", "side-R": "right side" };
+
+/** The big spin label, in the SYSTEM vocabulary (follow/stun/draw +
+    side-L/side-R) so the headline and the numbers table say the same
+    words. */
+const spinLabel = (sn) => sn.spin_vert.charAt(0).toUpperCase()
+  + `${sn.spin_vert.slice(1)} + ${sn.spin_side}`;
+
+const spinExplain = (sn) =>
+  `${SPIN_VERT_WORDS[sn.spin_vert] || sn.spin_vert}, `
+  + `${SPIN_SIDE_WORDS[sn.spin_side] || sn.spin_side}`;
+
+/** The hero at the top of the detail page: WHAT SPIN and HOW HARD, the two
+    things the player came for. It is on as soon as the page opens whenever
+    the shot has a `shotnet` block -- the widget used to wait for a replay,
+    which buried the headline.
+
+    Without a model block it says so in one line and falls back to the
+    coarse analytic spin baseline, rather than inventing numbers. */
+function fillAndHero(res) {
+  const sn = (res || {}).shotnet || null;
+  const none = $("#and-noshotnet");
+  $("#and-shotviz").classList.toggle("hidden", !sn);
+  none.classList.toggle("hidden", Boolean(sn));
+  if (sn) {
+    fillAndShotviz(sn);
+    $("#and-spin-label").textContent = spinLabel(sn);
+    $("#and-spin-explain").textContent = spinExplain(sn);
+    fillConfBadge($("#and-conf"), sn);
+    return;
+  }
+  none.textContent = "No model prediction for this shot."
+    + (res.spin_class
+      ? ` Analytic spin baseline: ${res.spin_class}`
+        + (res.spin_confidence ? ` (confidence: ${res.spin_confidence})` : "")
+        + "."
+      : "");
+}
+
+/** A shot whose JSON carries no numbers at all (an error result): there is
+    no headline to show, and the reason is printed with the warnings. */
+function hideAndHero() {
+  $("#and-shotviz").classList.add("hidden");
+  $("#and-noshotnet").classList.add("hidden");
+}
+
 /** The Analyzer's quickbar row -- the mobile version of the replay widget:
     shown while a shot is open, hidden on the list screen.
 
@@ -1366,9 +1456,8 @@ async function anvReplay() {
   closeSheet();
   const k = S.table.w / res.metrics.table_w_m;
   const pts = smoothTrack(res.track).map((p) => [p.x * k, p.y * k]);
-  if (fillAndShotviz(res.shotnet)) {
-    $("#and-shotviz").classList.remove("hidden");
-  }
+  // the spin/power widget is the page hero now and is already on screen --
+  // the replay no longer has to reveal it
   // disable it BY HAND rather than through syncQbAnalyzer: `S.animating`
   // only becomes true INSIDE animateShot, so a sync call here would read
   // false and leave the button live

app/static/index.html

@@ -89,24 +89,18 @@
             <a id="and-download" class="btn-mini and-link hidden">⬇ Download mp4</a>
           </div>
           <h3 id="and-title"></h3>
-          <video id="and-video" class="and-video hidden" controls playsinline></video>
-          <div id="and-video-missing" class="an-note hidden">This shot has
-            no overlay.mp4 yet -- the result comes from a run before A2 (the
-            clip is deleted, so it cannot be rendered retroactively), or the
-            render failed (see the warnings).</div>
-          <!-- The replay animates the OBSERVED trajectory, so the real
-               shot comes back to life and is right regardless of the
-               model. -->
-          <button id="and-replay" class="an-cta" disabled>▶ Replay the shot (observed path)</button>
-          <!-- The shot-info widget shown during a replay: the cue ball with
-               its contact dot (a/b) plus the V0 power bar. It reuses the
-               STYLE-ONLY markup and CSS (.viz*) of the older #shotviz, but
-               its interactive ids and classes are its own
-               (.and-spin-dot / .and-power-bar) because .spin-dot/.power-bar
-               were swept globally by the earlier initialisers. The numbers
-               come from the SHOTNET set (the analytic path has no a/b) and
-               the set is named in the label. -->
-          <div id="and-shotviz" class="viz hidden">
+          <!-- The HERO of the page: what spin and how hard, the two numbers
+               a player actually reads. It is on from the moment the page
+               opens whenever the shot carries a `shotnet` block -- it used
+               to appear only during a replay, which buried the headline
+               under the debug numbers. It keeps the STYLE-ONLY markup and
+               CSS (.viz*) of the older #shotviz, but its interactive ids
+               and classes are its own (.and-spin-dot / .and-power-bar)
+               because .spin-dot/.power-bar were swept globally by the
+               earlier initialisers. The numbers come from the SHOTNET set
+               (the analytic path has no a/b) and the set is named in the
+               label. -->
+          <div id="and-shotviz" class="viz and-hero hidden">
             <div class="viz-spin">
               <svg id="and-spin-ball" viewBox="0 0 100 100" aria-label="cue-ball contact point (model)">
                 <defs>
@@ -123,12 +117,37 @@
               <div class="viz-cap" id="and-spin-cap"></div>
             </div>
             <div class="viz-power">
+              <!-- The confidence badge borrows the STYLE-ONLY .anv-badge
+                   classes of the shot list (nothing binds events to them).
+                   It shows the DISPLAYED rank, which has already been
+                   through the detection-density valve, and keeps the same
+                   downgrade marker the list row uses. -->
+              <div class="and-hero-head">
+                <div id="and-spin-label" class="and-hero-spin"></div>
+                <span id="and-conf" class="anv-badge"></span>
+              </div>
+              <div id="and-spin-explain" class="and-hero-sub"></div>
               <div class="viz-lbl">Power <b id="and-power-val"></b></div>
               <div id="and-power-bar" class="and-power-bar"></div>
               <div class="viz-scale"><span>0.5</span><span>m/s</span><span>8.0</span></div>
               <div class="viz-cap" id="and-viz-label"></div>
             </div>
           </div>
+          <!-- No model block: say so in one line and fall back to the coarse
+               analytic spin baseline, rather than inventing a number. -->
+          <div id="and-noshotnet" class="an-note hidden"></div>
+          <div id="and-caveat" class="an-caveat hidden">The model is
+            trained purely on simulation (P2) and has not been tuned on real
+            footage.</div>
+          <video id="and-video" class="and-video hidden" controls playsinline></video>
+          <div id="and-video-missing" class="an-note hidden">This shot has
+            no overlay.mp4 yet -- the result comes from a run before A2 (the
+            clip is deleted, so it cannot be rendered retroactively), or the
+            render failed (see the warnings).</div>
+          <!-- The replay animates the OBSERVED trajectory, so the real
+               shot comes back to life and is right regardless of the
+               model. -->
+          <button id="and-replay" class="an-cta" disabled>▶ Replay the shot (observed path)</button>
           <div id="and-suspect" class="an-warn hidden"></div>
           <!-- The re-simulation layer is a toggle, DEFAULTING OFF (the
                observed path and the re-simulation currently disagree on the
@@ -141,9 +160,6 @@
           <div id="and-resim" class="an-note hidden"></div>
           <div id="and-warnings"></div>
           <table id="and-metrics" class="an-metrics"></table>
-          <div id="and-caveat" class="an-caveat hidden">The model is
-            trained purely on simulation (P2) and has not been tuned on real
-            footage.</div>
           <div class="an-note">The table on the left: a <b>solid line
             coloured by time</b> is the observed track; balls carry the
             number and colour from BallID when the result has them (older

app/static/style.css

@@ -154,7 +154,7 @@ main {
 /* The replay widget on the detail page: it looks EXACTLY like the older
    #shotviz but carries its OWN interactive classes, because .power-bar and
    .spin-dot were swept globally by the suggestion tab's initialisers. */
-#and-spin-ball { width: 88px; height: 88px; display: block; margin: 0 auto; }
+#and-spin-ball { width: 104px; height: 104px; display: block; margin: 0 auto; }
 .and-spin-dot { transition: cx .25s ease, cy .25s ease; }
 .and-power-bar { display: flex; gap: 4px; }
 .and-power-bar .seg {
@@ -165,6 +165,25 @@ main {
   transition: background .2s;
 }
 #and-shotviz { margin-top: 10px; }
+/* The hero at the top of the detail page: the spin label is the headline of
+   the whole page, so it reads at heading size with the plain sentence and
+   the power line stepping down from it. */
+.and-hero-head {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  flex-wrap: wrap;
+}
+.and-hero-spin {
+  font-size: 19px;
+  font-weight: 700;
+  letter-spacing: .2px;
+}
+.and-hero-sub {
+  color: var(--muted);
+  font-size: 12.5px;
+  margin: 3px 0 10px;
+}
 .and-toggle {
   display: flex;
   align-items: center;