@tldraw/editor 4.6.0-next.fe1474dc57d8 → 5.0.0

package/src/lib/editor/Editor.ts

@@ -89,7 +89,6 @@ import {
 	hasOwnProperty,
 	last,
 	lerp,
-	maxBy,
 	minBy,
 	sortById,
 	sortByIndex,
@@ -152,6 +151,7 @@ import { notVisibleShapes } from './derivations/notVisibleShapes'
 import { parentsToChildren } from './derivations/parentsToChildren'
 import { deriveShapeIdsInCurrentPage } from './derivations/shapeIdsInCurrentPage'
 import { ClickManager } from './managers/ClickManager/ClickManager'
+import { CollaboratorsManager } from './managers/CollaboratorsManager/CollaboratorsManager'
 import { EdgeScrollManager } from './managers/EdgeScrollManager/EdgeScrollManager'
 import { FocusManager } from './managers/FocusManager/FocusManager'
 import { FontManager } from './managers/FontManager/FontManager'
@@ -165,6 +165,8 @@ import { TextManager } from './managers/TextManager/TextManager'
 import { ThemeManager, resolveThemes } from './managers/ThemeManager/ThemeManager'
 import { TickManager } from './managers/TickManager/TickManager'
 import { UserPreferencesManager } from './managers/UserPreferencesManager/UserPreferencesManager'
+import { OverlayManager } from './overlays/OverlayManager'
+import { TLAnyOverlayUtilConstructor } from './overlays/OverlayUtil'
 import {
 	ShapeUtil,
 	TLEditStartInfo,
@@ -224,6 +226,11 @@ export interface TLEditorOptions {
 	 * An array of asset utils to use in the editor. These will be used to handle asset-type-specific behavior.
 	 */
 	assetUtils?: readonly TLAnyAssetUtilConstructor[]
+	/**
+	 * An array of overlay utils to use in the editor. These define canvas overlay UI elements
+	 * like selection handles, rotation corners, shape handles, etc.
+	 */
+	overlayUtils?: readonly TLAnyOverlayUtilConstructor[]
 	/**
 	 * An array of tools to use in the editor. These will be used to handle events and manage user interactions in the editor.
 	 */
@@ -330,6 +337,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 		shapeUtils,
 		bindingUtils,
 		assetUtils: assetUtilConstructors,
+		overlayUtils: overlayUtilConstructors,
 		tools,
 		getContainer,
 		// needs to be here for backwards compatibility with TldrawEditor
@@ -410,6 +418,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 		this.inputs = new InputsManager(this)
 		this.performance = new PerformanceManager(this)
 		this.disposables.add(() => this.performance.dispose())
+		this.collaborators = new CollaboratorsManager(this)
 
 		class NewRoot extends RootState {
 			static override initial = initialState ?? ''
@@ -489,6 +498,15 @@ export class Editor extends EventEmitter<TLEventMap> {
 
 		this.scribbles = new ScribbleManager(this)
 
+		// Overlay utils
+		this.overlays = new OverlayManager(this)
+		if (overlayUtilConstructors) {
+			for (const Util of overlayUtilConstructors) {
+				const util = new Util(this)
+				this.overlays.registerUtil(util)
+			}
+		}
+
 		// Cleanup
 
 		const cleanupInstancePageState = (
@@ -1033,6 +1051,13 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 */
 	readonly timers = tltime.forContext(this.contextId)
 
+	/**
+	 * A manager for remote peer collaborators connected to this editor.
+	 *
+	 * @public
+	 */
+	readonly collaborators: CollaboratorsManager
+
 	/**
 	 * A manager for the user and their preferences.
 	 *
@@ -1068,6 +1093,13 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 */
 	readonly scribbles: ScribbleManager
 
+	/**
+	 * A manager for canvas overlay UI elements (selection handles, shape handles, etc.).
+	 *
+	 * @public
+	 */
+	readonly overlays: OverlayManager
+
 	/**
 	 * A manager for side effects and correct state enforcement. See {@link @tldraw/store#StoreSideEffects} for details.
 	 *
@@ -1912,11 +1944,23 @@ export class Editor extends EventEmitter<TLEventMap> {
 	/**
 	 * Set the cursor.
 	 *
+	 * No-op when the partial wouldn't change the current cursor — `setCursor`
+	 * is called from pointer-move hot paths (see `updateHoveredOverlayId`,
+	 * various tool states) and skipping redundant writes avoids needlessly
+	 * dirtying instance state.
+	 *
 	 * @param cursor - The cursor to set.
 	 * @public
 	 */
 	setCursor(cursor: Partial<TLCursor>) {
-		this.updateInstanceState({ cursor: { ...this.getInstanceState().cursor, ...cursor } })
+		const current = this.getInstanceState().cursor
+		if (
+			(cursor.type === undefined || cursor.type === current.type) &&
+			(cursor.rotation === undefined || cursor.rotation === current.rotation)
+		) {
+			return this
+		}
+		this.updateInstanceState({ cursor: { ...current, ...cursor } })
 		return this
 	}
 
@@ -4222,43 +4266,55 @@ export class Editor extends EventEmitter<TLEventMap> {
 	}
 	// Collaborators
 
-	@computed
-	private _getCollaboratorsQuery() {
-		return this.store.query.records('instance_presence', () => ({
-			userId: { neq: this.user.getId() },
-		}))
-	}
-
 	/**
 	 * Returns a list of presence records for all peer collaborators.
 	 * This will return the latest presence record for each connected user.
 	 *
+	 * Convenience wrapper for {@link CollaboratorsManager.getCollaborators}.
+	 *
 	 * @public
 	 */
-	@computed
 	getCollaborators() {
-		const allPresenceRecords = this._getCollaboratorsQuery().get()
-		if (!allPresenceRecords.length) return EMPTY_ARRAY
-		const userIds = [...new Set(allPresenceRecords.map((c) => c.userId))].sort()
-		return userIds.map((id) => {
-			const latestPresence = maxBy(
-				allPresenceRecords.filter((c) => c.userId === id),
-				(p) => p.lastActivityTimestamp ?? 0
-			)
-			return latestPresence!
-		})
+		return this.collaborators.getCollaborators()
 	}
 
 	/**
 	 * Returns a list of presence records for all peer collaborators on the current page.
 	 * This will return the latest presence record for each connected user.
 	 *
+	 * Convenience wrapper for {@link CollaboratorsManager.getCollaboratorsOnCurrentPage}.
+	 *
 	 * @public
 	 */
-	@computed
 	getCollaboratorsOnCurrentPage() {
-		const currentPageId = this.getCurrentPageId()
-		return this.getCollaborators().filter((c) => c.currentPageId === currentPageId)
+		return this.collaborators.getCollaboratorsOnCurrentPage()
+	}
+
+	/**
+	 * Returns a list of presence records for peer collaborators who should currently be
+	 * shown in the UI. Filters {@link Editor.getCollaborators} by activity state
+	 * (active / idle / inactive) and visibility rules such as following and highlighted
+	 * users. Re-evaluates on the collaborator visibility clock, so callers don't need to
+	 * drive their own activity timer.
+	 *
+	 * Convenience wrapper for {@link CollaboratorsManager.getVisibleCollaborators}.
+	 *
+	 * @public
+	 */
+	getVisibleCollaborators() {
+		return this.collaborators.getVisibleCollaborators()
+	}
+
+	/**
+	 * Returns a list of presence records for peer collaborators who should currently be
+	 * shown in the UI, filtered to those on the current page.
+	 *
+	 * Convenience wrapper for {@link CollaboratorsManager.getVisibleCollaboratorsOnCurrentPage}.
+	 *
+	 * @public
+	 */
+	getVisibleCollaboratorsOnCurrentPage() {
+		return this.collaborators.getVisibleCollaboratorsOnCurrentPage()
 	}
 
 	// Attribution
@@ -5112,7 +5168,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 		const zoomStepFunction = (zoom: number) => Math.pow(2, Math.ceil(Math.log2(zoom)))
 		const steppedScreenScale = zoomStepFunction(screenScale)
 		const networkEffectiveType: string | null =
-			'connection' in navigator ? (navigator as any).connection.effectiveType : null
+			'connection' in navigator ? ((navigator as any).connection?.effectiveType ?? null) : null
 
 		return await this.store.props.assets.resolve(asset, {
 			screenScale: screenScale || 1,

package/src/lib/editor/managers/CollaboratorsManager/CollaboratorsManager.ts

@@ -0,0 +1,98 @@
+import { EMPTY_ARRAY, atom, computed } from '@tldraw/state'
+import { TLInstancePresence } from '@tldraw/tlschema'
+import { maxBy } from '@tldraw/utils'
+import {
+	getCollaboratorStateFromElapsedTime,
+	shouldShowCollaborator,
+} from '../../../utils/collaboratorState'
+import type { Editor } from '../../Editor'
+
+/**
+ * Tracks remote peers and exposes the collaborator-related queries used by the
+ * editor and its overlays. Encapsulates the visibility clock that periodically
+ * re-evaluates which collaborators should be visible based on activity.
+ *
+ * Accessed via {@link Editor.collaborators}.
+ *
+ * @public
+ */
+export class CollaboratorsManager {
+	constructor(private readonly editor: Editor) {
+		// Editor disposes `editor.timers` on its own teardown, so the interval is
+		// automatically cleared when the editor is disposed.
+		editor.timers.setInterval(() => {
+			this._visibilityClock.set(Date.now())
+		}, editor.options.collaboratorCheckIntervalMs)
+	}
+
+	/**
+	 * Drives reactive re-evaluation of {@link CollaboratorsManager.getVisibleCollaborators}.
+	 * Ticked on a fixed interval so callers don't need to manage their own activity timers.
+	 */
+	private readonly _visibilityClock = atom('collaboratorVisibilityClock', Date.now())
+
+	@computed
+	private _getCollaboratorsQuery() {
+		return this.editor.store.query.records('instance_presence', () => ({
+			userId: { neq: this.editor.user.getId() },
+		}))
+	}
+
+	/**
+	 * Returns a list of presence records for all peer collaborators.
+	 * This will return the latest presence record for each connected user.
+	 */
+	@computed
+	getCollaborators(): TLInstancePresence[] {
+		const allPresenceRecords = this._getCollaboratorsQuery().get()
+		if (!allPresenceRecords.length) return EMPTY_ARRAY
+		const userIds = [...new Set(allPresenceRecords.map((c) => c.userId))].sort()
+		return userIds.map((id) => {
+			const latestPresence = maxBy(
+				allPresenceRecords.filter((c) => c.userId === id),
+				(p) => p.lastActivityTimestamp ?? 0
+			)
+			return latestPresence!
+		})
+	}
+
+	/**
+	 * Returns a list of presence records for all peer collaborators on the current page.
+	 * This will return the latest presence record for each connected user.
+	 */
+	@computed
+	getCollaboratorsOnCurrentPage(): TLInstancePresence[] {
+		const currentPageId = this.editor.getCurrentPageId()
+		return this.getCollaborators().filter((c) => c.currentPageId === currentPageId)
+	}
+
+	/**
+	 * Returns a list of presence records for peer collaborators who should currently be
+	 * shown in the UI. Filters {@link CollaboratorsManager.getCollaborators} by activity
+	 * state (active / idle / inactive) and visibility rules such as following and
+	 * highlighted users. Re-evaluates on the visibility clock, so callers don't need to
+	 * drive their own activity timer.
+	 */
+	@computed
+	getVisibleCollaborators(): TLInstancePresence[] {
+		this._visibilityClock.get()
+		const now = Date.now()
+		return this.getCollaborators().filter((presence) => {
+			// Treat a missing `lastActivityTimestamp` as "active right now" (elapsed = 0)
+			// so newly-joined peers aren't immediately classified as idle/inactive.
+			const elapsed = Math.max(0, now - (presence.lastActivityTimestamp ?? now))
+			const state = getCollaboratorStateFromElapsedTime(this.editor, elapsed)
+			return shouldShowCollaborator(this.editor, presence, state)
+		})
+	}
+
+	/**
+	 * Returns a list of presence records for peer collaborators who should currently be
+	 * shown in the UI, filtered to those on the current page.
+	 */
+	@computed
+	getVisibleCollaboratorsOnCurrentPage(): TLInstancePresence[] {
+		const currentPageId = this.editor.getCurrentPageId()
+		return this.getVisibleCollaborators().filter((c) => c.currentPageId === currentPageId)
+	}
+}

package/src/lib/editor/managers/ThemeManager/defaultThemes.ts

@@ -136,6 +136,13 @@ export const DEFAULT_THEME: TLTheme = {
 			solid: '#fcfffe',
 			cursor: 'black',
 			noteBorder: 'rgb(144, 144, 144)',
+			snap: 'hsl(0, 76%, 60%)',
+			selectionStroke: 'hsl(214, 84%, 56%)',
+			selectionFill: 'hsl(210, 100%, 56%, 24%)',
+			brushFill: 'hsl(0, 0%, 56%, 10.2%)',
+			brushStroke: 'hsl(0, 0%, 56%, 25.1%)',
+			selectedContrast: '#ffffff',
+			laser: 'hsl(0, 100%, 50%)',
 			black: {
 				solid: '#1d1d1d',
 				fill: '#1d1d1d',
@@ -351,6 +358,13 @@ export const DEFAULT_THEME: TLTheme = {
 			negativeSpace: 'hsl(240, 5%, 6.5%)',
 			solid: '#010403',
 			cursor: 'white',
+			snap: 'hsl(0, 76%, 60%)',
+			selectionStroke: 'hsl(214, 84%, 56%)',
+			selectionFill: 'hsl(209, 100%, 57%, 20%)',
+			brushFill: 'hsl(0, 0%, 56%, 10.2%)',
+			brushStroke: 'hsl(0, 0%, 56%, 25.1%)',
+			selectedContrast: '#ffffff',
+			laser: 'hsl(0, 100%, 50%)',
 			noteBorder: 'rgb(20, 20, 20)',
 
 			black: {

package/src/lib/editor/overlays/OverlayManager.ts

@@ -0,0 +1,183 @@
+import { atom, computed } from '@tldraw/state'
+import { Geometry2d } from '../../primitives/geometry/Geometry2d'
+import { VecLike } from '../../primitives/Vec'
+import type { Editor } from '../Editor'
+import { OverlayUtil, TLOverlay } from './OverlayUtil'
+
+/**
+ * An active overlay util paired with the overlays it produced for the current
+ * editor state. Returned by {@link OverlayManager.getActiveOverlayEntries} so
+ * hit-test, render, and debug paths share a single scan per reactive tick.
+ *
+ * @public
+ */
+export interface TLOverlayEntry {
+	util: OverlayUtil
+	overlays: TLOverlay[]
+}
+
+/** @public */
+export class OverlayManager {
+	constructor(public readonly editor: Editor) {}
+
+	/** @internal */
+	readonly _overlayUtils = new Map<string, OverlayUtil>()
+
+	/**
+	 * Register an overlay util instance. Called during editor construction.
+	 * @internal
+	 */
+	registerUtil(util: OverlayUtil) {
+		const type = (util.constructor as typeof OverlayUtil).type
+		if (!type) {
+			throw new Error(`Overlay util ${util.constructor.name} is missing a static 'type' property.`)
+		}
+		if (this._overlayUtils.has(type)) {
+			throw new Error(`Duplicate overlay util type: "${type}"`)
+		}
+		this._overlayUtils.set(type, util)
+	}
+
+	/**
+	 * Get an overlay util by type string, overlay instance, or by passing
+	 * a util class as a generic parameter for type-safe lookup.
+	 *
+	 * @example
+	 * ```ts
+	 * const util = editor.overlays.getOverlayUtil('brush')
+	 * const util = editor.overlays.getOverlayUtil<BrushOverlayUtil>('brush')
+	 * const util = editor.overlays.getOverlayUtil(myOverlay)
+	 * ```
+	 *
+	 * @public
+	 */
+	getOverlayUtil<T extends OverlayUtil>(
+		type: T extends OverlayUtil<infer O> ? O['type'] : string
+	): T
+	getOverlayUtil<O extends TLOverlay>(overlay: O): OverlayUtil<O>
+	getOverlayUtil(arg: string | TLOverlay): OverlayUtil {
+		const type = typeof arg === 'string' ? arg : arg.type
+		const util = this._overlayUtils.get(type)
+		if (!util) throw new Error(`No overlay util found for type: "${type}"`)
+		return util
+	}
+
+	/**
+	 * Returns all registered overlay utils in paint order (ascending zIndex).
+	 * Utils with the same zIndex preserve their registration order.
+	 *
+	 * @public
+	 */
+	@computed getOverlayUtilsInZOrder(): OverlayUtil[] {
+		const utils = Array.from(this._overlayUtils.values())
+		// Stable sort by zIndex (registration order breaks ties).
+		return utils
+			.map((util, i) => ({ util, i, z: util.options.zIndex ?? 0 }))
+			.sort((a, b) => a.z - b.z || a.i - b.i)
+			.map((entry) => entry.util)
+	}
+
+	/**
+	 * Reactive list of active overlay utils paired with the overlays they
+	 * produced for the current editor state, in paint order (ascending
+	 * zIndex). Both the hit-test and render paths read from this single
+	 * cached scan instead of each re-deriving the active set. Active utils
+	 * are included even when their `getOverlays()` returns an empty array,
+	 * since `render()` may still draw non-interactive UI (e.g. the selection
+	 * bounding box during brushing).
+	 *
+	 * @public
+	 */
+	@computed getActiveOverlayEntries(): TLOverlayEntry[] {
+		const entries: TLOverlayEntry[] = []
+		for (const util of this.getOverlayUtilsInZOrder()) {
+			if (!util.isActive()) continue
+			entries.push({ util, overlays: util.getOverlays() })
+		}
+		return entries
+	}
+
+	/**
+	 * Reactively computed list of all currently active overlays, in paint order.
+	 * @public
+	 */
+	@computed getCurrentOverlays(): TLOverlay[] {
+		const all: TLOverlay[] = []
+		for (const { overlays } of this.getActiveOverlayEntries()) {
+			all.push(...overlays)
+		}
+		return all
+	}
+
+	// Hit-test geometry cache keyed by overlay identity. Entries remain valid
+	// while getActiveOverlayEntries() keeps returning the same overlay
+	// instances; when its reactive deps change, getOverlays() emits fresh
+	// objects and stale entries fall out by GC.
+	private _geometryCache = new WeakMap<TLOverlay, Geometry2d | null>()
+
+	/**
+	 * Get hit-test geometry for an overlay, cached by overlay identity. Lets
+	 * hit-testing on a pointermove storm skip the per-overlay geometry
+	 * allocation that {@link OverlayUtil.getGeometry} would otherwise do on
+	 * every call.
+	 *
+	 * @public
+	 */
+	getOverlayGeometry(overlay: TLOverlay): Geometry2d | null {
+		const cached = this._geometryCache.get(overlay)
+		if (cached !== undefined) return cached
+		const util = this.getOverlayUtil(overlay)
+		const geometry = util.getGeometry(overlay)
+		this._geometryCache.set(overlay, geometry)
+		return geometry
+	}
+
+	/**
+	 * The currently hovered overlay id.
+	 * @public
+	 */
+	private _hoveredOverlayId = atom<string | null>('hoveredOverlayId', null)
+
+	getHoveredOverlayId(): string | null {
+		return this._hoveredOverlayId.get()
+	}
+
+	getHoveredOverlay(): TLOverlay | null {
+		const id = this._hoveredOverlayId.get()
+		if (!id) return null
+		return this.getCurrentOverlays().find((o) => o.id === id) ?? null
+	}
+
+	setHoveredOverlay(id: string | null) {
+		if (id === this._hoveredOverlayId.get()) return
+		this._hoveredOverlayId.set(id)
+	}
+
+	/**
+	 * Hit test all active overlays at a given page point.
+	 * Returns the topmost overlay whose geometry contains the point, or null.
+	 * Utils are walked from highest zIndex to lowest so the overlay painted on
+	 * top also wins the hit test. Within a util, overlays are walked in
+	 * array order: the first overlay whose geometry contains the point wins,
+	 * so utils should place highest-priority overlays first in `getOverlays`.
+	 * Interactive overlays (those with geometry) are checked; non-interactive are skipped.
+	 *
+	 * @param point - Point in page coordinates
+	 * @param margin - Hit test margin
+	 * @public
+	 */
+	getOverlayAtPoint(point: VecLike, margin = 0): TLOverlay | null {
+		const entries = this.getActiveOverlayEntries()
+		for (let i = entries.length - 1; i >= 0; i--) {
+			const { overlays } = entries[i]
+			for (const overlay of overlays) {
+				const geometry = this.getOverlayGeometry(overlay)
+				if (!geometry) continue
+				if (geometry.hitTestPoint(point, geometry.isFilled ? 0 : margin, true)) {
+					return overlay
+				}
+			}
+		}
+		return null
+	}
+}

package/src/lib/editor/overlays/OverlayUtil.ts

@@ -0,0 +1,143 @@
+import { TLCursorType } from '@tldraw/tlschema'
+import { Geometry2d } from '../../primitives/geometry/Geometry2d'
+import type { Editor } from '../Editor'
+import { TLPointerEventInfo } from '../types/event-types'
+
+/** @public */
+export interface TLOverlay<Props = Record<string, unknown>> {
+	/**
+	 * Globally unique id for this overlay instance across all overlay utils.
+	 * Hit-test and hover lookup key on `id` alone, so utils must namespace their
+	 * ids (e.g. `'selection_fg:top_left'`, `'handle:<shapeId>:<handleId>'`) to
+	 * avoid colliding with overlays from other utils.
+	 */
+	id: string
+	/** The overlay util type that owns this instance */
+	type: string
+	/** Arbitrary props for the overlay (handle id, corner name, etc.) */
+	props: Props
+}
+
+/** @public */
+export interface TLOverlayUtilConstructor<U extends OverlayUtil = OverlayUtil> {
+	new (editor: Editor): U
+	type: string
+	configure<T extends TLOverlayUtilConstructor<any>>(
+		this: T,
+		options: T extends new (...args: any[]) => { options: infer Options } ? Partial<Options> : never
+	): T
+}
+
+/** @public */
+export type TLAnyOverlayUtilConstructor = TLOverlayUtilConstructor<any>
+
+/**
+ * Base class for overlay utilities. Overlays are ephemeral UI elements rendered
+ * on top of the canvas (selection handles, rotation corners, shape handles, etc.).
+ *
+ * Each OverlayUtil defines a type of overlay and knows how to:
+ * - Determine when its overlays should be active (predicate)
+ * - Produce overlay instances from current editor state
+ * - Provide hit-test geometry for interactive overlays
+ * - Provide cursor style on hover
+ * - Render into a canvas 2D context
+ *
+ * @public
+ */
+export abstract class OverlayUtil<T extends TLOverlay = TLOverlay> {
+	constructor(public editor: Editor) {}
+	static type: string
+
+	/**
+	 * Options for this overlay util. Override this to provide customization options.
+	 * Use {@link OverlayUtil.configure} to customize existing overlay utils.
+	 *
+	 * `zIndex` controls paint and hit-test order across utils — higher numbers
+	 * paint on top and are hit-tested first. Ties resolve by registration order.
+	 * Defaults to `0`; built-in utils use larger integers (100, 200, …) with
+	 * gaps so custom utils can slot between.
+	 *
+	 * @public
+	 */
+	options: { zIndex?: number } = {}
+
+	/**
+	 * Create a new overlay util class with the given options merged in.
+	 *
+	 * @example
+	 * ```ts
+	 * const MyBrush = BrushOverlayUtil.configure({ fill: 'rgba(0,0,255,0.1)' })
+	 * ```
+	 *
+	 * @public
+	 */
+	static configure<T extends TLOverlayUtilConstructor<any>>(
+		this: T,
+		options: T extends new (...args: any[]) => { options: infer Options } ? Partial<Options> : never
+	): T {
+		// @ts-expect-error -- typescript has no idea what's going on here but it's fine
+		return class extends this {
+			// @ts-expect-error
+			options = { ...this.options, ...options }
+		}
+	}
+
+	/**
+	 * Whether this overlay util's overlays should currently be active.
+	 * Checked reactively to determine which overlays exist at any given time.
+	 */
+	abstract isActive(): boolean
+
+	/**
+	 * Returns the overlay instances that currently exist.
+	 * Called only when `isActive()` returns true.
+	 */
+	abstract getOverlays(): T[]
+
+	/**
+	 * Returns hit-test geometry for an overlay instance, in page coordinates.
+	 * Return null for non-interactive overlays (e.g. snap indicators, scribbles).
+	 */
+	getGeometry(_overlay: T): Geometry2d | null {
+		return null
+	}
+
+	/**
+	 * Returns the cursor type to show when hovering this overlay.
+	 */
+	getCursor(_overlay: T): TLCursorType | undefined {
+		return undefined
+	}
+
+	/**
+	 * Called when the user points down on this overlay, before the default
+	 * routing runs. Acts as an interrupt: define it to take over the event.
+	 *
+	 * Return `false` to continue with the default behavior (e.g. the
+	 * built-in rotate/resize handle transitions or shape-handle dispatch).
+	 * Return `true` — or nothing at all — to skip the default. In other
+	 * words, once you override this method you own the event unless you
+	 * explicitly opt back in by returning `false`.
+	 */
+	onPointerDown?(overlay: T, info: TLPointerEventInfo): boolean | void
+
+	/**
+	 * Render all active overlays into the canvas context.
+	 * The context is already transformed to page space (camera transform applied).
+	 * Called reactively when overlays or editor state changes.
+	 */
+	render(_ctx: CanvasRenderingContext2D, _overlays: T[]): void {}
+
+	/**
+	 * Optional: render all active overlays into the minimap canvas.
+	 * The context is already transformed to page space (minimap camera applied),
+	 * so overlays can use the same page-space coordinates as in {@link OverlayUtil.render}.
+	 *
+	 * `zoom` is the minimap's screen-pixels-per-page-unit, analogous to
+	 * `editor.getCamera().z`; use `1 / zoom` for one-minimap-pixel line widths.
+	 *
+	 * Most overlays should leave this blank — only overlays that are meaningful
+	 * at minimap scale (e.g. brushes, collaborator cursors) should opt in.
+	 */
+	renderMinimap(_ctx: CanvasRenderingContext2D, _overlays: T[], _zoom: number): void {}
+}