fix(editor): keep focal point fixed when clamping zoom to min/max (tldraw#8957)

Thinks this works better than preserving the center, wdyt @steveruizok?

In order to stop the viewport from shifting when a zoom gesture
overshoots the zoom limits, this PR makes `getConstrainedCamera`
preserve the caller's focal point (e.g. the cursor) when it clamps the
zoom, instead of snapping back to the viewport center. Closes tldraw#8942.

When you wheel/pinch zoom out past the minimum (or in past the maximum),
the gesture computes a camera that keeps the point under the cursor
fixed at the *requested* zoom. The old code then clamped the zoom and
re-derived `x`/`y` to keep the viewport *center* fixed, discarding the
cursor anchor — so the canvas visibly jumped. Now the clamped camera
keeps the same focal point fixed. When that focal point happens to be
the viewport center (e.g. the zoom-out button), the math reduces to the
previous center-preserving behaviour, so nothing else changes.
`zoomIn`/`zoomOut` are unaffected because they snap exactly onto zoom
steps and never overshoot.

### Before


https://github.com/user-attachments/assets/0cc13c03-2ea5-4642-bcf4-2c5f62e57e4d

### After



https://github.com/user-attachments/assets/b800a301-b101-4e98-8303-3e5801b7bbeb


### Change type

- [x] `bugfix`

### Test plan

1. Open the editor at any zoom level with the pointer away from the
screen center.
2. Wheel- or pinch-zoom out until the zoom clamps at the minimum.
3. The point under the cursor should stay put as the zoom hits the
limit; further zoom-out gestures should not move the canvas.
4. Repeat zooming in past the maximum.

- [x] Unit tests

### Release notes

- Fix the viewport shifting slightly when zooming past the minimum or
maximum zoom level.

### Code changes

| Section   | LOC change |
| --------- | ---------- |
| Core code | +20 / -14  |
| Tests     | +97 / -1   |

Author: MitjaBezensek

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

@@ -3336,6 +3336,15 @@ export class Editor extends EventEmitter<TLEventMap> {
 
 		let { x, y, z = currentCamera.z } = point
 
+		// `requested` kept the caller's focal point (e.g. the cursor) fixed at
+		// zoom `rz`. When `rz` gets clamped, keep that same focal point fixed at
+		// the clamped zoom `z` rather than snapping to the viewport center.
+		const preserveFocalPoint = (current: number, requested: number, rz: number, z: number) => {
+			const cz = currentCamera.z
+			if (rz === cz) return current
+			return current + ((requested - current) * (1 / z - 1 / cz)) / (1 / rz - 1 / cz)
+		}
+
 		// If force is true, then we'll set the camera to the point regardless of
 		// the camera options, so that we can handle gestures that permit elasticity
 		// or decay, or animations that occur while the camera is locked.
@@ -3378,17 +3387,14 @@ export class Editor extends EventEmitter<TLEventMap> {
 				}
 
 				if (z < minZ || z > maxZ) {
-					// We're trying to zoom out past the minimum zoom level,
-					// or in past the maximum zoom level, so stop the camera
-					// but keep the current center
-					const { x: cx, y: cy, z: cz } = currentCamera
-					const cxA = -cx + vsb.w / cz / 2
-					const cyA = -cy + vsb.h / cz / 2
+					// We're trying to zoom out past the minimum zoom level, or in
+					// past the maximum zoom level, so clamp the zoom while keeping
+					// the caller's focal point fixed. Axis constraints below still
+					// apply on top of this.
+					const rz = z
 					z = clamp(z, minZ, maxZ)
-					const cxB = -cx + vsb.w / z / 2
-					const cyB = -cy + vsb.h / z / 2
-					x = cx + cxB - cxA
-					y = cy + cyB - cyA
+					x = preserveFocalPoint(currentCamera.x, x, rz, z)
+					y = preserveFocalPoint(currentCamera.y, y, rz, z)
 				}
 
 				// Calculate available space
@@ -3477,12 +3483,12 @@ export class Editor extends EventEmitter<TLEventMap> {
 					}
 				}
 			} else {
-				// constrain the zoom, preserving the center
+				// constrain the zoom, keeping the caller's focal point fixed
 				if (z > zoomMax || z < zoomMin) {
-					const { x: cx, y: cy, z: cz } = currentCamera
+					const rz = z
 					z = clamp(z, zoomMin, zoomMax)
-					x = cx + (-cx + vsb.w / z / 2) - (-cx + vsb.w / cz / 2)
-					y = cy + (-cy + vsb.h / z / 2) - (-cy + vsb.h / cz / 2)
+					x = preserveFocalPoint(currentCamera.x, x, rz, z)
+					y = preserveFocalPoint(currentCamera.y, y, rz, z)
 				}
 			}
 		}

packages/tldraw/src/test/commands/setCamera.test.ts

@@ -1,4 +1,4 @@
-import { Box, DEFAULT_CAMERA_OPTIONS, Vec, createShapeId } from '@tldraw/editor'
+import { Box, DEFAULT_CAMERA_OPTIONS, Vec, createShapeId, last } from '@tldraw/editor'
 import { vi } from 'vitest'
 import { TestEditor } from '../TestEditor'
 
@@ -141,6 +141,102 @@ describe('With default options', () => {
 	})
 })
 
+describe('Zoom clamping preserves the focal point', () => {
+	beforeEach(() => {
+		editor.setCameraOptions({ ...DEFAULT_CAMERA_OPTIONS })
+	})
+
+	// An off-center screen point, so a center-preserving clamp would shift it.
+	const cursor = { x: 200, y: 150 }
+
+	it('keeps the point under the cursor fixed when wheel zooming out past the min', () => {
+		editor.setCamera({ x: 0, y: 0, z: 0.06 }) // just above the 0.05 min
+		editor.pointerMove(cursor.x, cursor.y)
+		const before = editor.screenToPage(cursor)
+
+		// Each event halves the zoom, overshooting the min, then pins at it.
+		for (let i = 0; i < 4; i++) {
+			editor
+				.dispatch({
+					...wheelEvent,
+					point: new Vec(cursor.x, cursor.y),
+					delta: new Vec(0, 0, -0.5),
+					ctrlKey: true,
+				})
+				.forceTick()
+		}
+
+		expect(editor.getZoomLevel()).toBe(DEFAULT_CAMERA_OPTIONS.zoomSteps[0])
+		const after = editor.screenToPage(cursor)
+		expect(after.x).toBeCloseTo(before.x, 4)
+		expect(after.y).toBeCloseTo(before.y, 4)
+	})
+
+	it('keeps the point under the cursor fixed when wheel zooming in past the max', () => {
+		const max = last(DEFAULT_CAMERA_OPTIONS.zoomSteps)!
+		editor.setCamera({ x: 0, y: 0, z: max * 0.9 }) // just below the max
+		editor.pointerMove(cursor.x, cursor.y)
+		const before = editor.screenToPage(cursor)
+
+		for (let i = 0; i < 4; i++) {
+			editor
+				.dispatch({
+					...wheelEvent,
+					point: new Vec(cursor.x, cursor.y),
+					delta: new Vec(0, 0, 0.5),
+					ctrlKey: true,
+				})
+				.forceTick()
+		}
+
+		expect(editor.getZoomLevel()).toBe(max)
+		const after = editor.screenToPage(cursor)
+		expect(after.x).toBeCloseTo(before.x, 4)
+		expect(after.y).toBeCloseTo(before.y, 4)
+	})
+
+	it('does not translate the camera once zoom is pinned at the min', () => {
+		const min = DEFAULT_CAMERA_OPTIONS.zoomSteps[0]
+		editor.setCamera({ x: 0, y: 0, z: min })
+		editor.pointerMove(cursor.x, cursor.y)
+		const camera = { ...editor.getCamera() }
+
+		for (let i = 0; i < 3; i++) {
+			editor
+				.dispatch({
+					...wheelEvent,
+					point: new Vec(cursor.x, cursor.y),
+					delta: new Vec(0, 0, -0.5),
+					ctrlKey: true,
+				})
+				.forceTick()
+		}
+
+		expect(editor.getCamera()).toMatchObject({ x: camera.x, y: camera.y, z: min })
+	})
+
+	it('keeps the focal point fixed when setCamera requests an out-of-range zoom', () => {
+		// Mimic a cursor-anchored zoom request that overshoots the min: choose
+		// x/y so screen point (200, 150) stays fixed at the requested zoom.
+		const px = cursor.x
+		const py = cursor.y
+		editor.setCamera({ x: 0, y: 0, z: 0.06 })
+		const { x: cx, y: cy, z: cz } = editor.getCamera()
+		const before = editor.screenToPage(cursor)
+
+		const requestedZoom = 0.02 // below the 0.05 min
+		editor.setCamera(
+			new Vec(cx + px / requestedZoom - px / cz, cy + py / requestedZoom - py / cz, requestedZoom),
+			{ immediate: true }
+		)
+
+		expect(editor.getZoomLevel()).toBe(DEFAULT_CAMERA_OPTIONS.zoomSteps[0])
+		const after = editor.screenToPage(cursor)
+		expect(after.x).toBeCloseTo(before.x, 4)
+		expect(after.y).toBeCloseTo(before.y, 4)
+	})
+})
+
 it('Sets the camera options', () => {
 	const optionsA = { ...DEFAULT_CAMERA_OPTIONS, panSpeed: 2 }
 	editor.setCameraOptions(optionsA)