@forgecharts/sdk 1.1.23

package/src/core/InteractionManager.ts

@@ -0,0 +1,899 @@
+import type { Drawing, DrawingType, OHLCV, HitTestResult, ChartKeyAction, KeyModifiers } from '@forgecharts/types';
+import type { CoordTransform } from './CoordTransform';
+
+// ─── Public handler bag ───────────────────────────────────────────────────────
+
+/**
+ * Callbacks injected by the owning chart engine.
+ * Every handler is optional; omit the ones your engine doesn't need.
+ */
+export type InteractionHandlers = {
+  /** User dragged the chart. Apply `transform.pan(dx, dy)` and mark dirty. */
+  onPan?: (dx: number, dy: number) => void;
+  /**
+   * User scrolled the wheel or pressed +/-.
+   * `factor > 1` = zoom out (more bars visible); `factor < 1` = zoom in.
+   * Apply `transform.zoomTime(factor, originX)` and mark dirty.
+   */
+  onZoom?: (factor: number, originX: number) => void;
+  /** Mouse moved while not dragging — update the crosshair. */
+  onCrosshairMove?: (x: number, y: number, hit: HitTestResult) => void;
+  /** Mouse left the chart area — hide the crosshair. */
+  onCrosshairHide?: () => void;
+  /**
+   * Left-click without drag (click threshold not exceeded).
+   * Selection state is updated internally before this fires.
+   */
+  onSelect?: (x: number, y: number, hit: HitTestResult) => void;
+  /** User clicked empty space — selection cleared. */
+  onDeselect?: () => void;
+  /** Right-click / contextmenu. `e.preventDefault()` is already called. */
+  onContextMenu?: (x: number, y: number, hit: HitTestResult) => void;
+  /** Recognised keyboard shortcut. */
+  onKeyAction?: (action: ChartKeyAction, modifiers: KeyModifiers) => void;
+  /**
+   * Double-click on the price axis — reset price scale to fit visible bars
+   * and scroll to the latest bar.
+   */
+  onFitContent?: () => void;
+  /** User scrolled the wheel over the price axis — zoom the price scale. */
+  onPriceScaleZoom?: (factor: number, originY: number) => void;
+  /** User dragged up/down on the price axis strip — drag down expands, up compresses. */
+  onPriceAxisDrag?: (dy: number) => void;
+  // ── Drawing tool handlers ─────────────────────────────────────────────────
+  /** Called when the user clicks while a drawing tool is active. */
+  onDrawClick?: (x: number, y: number) => void;
+  /** Called on every mousemove while a drawing tool is active (preview). */
+  onDrawPointerMove?: (x: number, y: number) => void;
+  /** Handle drag start — anchor `handleIndex` of drawing `id`. */
+  onHandleDragStart?: (id: string, handleIndex: number) => void;
+  /** Handle dragged to new pixel position. */
+  onHandleDragMove?: (id: string, handleIndex: number, x: number, y: number) => void;
+  /** Handle drag released. */
+  onHandleDragEnd?: (id: string, handleIndex: number) => void;
+  /** Body of drawing `id` grabbed for move. */
+  onBodyMoveStart?: (id: string) => void;
+  /** Body dragged by (dx, dy) pixel delta. */
+  onBodyMoveMove?: (id: string, dx: number, dy: number) => void;
+  /** Body move released. */
+  onBodyMoveEnd?: (id: string) => void;
+};
+
+// ─── Construction options ─────────────────────────────────────────────────────
+
+export type InteractionOptions = {
+  /** Allow click-drag panning. Defaults to `true`. */
+  readonly enablePan?: boolean;
+  /** Allow mouse-wheel zooming. Defaults to `true`. */
+  readonly enableZoom?: boolean;
+  /**
+   * Pointer travel distance (px) below which mousedown + mouseup is treated
+   * as a click rather than a pan gesture. Defaults to `4`.
+   */
+  readonly clickThreshold?: number;
+  /**
+   * Zoom multiplier per wheel step.
+   * `factor > 1` = zoom out on scroll-down. Defaults to `1.1`.
+   */
+  readonly zoomStep?: number;
+  /** Pixels to scroll per arrow-key press. Defaults to `40`. */
+  readonly keyPanStep?: number;
+  /** Zoom multiplier per keyboard +/- press. Defaults to `1.1`. */
+  readonly keyZoomStep?: number;
+};
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+/** Tolerated pixel distance for drawing hit detection. */
+const DRAWING_HIT_PX = 6;
+/** Tolerated pixel distance for handle hit detection. */
+const HANDLE_HIT_PX = 8;
+
+// ─── InteractionManager ───────────────────────────────────────────────────────
+
+/**
+ * InteractionManager — the single owner of all DOM input events for a chart.
+ *
+ * Responsibilities:
+ * - Mouse: pan (left-drag), crosshair tracking, click detection
+ * - Wheel: zoom
+ * - Right-click: contextmenu routing
+ * - Keyboard: arrow-key pan, +/- zoom, Esc / Delete shortcuts
+ * - Hit-testing: drawings → bars → axis zones
+ * - Selection state: tracks the currently selected drawing id
+ *
+ * Usage:
+ * ```ts
+ * const interaction = new InteractionManager(
+ *   canvasElement,
+ *   chart.transform(),
+ *   {
+ *     onPan: (dx, dy) => { transform.pan(dx, dy); markDirty(); },
+ *     onZoom: (f, ox)  => { transform.zoomTime(f, ox); markDirty(); },
+ *     onCrosshairMove: (x, y) => { crosshair.update(x, y); markDirty(); },
+ *     onCrosshairHide: ()     => { crosshair.hide(); markDirty(); },
+ *     onContextMenu: (x, y, hit) => showMenu(x, y, hit),
+ *     onKeyAction: (action)   => handleKey(action),
+ *   },
+ * );
+ *
+ * // Call on chart resize:
+ * interaction.setTransform(chart.transform());
+ *
+ * // Feed visible bars for bar-snap hit-testing:
+ * interaction.setBars(series.data());
+ *
+ * // Feed drawings for drawing hit-testing:
+ * interaction.setDrawings(drawingManager.all());
+ *
+ * // Teardown:
+ * interaction.destroy();
+ * ```
+ */
+export class InteractionManager {
+  private readonly _el: HTMLElement;
+  private _transform: CoordTransform;
+  private readonly _handlers: InteractionHandlers;
+  private readonly _opts: Required<InteractionOptions>;
+
+  // ── Hit-test data feeds ───────────────────────────────────────────────────
+  private _drawings: readonly Drawing[] = [];
+  private _bars: readonly OHLCV[] = [];
+
+  // ── Mouse state ───────────────────────────────────────────────────────────
+  private _isDragging = false;
+  private _dragStartX = 0;
+  private _dragStartY = 0;
+  private _lastDragX = 0;
+  private _lastDragY = 0;
+  /** True once the pointer has moved past `clickThreshold` during a drag. */
+  private _hasMoved = false;
+  /** True while the user is dragging on the price axis strip. */
+  private _priceAxisDragging = false;
+
+  // ── Selection state ───────────────────────────────────────────────────────
+  private _selectedDrawingId: string | null = null;
+
+  // ── Drawing tool state ────────────────────────────────────────────────────
+  private _drawingMode = false;
+  /** True when the native cursor should be hidden (crosshair / dot / demonstration). */
+  private _hideCursor = false;
+
+  /** Sets cursor style, respecting _hideCursor — 'none' always wins when hiding. */
+  private _setCursor(style: string): void {
+    this._el.style.cursor = this._hideCursor ? 'none' : style;
+  }
+  /** Set when a drawing is committed mid-mousedown; prevents the paired mouseup from auto-selecting it. */
+  private _suppressNextClick = false;
+  private _handleDragId: string | null = null;
+  private _handleDragIdx = -1;
+  private _bodyMoveId: string | null = null;
+  private _bodyMovePrevX = 0;
+  private _bodyMovePrevY = 0;
+
+  constructor(
+    element: HTMLElement,
+    transform: CoordTransform,
+    handlers: InteractionHandlers,
+    options: InteractionOptions = {},
+  ) {
+    this._el = element;
+    this._transform = transform;
+    this._handlers = handlers;
+
+    this._opts = {
+      enablePan:      options.enablePan      ?? true,
+      enableZoom:     options.enableZoom     ?? true,
+      clickThreshold: options.clickThreshold ?? 4,
+      zoomStep:       options.zoomStep       ?? 1.1,
+      keyPanStep:     options.keyPanStep     ?? 40,
+      keyZoomStep:    options.keyZoomStep    ?? 1.1,
+    };
+
+    // Make container keyboard-focusable so `keydown` fires on it
+    if (element.tabIndex < 0) element.tabIndex = 0;
+    element.style.outline = 'none'; // suppress browser focus ring
+
+    this._attach();
+  }
+
+  // ─── Data feeds (call after every data / drawing change) ──────────────────
+
+  /** Swap the transform reference after a resize. */
+  setTransform(transform: CoordTransform): void {
+    this._transform = transform;
+  }
+
+  /** Provide the current drawing list for hit-testing. */
+  setDrawings(drawings: readonly Drawing[]): void {
+    this._drawings = drawings;
+  }
+
+  /**
+   * Provide the visible bars for bar-snap hit-testing on the primary series.
+   * Passing `series.data()` is fine; the manager filters by visible range.
+   */
+  setBars(bars: readonly OHLCV[]): void {
+    this._bars = bars;
+  }
+
+  // ─── Selection ────────────────────────────────────────────────────────────
+
+  /** Id of the currently selected drawing, or `null`. */
+  get selectedDrawingId(): string | null {
+    return this._selectedDrawingId;
+  }
+
+  /** Programmatically deselect (e.g. on symbol / timeframe change). */
+  clearSelection(): void {
+    this._selectedDrawingId = null;
+  }
+
+  /**
+   * Switches between drawing-tool mode (crosshair cursor, click fires onDrawClick)
+   * and normal cursor mode.  Also resets any in-progress drag state.
+   */
+  /** Hides (`true`) or shows (`false`) the native OS cursor. Used by crosshair, dot, and demonstration modes. */
+  setHideCursor(hidden: boolean): void {
+    this._hideCursor = hidden;
+    if (!this._drawingMode) {
+      this._el.style.cursor = hidden ? 'none' : 'default';
+    }
+  }
+
+  setDrawingMode(active: boolean): void {
+    if (this._drawingMode && !active) {
+      // Drawing was committed during a mousedown — suppress the paired mouseup click
+      // so it doesn't immediately auto-select the newly placed drawing.
+      this._suppressNextClick = true;
+    }
+    this._drawingMode = active;
+    this._el.style.cursor = active ? 'crosshair' : (this._hideCursor ? 'none' : 'default');
+    this._isDragging = false;
+    this._hasMoved   = false;
+    this._handleDragId  = null;
+    this._handleDragIdx = -1;
+    this._bodyMoveId    = null;
+  }
+
+  // ─── Lifecycle ────────────────────────────────────────────────────────────
+
+  /** Removes all DOM event listeners. Must be called in the chart's `destroy()`. */
+  destroy(): void {
+    this._detach();
+  }
+
+  // ─── DOM listener registry ────────────────────────────────────────────────
+
+  private _attach(): void {
+    const el = this._el;
+
+    // Mouse — always registered so crosshair works even with pan disabled
+    el.addEventListener('mousedown',  this._onMouseDown);
+    el.addEventListener('mousemove',  this._onMouseMove);
+    el.addEventListener('mouseup',    this._onMouseUp);
+    el.addEventListener('mouseleave', this._onMouseLeave);
+
+    if (this._opts.enableZoom) {
+      el.addEventListener('wheel', this._onWheel, { passive: false });
+    }
+
+    el.addEventListener('contextmenu', this._onContextMenu);
+    el.addEventListener('keydown',     this._onKeyDown);
+    el.addEventListener('dblclick',    this._onDblClick);
+  }
+
+  private _detach(): void {
+    const el = this._el;
+    el.removeEventListener('mousedown',  this._onMouseDown);
+    el.removeEventListener('mousemove',  this._onMouseMove);
+    el.removeEventListener('mouseup',    this._onMouseUp);
+    el.removeEventListener('mouseleave', this._onMouseLeave);
+    el.removeEventListener('wheel',      this._onWheel);
+    el.removeEventListener('contextmenu', this._onContextMenu);
+    el.removeEventListener('keydown',    this._onKeyDown);
+    el.removeEventListener('dblclick',   this._onDblClick);
+  }
+
+  // ─── Mouse handlers ───────────────────────────────────────────────────────
+
+  private _onMouseDown = (e: MouseEvent): void => {
+    if (e.button !== 0) return; // left button only
+    this._el.focus({ preventScroll: true });
+
+    const x = e.offsetX;
+    const y = e.offsetY;
+
+    // Drawing tool mode: route click to drawing placement
+    if (this._drawingMode) {
+      this._handlers.onDrawClick?.(x, y);
+      return;
+    }
+
+    // Cursor mode: check handles of the selected drawing first (highest priority)
+    if (this._selectedDrawingId !== null) {
+      for (const drawing of this._drawings) {
+        if (drawing.id !== this._selectedDrawingId || drawing.visible === false) continue;
+        const hi = this._hitTestHandles(x, y, drawing);
+        if (hi >= 0) {
+          this._handleDragId  = drawing.id;
+          this._handleDragIdx = hi;
+          this._setCursor('grabbing');
+          this._handlers.onHandleDragStart?.(drawing.id, hi);
+          return;
+        }
+        break; // handles checked — move on
+      }
+    }
+
+    // Auto-select + immediately start body drag on ANY hovered drawing.
+    // This means one mousedown is all that's needed — no separate
+    // "click to select, then click+drag" two-step required.
+    const drawingBodyHit = this._hitTestDrawings(x, y);
+    if (drawingBodyHit !== null) {
+      this._selectedDrawingId = drawingBodyHit.id;
+      this._bodyMoveId    = drawingBodyHit.id;
+      this._bodyMovePrevX = x;
+      this._bodyMovePrevY = y;
+      this._setCursor('grabbing');
+      this._handlers.onBodyMoveStart?.(drawingBodyHit.id);
+      return;
+    }
+
+    // Price axis — start vertical drag to stretch/compress price scale
+    if (x >= this._transform.plotWidth && y < this._transform.plotHeight) {
+      this._priceAxisDragging = true;
+      this._lastDragY = y;
+      this._setCursor('ns-resize');
+      return;
+    }
+
+    // Normal pan
+    this._isDragging = true;
+    this._hasMoved   = false;
+    this._dragStartX = x;
+    this._dragStartY = y;
+    this._lastDragX  = x;
+    this._lastDragY  = y;
+  };
+
+  private _onMouseMove = (e: MouseEvent): void => {
+    const x = e.offsetX;
+    const y = e.offsetY;
+
+    // Drawing-tool preview
+    if (this._drawingMode) {
+      this._handlers.onDrawPointerMove?.(x, y);
+      this._handlers.onCrosshairMove?.(x, y, this._hitTest(x, y));
+      return;
+    }
+
+    // Handle drag
+    if (this._handleDragId !== null) {
+      this._setCursor('grabbing');
+      this._handlers.onHandleDragMove?.(this._handleDragId, this._handleDragIdx, x, y);
+      return;
+    }
+
+    // Body move
+    if (this._bodyMoveId !== null) {
+      const dx = x - this._bodyMovePrevX;
+      const dy = y - this._bodyMovePrevY;
+      this._bodyMovePrevX = x;
+      this._bodyMovePrevY = y;
+      this._setCursor('grabbing');
+      this._handlers.onBodyMoveMove?.(this._bodyMoveId, dx, dy);
+      return;
+    }
+
+    // Price axis drag — zoom price scale vertically
+    if (this._priceAxisDragging) {
+      const dy = y - this._lastDragY;
+      this._lastDragY = y;
+      if (dy !== 0) this._handlers.onPriceAxisDrag?.(dy);
+      this._setCursor('ns-resize');
+      return;
+    }
+
+    if (this._isDragging) {
+      const dx = x - this._lastDragX;
+      const dy = y - this._lastDragY;
+
+      const totalDist = Math.hypot(x - this._dragStartX, y - this._dragStartY);
+      if (totalDist > this._opts.clickThreshold) {
+        this._hasMoved = true;
+      }
+
+      if (this._hasMoved && this._opts.enablePan) {
+        this._handlers.onPan?.(dx, dy);
+      }
+
+      this._lastDragX = x;
+      this._lastDragY = y;
+    }
+
+    // Crosshair + cursor feedback
+    const hit = this._hitTest(x, y);
+    this._handlers.onCrosshairMove?.(x, y, hit);
+
+    if (!this._isDragging) {
+      if (x >= this._transform.plotWidth && y < this._transform.plotHeight) {
+        this._setCursor('ns-resize');
+      } else if (hit.kind === 'drawingHandle') {
+        this._setCursor('grab');
+      } else if (hit.kind === 'drawing') {
+        this._setCursor('grab');
+      } else {
+        this._setCursor('default');
+      }
+    }
+  };
+
+  private _onMouseUp = (e: MouseEvent): void => {
+    if (e.button !== 0) return;
+
+    // Finish price axis drag
+    if (this._priceAxisDragging) {
+      this._priceAxisDragging = false;
+      this._setCursor('default');
+      return;
+    }
+
+    // Finish handle drag
+    if (this._handleDragId !== null) {
+      const id  = this._handleDragId;
+      const idx = this._handleDragIdx;
+      this._handleDragId  = null;
+      this._handleDragIdx = -1;
+      this._setCursor('grab');
+      this._handlers.onHandleDragEnd?.(id, idx);
+      return;
+    }
+
+    // Finish body move
+    if (this._bodyMoveId !== null) {
+      const id = this._bodyMoveId;
+      this._bodyMoveId = null;
+      this._setCursor('grab');
+      this._handlers.onBodyMoveEnd?.(id);
+      return;
+    }
+
+    const wasClick = !this._hasMoved;
+    this._isDragging = false;
+    this._hasMoved   = false;
+
+    if (wasClick) {
+      if (this._suppressNextClick) {
+        this._suppressNextClick = false;
+      } else {
+        const x   = e.offsetX;
+        const y   = e.offsetY;
+        const hit = this._hitTest(x, y);
+        this._handleClick(x, y, hit);
+      }
+    }
+  };
+
+  private _onMouseLeave = (): void => {
+    this._isDragging        = false;
+    this._hasMoved          = false;
+    this._priceAxisDragging = false;
+    this._handleDragId      = null;
+    this._handleDragIdx     = -1;
+    this._bodyMoveId        = null;
+    this._handlers.onCrosshairHide?.();
+  };
+
+  // ─── Wheel / zoom ─────────────────────────────────────────────────────────
+
+  private _onWheel = (e: WheelEvent): void => {
+    e.preventDefault();
+    const x = e.offsetX;
+    const y = e.offsetY;
+    const plotW = this._transform.plotWidth;
+    const plotH = this._transform.plotHeight;
+
+    // Proportional zoom: normalise deltaY against one standard notch (120 px).
+    // High-resolution trackpads send many small deltas; mice send 120 at a time.
+    // Range: 0.8% per tiny trackpad nudge → 4% per full mouse-wheel notch.
+    // This keeps one notch feeling gentle while fast spinning still zooms quickly.
+    const rawAbs    = Math.abs(e.deltaY);
+    const speed     = Math.min(rawAbs / 120, 1); // 0–1; 1 = one standard notch
+    const magnitude = 0.008 + speed * 0.032;     // 0.8% minimum → 4% per notch
+    const baseZoom  = 1 + magnitude;
+    const factor    = e.deltaY > 0 ? baseZoom : 1 / baseZoom;
+
+    // Price axis strip (right side) — zoom price scale
+    if (x >= plotW && y < plotH) {
+      this._handlers.onPriceScaleZoom?.(factor, y);
+      return;
+    }
+
+    // Time axis strip (bottom) — zoom time scale (expand/contract left-right)
+    if (y >= plotH) {
+      // Zoom around the horizontal centre of the plot so the chart expands
+      // and contracts symmetrically rather than anchored to the cursor.
+      this._handlers.onZoom?.(factor, plotW / 2);
+      return;
+    }
+
+    // Chart plot area — zoom time axis
+    this._handlers.onZoom?.(factor, x);
+  };
+
+  // ─── Double-click — price axis fit ──────────────────────────────────────
+
+  private _onDblClick = (e: MouseEvent): void => {
+    // Fire onFitContent when the double-click lands on the price axis (right)
+    // or the time axis (bottom) — both reset to the default viewport.
+    const onPriceAxis = e.offsetX >= this._transform.plotWidth;
+    const onTimeAxis  = e.offsetY >= this._transform.plotHeight;
+    if (onPriceAxis || onTimeAxis) {
+      e.preventDefault();
+      this._handlers.onFitContent?.();
+    }
+  };
+
+  // ─── Context menu ─────────────────────────────────────────────────────────
+
+  private _onContextMenu = (e: MouseEvent): void => {
+    e.preventDefault();
+    const x   = e.offsetX;
+    const y   = e.offsetY;
+    const hit = this._hitTest(x, y);
+    this._handlers.onContextMenu?.(x, y, hit);
+  };
+
+  // ─── Keyboard ─────────────────────────────────────────────────────────────
+
+  private _onKeyDown = (e: KeyboardEvent): void => {
+    const action = this._keyToAction(e.key);
+    if (action === null) return;
+
+    // Suppress browser scroll / zoom for chart keys
+    e.preventDefault();
+
+    const modifiers: KeyModifiers = {
+      shift: e.shiftKey,
+      ctrl:  e.ctrlKey,
+      alt:   e.altKey,
+      meta:  e.metaKey,
+    };
+
+    this._handlers.onKeyAction?.(action, modifiers);
+  };
+
+  private _keyToAction(key: string): ChartKeyAction | null {
+    switch (key) {
+      case 'ArrowLeft':  return 'panLeft';
+      case 'ArrowRight': return 'panRight';
+      case 'ArrowUp':    return 'panUp';
+      case 'ArrowDown':  return 'panDown';
+      case '+':
+      case '=':          return 'zoomIn';
+      case '-':
+      case '_':          return 'zoomOut';
+      case 'Home':       return 'scrollToStart';
+      case 'End':        return 'scrollToEnd';
+      case 'Escape':     return 'deselect';
+      case 'Delete':
+      case 'Backspace':  return 'deleteSelection';
+      default:           return null;
+    }
+  }
+
+  // ─── Click → selection ────────────────────────────────────────────────────
+
+  private _handleClick(x: number, y: number, hit: HitTestResult): void {
+    if (hit.kind === 'drawing') {
+      this._selectedDrawingId = hit.id;
+      this._handlers.onSelect?.(x, y, hit);
+    } else if (hit.kind === 'bar') {
+      this._selectedDrawingId = null;
+      this._handlers.onSelect?.(x, y, hit);
+    } else {
+      this._selectedDrawingId = null;
+      this._handlers.onDeselect?.();
+    }
+  }
+
+  // ─── Hit-testing ─────────────────────────────────────────────────────────
+
+  private _hitTest(x: number, y: number): HitTestResult {
+    const t = this._transform;
+
+    // Price axis zone (right strip)
+    if (x >= t.plotWidth) {
+      return { kind: 'priceAxis' };
+    }
+
+    // Time axis zone (bottom strip)
+    if (y >= t.plotHeight) {
+      return { kind: 'timeAxis' };
+    }
+
+    // Handles of selected drawing — highest priority
+    if (this._selectedDrawingId !== null) {
+      for (const drawing of this._drawings) {
+        if (drawing.id !== this._selectedDrawingId || drawing.visible === false) continue;
+        const hi = this._hitTestHandles(x, y, drawing);
+        if (hi >= 0) {
+          return { kind: 'drawingHandle', id: drawing.id, type: drawing.type, handleIndex: hi };
+        }
+      }
+    }
+
+    // Drawings — higher priority than bars
+    const drawingHit = this._hitTestDrawings(x, y);
+    if (drawingHit !== null) {
+      return { kind: 'drawing', id: drawingHit.id, type: drawingHit.type };
+    }
+
+    // Nearest visible bar
+    const barHit = this._hitTestBar(x);
+    if (barHit !== null) {
+      return { kind: 'bar', index: barHit.index, bar: barHit.bar };
+    }
+
+    return { kind: 'none' };
+  }
+
+  private _hitTestHandles(x: number, y: number, drawing: Drawing): number {
+    const t = this._transform;
+    for (let i = 0; i < drawing.points.length; i++) {
+      const p = drawing.points[i]!;
+      if (Math.hypot(x - t.timeToX(p.time), y - t.priceToY(p.price)) < HANDLE_HIT_PX) {
+        return i;
+      }
+    }
+    return -1;
+  }
+
+  private _hitTestDrawings(x: number, y: number): { id: string; type: DrawingType } | null {
+    let bestId: string | null = null;
+    let bestType: DrawingType | null = null;
+    let bestDist = DRAWING_HIT_PX + 1;
+
+    for (const drawing of this._drawings) {
+      if (drawing.visible === false) continue;
+
+      const rawDist = this._distToDrawing(x, y, drawing);
+      // Small bias for the selected drawing so it "sticks" under the cursor
+      const dist = rawDist + (drawing.id === this._selectedDrawingId ? -2 : 0);
+
+      if (dist < bestDist) {
+        bestDist = dist;
+        bestId   = drawing.id;
+        bestType = drawing.type;
+      }
+    }
+
+    return bestId !== null && bestType !== null ? { id: bestId, type: bestType } : null;
+  }
+
+  private _distToDrawing(mx: number, my: number, drawing: Drawing): number {
+    const t = this._transform;
+
+    switch (drawing.type) {
+      case 'horizontal': {
+        const p0 = drawing.points[0];
+        if (!p0) return Infinity;
+        return Math.abs(my - t.priceToY(p0.price));
+      }
+
+      case 'vertical': {
+        const p0 = drawing.points[0];
+        if (!p0) return Infinity;
+        return Math.abs(mx - t.timeToX(p0.time));
+      }
+
+      case 'trendline':
+      case 'fibRetracement': {
+        const p0 = drawing.points[0];
+        const p1 = drawing.points[1];
+        if (!p0 || !p1) return Infinity;
+        return this._distPointToSegment(
+          mx, my,
+          t.timeToX(p0.time), t.priceToY(p0.price),
+          t.timeToX(p1.time), t.priceToY(p1.price),
+        );
+      }
+
+      case 'ray': {
+        const p0 = drawing.points[0];
+        const p1 = drawing.points[1];
+        if (!p0 || !p1) return Infinity;
+        const x0 = t.timeToX(p0.time);
+        const y0 = t.priceToY(p0.price);
+        const dx = t.timeToX(p1.time) - x0;
+        const dy = t.priceToY(p1.price) - y0;
+        // Compute exit using the same formula as the renderer
+        const pw = t.plotWidth;
+        const ph = t.plotHeight;
+        let tMin = Infinity;
+        if (dx > 0) tMin = Math.min(tMin, (pw - x0) / dx);
+        else if (dx < 0) tMin = Math.min(tMin, -x0 / dx);
+        if (dy > 0) tMin = Math.min(tMin, (ph - y0) / dy);
+        else if (dy < 0) tMin = Math.min(tMin, -y0 / dy);
+        const ex = tMin === Infinity ? x0 : x0 + dx * tMin;
+        const ey = tMin === Infinity ? y0 : y0 + dy * tMin;
+        return this._distPointToSegment(mx, my, x0, y0, ex, ey);
+      }
+
+      case 'rectangle': {
+        const p0 = drawing.points[0];
+        const p1 = drawing.points[1];
+        if (!p0 || !p1) return Infinity;
+        const rx = Math.min(t.timeToX(p0.time),   t.timeToX(p1.time));
+        const ry = Math.min(t.priceToY(p0.price), t.priceToY(p1.price));
+        const rw = Math.abs(t.timeToX(p1.time)   - t.timeToX(p0.time));
+        const rh = Math.abs(t.priceToY(p1.price) - t.priceToY(p0.price));
+        return this._distToRect(mx, my, rx, ry, rw, rh);
+      }
+
+      case 'text': {
+        const p0 = drawing.points[0];
+        if (!p0) return Infinity;
+        const px = t.timeToX(p0.time);
+        const py = t.priceToY(p0.price);
+        // Approximate bounding box
+        const fs = drawing.fontSize ?? 13;
+        return this._distToRect(mx, my, px, py - fs - 8, 80, fs + 8);
+      }
+
+      // ── new line types (two-anchor, infinite or extended) ──────────────
+
+      case 'infoLine':
+      case 'extendedLine':
+      case 'trendAngle': {
+        const p0 = drawing.points[0];
+        const p1 = drawing.points[1];
+        if (!p0 || !p1) return Infinity;
+        // Approximate by segment; close enough for hit-testing
+        return this._distPointToSegment(
+          mx, my,
+          t.timeToX(p0.time), t.priceToY(p0.price),
+          t.timeToX(p1.time), t.priceToY(p1.price),
+        );
+      }
+
+      case 'horizontalRay': {
+        const p0 = drawing.points[0];
+        if (!p0) return Infinity;
+        const x0 = t.timeToX(p0.time);
+        const y  = t.priceToY(p0.price);
+        if (mx < x0) return Infinity;
+        return Math.abs(my - y);
+      }
+
+      case 'crossLine': {
+        const p0 = drawing.points[0];
+        if (!p0) return Infinity;
+        const x = t.timeToX(p0.time);
+        const y = t.priceToY(p0.price);
+        return Math.min(Math.abs(my - y), Math.abs(mx - x));
+      }
+
+      // ── channels ──────────────────────────────────────────────────────
+
+      case 'parallelChannel':
+      case 'flatTopBottom':
+      case 'regressionTrend':
+      case 'disjointChannel': {
+        const p0 = drawing.points[0];
+        const p1 = drawing.points[1];
+        if (!p0 || !p1) return Infinity;
+        const d0 = this._distPointToSegment(
+          mx, my,
+          t.timeToX(p0.time), t.priceToY(p0.price),
+          t.timeToX(p1.time), t.priceToY(p1.price),
+        );
+        const p2 = drawing.points[2];
+        if (!p2) return d0;
+        const d1 = this._distPointToSegment(
+          mx, my,
+          t.timeToX(p0.time), t.priceToY(p2.price),
+          t.timeToX(p1.time), t.priceToY(p2.price),
+        );
+        return Math.min(d0, d1);
+      }
+
+      // ── pitchforks ────────────────────────────────────────────────────
+
+      case 'pitchfork':
+      case 'schiffPitchfork':
+      case 'modifiedSchiffPitchfork':
+      case 'insidePitchfork': {
+        const p0 = drawing.points[0];
+        const p1 = drawing.points[1];
+        const p2 = drawing.points[2];
+        if (!p0 || !p1) return Infinity;
+        let best = this._distPointToSegment(
+          mx, my,
+          t.timeToX(p0.time), t.priceToY(p0.price),
+          t.timeToX(p1.time), t.priceToY(p1.price),
+        );
+        if (p2) {
+          best = Math.min(best, this._distPointToSegment(
+            mx, my,
+            t.timeToX(p0.time), t.priceToY(p0.price),
+            t.timeToX(p2.time), t.priceToY(p2.price),
+          ));
+        }
+        return best;
+      }
+
+      default:
+        // Fib/Gann and future drawing types are not hit-testable yet.
+        return Infinity;
+    }
+  }
+
+  /**
+   * Returns the nearest visible bar to x-coordinate `mx`, or `null` if no bar
+   * falls within half a bar-width.
+   */
+  private _hitTestBar(mx: number): { index: number; bar: OHLCV } | null {
+    const t              = this._transform;
+    const { from, to }   = t.timeRange;
+    const visibleSeconds = Math.max(1, to - from);
+    const barHalfPx      = (t.plotWidth / visibleSeconds) / 2;
+
+    let bestIndex = -1;
+    let bestDist  = Infinity;
+
+    for (let i = 0; i < this._bars.length; i++) {
+      const bar = this._bars[i];
+      if (!bar || bar.time < from || bar.time > to) continue;
+      const dist = Math.abs(mx - t.timeToX(bar.time));
+      if (dist < bestDist) {
+        bestDist  = dist;
+        bestIndex = i;
+      }
+    }
+
+    if (bestIndex < 0 || bestDist > barHalfPx) return null;
+
+    const bar = this._bars[bestIndex];
+    if (!bar) return null;
+    return { index: bestIndex, bar };
+  }
+
+  // ─── Geometry helpers ────────────────────────────────────────────────────
+
+  /** Distance from point (px, py) to line segment (x1,y1)→(x2,y2). */
+  private _distPointToSegment(
+    px: number, py: number,
+    x1: number, y1: number,
+    x2: number, y2: number,
+  ): number {
+    const dx    = x2 - x1;
+    const dy    = y2 - y1;
+    const lenSq = dx * dx + dy * dy;
+    if (lenSq === 0) return Math.hypot(px - x1, py - y1);
+    const t = Math.max(0, Math.min(1, ((px - x1) * dx + (py - y1) * dy) / lenSq));
+    return Math.hypot(px - (x1 + t * dx), py - (y1 + t * dy));
+  }
+
+  /**
+   * Minimum distance from point (px, py) to the perimeter of an
+   * axis-aligned rectangle.  Returns 0 if the point is inside.
+   */
+  private _distToRect(
+    px: number, py: number,
+    rx: number, ry: number,
+    rw: number, rh: number,
+  ): number {
+    const inside =
+      px >= rx && px <= rx + rw &&
+      py >= ry && py <= ry + rh;
+    if (inside) return 0;
+    return Math.min(
+      this._distPointToSegment(px, py, rx,      ry,      rx + rw, ry),
+      this._distPointToSegment(px, py, rx + rw, ry,      rx + rw, ry + rh),
+      this._distPointToSegment(px, py, rx + rw, ry + rh, rx,      ry + rh),
+      this._distPointToSegment(px, py, rx,      ry + rh, rx,      ry),
+    );
+  }
+}