feat(fastsense): hover crosshair + datatip with colored bullets (999.2) (#112)

* feat(260508-d8y-01): add HoverCrosshair class with chained motion handler

- New libs/FastSense/HoverCrosshair.m: handle class managing per-axes
  hover crosshair line + multi-line datatip lifecycle
- Chains existing WindowButtonMotionFcn so toolbar crosshair and
  NavigatorOverlay drag continue to work
- Pixel-bounds hit-test (skips hidden tabs/panels), ~40 Hz throttle,
  re-entrancy guard, em-dash for out-of-range / NaN y
- Theme-consistent colors via FastSense.Theme; safe fallbacks when
  theme is empty or partial
- Self-cleanup via ObjectBeingDestroyed listeners on figure + axes;
  delete() restores prior callback unconditionally
- tests/test_hover_crosshair.m: Octave-style smoke + chain + cleanup
  tests, gracefully skip on headless or pre-Task-2 builds

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(260508-d8y-02): wire HoverCrosshair into FastSense lifecycle

- Add HoverCrosshair public property (default true) for hover crosshair + datatip
- Add HoverCrosshair_ private property holding runtime instance
- Constructor accepts 'HoverCrosshair' option via parseOpts
- render() instantiates HoverCrosshair(obj) when enabled (try/catch for resilience)
- delete() tears down HoverCrosshair_ first so chained motion handler
  is restored before figure teardown
- Backward compatible: opt-out via fp.HoverCrosshair=false; serialization untouched

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(quick-260508-d8y): record FastSense hover crosshair + datatip in STATE.md

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(hover-crosshair): coerce CurrentPoint to pixels regardless of fig Units

DashboardEngine creates classic figures with Units='normalized', so
get(hFigure,'CurrentPoint') returned normalized [0..1] coords while
getpixelposition() always returns pixels. The hit test in
onFigureMove_ compared mismatched coordinate systems and always
fell through to onLeave(), so hover never showed inside dashboard
widgets (it worked for standalone FastSense figures because those
default to Units='pixels').

Switch the figure to Units='pixels' just long enough to read
CurrentPoint, then restore. No layout impact.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat(hover-crosshair): colored bullet per row in datatip

Each per-line row now starts with a TeX-rendered \bullet in that
line's actual rendered color (read from lineRec.hLine 'Color' with
fall-back to Options.Color), followed by the existing
"DisplayName: yStr". Multi-line plots become readable at a glance:
the bullet matches the line, the name matches the bullet.

- Tip box now uses Interpreter='tex' (set both at create-time and on
  every refresh) so \color[rgb]{...}\bullet directives render.
- New static helpers HoverCrosshair.resolveLineColor_ and
  HoverCrosshair.escapeTeX_ keep TeX-special chars in DisplayNames
  from breaking layout.
- Header row (formatted x value) is unchanged — no bullet.

HoverCrosshair stays default-on with opt-out via
'HoverCrosshair', false in the FastSense constructor (already shipped
in 289216a). All 10 targeted tests still pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(hover-crosshair): add multi-line dashboard widget test helper

MultiLineFastSenseWidget hosts multiple FastSense lines on a single
DashboardEngine widget panel — used to manually verify the colored-
bullet hover datatip end-to-end (multi-line, in-dashboard, themed).
Not a shipped widget; lives under tests/helpers/.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: HanSur94

.planning/STATE.md

@@ -3,8 +3,8 @@ gsd_state_version: 1.0
 milestone: v3.0
 milestone_name: FastSense Companion
 status: shipped
-last_updated: "2026-05-08T07:35:00.000Z"
-last_activity: 2026-05-08 -- Completed quick task 260508-d7k: fix companion app dark mode — uilistbox + 7 prophylactic widget classes added to theme walker
+last_updated: "2026-05-08T08:00:00.000Z"
+last_activity: 2026-05-08 -- Completed quick task 260508-d8y: FastSense hover crosshair + datatip
 progress:
   total_phases: 6
   completed_phases: 6
@@ -19,7 +19,7 @@ shipped_at: 2026-04-30
 
 Milestone: v3.0 FastSense Companion — SHIPPED 2026-04-30
 Status: Awaiting next milestone (run `/gsd:new-milestone` to scope v3.x or v4.0)
-Last activity: 2026-05-08 -- Completed quick task 260508-d7k: fix companion app dark mode — uilistbox + 7 prophylactic widget classes added to theme walker
+Last activity: 2026-05-08 -- Completed quick task 260508-d8y: FastSense hover crosshair + datatip
 
 ### Quick Tasks Completed
 
@@ -32,6 +32,7 @@ Last activity: 2026-05-08 -- Completed quick task 260508-d7k: fix companion app
 | 260508-bju | Lock down WebBridge CORS to localhost with env-var override | 2026-05-08 | 518b778 | Verified | [260508-bju-lock-down-webbridge-cors-to-localhost-on](./quick/260508-bju-lock-down-webbridge-cors-to-localhost-on/) |
 | 260508-bxh | Gate WebSocket /ws endpoint with same origin policy as HTTP CORS | 2026-05-08 | e1aeebc | — | [260508-bxh-gate-websocket-ws-endpoint-with-same-ori](./quick/260508-bxh-gate-websocket-ws-endpoint-with-same-ori/) |
 | 260508-d7k | Fix companion app dark mode — add uilistbox + 7 widget classes to theme walker | 2026-05-08 | 4472cc2 | Verified | [260508-d7k-fix-companion-app-dark-mode-switching-th](./quick/260508-d7k-fix-companion-app-dark-mode-switching-th/) |
+| 260508-d8y | FastSense hover crosshair + datatip | 2026-05-08 | 0221795 | — | [260508-d8y-fastsense-hover-crosshair-datatip](./quick/260508-d8y-fastsense-hover-crosshair-datatip/) |
 
 ## Progress Bar
 

libs/FastSense/FastSense.m

@@ -88,6 +88,7 @@
         ShowThresholdLabels = false  % show inline name labels on threshold lines
         ShowEventMarkers = true     % toggle event round-marker overlay (EVENT-07)
         EventStore = []             % EventStore handle for event overlay queries
+        HoverCrosshair = true       % enable hover crosshair + multi-line datatip (set false to disable; see HoverCrosshair.m)
     end
 
     % ====================== INTERNAL DATA STORAGE ========================
@@ -153,6 +154,7 @@
     properties (SetAccess = private)
         hEventDetails_ = []               % popup figure handle (empty when no popup open)
         EventContextMenu_ = []            % cached uicontextmenu (lazy; one per FastSense)
+        HoverCrosshair_ = []              % HoverCrosshair instance (created in render() when HoverCrosshair=true)
     end
 
     % ===================== PERFORMANCE TUNING ============================
@@ -216,6 +218,7 @@
             defaults.YScale = cfg.YScale;
             defaults.StorageMode = cfg.StorageMode;
             defaults.MemoryLimit = cfg.MemoryLimit;
+            defaults.HoverCrosshair = true;
             [opts, ~] = parseOpts(defaults, varargin);
 
             obj.ParentAxes = opts.Parent;
@@ -230,6 +233,7 @@
             obj.YScale = opts.YScale;
             obj.StorageMode = opts.StorageMode;
             obj.MemoryLimit = opts.MemoryLimit;
+            obj.HoverCrosshair = logical(opts.HoverCrosshair);
             obj.Theme = resolveTheme(opts.Theme, cfg.Theme);
         end
 
@@ -1571,6 +1575,19 @@ function render(obj, progressBar)
                 end
                 drawnow;
             end
+
+            % Attach hover crosshair (default on; opt-out via constructor or property).
+            % try/catch keeps render() resilient on platforms where mouse handlers misbehave.
+            if obj.HoverCrosshair && isempty(obj.HoverCrosshair_)
+                try
+                    obj.HoverCrosshair_ = HoverCrosshair(obj);
+                catch ME
+                    if obj.Verbose
+                        fprintf('[FastSense] HoverCrosshair init failed: %s\n', ME.message);
+                    end
+                    obj.HoverCrosshair_ = [];
+                end
+            end
         end
 
         function result = lookupMetadata(obj, lineIdx, xValue)
@@ -1898,6 +1915,12 @@ function delete(obj)
             %   timer callbacks referencing deleted objects.
             %
             %   See also stopLive, stopRefineTimer.
+            % Tear down HoverCrosshair FIRST so its chained motion handler
+            % is restored on the figure before any other teardown runs.
+            if ~isempty(obj.HoverCrosshair_) && isvalid(obj.HoverCrosshair_)
+                try delete(obj.HoverCrosshair_); catch; end
+            end
+            obj.HoverCrosshair_ = [];
             obj.stopRefineTimer();
             try obj.stopLive(); catch; end
             % Clean up disk-backed DataStores