CV: overhead ArUco localization panel

[JaredBaileyDuke]

Summary

Overhead ArUco localization is now a headless detection service that consumes whichever camera the helpers card designates, instead of a dedicated CV panel with its own video element and decoder. Every camera is a helper; each helper carries a single "Camera role" picker (Operator / Overhead / Mount on robot for phones; Idle / Overhead for local cams), mutually exclusive across the helpers list.

What's in

• aruco.js: headless service exposing setOverheadSource(videoEl, {onResult}) / clearOverheadSource(). No DOM ownership, no second decoder, single source of truth for the marker→robot binding.
• Helpers card (helpers.js): single role picker per helper. Local cameras enumerate via getUserMedia; empty deviceIds (pre-permission) fall back to {video:true} and the resolved track's getSettings().deviceId migrates the entry. Auto-resume on reload when camera permission is already granted.
• SVG overlay on the helper's existing preview tile — revives the patchArucoOverlay shape from the deleted phone-on-robot tracker, retargeted at the right surface (overhead, not robot-mounted).
• Per-robot binding via entry.arucoMarkerId (persisted in localStorage; set via window.bindArucoMarker(robotId, markerId)). Detection prefers explicit binding; positional fallback only when no entry has claimed a marker id. Substrate for the multi-robot orchestration direction in .claude/CLAUDE.md — N markers in frame → N robots updated per scan.
• Print-marker affordance is permanent under the role row whenever overhead is designated.
• Staleness contract: producer writes updatedAt; consumer (motion-planner PR) is responsible for gating. Documented in aruco.js header and .claude/notes.md.

What's deleted

• public/aruco.js (phone-on-robot tracker — wired but unproven against real hardware).
• public/cv-localize.js (dedicated CV panel with separate video element).
• <section id="aruco-panel"> and its controls in index.html.
• sendArucoStatus + the WebRTC aruco-status channel + the phone-side aruco-lock box (phone-on-robot lifecycle).

Bugs fixed along the way

• posit1.js does require('./svd') in browser context — loading svd.js first satisfies the this.SVD || short-circuit so the require branch never runs.
• Dictionary name corrected: ARUCO_4X4_50 doesn't exist in js-aruco2; switched to ARUCO_4X4_1000 and explicitly loaded its dictionary file. First 50 codes match the OpenCV DICT_4X4_50 PDFs in /assets/.
• getUserMedia({video:{deviceId:{exact:""}}}) failed pre-permission (empty deviceIds); now falls back to {video:true} and migrates the entry to the resolved id.
• Race protection: in-flight getUserMedia no longer leaks a stream if the user switches role mid-await.
• Track-ended: OS-level revoke / USB unplug flips the role back to Idle instead of leaving the detector chewing on dead frames.
• Dropdown-honest after reload: currentRole requires both isOverhead && live, matching the phone variant.

UI polish

• Helpers section gets a tight heading; helper cards have proper card chrome matching the robot cards above, WITHOUT reusing the green .robot.status-connected left-stripe (different semantic; would have stolen robot identity).
• Camera-role select gets a custom chevron via inline SVG so it doesn't read as a debug field.
• Print-marker links (Sheet 1 / Sheet 2) are permanent under the role row when overhead is designated.

Test plan

• make smoke passes (22/22).
• Helper card shows local cameras only when a robot or phone is already paired (no orphan local-cam card on first visit).
• Camera role picker on a phone helper: Operator / Overhead / Mount on <robot> are mutually exclusive.
• Local-camera helper: Idle / Overhead; getUserMedia prompt fires on first overhead selection.
• Designating either as overhead starts detection on the same preview tile (no duplicate video element).
• Detector loads cleanly (ARUCO_4X4_1000); no "dictionary not recognized" error.
• Auto-resume on reload when permission is granted; silent failure when origin changes (no console noise).
• Multi-robot end-to-end: print sheets 0 + 1, tape one marker on each robot, designate phone as overhead, confirm both robots' arucoPosition update simultaneously per scan.

Followups for sibling PRs

• Motion planning (PR Motion planning: diff drive pose controller + dashboard UI #1): rebase to read entry.arucoPosition (renamed from cvPosition) and add a Date.now() - updatedAt staleness gate before steering. Both flagged in .claude/notes.md under "Wired but unproven."

🤖 Generated with Claude Code