@tldraw/editor 3.14.0-canary.26943ba45368 → 3.14.0-canary.2f3caa391d5d

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/editor",
   "description": "A tiny little drawing app (editor).",
-  "version": "3.14.0-canary.26943ba45368",
+  "version": "3.14.0-canary.2f3caa391d5d",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
@@ -48,20 +48,19 @@
     "@tiptap/core": "^2.9.1",
     "@tiptap/pm": "^2.9.1",
     "@tiptap/react": "^2.9.1",
-    "@tldraw/state": "3.14.0-canary.26943ba45368",
-    "@tldraw/state-react": "3.14.0-canary.26943ba45368",
-    "@tldraw/store": "3.14.0-canary.26943ba45368",
-    "@tldraw/tlschema": "3.14.0-canary.26943ba45368",
-    "@tldraw/utils": "3.14.0-canary.26943ba45368",
-    "@tldraw/validate": "3.14.0-canary.26943ba45368",
+    "@tldraw/state": "3.14.0-canary.2f3caa391d5d",
+    "@tldraw/state-react": "3.14.0-canary.2f3caa391d5d",
+    "@tldraw/store": "3.14.0-canary.2f3caa391d5d",
+    "@tldraw/tlschema": "3.14.0-canary.2f3caa391d5d",
+    "@tldraw/utils": "3.14.0-canary.2f3caa391d5d",
+    "@tldraw/validate": "3.14.0-canary.2f3caa391d5d",
     "@types/core-js": "^2.5.8",
     "@use-gesture/react": "^10.3.1",
     "classnames": "^2.5.1",
     "core-js": "^3.40.0",
     "eventemitter3": "^4.0.7",
     "idb": "^7.1.1",
-    "is-plain-object": "^5.0.0",
-    "lodash.isequal": "^4.5.0"
+    "is-plain-object": "^5.0.0"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.0.0",

package/src/index.ts

@@ -147,15 +147,18 @@ export {
 	type BindingOnShapeIsolateOptions,
 	type TLBindingUtilConstructor,
 } from './lib/editor/bindings/BindingUtil'
-export { ClickManager, type TLClickState } from './lib/editor/managers/ClickManager'
-export { EdgeScrollManager } from './lib/editor/managers/EdgeScrollManager'
+export { ClickManager, type TLClickState } from './lib/editor/managers/ClickManager/ClickManager'
+export { EdgeScrollManager } from './lib/editor/managers/EdgeScrollManager/EdgeScrollManager'
 export {
 	FontManager,
 	type TLFontFace,
 	type TLFontFaceSource,
-} from './lib/editor/managers/FontManager'
-export { HistoryManager } from './lib/editor/managers/HistoryManager'
-export { ScribbleManager, type ScribbleItem } from './lib/editor/managers/ScribbleManager'
+} from './lib/editor/managers/FontManager/FontManager'
+export { HistoryManager } from './lib/editor/managers/HistoryManager/HistoryManager'
+export {
+	ScribbleManager,
+	type ScribbleItem,
+} from './lib/editor/managers/ScribbleManager/ScribbleManager'
 export {
 	BoundsSnaps,
 	type BoundsSnapGeometry,
@@ -169,8 +172,11 @@ export {
 	type SnapData,
 	type SnapIndicator,
 } from './lib/editor/managers/SnapManager/SnapManager'
-export { TextManager, type TLMeasureTextSpanOpts } from './lib/editor/managers/TextManager'
-export { UserPreferencesManager } from './lib/editor/managers/UserPreferencesManager'
+export {
+	TextManager,
+	type TLMeasureTextSpanOpts,
+} from './lib/editor/managers/TextManager/TextManager'
+export { UserPreferencesManager } from './lib/editor/managers/UserPreferencesManager/UserPreferencesManager'
 export { BaseBoxShapeUtil, type TLBaseBoxShape } from './lib/editor/shapes/BaseBoxShapeUtil'
 export {
 	ShapeUtil,

package/src/lib/config/TLSessionStateSnapshot.ts

@@ -14,12 +14,12 @@ import {
 import {
 	deleteFromSessionStorage,
 	getFromSessionStorage,
+	isEqual,
 	setInSessionStorage,
 	structuredClone,
 	uniqueId,
 } from '@tldraw/utils'
 import { T } from '@tldraw/validate'
-import isEqual from 'lodash.isequal'
 import { tlenv } from '../globals/environment'
 
 const tabIdKey = 'TLDRAW_TAB_ID_v2' as const

package/src/lib/editor/Editor.test.ts

@@ -17,6 +17,7 @@ type ICustomShape = TLBaseShape<
 		w: number
 		h: number
 		text: string | undefined
+		isFilled: boolean
 	}
 >
 
@@ -26,19 +27,21 @@ class CustomShape extends ShapeUtil<ICustomShape> {
 		w: T.number,
 		h: T.number,
 		text: T.string.optional(),
+		isFilled: T.boolean,
 	}
 	getDefaultProps(): ICustomShape['props'] {
 		return {
 			w: 200,
 			h: 200,
 			text: '',
+			isFilled: false,
 		}
 	}
 	getGeometry(shape: ICustomShape): Geometry2d {
 		return new Rectangle2d({
 			width: shape.props.w,
 			height: shape.props.h,
-			isFilled: true,
+			isFilled: shape.props.isFilled,
 		})
 	}
 	indicator() {}
@@ -81,11 +84,11 @@ describe('updateShape', () => {
 			props: { w: 100, h: 100, text: 'Hello' },
 		})
 		const shape = editor.getShape(id) as ICustomShape
-		expect(shape.props).toEqual({ w: 100, h: 100, text: 'Hello' })
+		expect(shape.props).toEqual({ w: 100, h: 100, text: 'Hello', isFilled: false })
 
 		editor.updateShape({ ...shape, props: { ...shape.props, text: undefined } })
 		const updatedShape = editor.getShape(id) as ICustomShape
-		expect(updatedShape.props).toEqual({ w: 100, h: 100, text: undefined })
+		expect(updatedShape.props).toEqual({ w: 100, h: 100, text: undefined, isFilled: false })
 	})
 })
 
@@ -176,3 +179,249 @@ describe('zoomToBounds', () => {
 		expect(editor.setCamera).toHaveBeenCalled()
 	})
 })
+
+describe('getShapesAtPoint', () => {
+	const ids = {
+		shape1: createShapeId('shape1'),
+		shape2: createShapeId('shape2'),
+		shape3: createShapeId('shape3'),
+		shape4: createShapeId('shape4'),
+		shape5: createShapeId('shape5'),
+		overlap1: createShapeId('overlap1'),
+		overlap2: createShapeId('overlap2'),
+		filledShape: createShapeId('filledShape'),
+		hollowShape: createShapeId('hollowShape'),
+		hiddenShape: createShapeId('hiddenShape'),
+	}
+
+	beforeEach(() => {
+		// Create test shapes with different z-index positions
+		// Shape 1: Bottom layer, large square
+		editor.createShape({
+			id: ids.shape1,
+			type: 'my-custom-shape',
+			x: 0,
+			y: 0,
+			props: { w: 200, h: 200, text: 'Bottom' },
+		})
+
+		// Shape 2: Middle layer, overlapping square
+		editor.createShape({
+			id: ids.shape2,
+			type: 'my-custom-shape',
+			x: 100,
+			y: 0,
+			props: { w: 200, h: 200, text: 'Middle' },
+		})
+
+		// Shape 3: Top layer, small square
+		editor.createShape({
+			id: ids.shape3,
+			type: 'my-custom-shape',
+			x: 50,
+			y: 50,
+			props: { w: 100, h: 100, text: 'Top' },
+		})
+
+		// Shape 4: Separate area, no overlap
+		editor.createShape({
+			id: ids.shape4,
+			type: 'my-custom-shape',
+			x: 50,
+			y: 100,
+			props: { w: 100, h: 100, text: 'Separate' },
+		})
+	})
+
+	it('returns shapes at a point in reverse z-index order', () => {
+		// Point at (50, 50) should hit shape3's edge (since it's at 50,50 with size 100x100)
+		// This point is exactly at the top-left corner of shape3
+		const shapes = editor.getShapesAtPoint({ x: 50, y: 50 })
+		const shapeIds = shapes.map((s) => s.id)
+
+		expect(shapeIds).toEqual([ids.shape3])
+		expect(shapes).toHaveLength(1)
+	})
+
+	it('returns empty array when no shapes at point', () => {
+		const shapes = editor.getShapesAtPoint({ x: 1000, y: 1000 })
+		expect(shapes).toEqual([])
+	})
+
+	it('returns single shape when point hits only one shape', () => {
+		// Point at right edge of shape2 where it doesn't overlap with other shapes
+		// Shape2 is at (100,0) with size 200x200, so right edge is at x=300
+		const shapes = editor.getShapesAtPoint({ x: 300, y: 100 })
+		expect(shapes).toHaveLength(1)
+		expect(shapes[0].id).toBe(ids.shape2)
+	})
+
+	it('returns shapes on edge when point is exactly on boundary', () => {
+		// Point at exact edge of shape1
+		const shapes = editor.getShapesAtPoint({ x: 0, y: 0 })
+		expect(shapes).toHaveLength(1)
+		expect(shapes[0].id).toBe(ids.shape1)
+	})
+
+	it('respects hitInside option when false (default)', () => {
+		// Point inside shape1 (at 0,0 with size 200x200) but with hitInside false should not hit
+		const shapes = editor.getShapesAtPoint({ x: 25, y: 25 }, { hitInside: false })
+		expect(shapes).toEqual([])
+	})
+
+	it('respects hitInside option when true', () => {
+		// Point inside shape1 (at 0,0 with size 200x200) with hitInside true should hit
+		const shapes = editor.getShapesAtPoint({ x: 25, y: 25 }, { hitInside: true })
+		expect(shapes).toHaveLength(1)
+		expect(shapes[0].id).toBe(ids.shape1)
+	})
+
+	it('respects margin option', () => {
+		// Point slightly outside shape1 at bottom edge but within margin should hit only shape1
+		// Shape1 is at (0,0) with size 200x200, shape2 goes to (300,200) so avoid overlap at (200,200)
+		const shapes = editor.getShapesAtPoint({ x: 205, y: 100 }, { margin: 10 })
+		expect(shapes).toHaveLength(1)
+		expect(shapes[0].id).toBe(ids.shape1)
+	})
+
+	it('filters out hidden shapes', () => {
+		// Create a spy to mock isShapeHidden
+		const isShapeHiddenSpy = jest.spyOn(editor, 'isShapeHidden')
+		isShapeHiddenSpy.mockImplementation((shape) => {
+			return typeof shape === 'string' ? shape === ids.shape3 : shape.id === ids.shape3
+		})
+
+		const shapes = editor.getShapesAtPoint({ x: 50, y: 50 })
+		const shapeIds = shapes.map((s) => s.id)
+
+		// Should not include shape3 since it's hidden, and no other shapes are at this point
+		expect(shapeIds).toEqual([])
+		expect(shapes).toHaveLength(0)
+
+		isShapeHiddenSpy.mockRestore()
+	})
+
+	it('handles point exactly at shape corner', () => {
+		// Point at bottom-left corner of shape1 where it doesn't overlap with other shapes
+		const shapes = editor.getShapesAtPoint({ x: 0, y: 200 })
+		expect(shapes).toHaveLength(1)
+		expect(shapes[0].id).toBe(ids.shape1)
+	})
+
+	it('handles overlapping shapes with different hit areas', () => {
+		// Point that hits both shape1 and shape2 edges (they overlap at x=100,y=0)
+		const shapes = editor.getShapesAtPoint({ x: 100, y: 0 })
+		const shapeIds = shapes.map((s) => s.id)
+
+		// Both shapes should be detected at this overlapping point (reversed order - top-most first)
+		expect(shapeIds).toEqual([ids.shape2, ids.shape1])
+		expect(shapes).toHaveLength(2)
+	})
+
+	it('maintains reverse shape order and responds to z-index changes', () => {
+		// Create filled shape that overlaps with shape2
+		editor.createShape({
+			id: ids.shape5,
+			type: 'my-custom-shape',
+			x: 110,
+			y: 110,
+			props: { w: 200, h: 200, isFilled: true, text: 'Shape5' },
+		})
+
+		// Test with hitInside to detect multiple shapes
+		// Point (120,120) will hit shape1, shape2, shape3, shape4, and shape5 with hitInside: true
+		const shapes = editor.getShapesAtPoint({ x: 120, y: 120 }, { hitInside: true })
+		const shapeIds = shapes.map((s) => s.id)
+
+		// All shapes that contain this point should be returned in reverse z-index order (top-most first)
+		expect(shapeIds).toEqual([ids.shape5, ids.shape4, ids.shape3, ids.shape2, ids.shape1])
+
+		// After bringing shape2 to front, order should change (shape2 becomes top-most)
+		editor.bringToFront([ids.shape2])
+		const shapes2 = editor.getShapesAtPoint({ x: 120, y: 120 }, { hitInside: true })
+		const shapeIds2 = shapes2.map((s) => s.id)
+		expect(shapeIds2).toEqual([ids.shape2, ids.shape5, ids.shape4, ids.shape3, ids.shape1])
+	})
+
+	it('combines hitInside and margin options', () => {
+		// Point inside shape1 (at 0,0 with size 200x200) with hitInside and margin
+		const shapes = editor.getShapesAtPoint({ x: 25, y: 25 }, { hitInside: true, margin: 5 })
+		expect(shapes).toHaveLength(1)
+		expect(shapes[0].id).toBe(ids.shape1)
+	})
+
+	it('returns empty array when all shapes are hidden', () => {
+		// Mock all shapes as hidden
+		const isShapeHiddenSpy = jest.spyOn(editor, 'isShapeHidden')
+		isShapeHiddenSpy.mockReturnValue(true)
+
+		const shapes = editor.getShapesAtPoint({ x: 50, y: 50 })
+		expect(shapes).toEqual([])
+
+		isShapeHiddenSpy.mockRestore()
+	})
+
+	it('returns multiple shapes at same point in reverse z-index order', () => {
+		// Create two shapes at exactly the same position (away from existing shapes)
+		editor.createShape({
+			id: ids.overlap1,
+			type: 'my-custom-shape',
+			x: 600,
+			y: 600,
+			props: { w: 100, h: 100, text: 'First' },
+		})
+
+		editor.createShape({
+			id: ids.overlap2,
+			type: 'my-custom-shape',
+			x: 600,
+			y: 600,
+			props: { w: 100, h: 100, text: 'Second' },
+		})
+
+		// Test at corner where both shapes' edges meet
+		const shapes = editor.getShapesAtPoint({ x: 600, y: 600 })
+		const shapeIds = shapes.map((s) => s.id)
+
+		// Should return both shapes in reverse z-index order (top-most first)
+		expect(shapeIds).toEqual([ids.overlap2, ids.overlap1])
+		expect(shapes).toHaveLength(2)
+	})
+
+	it('respects isFilled property for hit detection', () => {
+		// Create a filled shape
+		editor.createShape({
+			id: ids.filledShape,
+			type: 'my-custom-shape',
+			x: 300,
+			y: 300,
+			props: { w: 100, h: 100, isFilled: true, text: 'Filled' },
+		})
+
+		// Create a hollow shape at the same position
+		editor.createShape({
+			id: ids.hollowShape,
+			type: 'my-custom-shape',
+			x: 400,
+			y: 300,
+			props: { w: 100, h: 100, isFilled: false, text: 'Hollow' },
+		})
+
+		// Test point inside filled shape - should hit without hitInside option
+		const filledShapes = editor.getShapesAtPoint({ x: 350, y: 350 })
+		expect(filledShapes).toHaveLength(1)
+		expect(filledShapes[0].id).toBe(ids.filledShape)
+
+		// Test point inside hollow shape - should not hit without hitInside option
+		const hollowShapes = editor.getShapesAtPoint({ x: 450, y: 350 })
+		expect(hollowShapes).toHaveLength(0)
+
+		// Test point inside hollow shape with hitInside - should hit
+		const hollowShapesWithHitInside = editor.getShapesAtPoint(
+			{ x: 450, y: 350 },
+			{ hitInside: true }
+		)
+		expect(hollowShapesWithHitInside).toHaveLength(1)
+		expect(hollowShapesWithHitInside[0].id).toBe(ids.hollowShape)
+	})
+})

package/src/lib/editor/Editor.ts

@@ -148,16 +148,16 @@ import { bindingsIndex } from './derivations/bindingsIndex'
 import { notVisibleShapes } from './derivations/notVisibleShapes'
 import { parentsToChildren } from './derivations/parentsToChildren'
 import { deriveShapeIdsInCurrentPage } from './derivations/shapeIdsInCurrentPage'
-import { ClickManager } from './managers/ClickManager'
-import { EdgeScrollManager } from './managers/EdgeScrollManager'
-import { FocusManager } from './managers/FocusManager'
-import { FontManager } from './managers/FontManager'
-import { HistoryManager } from './managers/HistoryManager'
-import { ScribbleManager } from './managers/ScribbleManager'
+import { ClickManager } from './managers/ClickManager/ClickManager'
+import { EdgeScrollManager } from './managers/EdgeScrollManager/EdgeScrollManager'
+import { FocusManager } from './managers/FocusManager/FocusManager'
+import { FontManager } from './managers/FontManager/FontManager'
+import { HistoryManager } from './managers/HistoryManager/HistoryManager'
+import { ScribbleManager } from './managers/ScribbleManager/ScribbleManager'
 import { SnapManager } from './managers/SnapManager/SnapManager'
-import { TextManager } from './managers/TextManager'
-import { TickManager } from './managers/TickManager'
-import { UserPreferencesManager } from './managers/UserPreferencesManager'
+import { TextManager } from './managers/TextManager/TextManager'
+import { TickManager } from './managers/TickManager/TickManager'
+import { UserPreferencesManager } from './managers/UserPreferencesManager/UserPreferencesManager'
 import { ShapeUtil, TLGeometryOpts, TLResizeMode } from './shapes/ShapeUtil'
 import { RootState } from './tools/RootState'
 import { StateNode, TLStateNodeConstructor } from './tools/StateNode'
@@ -328,7 +328,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 		this.store = store
 		this.history = new HistoryManager<TLRecord>({
 			store,
-			annotateError: (error) => {
+			annotateError: (error: any) => {
 				this.annotateError(error, { origin: 'history.batch', willCrashApp: true })
 				this.crash(error)
 			},
@@ -512,6 +512,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 									binding,
 									shapeBefore,
 									shapeAfter,
+									reason: 'self',
 								})
 							}
 							if (binding.toId === shapeAfter.id) {
@@ -519,6 +520,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 									binding,
 									shapeBefore,
 									shapeAfter,
+									reason: 'self',
 								})
 							}
 						}
@@ -537,6 +539,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 											binding,
 											shapeBefore: descendantShape,
 											shapeAfter: descendantShape,
+											reason: 'ancestry',
 										})
 									}
 									if (binding.toId === descendantShape.id) {
@@ -544,6 +547,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 											binding,
 											shapeBefore: descendantShape,
 											shapeAfter: descendantShape,
+											reason: 'ancestry',
 										})
 									}
 								}
@@ -3715,10 +3719,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 */
 	@computed getViewportScreenCenter() {
 		const viewportScreenBounds = this.getViewportScreenBounds()
-		return new Vec(
-			viewportScreenBounds.midX - viewportScreenBounds.minX,
-			viewportScreenBounds.midY - viewportScreenBounds.minY
-		)
+		return new Vec(viewportScreenBounds.w / 2, viewportScreenBounds.h / 2)
 	}
 
 	/**
@@ -4644,44 +4645,6 @@ export class Editor extends EventEmitter<TLEventMap> {
 		)! as T
 	}
 
-	private _shapePageGeometryCaches: Record<string, ComputedCache<Geometry2d, TLShape>> = {}
-
-	/**
-	 * Get the geometry of a shape in page-space.
-	 *
-	 * @example
-	 * ```ts
-	 * editor.getShapePageGeometry(myShape)
-	 * editor.getShapePageGeometry(myShapeId)
-	 * editor.getShapePageGeometry(myShapeId, { context: "arrow" })
-	 * ```
-	 *
-	 * @param shape - The shape (or shape id) to get the geometry for.
-	 * @param opts - Additional options about the request for geometry. Passed to {@link ShapeUtil.getGeometry}.
-	 *
-	 * @public
-	 */
-	getShapePageGeometry<T extends Geometry2d>(shape: TLShape | TLShapeId, opts?: TLGeometryOpts): T {
-		const context = opts?.context ?? 'none'
-		if (!this._shapePageGeometryCaches[context]) {
-			this._shapePageGeometryCaches[context] = this.store.createComputedCache(
-				'bounds',
-				(shape) => {
-					const geometry = this.getShapeGeometry(shape.id, opts)
-					const pageTransform = this.getShapePageTransform(shape.id)
-					return geometry.transform(pageTransform)
-				},
-				{
-					// we only depend directly on the shape id, and changing geometry/transform will update us anyway
-					areRecordsEqual: () => true,
-				}
-			)
-		}
-		return this._shapePageGeometryCaches[context].get(
-			typeof shape === 'string' ? shape : shape.id
-		)! as T
-	}
-
 	/** @internal */
 	@computed private _getShapeHandlesCache(): ComputedCache<TLHandle[] | undefined, TLShape> {
 		return this.store.createComputedCache(
@@ -4794,7 +4757,10 @@ export class Editor extends EventEmitter<TLEventMap> {
 	/** @internal */
 	@computed private _getShapePageBoundsCache(): ComputedCache<Box, TLShape> {
 		return this.store.createComputedCache<Box, TLShape>('pageBoundsCache', (shape) => {
-			return this.getShapePageGeometry(shape).bounds
+			const pageTransform = this.getShapePageTransform(shape)
+			if (!pageTransform) return undefined
+			const geometry = this.getShapeGeometry(shape)
+			return Box.FromPoints(pageTransform.applyToPoints(geometry.vertices))
 		})
 	}
 
@@ -4868,11 +4834,12 @@ export class Editor extends EventEmitter<TLEventMap> {
 			if (frameAncestors.length === 0) return undefined
 
 			const pageMask = frameAncestors
-				.map<Vec[] | undefined>(
-					(s) =>
-						// Apply the frame transform to the frame outline to get the frame outline in the current page space
-						this.getShapePageGeometry(s.id).vertices
-				)
+				.map<Vec[] | undefined>((s) => {
+					// Apply the frame transform to the frame outline to get the frame outline in the current page space
+					const geometry = this.getShapeGeometry(s.id)
+					const pageTransform = this.getShapePageTransform(s.id)
+					return pageTransform.applyToPoints(geometry.vertices)
+				})
 				.reduce((acc, b) => {
 					if (!(b && acc)) return undefined
 					const intersection = intersectPolygonPolygon(acc, b)
@@ -5070,28 +5037,33 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 *
 	 * @public
 	 */
-	isShapeOrAncestorLocked(shape?: TLShape): boolean
-	isShapeOrAncestorLocked(id?: TLShapeId): boolean
-	isShapeOrAncestorLocked(arg?: TLShape | TLShapeId): boolean {
-		const shape = typeof arg === 'string' ? this.getShape(arg) : arg
-		if (shape === undefined) return false
-		if (shape.isLocked) return true
-		return this.isShapeOrAncestorLocked(this.getShapeParent(shape))
+	isShapeOrAncestorLocked(shape?: TLShape | TLShapeId): boolean {
+		const _shape = shape && this.getShape(shape)
+		if (_shape === undefined) return false
+		if (_shape.isLocked) return true
+		return this.isShapeOrAncestorLocked(this.getShapeParent(_shape))
 	}
 
+	/**
+	 * Get shapes that are outside of the viewport.
+	 *
+	 * @public
+	 */
 	@computed
-	private _notVisibleShapes() {
-		return notVisibleShapes(this)
+	getNotVisibleShapes() {
+		return this._notVisibleShapes.get()
 	}
 
+	private _notVisibleShapes = notVisibleShapes(this)
+
 	/**
-	 * Get culled shapes.
+	 * Get culled shapes (those that should not render), taking into account which shapes are selected or editing.
 	 *
 	 * @public
 	 */
 	@computed
 	getCulledShapes() {
-		const notVisibleShapes = this._notVisibleShapes().get()
+		const notVisibleShapes = this.getNotVisibleShapes()
 		const selectedShapeIds = this.getSelectedShapeIds()
 		const editingId = this.getEditingShapeId()
 		const culledShapes = new Set<TLShapeId>(notVisibleShapes)
@@ -5340,21 +5312,23 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 * @example
 	 * ```ts
 	 * editor.getShapesAtPoint({ x: 100, y: 100 })
-	 * editor.getShapesAtPoint({ x: 100, y: 100 }, { hitInside: true, exact: true })
+	 * editor.getShapesAtPoint({ x: 100, y: 100 }, { hitInside: true, margin: 8 })
 	 * ```
 	 *
 	 * @param point - The page point to test.
 	 * @param opts - The options for the hit point testing.
 	 *
+	 * @returns An array of shapes at the given point, sorted in reverse order of their absolute z-index (top-most shape first).
+	 *
 	 * @public
 	 */
 	getShapesAtPoint(
 		point: VecLike,
 		opts = {} as { margin?: number; hitInside?: boolean }
 	): TLShape[] {
-		return this.getCurrentPageShapes().filter(
-			(shape) => !this.isShapeHidden(shape) && this.isPointInShape(shape, point, opts)
-		)
+		return this.getCurrentPageShapesSorted()
+			.filter((shape) => !this.isShapeHidden(shape) && this.isPointInShape(shape, point, opts))
+			.reverse()
 	}
 
 	/**
@@ -9303,6 +9277,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 			if (rootShapes.length === 1) {
 				const onlyRoot = rootShapes[0] as TLFrameShape
 				// If the old bounds are in the viewport...
+				// todo: replace frame references with shapes that can accept children
 				if (this.isShapeOfType<TLFrameShape>(onlyRoot, 'frame')) {
 					while (
 						this.getShapesAtPoint(point).some(

package/src/lib/editor/bindings/BindingUtil.ts

@@ -62,6 +62,12 @@ export interface BindingOnShapeChangeOptions<Binding extends TLUnknownBinding> {
 	shapeBefore: TLShape
 	/** The shape record after the change is made. */
 	shapeAfter: TLShape
+	/**
+	 * Why did this shape change?
+	 * - 'self': the shape itself changed
+	 * - 'ancestry': the ancestry of the shape changed, but the shape itself may not have done
+	 */
+	reason: 'self' | 'ancestry'
 }
 
 /**