xability
diff --git a/‎src/command/factory.ts‎
Lines changed: 5 additions & 0 deletions b/‎src/command/factory.ts‎
Lines changed: 5 additions & 0 deletions
diff --git a/‎src/command/pointerGuidance.ts‎
Lines changed: 75 additions & 0 deletions b/‎src/command/pointerGuidance.ts‎
Lines changed: 75 additions & 0 deletions
diff --git a/‎src/model/abstract.ts‎
Lines changed: 91 additions & 26 deletions b/‎src/model/abstract.ts‎
Lines changed: 91 additions & 26 deletions
diff --git a/‎src/model/bar.ts‎
Lines changed: 19 additions & 4 deletions b/‎src/model/bar.ts‎
Lines changed: 19 additions & 4 deletions
diff --git a/‎src/model/box.ts‎
Lines changed: 16 additions & 4 deletions b/‎src/model/box.ts‎
Lines changed: 16 additions & 4 deletions
diff --git a/‎src/model/candlestick.ts‎
Lines changed: 4 additions & 2 deletions b/‎src/model/candlestick.ts‎
Lines changed: 4 additions & 2 deletions
diff --git a/‎src/model/context.ts‎
Lines changed: 8 additions & 13 deletions b/‎src/model/context.ts‎
Lines changed: 8 additions & 13 deletions
@@ -99,6 +99,11 @@ import {
 
 /**
  * Factory for creating command instances based on key input.
+ *
+ * Note: `PointerGuidanceCommand` is intentionally not produced here. It is
+ * wired directly by `Mousebindingservice` because its contract carries raw
+ * pointer coordinates (`clientX`/`clientY`) per event, which doesn't fit the
+ * keyword-based `Keys` lookup this factory uses.
  */
 export class CommandFactory {
   private readonly context: Context;
 
@@ -0,0 +1,75 @@
+import type { Context } from '@model/context';
+import type { AudioService } from '@service/audio';
+import type { Command } from './command';
+import { Scope } from '@type/event';
+
+/**
+ * Routes pointer/touch movement into guidance sonification.
+ *
+ * Constructed directly by `Mousebindingservice` rather than through
+ * `CommandFactory` because pointer events carry coordinates the
+ * keyboard-oriented factory contract does not accept.
+ *
+ * Keyboard commands rely on hotkeys-js scope routing — only the active
+ * scope receives the event, so commands don't self-validate. DOM
+ * pointer listeners receive every event regardless of scope, so this
+ * command must filter via {@link isInTraceScope}. The check is unique
+ * to this code path; there is no peer implementation to keep in sync.
+ */
+export class PointerGuidanceCommand implements Command {
+  private readonly context: Context;
+  private readonly audioService: AudioService;
+
+  constructor(context: Context, audioService: AudioService) {
+    this.context = context;
+    this.audioService = audioService;
+  }
+
+  /**
+   * No-ops outside `Scope.TRACE` so guidance stays silent while modals or
+   * other scopes own input.
+   */
+  public execute(event?: Event): void {
+    // Pointer-leave / missing-coordinate / out-of-scope events all need to
+    // clear in-flight guidance: otherwise a throttle slot armed during a
+    // prior trace-scope hover would silently delay the next beep when the
+    // user returns to trace scope.
+    if (!event || !this.hasClientCoordinates(event) || !this.isInTraceScope()) {
+      this.reset();
+      return;
+    }
+
+    const { clientX, clientY } = event;
+    const guidance = this.context.moveToPointAndGetPointerGuidance(clientX, clientY);
+    this.audioService.playPointerGuidance(guidance);
+  }
+
+  /** Clears in-flight guidance and the throttle so a fresh entry starts clean. */
+  public reset(): void {
+    this.audioService.playPointerGuidance(null);
+  }
+
+  /**
+   * Click-mode entry point: snaps to the nearest point without a guidance
+   * beep, leaving the regular Observer-chain sonification to fire. The
+   * runtime coordinate check stays despite the narrowed parameter type
+   * because exotic event subclasses can still arrive at the listener.
+   */
+  public executeNavigateOnly(event: PointerEvent | MouseEvent): void {
+    if (!this.isInTraceScope() || !this.hasClientCoordinates(event)) {
+      return;
+    }
+    this.context.moveToPointAndGetPointerGuidance(event.clientX, event.clientY);
+  }
+
+  private isInTraceScope(): boolean {
+    return this.context.scope === Scope.TRACE;
+  }
+
+  private hasClientCoordinates(
+    event: Event,
+  ): event is Event & { clientX: number; clientY: number } {
+    const candidate = event as Partial<{ clientX: unknown; clientY: unknown }>;
+    return typeof candidate.clientX === 'number' && typeof candidate.clientY === 'number';
+  }
+}
@@ -10,6 +10,7 @@ import type {
   BrailleState,
   DescriptionState,
   HighlightState,
+  PointerGuidanceState,
   TextState,
   TraceState,
 } from '@type/state';
@@ -53,6 +54,8 @@ export interface NearestPoint {
   element: SVGElement;
   row: number;
   col: number;
+  centerX: number;
+  centerY: number;
 }
 
 export abstract class AbstractPlot<State> implements Movable, Observable<State>, Disposable {
@@ -281,20 +284,6 @@ export abstract class AbstractPlot<State> implements Movable, Observable<State>,
     throw new Error('Move right function is not defined for this trace');
   }
 
-  /**
-   * Moves the element to the specified (x, y) point.
-   *
-   * This base implementation is intentionally left empty. Subclasses should override
-   * this method to provide specific logic for moving to a point, such as updating
-   * highlight values or managing selection boxes.
-   *
-   * @param _x - The x-coordinate to move to.
-   * @param _y - The y-coordinate to move to.
-   */
-  public moveToPoint(_x: number, _y: number): void {
-    // implement basic stuff, assuming something like highlightValues that holds the points and boxes
-  }
-
   /**
    * Returns true if this trace supports compare (lower/higher value) navigation.
    * Override to false for trace types that don't use compare modes (e.g., scatter, which is all we
@@ -311,6 +300,25 @@ export abstract class AbstractPlot<State> implements Movable, Observable<State>,
   public dataModeName(): string {
     return Constant.DATA_MODE;
   }
+
+  /**
+   * Moves the active point to the (x, y) pointer location and returns
+   * directional guidance toward the nearest data geometry.
+   *
+   * Combines navigation and guidance into a single call so traces compute
+   * `findNearestPoint` only once per pointer event. Default returns null
+   * for non-trace contexts.
+   *
+   * @param _x - Screen-space x position of the pointer/finger
+   * @param _y - Screen-space y position of the pointer/finger
+   * @returns Guidance state, or null when unavailable
+   */
+  public moveToPointAndGetPointerGuidance(
+    _x: number,
+    _y: number,
+  ): PointerGuidanceState | null {
+    return null;
+  }
 }
 
 export abstract class AbstractTrace extends AbstractPlot<TraceState> implements Trace {
@@ -795,21 +803,78 @@ export abstract class AbstractTrace extends AbstractPlot<TraceState> implements
   ): NearestPoint | null;
 
   /**
-   * Moves to the nearest point at the specified coordinates (used for hover functionality).
-   * @param x - The x-coordinate
-   * @param y - The y-coordinate
+   * Moves the active point to the pointer location and returns directional
+   * guidance toward the nearest data geometry in a single call.
+   *
+   * Combining both operations avoids running `findNearestPoint` twice per
+   * `pointermove` event — important on dense plots where the scan is the
+   * hot path.
+   *
+   * @param x - Screen-space x position of the pointer/finger
+   * @param y - Screen-space y position of the pointer/finger
+   * @returns Guidance state relative to nearest point, or null when unavailable
    */
-  public moveToPoint(x: number, y: number): void {
+  public override moveToPointAndGetPointerGuidance(
+    x: number,
+    y: number,
+  ): PointerGuidanceState | null {
     const nearest = this.findNearestPoint(x, y);
-    if (nearest) {
-      if (this.isPointInBounds(x, y, nearest)) {
-        // don't move if we're already there
-        if (this.row === nearest.row && this.col === nearest.col) {
-          return;
-        }
-        this.moveToIndex(nearest.row, nearest.col);
-      }
+    if (!nearest) {
+      return null;
+    }
+
+    const onCurve = this.isPointInBounds(x, y, nearest);
+    this.moveToNearest(x, y, nearest, onCurve);
+
+    if (onCurve) {
+      return { onCurve: true };
+    }
+
+    // Fields describe where the curve center sits relative to the cursor.
+    // Screen-space: y grows downward, so a smaller y is higher on screen —
+    // `y < centerY` puts the curve center below the cursor. The vertical
+    // tie-break collapses to 'above'; at single-pixel precision the user
+    // can't perceive the difference, and forcing strict inequality avoids
+    // a third "centered" state that pitch mapping would need to handle.
+    // Horizontally we DO distinguish ties: heatmap centers are computed
+    // pixel integers users can hit exactly, and panning left at the moment
+    // the cursor crosses centerX would be a misleading directional cue.
+    return {
+      onCurve: false,
+      distancePx: Math.hypot(nearest.centerX - x, nearest.centerY - y),
+      curveVertical: y < nearest.centerY ? 'below' : 'above',
+      curveHorizontal: x === nearest.centerX
+        ? 'center'
+        : x < nearest.centerX ? 'right' : 'left',
+    };
+  }
+
+  /**
+   * Moves the trace to the nearest point when the pointer is within its
+   * bounds and the trace is not already focused on that point.
+   *
+   * `onCurve` is intentionally non-optional: the caller has already paid
+   * the cost of {@link isPointInBounds} to assemble guidance state, and
+   * forcing subclasses to accept the value makes the contract explicit so a
+   * future override cannot silently recompute (or worse, ignore) it.
+   *
+   * Subclasses override this to customise hover-driven navigation:
+   * - Box / ViolinBox no-op the move while still surfacing guidance.
+   * - Scatter switches into column navigation mode before delegating.
+   */
+  protected moveToNearest(
+    _x: number,
+    _y: number,
+    nearest: NearestPoint,
+    onCurve: boolean,
+  ): void {
+    if (!onCurve) {
+      return;
+    }
+    if (this.row === nearest.row && this.col === nearest.col) {
+      return;
     }
+    this.moveToIndex(nearest.row, nearest.col);
   }
 
   /**
 
@@ -2,7 +2,7 @@ import type { ExtremaTarget } from '@type/extrema';
 import type { BarPoint, MaidrLayer } from '@type/grammar';
 import type { Movable } from '@type/movable';
 import type { AudioState, BrailleState, DescriptionState, TextState } from '@type/state';
-import type { Dimension } from './abstract';
+import type { Dimension, NearestPoint } from './abstract';
 import { Orientation } from '@type/grammar';
 import { MathUtil } from '@util/math';
 import { Svg } from '@util/svg';
@@ -239,15 +239,24 @@ export abstract class AbstractBarPlot<T extends BarPoint> extends AbstractTrace
   }
 
   /**
-   * Finds the nearest bar element at the specified coordinates.
+   * Finds the bar element under the specified coordinates.
+   *
+   * Unlike line/scatter/box traces (which return the nearest center regardless
+   * of cursor position), bar charts hit-test against each bar's bounding box
+   * and return null when the cursor is between bars. As a consequence, pointer
+   * guidance beeps fire only when the pointer is inside a bar — there is no
+   * directional guidance toward the closest bar from outside. This is
+   * intentional: bars are area marks (not points), and "nearest bar" from
+   * an arbitrary position is rarely the user's intent.
+   *
    * @param x - The x-coordinate
    * @param y - The y-coordinate
    * @returns Object containing the element and its position, or null if not found
    */
   public findNearestPoint(
     x: number,
     y: number,
-  ): { element: SVGElement; row: number; col: number } | null {
+  ): NearestPoint | null {
     // we differ from the base implementation (which is to loop through centers and return one),
     // as sometimes the closest center is not the bar we clicked on
     // so instead, we just do the hard thing and loop through all highlightValues
@@ -284,7 +293,13 @@ export abstract class AbstractBarPlot<T extends BarPoint> extends AbstractTrace
           && y >= bbox.y
           && y <= bbox.y + bbox.height
         ) {
-          return { element: targetElement, row, col };
+          return {
+            element: targetElement,
+            row,
+            col,
+            centerX: bbox.x + bbox.width / 2,
+            centerY: bbox.y + bbox.height / 2,
+          };
         }
       }
     }
 
@@ -1,7 +1,7 @@
 import type { BoxPoint, BoxSelector, MaidrLayer } from '@type/grammar';
 import type { Movable } from '@type/movable';
 import type { AudioState, BrailleState, DescriptionState, TextState } from '@type/state';
-import type { Dimension } from './abstract';
+import type { Dimension, NearestPoint } from './abstract';
 import { BoxplotSection } from '@type/boxplotSection';
 import { Orientation } from '@type/grammar';
 import { Constant } from '@util/constant';
@@ -496,7 +496,7 @@ export class BoxTrace extends AbstractTrace {
   public findNearestPoint(
     x: number,
     y: number,
-  ): { element: SVGElement; row: number; col: number } | null {
+  ): NearestPoint | null {
     if (!this.highlightCenters) {
       return null;
     }
@@ -521,13 +521,25 @@ export class BoxTrace extends AbstractTrace {
       element: this.highlightCenters[nearestIndex].element,
       row: this.highlightCenters[nearestIndex].row,
       col: this.highlightCenters[nearestIndex].col,
+      centerX: this.highlightCenters[nearestIndex].x,
+      centerY: this.highlightCenters[nearestIndex].y,
     };
   }
 
   /**
-   * Moves to the nearest point at the specified coordinates (disabled for boxplots).
+   * Hover-driven movement is disabled for boxplots, but pointer guidance
+   * still surfaces directional cues toward the nearest box element.
+   *
+   * Parameters retained on the signature (rather than the zero-arg form
+   * TypeScript permits) so the override matches the base contract at a
+   * glance.
    */
-  public moveToPoint(_x: number, _y: number): void {
+  protected override moveToNearest(
+    _x: number,
+    _y: number,
+    _nearest: NearestPoint,
+    _onCurve: boolean,
+  ): void {
     // Disabled for boxplots
   }
 }
@@ -1,4 +1,4 @@
-import type { Dimension } from '@model/abstract';
+import type { Dimension, NearestPoint } from '@model/abstract';
 import type { ExtremaTarget } from '@type/extrema';
 import type {
   CandlestickPoint,
@@ -1046,7 +1046,7 @@ export class Candlestick extends AbstractTrace {
   public findNearestPoint(
     x: number,
     y: number,
-  ): { element: SVGElement; row: number; col: number } | null {
+  ): NearestPoint | null {
     // loop through highlightCenters to find nearest point
     if (!this.highlightCenters) {
       return null;
@@ -1072,6 +1072,8 @@ export class Candlestick extends AbstractTrace {
       element: this.highlightCenters[nearestIndex].element,
       row: this.highlightCenters[nearestIndex].row,
       col: this.highlightCenters[nearestIndex].col,
+      centerX: this.highlightCenters[nearestIndex].x,
+      centerY: this.highlightCenters[nearestIndex].y,
     };
   }
 
 
@@ -1,6 +1,6 @@
 import type { Disposable } from '@type/disposable';
 import type { MovableDirection } from '@type/movable';
-import type { PlotState, SubplotSummary } from '@type/state';
+import type { PlotState, PointerGuidanceState, SubplotSummary } from '@type/state';
 import type { Figure, Subplot, Trace } from './plot';
 import { NavigationService } from '@service/navigation';
 import { Scope } from '@type/event';
@@ -420,20 +420,15 @@ export class Context implements Disposable {
   }
 
   /**
-   * Moves the active plot element to the specified (x, y) point.
+   * Moves to the nearest point at (x, y) and returns directional guidance
+   * toward the nearest data geometry in a single call.
    *
-   * @param x - The x-coordinate to move to.
-   * @param y - The y-coordinate to move to.
-   * @remarks
-   * This method assumes that `this.active` is a valid object with a `moveToPoint` method.
-   * If `this.active` is `null` or does not implement `moveToPoint`, this method will do nothing.
-   *
-   * Limitations:
-   * - If `this.active` is `null` or `undefined`, the method will not perform any action.
-   * - If `this.active` does not implement `moveToPoint`, the method will not perform any action.
+   * @param x - Screen-space x position
+   * @param y - Screen-space y position
+   * @returns Guidance state, or null when unavailable for current scope
    */
-  public moveToPoint(x: number, y: number): void {
-    this.active.moveToPoint(x, y);
+  public moveToPointAndGetPointerGuidance(x: number, y: number): PointerGuidanceState | null {
+    return this.active.moveToPointAndGetPointerGuidance(x, y);
   }
 
   public stepTrace(direction: MovableDirection): void {