events: explore using getCoalescedEvents (tldraw#5554)

Wanted to open a discussion on `getCoalescedEvents` and see if it's
worth integrating into the canvas. The videos below show trying to draw
with a CPU 20x slowdown.

(I know we've talked about `getPredictedEvents` but that's a separate
topic)
Testbed:
https://patrickhlauke.github.io/touch/coalesced-predicted-events/

Before:


https://github.com/user-attachments/assets/f4b0648e-22e5-43a3-874a-959d6011ada7

After:


https://github.com/user-attachments/assets/6a99db52-98e4-4a5c-aaab-9ccc1b970e9c


### Change type

- [ ] `bugfix`
- [x] `improvement`
- [ ] `feature`
- [ ] `api`
- [ ] `other`

### Release notes

- Improve draw fluidity on slower CPUs by using getCoalescedEvents.

Author: mimecuvalo

packages/editor/api-report.api.md

@@ -2807,6 +2807,10 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
     transition(id: string, info?: any): this;
     // (undocumented)
     type: 'branch' | 'leaf' | 'root';
+    // (undocumented)
+    static useCoalescedEvents: boolean;
+    // (undocumented)
+    useCoalescedEvents: boolean;
 }
 
 // @public (undocumented)
@@ -4014,6 +4018,8 @@ export interface TLStateNodeConstructor {
     initial?: string;
     // (undocumented)
     isLockable: boolean;
+    // (undocumented)
+    useCoalescedEvents: boolean;
 }
 
 // @public (undocumented)

packages/editor/src/lib/editor/tools/StateNode.ts

@@ -38,6 +38,7 @@ export interface TLStateNodeConstructor {
 	initial?: string
 	children?(): TLStateNodeConstructor[]
 	isLockable: boolean
+	useCoalescedEvents: boolean
 }
 
 /** @public */
@@ -47,7 +48,8 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 		public editor: Editor,
 		parent?: StateNode
 	) {
-		const { id, children, initial, isLockable } = this.constructor as TLStateNodeConstructor
+		const { id, children, initial, isLockable, useCoalescedEvents } = this
+			.constructor as TLStateNodeConstructor
 
 		this.id = id
 		this._isActive = atom<boolean>('toolIsActive' + this.id, false)
@@ -83,20 +85,23 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 			}
 		}
 		this.isLockable = isLockable
+		this.useCoalescedEvents = useCoalescedEvents
 		this.performanceTracker = new PerformanceTracker()
 	}
 
 	static id: string
 	static initial?: string
 	static children?: () => TLStateNodeConstructor[]
 	static isLockable = true
+	static useCoalescedEvents = false
 
 	id: string
 	type: 'branch' | 'leaf' | 'root'
 	shapeType?: string
 	initial?: string
 	children?: Record<string, StateNode>
 	isLockable: boolean
+	useCoalescedEvents: boolean
 	parent: StateNode
 
 	/**

packages/editor/src/lib/hooks/useCanvasEvents.ts

@@ -1,3 +1,4 @@
+import { useValue } from '@tldraw/state-react'
 import React, { useMemo } from 'react'
 import { RIGHT_MOUSE_BUTTON } from '../constants'
 import {
@@ -11,6 +12,7 @@ import { useEditor } from './useEditor'
 
 export function useCanvasEvents() {
 	const editor = useEditor()
+	const currentTool = useValue('current tool', () => editor.getCurrentTool(), [editor])
 
 	const events = useMemo(
 		function canvasEvents() {
@@ -49,12 +51,17 @@ export function useCanvasEvents() {
 				lastX = e.clientX
 				lastY = e.clientY
 
-				editor.dispatch({
-					type: 'pointer',
-					target: 'canvas',
-					name: 'pointer_move',
-					...getPointerInfo(e),
-				})
+				// For tools that benefit from a higher fidelity of events,
+				// we dispatch the coalesced events.
+				const events = currentTool.useCoalescedEvents ? e.nativeEvent.getCoalescedEvents() : [e]
+				for (const singleEvent of events) {
+					editor.dispatch({
+						type: 'pointer',
+						target: 'canvas',
+						name: 'pointer_move',
+						...getPointerInfo(singleEvent),
+					})
+				}
 			}
 
 			function onPointerUp(e: React.PointerEvent) {
@@ -159,7 +166,7 @@ export function useCanvasEvents() {
 				onClick,
 			}
 		},
-		[editor]
+		[editor, currentTool]
 	)
 
 	return events

packages/tldraw/api-report.api.md

@@ -904,6 +904,8 @@ export class DrawShapeTool extends StateNode {
     onExit(): void;
     // (undocumented)
     shapeType: string;
+    // (undocumented)
+    static useCoalescedEvents: boolean;
 }
 
 // @public (undocumented)
@@ -1465,6 +1467,8 @@ export class HighlightShapeTool extends StateNode {
     onExit(): void;
     // (undocumented)
     shapeType: string;
+    // (undocumented)
+    static useCoalescedEvents: boolean;
 }
 
 // @public (undocumented)

packages/tldraw/src/lib/shapes/draw/DrawShapeTool.ts

@@ -7,6 +7,7 @@ export class DrawShapeTool extends StateNode {
 	static override id = 'draw'
 	static override initial = 'idle'
 	static override isLockable = false
+	static override useCoalescedEvents = true
 	static override children(): TLStateNodeConstructor[] {
 		return [Idle, Drawing]
 	}

packages/tldraw/src/lib/shapes/highlight/HighlightShapeTool.ts

@@ -7,6 +7,7 @@ import { Idle } from '../draw/toolStates/Idle'
 export class HighlightShapeTool extends StateNode {
 	static override id = 'highlight'
 	static override initial = 'idle'
+	static override useCoalescedEvents = true
 	static override children(): TLStateNodeConstructor[] {
 		return [Idle, Drawing]
 	}