snapshot of https://github.com/tldraw/tldraw.git (main, 2026-09-23; blobs > 131072B omitted)

packages/tldraw/src/lib/overlays/CollaboratorHintOverlayUtil.ts

@@ -0,0 +1,96 @@
+import { OverlayUtil, TLOverlay, Vec, clamp, isCursorInViewport } from '@tldraw/editor'
+
+/** @public */
+export interface TLCollaboratorHintOverlay extends TLOverlay {
+	props: {
+		/** Clamped point on viewport edge, in page coordinates */
+		x: number
+		y: number
+		/** Rotation angle pointing toward the collaborator's actual cursor */
+		rotation: number
+		color: string
+	}
+}
+
+// Lazy-init a Path2D for the hint arrow shape to avoid per-frame path building
+let _arrowPath: Path2D | null = null
+function getArrowPath() {
+	if (!_arrowPath) {
+		// Matches the path drawn via: M -2,-5 2,0 -2,5 Z
+		_arrowPath = new Path2D('M -2 -5 L 2 0 L -2 5 Z')
+	}
+	return _arrowPath!
+}
+
+/**
+ * Overlay util for off-screen collaborator cursor hints.
+ * Shows a small directional arrow at the viewport edge pointing toward the collaborator.
+ *
+ * @public
+ */
+export class CollaboratorHintOverlayUtil extends OverlayUtil<TLCollaboratorHintOverlay> {
+	static override type = 'collaborator_hint'
+	override options = { zIndex: 900, lineWidth: 3, viewportPadding: 5 }
+
+	override isActive(): boolean {
+		const viewport = this.editor.getViewportPageBounds()
+		const zoom = this.editor.getZoomLevel()
+		return this.editor.getVisibleCollaboratorsOnCurrentPage().some((presence) => {
+			const { cursor } = presence
+			if (!cursor) return false
+			return !isCursorInViewport(cursor, viewport, zoom)
+		})
+	}
+
+	override getOverlays(): TLCollaboratorHintOverlay[] {
+		const overlays: TLCollaboratorHintOverlay[] = []
+		const viewport = this.editor.getViewportPageBounds()
+		const zoom = this.editor.getZoomLevel()
+
+		for (const presence of this.editor.getVisibleCollaboratorsOnCurrentPage()) {
+			const { cursor, color, userId } = presence
+			if (!cursor) continue
+			if (isCursorInViewport(cursor, viewport, zoom)) continue
+
+			const pad = this.options.viewportPadding / zoom
+			const x = clamp(cursor.x, viewport.minX + pad, viewport.maxX - pad)
+			const y = clamp(cursor.y, viewport.minY + pad, viewport.maxY - pad)
+			const rotation = Vec.Angle(viewport.center, cursor)
+
+			overlays.push({
+				id: `collaborator_hint:${userId}`,
+				type: 'collaborator_hint',
+				props: { x, y, rotation, color },
+			})
+		}
+		return overlays
+	}
+
+	override render(ctx: CanvasRenderingContext2D, overlays: TLCollaboratorHintOverlay[]): void {
+		const zoom = this.editor.getZoomLevel()
+		const scale = 1 / zoom
+
+		for (const overlay of overlays) {
+			const { x, y, rotation, color } = overlay.props
+
+			ctx.save()
+			ctx.translate(x, y)
+			ctx.scale(scale, scale)
+			ctx.rotate(rotation)
+
+			const path = getArrowPath()
+
+			// Outline stroke (white background for contrast)
+			ctx.lineWidth = this.options.lineWidth
+			// Canvas doesn't support CSS vars in strokeStyle; use white
+			ctx.strokeStyle = '#ffffff'
+			ctx.stroke(path)
+
+			// Fill with collaborator color
+			ctx.fillStyle = color
+			ctx.fill(path)
+
+			ctx.restore()
+		}
+	}
+}