@tldraw/editor 5.3.0-canary.263f9dbe88bb → 5.3.0-canary.2deebf21bdcd

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

@@ -1,6 +1,12 @@
-import { Computed, RESET_VALUE, computed, isUninitialized } from '@tldraw/state'
+import {
+	Computed,
+	RESET_VALUE,
+	computed,
+	isUninitialized,
+	unsafe__withoutCapture,
+} from '@tldraw/state'
 import type { RecordsDiff } from '@tldraw/store'
-import { TLPageId, TLShape, TLShapeId, isShape } from '@tldraw/tlschema'
+import { TLPageId, TLShape, TLShapeId, isBinding, isPageId, isShape } from '@tldraw/tlschema'
 import type { TLRecord } from '@tldraw/tlschema'
 import { objectMapValues } from '@tldraw/utils'
 import { Box } from '../../../primitives/Box'
@@ -11,16 +17,24 @@ import { RBushIndex, type SpatialElement } from './RBushIndex'
  * Manages spatial indexing for efficient shape location queries.
  *
  * Uses an R-tree (via RBush) to enable O(log n) spatial queries instead of O(n) iteration.
- * Handles shapes with computed bounds (arrows, groups, custom shapes) by checking all shapes'
- * bounds on each update using the reactive bounds cache.
+ * Derived-bounds changes (arrows following bound shapes, groups resizing with children) are
+ * tracked structurally: each record diff is expanded into a dirty set covering the changed
+ * shapes' descendants, ancestors, and binding partners, and only those shapes' bounds are
+ * rechecked — O(affected) per update instead of O(page).
  *
  * Key features:
- * - Incremental updates using filterHistory pattern
- * - Leverages existing bounds cache reactivity for dependency tracking
- * - Works with any custom shape type with computed bounds
+ * - Incremental updates using filterHistory pattern (shape and binding history)
+ * - Dirty-set expansion via parent/child and binding relationships
  * - Per-page index (rebuilds on page change)
  * - Optimized for viewport culling queries
  *
+ * Known limitation: a custom shape whose geometry reads other shapes outside the
+ * parent/child and binding relationships is not rechecked when those shapes change.
+ * Core shapes only depend on other shapes via bindings (arrows) and parent/child
+ * relationships (groups), which are both covered. This narrows the previous
+ * approach, which rechecked every indexed shape on every update and so happened to
+ * cover such shapes; the structural expansion trades that for O(affected) updates.
+ *
  * @internal
  */
 export class SpatialIndexManager {
@@ -52,27 +66,28 @@ export class SpatialIndexManager {
 		const bindingHistory = this.editor.store.query.filterHistory('binding')
 
 		return computed<number>('spatialIndex', (_prevValue, lastComputedEpoch) => {
-			if (isUninitialized(_prevValue)) {
-				return this.rebuildAndBumpEpoch()
-			}
-
+			// These three reads are the computed's only tracked dependencies.
+			// Every input to a shape's page bounds is a shape or binding record,
+			// so the two histories cover all invalidation; the rebuild/update
+			// paths below run without capture to avoid registering a dependency
+			// per checked shape on every update (and ~page-size dependencies on
+			// every rebuild).
 			const shapeDiff = shapeHistory.getDiffSince(lastComputedEpoch)
 			const bindingDiff = bindingHistory.getDiffSince(lastComputedEpoch)
-
-			if (shapeDiff === RESET_VALUE || bindingDiff === RESET_VALUE) {
-				return this.rebuildAndBumpEpoch()
-			}
-
 			const currentPageId = this.editor.getCurrentPageId()
-			if (this.lastPageId !== currentPageId) {
-				return this.rebuildAndBumpEpoch()
+
+			if (
+				isUninitialized(_prevValue) ||
+				shapeDiff === RESET_VALUE ||
+				bindingDiff === RESET_VALUE ||
+				this.lastPageId !== currentPageId
+			) {
+				return unsafe__withoutCapture(() => this.rebuildAndBumpEpoch())
 			}
 
 			if (shapeDiff.length === 0 && bindingDiff.length === 0) return this._boundsEpoch
 
-			// A binding-only diff passes an empty shape diff: step 1 is a no-op
-			// and the step-2 sweep re-checks the indexed bounds of every shape.
-			if (this.processIncrementalUpdate(shapeDiff)) {
+			if (unsafe__withoutCapture(() => this.processIncrementalUpdate(shapeDiff, bindingDiff))) {
 				this._boundsEpoch++
 			}
 			return this._boundsEpoch
@@ -101,88 +116,160 @@ export class SpatialIndexManager {
 		this.rbush.bulkLoad(elements)
 	}
 
-	private processIncrementalUpdate(shapeDiff: RecordsDiff<TLRecord>[]): boolean {
-		const processedShapeIds = new Set<TLShapeId>()
-		let changed = false
+	private processIncrementalUpdate(
+		shapeDiff: RecordsDiff<TLRecord>[],
+		bindingDiff: RecordsDiff<TLRecord>[]
+	): boolean {
+		// Rbush mutations are collected and applied as one batch at the end so
+		// large updates can use a bulk rebuild instead of per-item tree ops.
+		const pendingRemoves = new Set<TLShapeId>()
+		const pendingUpserts: SpatialElement[] = []
+
+		// Shapes whose page transform may have moved (their record was added or
+		// updated). Their descendants' transforms move with them.
+		const transformChanged = new Set<TLShapeId>()
+		// Shapes whose page bounds need rechecking against the index.
+		const dirty = new Set<TLShapeId>()
+		// Subset of `dirty` not yet expanded into ancestors/binding partners.
+		const queue: TLShapeId[] = []
 
-		// Step 1: apply diff entries directly. `changed` flips only on real
-		// rbush mutations, so prop-only updates and no-op removes (e.g. shapes
-		// from other pages, or never-indexed shapes with invalid bounds) don't
-		// bump the epoch.
+		const markDirty = (id: TLShapeId) => {
+			if (!dirty.has(id)) {
+				dirty.add(id)
+				queue.push(id)
+			}
+		}
+
+		// Step 1: seed the dirty set from the record diffs.
 		for (const changes of shapeDiff) {
 			for (const shape of objectMapValues(changes.added) as TLShape[]) {
-				if (isShape(shape) && this.editor.getAncestorPageId(shape) === this.lastPageId) {
-					const bounds = this.editor.getShapePageBounds(shape.id)
-					if (bounds && bounds.isValid()) {
-						this.rbush.upsert(shape.id, bounds)
-						changed = true
-					}
-					processedShapeIds.add(shape.id)
-				}
+				if (!isShape(shape)) continue
+				transformChanged.add(shape.id)
+				markDirty(shape.id)
 			}
 
 			for (const shape of objectMapValues(changes.removed) as TLShape[]) {
-				if (isShape(shape)) {
-					if (this.rbush.has(shape.id)) {
-						this.rbush.remove(shape.id)
-						changed = true
-					}
-					processedShapeIds.add(shape.id)
+				if (!isShape(shape)) continue
+				if (this.rbush.has(shape.id)) {
+					pendingRemoves.add(shape.id)
 				}
+				// The old parent's derived bounds (groups) may shrink. Bindings
+				// involving the shape are deleted in the same transaction, so the
+				// binding diff below dirties the other ends.
+				if (!isPageId(shape.parentId)) markDirty(shape.parentId)
 			}
 
-			for (const [, to] of objectMapValues(changes.updated) as [TLShape, TLShape][]) {
+			for (const [from, to] of objectMapValues(changes.updated) as [TLShape, TLShape][]) {
 				if (!isShape(to)) continue
-				processedShapeIds.add(to.id)
-
-				const isOnPage = this.editor.getAncestorPageId(to) === this.lastPageId
-
-				if (isOnPage) {
-					const bounds = this.editor.getShapePageBounds(to.id)
-					if (bounds && bounds.isValid()) {
-						const indexedElement = this.rbush.getElement(to.id)
-						if (!this.areBoundsEqualToSpatialElement(bounds, indexedElement)) {
-							this.rbush.upsert(to.id, bounds)
-							changed = true
-						}
-					} else if (this.rbush.has(to.id)) {
-						this.rbush.remove(to.id)
-						changed = true
-					}
-				} else if (this.rbush.has(to.id)) {
-					this.rbush.remove(to.id)
-					changed = true
+				transformChanged.add(to.id)
+				markDirty(to.id)
+				// On reparent, the old ancestor chain needs rechecking too
+				if (isShape(from) && from.parentId !== to.parentId && !isPageId(from.parentId)) {
+					markDirty(from.parentId)
+				}
+			}
+		}
+
+		for (const changes of bindingDiff) {
+			for (const binding of objectMapValues(changes.added)) {
+				if (!isBinding(binding)) continue
+				markDirty(binding.fromId)
+				markDirty(binding.toId)
+			}
+			for (const binding of objectMapValues(changes.removed)) {
+				if (!isBinding(binding)) continue
+				markDirty(binding.fromId)
+				markDirty(binding.toId)
+			}
+			for (const [from, to] of objectMapValues(changes.updated)) {
+				if (!isBinding(to)) continue
+				markDirty(to.fromId)
+				markDirty(to.toId)
+				// A reassigned binding leaves its old endpoints needing a
+				// recheck too (mirrors the reparent case for shapes above).
+				if (isBinding(from) && (from.fromId !== to.fromId || from.toId !== to.toId)) {
+					markDirty(from.fromId)
+					markDirty(from.toId)
+				}
+			}
+		}
+
+		// Step 2: a moved record moves the page transforms of all its
+		// descendants, so their bounds need rechecking even though their
+		// records never changed. Expand before the fixpoint below so each
+		// descendant also gets its ancestors and binding partners visited.
+		const transformQueue = [...transformChanged]
+		while (transformQueue.length) {
+			const id = transformQueue.pop()!
+			for (const childId of this.editor.getSortedChildIdsForParent(id)) {
+				if (!transformChanged.has(childId)) {
+					transformChanged.add(childId)
+					transformQueue.push(childId)
 				}
+				markDirty(childId)
+			}
+		}
+
+		// Step 3: expand to a fixpoint. Any shape whose bounds may have changed
+		// can resize its ancestor groups and move arrows bound to it. A derived
+		// bounds change does not move the shape's own transform, so descendants
+		// are not affected by this expansion (only by step 2).
+		while (queue.length) {
+			const id = queue.pop()!
+
+			const record = this.editor.store.unsafeGetWithoutCapture(id)
+			if (record && isShape(record) && !isPageId(record.parentId)) {
+				markDirty(record.parentId)
+			}
+
+			for (const binding of this.editor.getBindingsInvolvingShape(id)) {
+				markDirty(binding.fromId)
+				markDirty(binding.toId)
 			}
 		}
 
-		// Step 2: must always run. Diff entries can dirty derived bounds —
-		// arrows bound to moved shapes, groups with moved children — without
-		// touching any record visited in step 1. Also catches outline-only
-		// changes (e.g. geo rectangle→ellipse at the same w/h) that shift a
-		// bound arrow's intersection points: step 1 sees the geo's
-		// axis-aligned bounds unchanged and skips, but the dependent arrow's
-		// bounds have moved.
-		//
-		// Iterating the rbush's element map directly avoids allocating a
-		// shape-id array per pointer move. Mutation here is limited to
-		// upserts of existing keys and deletions, both safe during Map
-		// iteration.
-		for (const [shapeId, indexedElement] of this.rbush.entries()) {
-			if (processedShapeIds.has(shapeId)) continue
-
-			const currentBounds = this.editor.getShapePageBounds(shapeId)
-			if (this.areBoundsEqualToSpatialElement(currentBounds, indexedElement)) continue
-
-			if (currentBounds && currentBounds.isValid()) {
-				this.rbush.upsert(shapeId, currentBounds)
-			} else {
-				this.rbush.remove(shapeId)
+		// Step 4: recheck only the dirty shapes' bounds. The batch stays empty
+		// on prop-only updates with unchanged bounds, so they don't bump the
+		// epoch.
+		for (const id of dirty) {
+			// A shape removed in an earlier diff entry may have been re-added in
+			// a later one; its pending removal means the indexed bounds no
+			// longer count.
+			const indexedElement = pendingRemoves.has(id) ? undefined : this.rbush.getElement(id)
+			const record = this.editor.store.unsafeGetWithoutCapture(id)
+
+			if (
+				!record ||
+				!isShape(record) ||
+				this.editor.getAncestorPageId(record) !== this.lastPageId
+			) {
+				if (this.rbush.has(id)) {
+					pendingRemoves.add(id)
+				}
+				continue
+			}
+
+			const bounds = this.editor.getShapePageBounds(id)
+			if (bounds && bounds.isValid()) {
+				if (!this.areBoundsEqualToSpatialElement(bounds, indexedElement)) {
+					pendingRemoves.delete(id)
+					pendingUpserts.push({
+						minX: bounds.minX,
+						minY: bounds.minY,
+						maxX: bounds.maxX,
+						maxY: bounds.maxY,
+						id,
+					})
+				}
+			} else if (this.rbush.has(id)) {
+				pendingRemoves.add(id)
 			}
-			changed = true
 		}
 
-		return changed
+		if (pendingRemoves.size === 0 && pendingUpserts.length === 0) return false
+
+		this.rbush.applyBatch(pendingRemoves, pendingUpserts)
+		return true
 	}
 
 	private areBoundsEqualToSpatialElement(

package/src/lib/editor/shapes/BaseFrameLikeShapeUtil.tsx

@@ -5,7 +5,7 @@ import { BaseBoxShapeUtil, TLBaseBoxShape } from './BaseBoxShapeUtil'
 import { TLDragShapesInInfo, TLDragShapesOutInfo } from './ShapeUtil'
 
 /**
- * A base class for frame-like shapes — containers that clip their children,
+ * A base class for frame-like shapes — containers that clip their children except arrows,
  * require full-brush selection, block erasure from inside, and support
  * drag-and-drop reparenting.
  *
@@ -17,6 +17,7 @@ import { TLDragShapesInInfo, TLDragShapesOutInfo } from './ShapeUtil'
  * - `canReceiveNewChildrenOfType()` returns `true` unless the container is locked
  * - `canRemoveChildrenOfType()` returns `true` unless the container is locked
  * - `getClipPath()` returns the shape geometry's vertices
+ * - `shouldClipChild()` clips all children except arrows
  * - `onDragShapesIn()` reparents shapes into the frame (with index restoration)
  * - `onDragShapesOut()` reparents shapes back to the page
  *
@@ -69,6 +70,10 @@ export abstract class BaseFrameLikeShapeUtil<
 		return this.editor.getShapeGeometry(shape.id).vertices
 	}
 
+	override shouldClipChild(child: TLShape): boolean {
+		return child.type !== 'arrow'
+	}
+
 	override onDragShapesIn(
 		shape: Shape,
 		draggingShapes: TLShape[],

package/src/lib/editor/types/emit-types.ts

@@ -6,6 +6,7 @@ import { TLEventInfo } from './event-types'
 export interface TLEventMap {
 	// Lifecycle / Internal
 	mount: []
+	unmount: []
 	'max-shapes': [{ name: string; pageId: TLPageId; count: number }]
 	change: [HistoryEntry<TLRecord>]
 	update: []

package/src/lib/options.ts

@@ -86,6 +86,7 @@ export interface TldrawOptions {
 	readonly collaboratorCheckIntervalMs: number
 	readonly cameraMovingTimeoutMs: number
 	readonly hitTestMargin: number
+	readonly coarseHitTestMargin: number
 	readonly edgeScrollDelay: number
 	readonly edgeScrollEaseDuration: number
 	readonly edgeScrollSpeed: number
@@ -312,7 +313,8 @@ export const defaultTldrawOptions = {
 	collaboratorIdleTimeoutMs: 3000,
 	collaboratorCheckIntervalMs: 1200,
 	cameraMovingTimeoutMs: 64,
-	hitTestMargin: 8,
+	hitTestMargin: 3,
+	coarseHitTestMargin: 4,
 	edgeScrollDelay: 200,
 	edgeScrollEaseDuration: 200,
 	edgeScrollSpeed: 25,

package/src/version.ts

@@ -1,9 +1,9 @@
 // This file is automatically generated by internal/scripts/refresh-assets.ts.
 // Do not edit manually. Or do, I'm a comment, not a cop.
 
-export const version = '5.3.0-canary.263f9dbe88bb'
+export const version = '5.3.0-canary.2deebf21bdcd'
 export const publishDates = {
 	major: '2026-05-06T16:28:18.473Z',
-	minor: '2026-07-01T09:30:40.438Z',
-	patch: '2026-07-01T09:30:40.438Z',
+	minor: '2026-07-09T17:39:43.688Z',
+	patch: '2026-07-09T17:39:43.688Z',
 }