feat: guidance

Author: soundaryakp1999

src/model/abstract.ts

@@ -11,6 +11,7 @@ import type {
   DescriptionState,
   HighlightState,
   TextState,
+  TouchGuidanceState,
   TraceState,
 } from '@type/state';
 import type { Trace } from './plot';
@@ -298,6 +299,18 @@ export abstract class AbstractPlot<State> implements Movable, Observable<State>,
   public dataModeName(): string {
     return Constant.DATA_MODE;
   }
+
+  /**
+   * Gets directional touch/pointer guidance near the active data geometry.
+   * Default behavior 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 Null when guidance is unavailable
+   */
+  public getTouchGuidance(_x: number, _y: number): TouchGuidanceState | null {
+    return null;
+  }
 }
 
 export abstract class AbstractTrace extends AbstractPlot<TraceState> implements Trace {
@@ -760,6 +773,31 @@ export abstract class AbstractTrace extends AbstractPlot<TraceState> implements
     }
   }
 
+  /**
+   * Computes directional guidance for pointer/touch exploration near curves.
+   *
+   * @param x - Screen-space x position
+   * @param y - Screen-space y position
+   * @returns Guidance state relative to nearest point, or null when unavailable
+   */
+  public override getTouchGuidance(x: number, y: number): TouchGuidanceState | null {
+    const nearest = this.findNearestPoint(x, y);
+    if (!nearest) {
+      return null;
+    }
+
+    const bbox = nearest.element.getBoundingClientRect();
+    const centerX = bbox.x + bbox.width / 2;
+    const centerY = bbox.y + bbox.height / 2;
+
+    return {
+      onCurve: this.isPointInBounds(x, y, nearest),
+      distancePx: Math.hypot(centerX - x, centerY - y),
+      verticalRelation: y < centerY ? 'above' : 'below',
+      horizontalRelation: x < centerX ? 'left' : 'right',
+    };
+  }
+
   /**
    * Checks if the specified coordinates are within bounds of the element.
    * @param x - The x-coordinate

src/model/context.ts

@@ -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, SubplotSummary, TouchGuidanceState } from '@type/state';
 import type { Figure, Subplot, Trace } from './plot';
 import { NavigationService } from '@service/navigation';
 import { Scope } from '@type/event';
@@ -200,6 +200,17 @@ export class Context implements Disposable {
     this.active.moveToPoint(x, y);
   }
 
+  /**
+   * Gets directional guidance for pointer/touch exploration near the active trace.
+   *
+   * @param x - Screen-space x position
+   * @param y - Screen-space y position
+   * @returns Guidance state, or null when unavailable for current scope
+   */
+  public getTouchGuidance(x: number, y: number): TouchGuidanceState | null {
+    return this.active.getTouchGuidance(x, y);
+  }
+
   public stepTrace(direction: MovableDirection): void {
     if (this.plotContext.size() > 1) {
       const previousTrace = this.active as Trace;

src/model/plot.ts

@@ -3,7 +3,14 @@ import type { ExtremaTarget } from '@type/extrema';
 import type { Maidr, MaidrSubplot } from '@type/grammar';
 import type { Movable, MovableDirection } from '@type/movable';
 import type { Observable } from '@type/observable';
-import type { FigureState, HighlightState, SubplotState, SubplotSummary, TraceState } from '@type/state';
+import type {
+  FigureState,
+  HighlightState,
+  SubplotState,
+  SubplotSummary,
+  TouchGuidanceState,
+  TraceState,
+} from '@type/state';
 import type { SubplotLayout } from '@util/subplotLayout';
 import type { Dimension } from './abstract';
 import { TraceType } from '@type/grammar';
@@ -587,6 +594,13 @@ export interface Trace extends Movable, Observable<TraceState>, Disposable {
    */
   moveToPoint: (x: number, y: number) => void;
 
+  /**
+   * Computes directional guidance for pointer/touch exploration near this trace.
+   * @param x - Screen-space x position
+   * @param y - Screen-space y position
+   * @returns Guidance state or null if unavailable
+   */
+  getTouchGuidance: (x: number, y: number) => TouchGuidanceState | null;
   /**
    * Gets extrema targets for navigation.
    * Optional method implemented by traces that support extrema navigation.

src/service/audio.ts

@@ -1,6 +1,6 @@
 import type { Disposable } from '@type/disposable';
 import type { Observer } from '@type/observable';
-import type { AudioState, PlotState } from '@type/state';
+import type { AudioState, PlotState, TouchGuidanceState } from '@type/state';
 import type { AudioPaletteEntry } from './audioPalette';
 import type { NotificationService } from './notification';
 import type { SettingsService } from './settings';
@@ -40,6 +40,15 @@ const WARNING_FREQUENCY = 180;
 const WARNING_DURATION = 0.2;
 const WARNING_SPACE = 0.1;
 
+const TOUCH_GUIDANCE_MAX_DISTANCE_PX = 160;
+const TOUCH_GUIDANCE_MIN_INTERVAL = 0.08;
+const TOUCH_GUIDANCE_MAX_INTERVAL = 0.55;
+const TOUCH_GUIDANCE_HIGH_FREQUENCY = 1280;
+const TOUCH_GUIDANCE_LOW_FREQUENCY = 420;
+const TOUCH_GUIDANCE_BEEP_DURATION = 0.06;
+const TOUCH_GUIDANCE_PAN_MAGNITUDE = 0.7;
+const TOUCH_GUIDANCE_VOLUME = 0.35;
+
 const DEFAULT_DURATION = 0.3;
 const DEFAULT_PALETTE_INDEX = AudioPaletteIndex.SINE_BASIC;
 
@@ -81,6 +90,7 @@ export class AudioService implements Observer<PlotState>, Disposable {
   private maxFrequency: number;
   private readonly audioContext: AudioContext;
   private readonly compressor: DynamicsCompressorNode;
+  private nextTouchGuidanceBeepAt: number;
 
   /**
    * Creates an instance of AudioService.
@@ -117,6 +127,7 @@ export class AudioService implements Observer<PlotState>, Disposable {
 
     this.audioContext = new AudioContext();
     this.compressor = this.initCompressor();
+    this.nextTouchGuidanceBeepAt = 0;
   }
 
   /**
@@ -627,6 +638,88 @@ export class AudioService implements Observer<PlotState>, Disposable {
     this.playWarningTone();
   }
 
+  /**
+   * Plays directional touch/pointer guidance beeps for nearby curve exploration.
+   *
+   * Behavior:
+   * - No guidance beep when on-curve (regular sonification continues to apply).
+   * - Off-curve beeps repeat faster when closer and slower when farther.
+   * - High pitch when pointer is below the curve, low pitch when above.
+   * - Pan left when pointer is right of curve, pan right when left of curve.
+   *
+   * @param guidance - Touch guidance state from the active trace, or null to reset guidance
+   */
+  public playTouchGuidance(guidance: TouchGuidanceState | null): void {
+    if (
+      this.mode === AudioMode.OFF
+      || !guidance
+      || guidance.onCurve
+      || guidance.distancePx > TOUCH_GUIDANCE_MAX_DISTANCE_PX
+    ) {
+      this.nextTouchGuidanceBeepAt = 0;
+      return;
+    }
+
+    const now = this.audioContext.currentTime;
+    if (now < this.nextTouchGuidanceBeepAt) {
+      return;
+    }
+
+    const distanceNorm = this.clamp(
+      guidance.distancePx / TOUCH_GUIDANCE_MAX_DISTANCE_PX,
+      0,
+      1,
+    );
+    const interval = this.interpolate(
+      distanceNorm,
+      { min: 0, max: 1 },
+      { min: TOUCH_GUIDANCE_MIN_INTERVAL, max: TOUCH_GUIDANCE_MAX_INTERVAL },
+    );
+
+    const frequency = guidance.verticalRelation === 'below'
+      ? TOUCH_GUIDANCE_HIGH_FREQUENCY
+      : TOUCH_GUIDANCE_LOW_FREQUENCY;
+    const pan = guidance.horizontalRelation === 'right'
+      ? -TOUCH_GUIDANCE_PAN_MAGNITUDE
+      : TOUCH_GUIDANCE_PAN_MAGNITUDE;
+
+    this.playTouchGuidanceBeep(frequency, pan, now);
+    this.nextTouchGuidanceBeepAt = now + interval;
+  }
+
+  private playTouchGuidanceBeep(
+    frequency: number,
+    pan: number,
+    startTime: number,
+  ): void {
+    const oscillator = this.audioContext.createOscillator();
+    oscillator.type = 'sine';
+    oscillator.frequency.value = frequency;
+
+    const gainNode = this.audioContext.createGain();
+    const guidanceVolume = Math.max(this.volume * TOUCH_GUIDANCE_VOLUME, 0.05);
+    gainNode.gain.setValueAtTime(guidanceVolume, startTime);
+    gainNode.gain.exponentialRampToValueAtTime(0.001, startTime + TOUCH_GUIDANCE_BEEP_DURATION);
+
+    const stereoPanner = this.audioContext.createStereoPanner();
+    stereoPanner.pan.value = this.clamp(pan, -1, 1);
+
+    oscillator.connect(gainNode);
+    gainNode.connect(stereoPanner);
+    stereoPanner.connect(this.compressor);
+
+    oscillator.start(startTime);
+    oscillator.stop(startTime + TOUCH_GUIDANCE_BEEP_DURATION);
+
+    const audioId = setTimeout(() => {
+      oscillator.disconnect();
+      gainNode.disconnect();
+      stereoPanner.disconnect();
+      this.activeAudioIds.delete(audioId);
+    }, TOUCH_GUIDANCE_BEEP_DURATION * 1000 * 2);
+    this.activeAudioIds.set(audioId, oscillator);
+  }
+
   private playZeroTone(panning: Panning): AudioId {
     const xPos = this.clamp(this.interpolate(panning.x, { min: 0, max: panning.cols - 1 }, { min: -1, max: 1 }), -1, 1);
     // Y-axis not used for stereo panning

src/service/keybinding.ts

@@ -406,7 +406,8 @@ export class KeybindingService {
  * Service for managing mouse interactions with plot elements based on hover settings.
  */
 export class Mousebindingservice implements Observer<Settings>, Disposable {
-  private mouseListener!: (event: MouseEvent) => void;
+  private mouseListener!: (event: MouseEvent | PointerEvent) => void;
+  private pointerLeaveListener!: () => void;
 
   private readonly commandContext: CommandContext;
   private hoverMode: string = 'none';
@@ -440,11 +441,20 @@ export class Mousebindingservice implements Observer<Settings>, Disposable {
   public registerEvents(): void {
     // Create the mouse listener if it doesn't exist
     if (!this.mouseListener) {
-      this.mouseListener = (event: MouseEvent) => {
+      this.mouseListener = (event: MouseEvent | PointerEvent) => {
         const x = event.clientX;
         const y = event.clientY;
 
         this.commandContext.context.moveToPoint(x, y);
+
+        const guidance = this.commandContext.context.getTouchGuidance(x, y);
+        this.commandContext.audioService.playTouchGuidance(guidance);
+      };
+    }
+
+    if (!this.pointerLeaveListener) {
+      this.pointerLeaveListener = () => {
+        this.commandContext.audioService.playTouchGuidance(null);
       };
     }
 
@@ -454,8 +464,12 @@ export class Mousebindingservice implements Observer<Settings>, Disposable {
     // Add appropriate listeners based on hover mode
     if (this.hoverMode === 'pointermove') {
       this.plot.addEventListener('pointermove', this.mouseListener);
+      this.plot.addEventListener('pointerleave', this.pointerLeaveListener);
     } else if (this.hoverMode === 'click') {
       this.plot.addEventListener('click', this.mouseListener);
+      this.plot.addEventListener('pointerleave', this.pointerLeaveListener);
+    } else {
+      this.commandContext.audioService.playTouchGuidance(null);
     }
   }
 
@@ -467,6 +481,10 @@ export class Mousebindingservice implements Observer<Settings>, Disposable {
       this.plot.removeEventListener('pointermove', this.mouseListener);
       this.plot.removeEventListener('click', this.mouseListener);
     }
+    if (this.pointerLeaveListener) {
+      this.plot.removeEventListener('pointerleave', this.pointerLeaveListener);
+    }
+    this.commandContext.audioService.playTouchGuidance(null);
   }
 
   /**

src/type/state.ts

@@ -181,6 +181,20 @@ export interface AudioState {
   volumeScale?: number;
 }
 
+/**
+ * Directional guidance state for pointer/touch exploration near a curve.
+ */
+export interface TouchGuidanceState {
+  /** True when pointer/finger is touching the curve's active point region. */
+  onCurve: boolean;
+  /** Distance in screen pixels from pointer/finger to the nearest curve point center. */
+  distancePx: number;
+  /** Relative vertical relation of pointer/finger to the curve. */
+  verticalRelation: 'above' | 'below';
+  /** Relative horizontal relation of pointer/finger to the curve. */
+  horizontalRelation: 'left' | 'right';
+}
+
 /**
  * Union type for all braille display states across different plot types.
  */