refactor(editor): add CollaboratorsManager; split collaborator indicators (tldraw#8648)

In order to clean up a few rough edges from the OverlayUtil system
landed in tldraw#8633, this PR (a) encapsulates collaborator state in a new
manager, (b) gets remote-collaborator rendering out of the
local-indicator overlay util, and (c) makes `setCursor` cheap to call
from pointer-move hot paths.

### Concepts

| Term | Type | Meaning |
| ---- | ---- | ------- |
| `CollaboratorsManager` | class | Lives on `editor.collaborators`; owns
the visibility clock and exposes `getCollaborators*` queries |
| `CollaboratorShapeIndicatorOverlayUtil` | class | tldraw-package
overlay util that draws remote collaborators' selection indicators
(split out of `ShapeIndicatorOverlayUtil`) |
| `strokeShapeIndicators` | function | Shared canvas helper exported
from `@tldraw/editor`, used by both local and collaborator indicator
overlays |

### What changed

**`CollaboratorsManager`.** The visibility clock atom and the
collaborator-presence queries used to live directly on `Editor`. They
now live on a small dedicated manager, in the same style as
`ClickManager` / `EdgeScrollManager` / `FocusManager` etc. The
previously `@internal` `Editor._collaboratorVisibilityClock` is now a
private field on the manager. The four `Editor.getCollaborators*()`
methods stay as thin convenience wrappers that delegate to
`editor.collaborators.*` so existing callers don't break.

**Collaborator indicators split out.** `ShapeIndicatorOverlayUtil` (in
`@tldraw/editor`) used to also render remote collaborators' selected
shapes via a third `collaboratorIndicators` prop on its overlay. That
mixed two concerns: a generic editor-package util shouldn't know about
presence records. Remote-indicator rendering is now its own
`CollaboratorShapeIndicatorOverlayUtil` in `@tldraw/tldraw`, registered
ahead of the local indicator util in `defaultOverlayUtils` and given a
lower `zIndex` so local selection always paints on top. To avoid
duplicating the canvas drawing code, the stroke logic was extracted into
a public `strokeShapeIndicators(editor, ctx, shapeIds)` helper.

**`setCursor` equality guard.** `updateHoveredOverlayId` (and various
tool states) call `editor.setCursor(...)` from pointer-move handlers.
Without a guard, every pointer move builds a fresh cursor object, enters
a history batch, spreads instance state, and walks the validator before
the store deduplicates the no-op write. The guard short-circuits when
the requested `type`/`rotation` already match `instanceState.cursor`,
skipping all of that on the hot path. The store-level
`validateUsingKnownGoodVersion` dedup is still the source of truth —
this is purely a perf shortcut.

### Editor API

| Method / property | Description |
| ----------------- | ----------- |
| `editor.collaborators` | The `CollaboratorsManager` instance |
| `editor.collaborators.getCollaborators()` /
`getCollaboratorsOnCurrentPage()` / `getVisibleCollaborators()` /
`getVisibleCollaboratorsOnCurrentPage()` | Same shape as the existing
`Editor.getCollaborators*()` methods (which now delegate here) |
| `strokeShapeIndicators(editor, ctx, shapeIds)` | Strokes the indicator
path for each shape into the given 2D context. Uses the current stroke
style — set color/`lineWidth`/`globalAlpha` on the context first |
| `CollaboratorShapeIndicatorOverlayUtil` | New default overlay util in
`@tldraw/tldraw`. Subclass to customize remote-indicator rendering
independently of local selection |

### Change type

- [x] `api`

### Test plan

1. Run `yarn dev` and confirm local selection / hover / hint indicators
still render identically to before.
2. Open a multiplayer room (e.g. `yarn dev-app`); remote collaborators'
selections should render below your own selection if you both select the
same shape.
3. Move the pointer continuously over and off overlays — cursor should
still update correctly, with no visible regression in responsiveness.
4. Confirm `editor.collaborators.getVisibleCollaborators()` and
`editor.getVisibleCollaborators()` return identical results.

- [ ] Unit tests
- [ ] End to end tests

### Release notes

- Add `editor.collaborators` (`CollaboratorsManager`) owning the
collaborator visibility clock and presence queries.
`Editor.getCollaborators()` / `getCollaboratorsOnCurrentPage()` /
`getVisibleCollaborators()` / `getVisibleCollaboratorsOnCurrentPage()`
are unchanged and now delegate to it.
- Add `CollaboratorShapeIndicatorOverlayUtil` in `@tldraw/tldraw` for
remote-collaborator selection indicators (split out of
`ShapeIndicatorOverlayUtil`); add `strokeShapeIndicators` helper from
`@tldraw/editor` for sharing indicator rendering between overlay utils.
- `Editor.setCursor` now skips redundant writes when the requested
cursor type and rotation already match the current cursor.

### API changes

- Added `CollaboratorsManager` and `Editor.collaborators`.
- Added `strokeShapeIndicators(editor, ctx, shapeIds)`.
- Added `CollaboratorShapeIndicatorOverlayUtil` and
`TLCollaboratorShapeIndicatorOverlay` to `@tldraw/tldraw`; added it to
`defaultOverlayUtils` (registered before `ShapeIndicatorOverlayUtil`).
- Removed the `@internal` `Editor._collaboratorVisibilityClock` atom
(now private to `CollaboratorsManager`).
- Removed the `collaboratorIndicators` prop from
`TLShapeIndicatorOverlay`; remote-collaborator rendering moved to
`CollaboratorShapeIndicatorOverlayUtil`.

### Code changes

| Section         | LOC change |
| --------------- | ---------- |
| Core code       | +295 / -137 |
| Automated files | +43 / -7   |

Relates to tldraw#8633.

Made with [Cursor](https://cursor.com)

---------

Co-authored-by: Steve Ruiz <steveruizok@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

packages/editor/api-report.api.md

@@ -534,6 +534,15 @@ export class ClickManager {
 // @public
 export function clockwiseAngleDist(a0: number, a1: number): number;
 
+// @public
+export class CollaboratorsManager {
+    constructor(editor: Editor);
+    getCollaborators(): TLInstancePresence[];
+    getCollaboratorsOnCurrentPage(): TLInstancePresence[];
+    getVisibleCollaborators(): TLInstancePresence[];
+    getVisibleCollaboratorsOnCurrentPage(): TLInstancePresence[];
+}
+
 // @public (undocumented)
 export function ContainerProvider({ container, children }: ContainerProviderProps): JSX.Element;
 
@@ -911,8 +920,7 @@ export class Editor extends EventEmitter<TLEventMap> {
     clearHistory(): this;
     // @internal
     protected _clickManager: ClickManager;
-    // @internal (undocumented)
-    readonly _collaboratorVisibilityClock: Atom<number, unknown>;
+    readonly collaborators: CollaboratorsManager;
     complete(): this;
     // (undocumented)
     readonly contextId: string;
@@ -3261,6 +3269,9 @@ export const stopEventPropagation: (e: any) => any;
 // @internal (undocumented)
 export type StoreName = (typeof Table)[keyof typeof Table];
 
+// @public
+export function strokeShapeIndicators(editor: Editor, ctx: CanvasRenderingContext2D, shapeIds: TLShapeId[]): void;
+
 // @public (undocumented)
 export function suffixSafeId(id: SafeId, suffix: string): SafeId;
 
@@ -4600,10 +4611,6 @@ export type TLShapeErrorFallbackComponent = ComponentType<{
 export interface TLShapeIndicatorOverlay extends TLOverlay {
     // (undocumented)
     props: {
-        collaboratorIndicators: Array<{
-            color: string;
-            shapeIds: TLShapeId[];
-        }>;
         hintingShapeIds: TLShapeId[];
         idsToDisplay: TLShapeId[];
     };

packages/editor/src/index.ts

@@ -136,6 +136,7 @@ export {
 export { DEFAULT_THEME } from './lib/editor/managers/ThemeManager/defaultThemes'
 export { ThemeManager, resolveThemes } from './lib/editor/managers/ThemeManager/ThemeManager'
 export { TickManager } from './lib/editor/managers/TickManager/TickManager'
+export { CollaboratorsManager } from './lib/editor/managers/CollaboratorsManager/CollaboratorsManager'
 export { PerformanceApiAdapter } from './lib/editor/managers/PerformanceManager/PerformanceApiAdapter'
 export { PerformanceManager } from './lib/editor/managers/PerformanceManager/PerformanceManager'
 export {
@@ -182,6 +183,7 @@ export {
 } from './lib/editor/overlays/OverlayUtil'
 export {
 	ShapeIndicatorOverlayUtil,
+	strokeShapeIndicators,
 	type TLShapeIndicatorOverlay,
 } from './lib/editor/overlays/ShapeIndicatorOverlayUtil'
 export {

packages/editor/src/lib/editor/Editor.ts

@@ -89,7 +89,6 @@ import {
 	hasOwnProperty,
 	last,
 	lerp,
-	maxBy,
 	minBy,
 	sortById,
 	sortByIndex,
@@ -132,10 +131,6 @@ import { PI, approximately, areAnglesCompatible, clamp, pointInPolygon } from '.
 import { Vec, VecLike } from '../primitives/Vec'
 import { areShapesContentEqual } from '../utils/areShapesContentEqual'
 import { dataUrlToFile } from '../utils/assets'
-import {
-	getCollaboratorStateFromElapsedTime,
-	shouldShowCollaborator,
-} from '../utils/collaboratorState'
 import { debugFlags } from '../utils/debug-flags'
 import {
 	TLDeepLink,
@@ -156,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'
@@ -422,9 +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.timers.setInterval(() => {
-			this._collaboratorVisibilityClock.set(Date.now())
-		}, this.options.collaboratorCheckIntervalMs)
+		this.collaborators = new CollaboratorsManager(this)
 
 		class NewRoot extends RootState {
 			static override initial = initialState ?? ''
@@ -1057,8 +1051,12 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 */
 	readonly timers = tltime.forContext(this.contextId)
 
-	/** @internal */
-	readonly _collaboratorVisibilityClock = atom('collaboratorVisibilityClock', Date.now())
+	/**
+	 * A manager for remote peer collaborators connected to this editor.
+	 *
+	 * @public
+	 */
+	readonly collaborators: CollaboratorsManager
 
 	/**
 	 * A manager for the user and their preferences.
@@ -1946,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
 	}
 
@@ -4256,43 +4266,28 @@ 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()
 	}
 
 	/**
@@ -4302,29 +4297,24 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 * 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
 	 */
-	@computed
 	getVisibleCollaborators() {
-		this._collaboratorVisibilityClock.get()
-		const now = Date.now()
-		return this.getCollaborators().filter((presence) => {
-			const elapsed = Math.max(0, now - (presence.lastActivityTimestamp ?? Infinity))
-			const state = getCollaboratorStateFromElapsedTime(this, elapsed)
-			return shouldShowCollaborator(this, presence, state)
-		})
+		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
 	 */
-	@computed
 	getVisibleCollaboratorsOnCurrentPage() {
-		const currentPageId = this.getCurrentPageId()
-		return this.getVisibleCollaborators().filter((c) => c.currentPageId === currentPageId)
+		return this.collaborators.getVisibleCollaboratorsOnCurrentPage()
 	}
 
 	// Attribution

packages/editor/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)
+	}
+}