Fix a real OpenCV.js readiness race hanging the seeded demo

cv.onRuntimeInitialized (the callback OpenCV.js is supposed to call once
its WASM runtime is ready) could silently never fire, even though OpenCV
was actually fully loaded and usable underneath - confirmed live: cv.Mat
existed and worked while the app sat frozen on "Loading OpenCV.js..."
for 400+ seconds, with nothing else watching for real readiness. Every
path that awaits cvReadyPromise (Compute Background, the seeded demo's
skip-to-results restore, resume) hung at that exact point - "the seeded
demo just loads like usual, need to retrack everything" was this same
hang, not a regression in the restore logic itself.

Fixed with a polling fallback alongside the callback: every 250ms, does
a real `new cv.Mat().delete()` call (proof OpenCV actually answers, not
just that the property exists) - whichever signal fires first wins,
idempotent so neither path double-fires. Root cause not fully pinned to
one line in OpenCV.js's own bootstrapping (looks like a build/timing
quirk in this exact pinned version), so the fix doesn't depend on
diagnosing that exactly. Verified locally end to end: a full seeded-demo
run now correctly restores all 24 real overrides and completes with
"tracking skipped, everything else recomputed fresh."

Also this pass: the events-table legend's Poke/Entry swatches were
showing the Raster tab's bold solid colors, not the pale/white colors
this specific table actually uses (an earlier readability override) -
legend now matches what the table really shows. Logged the fixed-size
tracking crosshair/X as a real, deliberately-deferred polish item in
KNOWN_LIMITATIONS.md, found during a full dry run through all three
clips.

85/85 tests passing.

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

Author: sschabacker

KNOWN_LIMITATIONS.md

@@ -43,6 +43,16 @@
 
 ## Deliberately out of scope
 <!-- things I chose not to build, and why -->
+- The green crosshair/red X drawn on the frame viewer to show a tracked/
+  failed frame (`drawTrackOverlay` in `app.js`) is a fixed size and shape
+  regardless of the video's own resolution or the mouse's actual size in
+  frame - on some clips it may read as larger or a different shape than
+  feels right next to the animal. Noted from watching it during a full
+  dry run through all three clips (2026-09-07), deliberately not changed
+  the same day it was found - a real polish item, not a correctness gap
+  (the crosshair position itself is exactly the tracked coordinate; only
+  its drawn size/shape is fixed). Revisit if there's time after the demo
+  video.
 - RESOLVED (was: "ROI confirmation (Piece 4): resizing/repositioning the
   platform and hole circles is drag-only, no keyboard equivalent"). Built:
   a "select a shape to adjust" dropdown next to the drag instructions

app/index.html

@@ -409,6 +409,14 @@
   .legend-mark { display: inline-block; width: 1.2rem; height: 0.8rem; border-radius: 2px; }
   .events-legend { display: flex; flex-wrap: wrap; gap: 0.75rem; margin: 0.5rem 0; font-size: 0.85rem; color: #555; }
   .events-legend .legend-flag-icon { color: #6b5900; font-weight: bold; }
+  /* Real find, from her screenshot: this legend used to reuse .type-poke/
+     .type-entry's shared solid blue/green swatches (the Raster tab's own
+     look), but THIS table deliberately overrides both to white/pale-green
+     for readability (see the class-collision comment above) - so the
+     legend was showing colors that appear nowhere in the actual table.
+     Matches the real row colors now instead. */
+  .events-legend .legend-mark.type-poke { background: white; border: 1px solid var(--border); }
+  .events-legend .legend-mark.type-entry { background: #eaf6ee; border: 1px solid #0d4d24; }
   #medianSection, #detectSection { margin-top: 2rem; padding-top: 1rem; border-top: 1px solid var(--border); }
   #medianSection h2, #detectSection h2 { font-size: 1.2rem; margin-bottom: 0.25rem; }
   #computeMedianBtn, #detectBtn {

app/js/app.js

@@ -1264,13 +1264,40 @@ if (typeof cv !== 'undefined') {
             computeMedianBtn.textContent = `Loading OpenCV.js... (${elapsed}s - large one-time download)`;
         }
     }, 1000);
-    cv['onRuntimeInitialized'] = () => {
+    // Real bug, found by hand-testing (2026-09-07): cv.onRuntimeInitialized
+    // sometimes never fires even though OpenCV's WASM runtime is genuinely
+    // ready to use (confirmed live: cv.Mat existed and was callable while
+    // the app sat stuck on "Loading OpenCV.js..." for 400+ seconds) -
+    // a real hang, not just slow, that broke both Compute Background and
+    // the seeded demo (which awaits this same promise before it can skip
+    // to tracking-restore). Root cause not fully pinned down (looks like a
+    // build/timing quirk in this exact OpenCV.js version rather than
+    // anything on this app's side), so the fix doesn't depend on
+    // diagnosing it exactly: polls for the actual readiness signal - a
+    // real cv.Mat construct-and-delete, the same pattern already used
+    // throughout detect.js, not just the property existing as a name -
+    // as a fallback alongside the callback. Idempotent (markCvReady no-ops
+    // once already ready), so whichever signal fires first wins and
+    // nothing double-fires.
+    function markCvReady() {
+        if (cvReady) return;
         clearInterval(cvLoadTicker);
+        clearInterval(cvReadyPoll);
         cvReady = true;
         computeMedianBtn.disabled = totalFrames === 0;
         computeMedianBtn.textContent = 'Compute background';
         cvReadyResolve();
-    };
+    }
+    cv['onRuntimeInitialized'] = markCvReady;
+    const cvReadyPoll = setInterval(() => {
+        if (typeof cv.Mat !== 'function') return; // not even the stub exists yet
+        try {
+            new cv.Mat().delete(); // real call, not just a truthiness check - proves the WASM runtime actually answers, not just that the name exists
+            markCvReady();
+        } catch (err) {
+            // not actually callable yet - keep polling
+        }
+    }, 250);
 }
 
 // --- Reload persistence: offer to resume whatever was last worked on ---