feat: add smooth freehand drawing with continuous drawing mode

- Add continuous drawing mode for overlays (click-drag-release pattern)
- Implement smooth freehand drawing with sub-pixel precision using float indices
- Add precise timestamp interpolation for drawings to persist across timeframe changes
- Support drawing beyond the last candle (extrapolation into future)
- Add freePath overlay for freehand drawing
- Add lineCap/lineJoin support for smooth stroke rendering

New methods in Store:
- floatIndexToTimestamp(): converts float indices to interpolated timestamps
- timestampToFloatIndex(): converts precise timestamps back to float indices

Author: benoist

src/Event.ts

@@ -155,14 +155,19 @@ export default class Event implements EventHandler {
           return widget.dispatchEvent('mouseDownEvent', event)
         }
         case WidgetNameConstants.MAIN: {
-          const yAxis = (pane as DrawPane<YAxis>).getAxisComponent()
-          if (!yAxis.getAutoCalcTickFlag()) {
-            const range = yAxis.getRange()
-            this._prevYAxisRange = { ...range }
+          // Dispatch event first to allow overlays (e.g., continuous drawing) to consume it
+          const consumed = widget.dispatchEvent('mouseDownEvent', event)
+          // Only start scrolling if the event was not consumed by an overlay
+          if (!consumed) {
+            const yAxis = (pane as DrawPane<YAxis>).getAxisComponent()
+            if (!yAxis.getAutoCalcTickFlag()) {
+              const range = yAxis.getRange()
+              this._prevYAxisRange = { ...range }
+            }
+            this._startScrollCoordinate = { x: event.x, y: event.y }
+            this._chart.getChartStore().startScroll()
           }
-          this._startScrollCoordinate = { x: event.x, y: event.y }
-          this._chart.getChartStore().startScroll()
-          return widget.dispatchEvent('mouseDownEvent', event)
+          return consumed
         }
         case WidgetNameConstants.X_AXIS: {
           return this._processXAxisScrollStartEvent(widget, event)
@@ -234,6 +239,9 @@ export default class Event implements EventHandler {
           const consumed = widget.dispatchEvent('pressedMouseMoveEvent', event)
           if (!consumed) {
             this._processMainScrollingEvent(widget as Widget<DrawPane<YAxis>>, event)
+          } else {
+            // Explicitly update overlay when event was consumed (e.g., continuous drawing)
+            this._chart.updatePane(UpdateLevel.Overlay)
           }
           if (!consumed || widget.getForceCursor() === 'pointer') {
             crosshair = { x: event.x, y: event.y, paneId: pane?.getId() }

src/Store.ts

@@ -1027,6 +1027,140 @@ export default class StoreImp implements Store {
     return Math.ceil(this.coordinateToFloatIndex(x)) - 1
   }
 
+  /**
+   * Converts a float data index to an interpolated timestamp.
+   * This allows sub-bar precision for smooth freehand drawings.
+   * Supports extrapolation beyond the data range (drawing in the "future").
+   * @param floatIndex - A floating point index (e.g., 42.75)
+   * @returns An interpolated timestamp between two bars
+   */
+  floatIndexToTimestamp (floatIndex: number): Nullable<number> {
+    const length = this._dataList.length
+    if (length === 0) {
+      return null
+    }
+
+    const lastIndex = length - 1
+
+    // Handle float index beyond the last bar (extrapolate into the future)
+    if (floatIndex > lastIndex && length >= 2) {
+      const lastTimestamp = this._dataList[lastIndex].timestamp
+      const secondLastTimestamp = this._dataList[lastIndex - 1].timestamp
+      const barDuration = lastTimestamp - secondLastTimestamp
+      if (barDuration > 0) {
+        const barsBeyondLast = floatIndex - lastIndex
+        return Math.round(lastTimestamp + barsBeyondLast * barDuration)
+      }
+    }
+
+    // Handle float index before the first bar (extrapolate into the past)
+    if (floatIndex < 0 && length >= 2) {
+      const firstTimestamp = this._dataList[0].timestamp
+      const secondTimestamp = this._dataList[1].timestamp
+      const barDuration = secondTimestamp - firstTimestamp
+      if (barDuration > 0) {
+        return Math.round(firstTimestamp + floatIndex * barDuration)
+      }
+    }
+
+    // Normal case: interpolate between two bars within the data range
+    const intIndex = Math.floor(floatIndex)
+    const fraction = floatIndex - intIndex
+
+    // Get timestamp at the integer index
+    const timestampAtInt = this.dataIndexToTimestamp(intIndex)
+
+    // If no fractional part, return the integer timestamp
+    if (fraction === 0 || !isNumber(timestampAtInt)) {
+      return timestampAtInt
+    }
+
+    // Get timestamp at the next index for interpolation
+    const timestampAtNext = this.dataIndexToTimestamp(intIndex + 1)
+
+    if (isNumber(timestampAtNext)) {
+      // Linear interpolation between the two timestamps
+      return Math.round(timestampAtInt + (timestampAtNext - timestampAtInt) * fraction)
+    }
+
+    return timestampAtInt
+  }
+
+  /**
+   * Converts a precise timestamp to a float data index.
+   * This preserves sub-bar precision for smooth freehand drawings across timeframe changes.
+   * Supports extrapolation beyond the data range (drawing in the "future").
+   * @param timestamp - A precise timestamp (possibly between or beyond bars)
+   * @returns A floating point index representing the exact position
+   */
+  timestampToFloatIndex (timestamp: number): number {
+    const length = this._dataList.length
+    if (length === 0) {
+      return 0
+    }
+
+    const firstTimestamp = this._dataList[0].timestamp
+    const lastTimestamp = this._dataList[length - 1].timestamp
+
+    // Handle timestamp beyond the last bar (drawing in the "future")
+    if (timestamp > lastTimestamp && length >= 2) {
+      // Calculate average bar duration from the last two bars
+      const secondLastTimestamp = this._dataList[length - 2].timestamp
+      const barDuration = lastTimestamp - secondLastTimestamp
+      if (barDuration > 0) {
+        const timeBeyondLast = timestamp - lastTimestamp
+        const barsBeyond = timeBeyondLast / barDuration
+        return length - 1 + barsBeyond
+      }
+    }
+
+    // Handle timestamp before the first bar
+    if (timestamp < firstTimestamp && length >= 2) {
+      const secondTimestamp = this._dataList[1].timestamp
+      const barDuration = secondTimestamp - firstTimestamp
+      if (barDuration > 0) {
+        const timeBeforeFirst = firstTimestamp - timestamp
+        const barsBefore = timeBeforeFirst / barDuration
+        return -barsBefore
+      }
+    }
+
+    // Find the floor bar index using binary search
+    // We need the bar where barTimestamp <= timestamp < nextBarTimestamp
+    let left = 0
+    let right = length - 1
+    let floorIndex = 0
+
+    while (left <= right) {
+      const mid = Math.floor((left + right) / 2)
+      const midTimestamp = this._dataList[mid].timestamp
+
+      if (midTimestamp <= timestamp) {
+        floorIndex = mid
+        left = mid + 1
+      } else {
+        right = mid - 1
+      }
+    }
+
+    // Get the floor bar and the next bar for interpolation
+    const dataAtFloor = this._dataList[floorIndex]
+    const dataAtNext = floorIndex + 1 < length ? this._dataList[floorIndex + 1] : null
+
+    if (isValid(dataAtFloor) && isValid(dataAtNext)) {
+      const timestampAtFloor = dataAtFloor.timestamp
+      const timestampAtNext = dataAtNext.timestamp
+
+      // Calculate fractional position between the two bars
+      if (timestamp >= timestampAtFloor && timestampAtNext > timestampAtFloor) {
+        const fraction = (timestamp - timestampAtFloor) / (timestampAtNext - timestampAtFloor)
+        return floorIndex + Math.min(fraction, 1) // Clamp to max 1
+      }
+    }
+
+    return floorIndex
+  }
+
   zoom (scale: number, coordinate: Nullable<Partial<Coordinate>>, position: 'main' | 'xAxis'): void {
     if (!this._zoomEnabled) {
       return
@@ -1595,7 +1729,11 @@ export default class StoreImp implements Store {
   }
 
   isOverlayDrawing (): boolean {
-    return this._progressOverlayInfo?.overlay.isDrawing() ?? false
+    const info = this._progressOverlayInfo
+    if (info !== null) {
+      return info.overlay.isDrawing()
+    }
+    return false
   }
 
   private _clearLastPriceMarkExtendTextUpdateTimer (): void {

src/component/Overlay.ts

@@ -37,6 +37,13 @@ export interface OverlayPerformEventParams {
   performPoint: Partial<Point>
 }
 
+/**
+ * Drawing mode for overlays
+ * - 'step': Traditional click-based drawing (default)
+ * - 'continuous': Freehand drawing with mouse down, move, up
+ */
+export type OverlayDrawingMode = 'step' | 'continuous'
+
 export interface OverlayEventCollection<E> {
   onDrawStart: Nullable<OverlayEventCallback<E>>
   onDrawing: Nullable<OverlayEventCallback<E>>
@@ -124,6 +131,11 @@ export interface Overlay<E = unknown> extends OverlayEventCollection<E> {
    */
   currentStep: number
 
+  /**
+   * Drawing mode: 'step' for click-based, 'continuous' for freehand
+   */
+  drawingMode: OverlayDrawingMode
+
   /**
    * Whether it is locked. When it is true, it will not respond to events
    */
@@ -229,6 +241,7 @@ export default class OverlayImp<E = unknown> implements Overlay<E> {
   name: string
   totalStep = 1
   currentStep = OVERLAY_DRAW_STEP_START
+  drawingMode: OverlayDrawingMode = 'step'
   lock = false
   visible = true
   zLevel = 0
@@ -237,7 +250,7 @@ export default class OverlayImp<E = unknown> implements Overlay<E> {
   needDefaultYAxisFigure = false
   mode: OverlayMode = 'normal'
   modeSensitivity = 8
-  points: Array<Partial<Omit<Point, 'dataIndex'>>> = []
+  points: Array<Partial<Point>> = []
   extendData: E
   styles: Nullable<DeepPartial<OverlayStyle>> = null
   createPointFigures: Nullable<OverlayCreateFiguresCallback<E>> = null
@@ -372,6 +385,44 @@ export default class OverlayImp<E = unknown> implements Overlay<E> {
     return this.currentStep === OVERLAY_DRAW_STEP_START
   }
 
+  isContinuousDrawing (): boolean {
+    return this.drawingMode === 'continuous'
+  }
+
+  /**
+   * Add a point during continuous drawing mode
+   */
+  addPointForContinuousDrawing (point: Partial<Point>): boolean {
+    const newPoint: Partial<Point> = {}
+    if (isNumber(point.timestamp)) {
+      newPoint.timestamp = point.timestamp
+    }
+    if (isNumber(point.dataIndex)) {
+      newPoint.dataIndex = point.dataIndex
+    }
+    if (isNumber(point.value)) {
+      newPoint.value = point.value
+    }
+    this.points.push(newPoint)
+    return true
+  }
+
+  /**
+   * Start continuous drawing - set first point
+   */
+  startContinuousDrawing (point: Partial<Point>): void {
+    this.points = []
+    this.addPointForContinuousDrawing(point)
+    this.currentStep = 2 // Mark as actively drawing
+  }
+
+  /**
+   * Complete continuous drawing
+   */
+  completeContinuousDrawing (): void {
+    this.currentStep = OVERLAY_DRAW_STEP_FINISHED
+  }
+
   eventMoveForDrawing (point: Partial<Point>): void {
     const pointIndex = this.currentStep - 1
     const newPoint: Partial<Point> = {}

src/extension/figure/line.ts

@@ -138,12 +138,27 @@ export function lineTo (ctx: CanvasRenderingContext2D, coordinates: Coordinate[]
   }
 }
 
-export function drawLine (ctx: CanvasRenderingContext2D, attrs: LineAttrs | LineAttrs[], styles: Partial<SmoothLineStyle>): void {
+export function drawLine (ctx: CanvasRenderingContext2D, attrs: LineAttrs | LineAttrs[], styles: Partial<SmoothLineStyle> & { lineCap?: CanvasLineCap, lineJoin?: CanvasLineJoin }): void {
   let lines: LineAttrs[] = []
   lines = lines.concat(attrs)
-  const { style = 'solid', smooth = false, size = 1, color = 'currentColor', dashedValue = [2, 2] } = styles
+  const { style = 'solid', smooth = false, size = 1, color = 'currentColor', dashedValue = [2, 2], lineCap, lineJoin } = styles
   ctx.lineWidth = size
   ctx.strokeStyle = color
+  // Use explicit lineCap/lineJoin if provided, otherwise default based on smooth
+  if (lineCap !== undefined) {
+    ctx.lineCap = lineCap
+  } else if (smooth !== false && smooth !== 0) {
+    ctx.lineCap = 'round'
+  } else {
+    ctx.lineCap = 'butt'
+  }
+  if (lineJoin !== undefined) {
+    ctx.lineJoin = lineJoin
+  } else if (smooth !== false && smooth !== 0) {
+    ctx.lineJoin = 'round'
+  } else {
+    ctx.lineJoin = 'miter'
+  }
   if (style === 'dashed') {
     ctx.setLineDash(dashedValue)
   } else {

src/extension/overlay/freePath.ts

@@ -0,0 +1,46 @@
+/**
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+
+ * http://www.apache.org/licenses/LICENSE-2.0
+
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import type { OverlayTemplate } from '../../component/Overlay'
+
+/**
+ * Free path overlay - freehand drawing with click and drag
+ * Uses continuous drawing mode for smooth path creation
+ */
+const freePath: OverlayTemplate = {
+  name: 'freePath',
+  totalStep: 2,
+  drawingMode: 'continuous',
+  needDefaultPointFigure: false,
+  needDefaultXAxisFigure: false,
+  needDefaultYAxisFigure: false,
+  createPointFigures: ({ coordinates }) => {
+    if (coordinates.length < 2) {
+      return []
+    }
+    return [
+      {
+        type: 'line',
+        attrs: { coordinates },
+        styles: {
+          smooth: false,
+          lineCap: 'round',
+          lineJoin: 'round'
+        }
+      }
+    ]
+  }
+}
+
+export default freePath

src/extension/overlay/index.ts

@@ -32,14 +32,15 @@ import verticalStraightLine from './verticalStraightLine'
 
 import simpleAnnotation from './simpleAnnotation'
 import simpleTag from './simpleTag'
+import freePath from './freePath'
 
 const overlays: Record<string, OverlayInnerConstructor> = {}
 
 const extensions = [
   fibonacciLine, horizontalRayLine, horizontalSegment, horizontalStraightLine,
   parallelStraightLine, priceChannelLine, priceLine, rayLine, segment,
   straightLine, verticalRayLine, verticalSegment, verticalStraightLine,
-  simpleAnnotation, simpleTag
+  simpleAnnotation, simpleTag, freePath
 ]
 
 extensions.forEach((template: OverlayTemplate) => {

src/index.ts

@@ -46,7 +46,7 @@ import {
 import { calcTextWidth } from './common/utils/canvas'
 import type { ActionType } from './common/Action'
 import type { IndicatorSeries } from './component/Indicator'
-import type { OverlayMode } from './component/Overlay'
+import type { OverlayMode, OverlayDrawingMode } from './component/Overlay'
 
 import type { FormatDateType, Options, ZoomAnchor } from './Options'
 import ChartImp, { type Chart, type DomPosition } from './Chart'
@@ -175,5 +175,5 @@ export {
   utils,
   type LineType, type PolygonType, type TooltipShowRule, type TooltipShowType, type FeatureType, type TooltipFeaturePosition, type CandleTooltipRectPosition,
   type CandleType, type FormatDateType, type ZoomAnchor,
-  type DomPosition, type ActionType, type IndicatorSeries, type OverlayMode
+  type DomPosition, type ActionType, type IndicatorSeries, type OverlayMode, type OverlayDrawingMode
 }