@tldraw/editor 5.4.0-next.ebc95cf01337 → 5.4.0

package/src/lib/primitives/geometry/Stadium2d.test.ts

@@ -1,5 +1,193 @@
-describe('Stadium2d', () => {
-	it('should be tested', () => {
-		expect(true).toBe(true)
+import { Vec } from '../Vec'
+import { Stadium2d } from './Stadium2d'
+
+// A wide 100x50 stadium: semicircles of radius 25 centred at (25, 25) and (75, 25)
+const wide = () => new Stadium2d({ width: 100, height: 50, isFilled: false })
+const wideFilled = () => new Stadium2d({ width: 100, height: 50, isFilled: true })
+// A tall 50x100 stadium: semicircles of radius 25 centred at (25, 25) and (25, 75)
+const tall = () => new Stadium2d({ width: 50, height: 100, isFilled: false })
+
+function expectVec(actual: Vec, expected: { x: number; y: number }) {
+	expect(actual.x).toBeCloseTo(expected.x)
+	expect(actual.y).toBeCloseTo(expected.y)
+}
+
+describe('Stadium2d construction', () => {
+	it('is always closed and keeps the fill flag from config', () => {
+		expect(wide()).toMatchObject({ isClosed: true, isFilled: false })
+		expect(wideFilled()).toMatchObject({ isClosed: true, isFilled: true })
+	})
+})
+
+describe('Stadium2d.bounds', () => {
+	it('is the width by height box at the origin', () => {
+		expect(wide().bounds).toMatchObject({ x: 0, y: 0, w: 100, h: 50 })
+		expect(wide().center).toMatchObject({ x: 50, y: 25 })
+		expect(tall().bounds).toMatchObject({ x: 0, y: 0, w: 50, h: 100 })
+	})
+})
+
+describe('Stadium2d.getLength', () => {
+	it('is two straight sides plus a full circle', () => {
+		expect(wide().length).toBeCloseTo(2 * 50 + Math.PI * 50)
+		expect(tall().length).toBeCloseTo(2 * 50 + Math.PI * 50)
+	})
+
+	it('is a circle circumference when width equals height', () => {
+		expect(new Stadium2d({ width: 50, height: 50, isFilled: false }).length).toBeCloseTo(
+			Math.PI * 50
+		)
+	})
+})
+
+describe('Stadium2d.getVertices', () => {
+	it('concatenates the vertices of the two arcs and two edges', () => {
+		const { vertices } = wide()
+		// each semicircle samples the minimum 8 segments (9 vertices), each edge has 2
+		expect(vertices.length).toBe(9 + 2 + 9 + 2)
+		// left arc runs from the bottom to the top through the leftmost point
+		expectVec(vertices[0], { x: 25, y: 50 })
+		expectVec(vertices[4], { x: 0, y: 25 })
+		expectVec(vertices[8], { x: 25, y: 0 })
+		// top edge
+		expect(vertices[9]).toMatchObject({ x: 25, y: 0 })
+		expect(vertices[10]).toMatchObject({ x: 75, y: 0 })
+		// right arc runs from the top to the bottom through the rightmost point
+		expectVec(vertices[11], { x: 75, y: 0 })
+		expectVec(vertices[15], { x: 100, y: 25 })
+		expectVec(vertices[19], { x: 75, y: 50 })
+		// bottom edge
+		expect(vertices[20]).toMatchObject({ x: 75, y: 50 })
+		expect(vertices[21]).toMatchObject({ x: 25, y: 50 })
+	})
+
+	it('keeps every vertex inside the bounds', () => {
+		for (const s of [wide(), tall()]) {
+			for (const v of s.vertices) {
+				expect(v.x).toBeGreaterThanOrEqual(-1e-9)
+				expect(v.y).toBeGreaterThanOrEqual(-1e-9)
+				expect(v.x).toBeLessThanOrEqual(s.bounds.w + 1e-9)
+				expect(v.y).toBeLessThanOrEqual(s.bounds.h + 1e-9)
+			}
+		}
+	})
+
+	it('starts a tall stadium with the top arc from left to right', () => {
+		const { vertices } = tall()
+		expectVec(vertices[0], { x: 0, y: 25 })
+		expectVec(vertices[4], { x: 25, y: 0 })
+		expectVec(vertices[8], { x: 50, y: 25 })
+		expect(vertices[10]).toMatchObject({ x: 50, y: 75 })
+		expectVec(vertices[15], { x: 25, y: 100 })
+		expect(vertices[21]).toMatchObject({ x: 0, y: 25 })
+	})
+})
+
+describe('Stadium2d.nearestPoint', () => {
+	it('projects onto the straight edges', () => {
+		expect(wide().nearestPoint(new Vec(50, -10))).toMatchObject({ x: 50, y: 0 })
+		expect(wide().nearestPoint(new Vec(50, 60))).toMatchObject({ x: 50, y: 50 })
+		expect(tall().nearestPoint(new Vec(-10, 50))).toMatchObject({ x: 0, y: 50 })
+	})
+
+	it('projects radially onto the arcs', () => {
+		expectVec(wide().nearestPoint(new Vec(-10, 25)), { x: 0, y: 25 })
+		expectVec(wide().nearestPoint(new Vec(110, 25)), { x: 100, y: 25 })
+		expectVec(tall().nearestPoint(new Vec(25, -10)), { x: 25, y: 0 })
+		// towards the top-left corner of the bounds the nearest point is on the arc, not the corner
+		const p = wide().nearestPoint(new Vec(0, 0))
+		expectVec(p, { x: 25 - 25 / Math.SQRT2, y: 25 - 25 / Math.SQRT2 })
+	})
+
+	it('projects from inside', () => {
+		expect(wide().nearestPoint(new Vec(50, 20))).toMatchObject({ x: 50, y: 0 })
+	})
+})
+
+describe('Stadium2d.distanceToPoint', () => {
+	it('is positive outside', () => {
+		expect(wide().distanceToPoint(new Vec(50, -10))).toBe(10)
+		expect(wide().distanceToPoint(new Vec(-10, 25))).toBeCloseTo(10)
+		expect(wideFilled().distanceToPoint(new Vec(50, -10))).toBe(10)
+	})
+
+	it('is negative inside only when filled or hitInside', () => {
+		expect(wide().distanceToPoint(new Vec(50, 25))).toBe(25)
+		expect(wideFilled().distanceToPoint(new Vec(50, 25))).toBe(-25)
+		expect(wide().distanceToPoint(new Vec(50, 25), true)).toBe(-25)
+	})
+
+	it('measures to the arc inside the rounded corners', () => {
+		// (5, 5) is inside the bounds but outside the left semicircle
+		expect(wide().distanceToPoint(new Vec(5, 5))).toBeCloseTo(Math.hypot(20, 20) - 25)
+		expect(wideFilled().distanceToPoint(new Vec(5, 5))).toBeCloseTo(Math.hypot(20, 20) - 25)
+	})
+})
+
+describe('Stadium2d.hitTestPoint', () => {
+	it('hits the interior only when filled or hitInside', () => {
+		expect(wideFilled().hitTestPoint(new Vec(50, 25))).toBe(true)
+		expect(wide().hitTestPoint(new Vec(50, 25))).toBe(false)
+		expect(wide().hitTestPoint(new Vec(50, 25), 0, true)).toBe(true)
+	})
+
+	it('misses the rounded corners even when filled', () => {
+		expect(wideFilled().hitTestPoint(new Vec(5, 5))).toBe(false)
+		expect(wideFilled().hitTestPoint(new Vec(95, 45))).toBe(false)
+	})
+
+	it('hits the rounded corners within the margin', () => {
+		const d = Math.hypot(20, 20) - 25 // ≈ 3.28
+		expect(wide().hitTestPoint(new Vec(5, 5), d + 0.01)).toBe(true)
+		expect(wide().hitTestPoint(new Vec(5, 5), d - 0.01)).toBe(false)
+	})
+
+	it('hits the straight edge and respects the margin', () => {
+		expect(wide().hitTestPoint(new Vec(50, 0))).toBe(true)
+		expect(wide().hitTestPoint(new Vec(50, -5), 5)).toBe(true)
+		expect(wide().hitTestPoint(new Vec(50, -5), 4)).toBe(false)
+	})
+})
+
+describe('Stadium2d.hitTestLineSegment', () => {
+	it('hits a segment crossing a straight edge', () => {
+		expect(wide().hitTestLineSegment(new Vec(50, -10), new Vec(50, 60))).toBe(true)
+	})
+
+	it('hits a segment crossing an arc', () => {
+		expect(wide().hitTestLineSegment(new Vec(-10, 25), new Vec(10, 25))).toBe(true)
+		// the diagonal from the bounds corner reaches the arc at t ≈ 7.3
+		expect(wide().hitTestLineSegment(new Vec(0, 0), new Vec(10, 10))).toBe(true)
+	})
+
+	it('misses a segment that stays within a rounded corner gap', () => {
+		expect(wide().hitTestLineSegment(new Vec(0, 0), new Vec(5, 5))).toBe(false)
+	})
+
+	it('misses segments entirely outside or entirely inside', () => {
+		expect(wide().hitTestLineSegment(new Vec(110, 0), new Vec(110, 50))).toBe(false)
+		expect(wideFilled().hitTestLineSegment(new Vec(40, 25), new Vec(45, 25))).toBe(false)
+		expect(wideFilled().hitTestLineSegment(new Vec(45, 2), new Vec(55, 2))).toBe(false)
+	})
+
+	// Locks in current behaviour, see #10555.
+	it('hits an interior segment that crosses the far side of an arc circle (known quirk)', () => {
+		// (50, 25) is on the left arc's circle but opposite the arc itself; Arc2d clamps points on
+		// the complementary arc to the nearest end point, so the crossing counts as a hit
+		expect(wideFilled().hitTestLineSegment(new Vec(30, 25), new Vec(70, 25))).toBe(true)
+	})
+})
+
+describe('Stadium2d.getSvgPathData', () => {
+	it('draws arc, line, arc, line and closes', () => {
+		expect(wide().getSvgPathData()).toBe(
+			'M25, 50 A25 25 0 1 1 25, 0  L75, 0  A25 25 0 1 1 75, 50  L25, 50 Z'
+		)
+	})
+
+	it('draws a tall stadium starting from the left of the top arc', () => {
+		expect(tall().getSvgPathData()).toBe(
+			'M0, 25 A25 25 0 1 1 50, 25  L50, 75  A25 25 0 1 1 0, 75  L0, 25 Z'
+		)
 	})
 })

package/src/lib/primitives/utils.test.ts

@@ -1,4 +1,4 @@
-import { getPointInArcT } from './utils'
+import { areAnglesCompatible, getPointInArcT } from './utils'
 
 describe('getPointInArcT', () => {
 	it('should return 0 for the start of the arc', () => {
@@ -57,3 +57,12 @@ describe('getPointInArcT', () => {
 		expect(getPointInArcT(mAB, A, B, P)).toBe(1)
 	})
 })
+
+describe('areAnglesCompatible', () => {
+	it('treats angles a multiple of PI/2 apart as compatible regardless of sign', () => {
+		expect(areAnglesCompatible(-Math.PI / 4, Math.PI / 4)).toBe(true)
+		expect(areAnglesCompatible(Math.PI / 2 - 1e-9, 0)).toBe(true)
+		expect(areAnglesCompatible(Math.PI, -Math.PI / 2)).toBe(true)
+		expect(areAnglesCompatible(0, Math.PI / 3)).toBe(false)
+	})
+})

package/src/lib/primitives/utils.ts

@@ -189,7 +189,10 @@ export function snapAngle(r: number, segments: number): number {
  * @public
  */
 export function areAnglesCompatible(a: number, b: number) {
-	return a === b || approximately((a % (Math.PI / 2)) - (b % (Math.PI / 2)), 0)
+	// Reduce the difference, not each angle: a sign-preserving % on each made
+	// -PI/4 and PI/4 incompatible. A remainder just under PI/2 is a multiple too.
+	const d = Math.abs(a - b) % (Math.PI / 2)
+	return approximately(d, 0) || approximately(d, Math.PI / 2)
 }
 
 /**

package/src/lib/test/useCanvasEvents.test.tsx

@@ -0,0 +1,74 @@
+import { act, render } from '@testing-library/react'
+import { Editor } from '../editor/Editor'
+import { TldrawEditor } from '../TldrawEditor'
+
+function dropEvent(dataTransfer: { files: File[]; getData(type: string): string }) {
+	const event = new Event('drop', { bubbles: true, cancelable: true })
+	Object.defineProperty(event, 'dataTransfer', { value: dataTransfer })
+	return event
+}
+
+describe('useCanvasEvents drop handling', () => {
+	let editor: Editor
+	let canvas: HTMLElement
+
+	beforeEach(async () => {
+		await act(async () => {
+			render(
+				<TldrawEditor
+					shapeUtils={[]}
+					bindingUtils={[]}
+					onMount={(e) => {
+						editor = e
+					}}
+				/>
+			)
+		})
+		canvas = document.querySelector('[data-testid="canvas"]') as HTMLElement
+
+		// Stand-ins for the default handlers: any undoable change will do.
+		editor.registerExternalContentHandler('files', async () => {
+			editor.createPage({ name: 'dropped' })
+		})
+		editor.registerExternalContentHandler('url', async () => {
+			editor.createPage({ name: 'dropped' })
+		})
+
+		// An unmarked change before the drop, like a stroke the user just drew.
+		editor.createPage({ name: 'before drop' })
+	})
+
+	afterEach(() => {
+		editor?.dispose()
+	})
+
+	function pageNames() {
+		return editor.getPages().map((p) => p.name)
+	}
+
+	it('makes a dropped file its own undo step', async () => {
+		await act(async () => {
+			canvas.dispatchEvent(
+				dropEvent({ files: [new File(['x'], 'x.png', { type: 'image/png' })], getData: () => '' })
+			)
+		})
+		expect(pageNames()).toEqual(['Page 1', 'before drop', 'dropped'])
+
+		editor.undo()
+
+		expect(pageNames()).toEqual(['Page 1', 'before drop'])
+	})
+
+	it('makes a dropped url its own undo step', async () => {
+		await act(async () => {
+			canvas.dispatchEvent(
+				dropEvent({ files: [], getData: (type) => (type === 'url' ? 'https://example.com' : '') })
+			)
+		})
+		expect(pageNames()).toEqual(['Page 1', 'before drop', 'dropped'])
+
+		editor.undo()
+
+		expect(pageNames()).toEqual(['Page 1', 'before drop'])
+	})
+})

package/src/lib/test/useDocumentEvents.test.tsx

@@ -0,0 +1,107 @@
+import { act, cleanup, render } from '@testing-library/react'
+import { vi } from 'vitest'
+import { createTLStore } from '../config/createTLStore'
+import { Editor } from '../editor/Editor'
+import { TLKeyboardEventInfo } from '../editor/types/event-types'
+import { TL_CONTAINER_CLASS, TldrawEditor } from '../TldrawEditor'
+
+describe('useDocumentEvents drop handling', () => {
+	// The container's native drop listener used to stop propagation before the event reached
+	// React's root, so React onDrop handlers inside the canvas never fired.
+	it('lets a drop inside the canvas reach React drop handlers there', async () => {
+		const onDrop = vi.fn((e: React.DragEvent) => e.stopPropagation())
+		function DropTarget() {
+			return <div data-testid="drop-target" onDrop={onDrop} />
+		}
+		const store = createTLStore({ shapeUtils: [], bindingUtils: [] })
+		await act(async () => {
+			render(<TldrawEditor store={store} components={{ OnTheCanvas: DropTarget }} />)
+		})
+
+		const target = document.querySelector('[data-testid="drop-target"]')!
+		expect(target.closest('.tl-canvas')).not.toBeNull()
+		const event = new Event('drop', { bubbles: true, cancelable: true })
+		Object.defineProperty(event, 'dataTransfer', { value: { files: [], getData: () => '' } })
+		act(() => {
+			target.dispatchEvent(event)
+		})
+
+		expect(onDrop).toHaveBeenCalledTimes(1)
+		// the browser default (navigating to the dropped file) is still prevented
+		expect(event.defaultPrevented).toBe(true)
+	})
+})
+
+describe('useDocumentEvents window blur', () => {
+	async function renderEditor() {
+		let editor!: Editor
+		const store = createTLStore({ shapeUtils: [], bindingUtils: [] })
+		await act(async () => {
+			render(<TldrawEditor store={store} autoFocus onMount={(e) => void (editor = e)} />)
+		})
+		const container = document.querySelector<HTMLElement>(`.${TL_CONTAINER_CLASS}`)!
+		return { editor, container }
+	}
+
+	function keyDown(container: HTMLElement, init: KeyboardEventInit) {
+		act(() => {
+			container.dispatchEvent(new KeyboardEvent('keydown', { bubbles: true, ...init }))
+		})
+	}
+
+	function blurWindow() {
+		act(() => {
+			window.dispatchEvent(new Event('blur'))
+		})
+	}
+
+	afterEach(() => {
+		cleanup()
+	})
+
+	// Alt+Tab / Cmd+Tab while holding Space: the keyup goes to the other app, so the editor
+	// used to stay in spacebar panning mode with the grab cursor until Space was pressed again.
+	it('ends spacebar panning and restores the cursor', async () => {
+		const { editor, container } = await renderEditor()
+		editor.setCursor({ type: 'cross', rotation: 0 })
+
+		keyDown(container, { key: ' ', code: 'Space' })
+		expect(editor.inputs.keys.has('Space')).toBe(true)
+		expect(editor.inputs.getIsSpacebarPanning()).toBe(true)
+		expect(editor.inputs.getIsPanning()).toBe(true)
+		expect(editor.getInstanceState().cursor.type).toBe('grab')
+
+		blurWindow()
+		expect(editor.inputs.keys.has('Space')).toBe(false)
+		expect(editor.inputs.getIsSpacebarPanning()).toBe(false)
+		expect(editor.inputs.getIsPanning()).toBe(false)
+		expect(editor.getInstanceState().cursor.type).toBe('cross')
+	})
+
+	it('releases every held key through a key_up that tools can match on key', async () => {
+		const { editor, container } = await renderEditor()
+		const keyUps: TLKeyboardEventInfo[] = []
+		editor.on('event', (info) => {
+			if (info.type === 'keyboard' && info.name === 'key_up') keyUps.push(info)
+		})
+
+		keyDown(container, { key: 'ArrowLeft', code: 'ArrowLeft' })
+		keyDown(container, { key: 'a', code: 'KeyA' })
+		expect([...editor.inputs.keys]).toEqual(['ArrowLeft', 'KeyA'])
+
+		blurWindow()
+		expect(editor.inputs.keys.size).toBe(0)
+		expect(keyUps.map((info) => [info.key, info.code])).toEqual([
+			['ArrowLeft', 'ArrowLeft'],
+			['a', 'KeyA'],
+		])
+	})
+
+	it('does nothing when no keys are held', async () => {
+		const { editor } = await renderEditor()
+		const onEvent = vi.fn()
+		editor.on('event', onEvent)
+		blurWindow()
+		expect(onEvent).not.toHaveBeenCalled()
+	})
+})

package/src/lib/test/usePassThroughWheelEvents.test.tsx

@@ -22,11 +22,27 @@ function Culled() {
 	return <button ref={ref} data-testid="marker" />
 }
 
+/**
+ * The shape the navigation panel has: a pass-through root wrapping another pass-through root (the
+ * minimap).
+ */
+function Nested() {
+	const outer = useRef<HTMLDivElement>(null)
+	const inner = useRef<HTMLButtonElement>(null)
+	usePassThroughWheelEvents(outer)
+	usePassThroughWheelEvents(inner)
+	return (
+		<div ref={outer}>
+			<button ref={inner} data-testid="marker" />
+		</div>
+	)
+}
+
 describe('usePassThroughWheelEvents', () => {
-	async function renderEditor() {
+	async function renderEditor(InFrontOfTheCanvas = Culled) {
 		const store = createTLStore({ shapeUtils: [], bindingUtils: [] })
 		await act(async () => {
-			render(<TldrawEditor store={store} components={{ InFrontOfTheCanvas: Culled }} />)
+			render(<TldrawEditor store={store} components={{ InFrontOfTheCanvas }} />)
 		})
 		return document.querySelector(`.${TL_CONTAINER_CLASS}`)!
 	}
@@ -64,6 +80,13 @@ describe('usePassThroughWheelEvents', () => {
 		expect(wheelOverMarker(container)).toHaveLength(1)
 	})
 
+	// Issue #10441: the original event keeps bubbling after the inner root redispatches it, so
+	// without a flag on it the outer root would redispatch it again.
+	it('redispatches once when the element is inside another pass-through element', async () => {
+		const container = await renderEditor(Nested)
+		expect(wheelOverMarker(container)).toHaveLength(1)
+	})
+
 	it('stops redispatching once the owner unmounts', async () => {
 		const container = await renderEditor()
 		const marker = container.querySelector('[data-testid="marker"]')!

package/src/lib/utils/deepLinks.test.ts

@@ -70,3 +70,18 @@ test.each(testCases)('works with $name', ({ deepLink, expected }) => {
 	expect(createDeepLinkString(deepLink)).toBe(expected)
 	expect(parseDeepLinkString(expected)).toEqual(deepLink)
 })
+
+describe('parseDeepLinkString', () => {
+	it('throws on a viewport link with non-numeric bounds', () => {
+		expect(() => parseDeepLinkString('vabc.def.ghi.jkl')).toThrow('Invalid deep link string')
+	})
+
+	it('throws on a viewport link with missing bounds', () => {
+		expect(() => parseDeepLinkString('v1.2')).toThrow('Invalid deep link string')
+		expect(() => parseDeepLinkString('v')).toThrow('Invalid deep link string')
+	})
+
+	it('throws on an unknown link type', () => {
+		expect(() => parseDeepLinkString('xabc')).toThrow('Invalid deep link string')
+	})
+})

package/src/lib/utils/deepLinks.ts

@@ -73,9 +73,15 @@ export function parseDeepLinkString(deepLinkString: string): TLDeepLink {
 		}
 		case 'v': {
 			const [x, y, w, h, pageId] = deepLinkString.slice(1).split('.')
+			const bounds = new Box(Number(x), Number(y), Number(w), Number(h))
+			// Number('abc') is NaN rather than an error, so without this check a malformed
+			// viewport link would bypass the caller's fallback and park the camera at the origin
+			if (![bounds.x, bounds.y, bounds.w, bounds.h].every(Number.isFinite)) {
+				throw Error('Invalid deep link string')
+			}
 			return {
 				type: 'viewport',
-				bounds: new Box(Number(x), Number(y), Number(w), Number(h)),
+				bounds,
 				pageId: pageId ? PageRecordType.createId(decodeURIComponent(pageId)) : undefined,
 			}
 		}

package/src/lib/utils/rotation.ts

@@ -1,7 +1,6 @@
-import { isShapeId, TLShape, TLShapeId, TLShapePartial } from '@tldraw/tlschema'
+import { TLShape, TLShapeId, TLShapePartial } from '@tldraw/tlschema'
 import { compact } from '@tldraw/utils'
 import type { Editor } from '../editor/Editor'
-import { Mat } from '../primitives/Mat'
 import { canonicalizeRotation } from '../primitives/utils'
 import { Vec, VecLike } from '../primitives/Vec'
 
@@ -75,18 +74,11 @@ export function applyRotationToSnapshotShapes({
 			// We need to both rotate each shape individually and rotate the shapes
 			// around the pivot point (the average center of all rotating shapes.)
 
-			const parentTransform = isShapeId(shape.parentId)
-				? editor.getShapePageTransform(shape.parentId)!
-				: Mat.Identity()
-
 			const newPagePoint = Vec.RotWith(initialPagePoint, centerOverride ?? initialPageCenter, delta)
 
-			const newLocalPoint = Mat.applyToPoint(
-				// use the current parent transform in case it has moved/resized since the start
-				// (e.g. if rotating a shape at the edge of a group)
-				Mat.Inverse(parentTransform),
-				newPagePoint
-			)
+			// uses the current parent transform in case it has moved/resized since the start
+			// (e.g. if rotating a shape at the edge of a group)
+			const newLocalPoint = editor.getPointInParentSpace(shape.id, newPagePoint)
 			const newRotation = canonicalizeRotation(shape.rotation + delta)
 
 			return {

package/src/lib/utils/sync/TLLocalSyncClient.test.ts

@@ -172,3 +172,59 @@ test('writes that come in during a persist operation will get persisted afterwar
 	await tick()
 	expect(client.db.storeChanges).toHaveBeenCalledTimes(1)
 })
+
+test('pagehide flushes pending changes without waiting for the throttle', async () => {
+	const { client, tick } = testClient()
+	await tick()
+	client.store.put([PageRecordType.create({ name: 'test', index: 'a0' as IndexKey })])
+	await tick()
+	expect(client.db.storeSnapshot).toHaveBeenCalledTimes(1)
+
+	client.store.put([PageRecordType.create({ name: 'test2', index: 'a1' as IndexKey })])
+	expect(client.db.storeChanges).not.toHaveBeenCalled()
+
+	window.dispatchEvent(new Event('pagehide'))
+	expect(client.db.storeChanges).toHaveBeenCalledTimes(1)
+})
+
+test('hiding the tab flushes pending changes without waiting for the throttle', async () => {
+	const { client, tick } = testClient()
+	await tick()
+	client.store.put([PageRecordType.create({ name: 'test', index: 'a0' as IndexKey })])
+	await tick()
+	expect(client.db.storeSnapshot).toHaveBeenCalledTimes(1)
+
+	client.store.put([PageRecordType.create({ name: 'test2', index: 'a1' as IndexKey })])
+	expect(client.db.storeChanges).not.toHaveBeenCalled()
+
+	const visibilityState = vi.spyOn(document, 'visibilityState', 'get')
+	try {
+		visibilityState.mockReturnValue('hidden')
+		document.dispatchEvent(new Event('visibilitychange'))
+		expect(client.db.storeChanges).toHaveBeenCalledTimes(1)
+	} finally {
+		visibilityState.mockRestore()
+	}
+})
+
+test('pagehide does not write before the initial load has completed', async () => {
+	const { client } = testClient()
+	window.dispatchEvent(new Event('pagehide'))
+	expect(client.db.storeSnapshot).not.toHaveBeenCalled()
+	expect(client.db.storeChanges).not.toHaveBeenCalled()
+})
+
+test('pagehide and visibilitychange listeners are removed when the client closes', async () => {
+	const removeWindowListener = vi.spyOn(window, 'removeEventListener')
+	const removeDocumentListener = vi.spyOn(document, 'removeEventListener')
+	try {
+		const { client, tick } = testClient()
+		await tick()
+		client.close()
+		expect(removeWindowListener).toHaveBeenCalledWith('pagehide', expect.any(Function))
+		expect(removeDocumentListener).toHaveBeenCalledWith('visibilitychange', expect.any(Function))
+	} finally {
+		removeWindowListener.mockRestore()
+		removeDocumentListener.mockRestore()
+	}
+})

package/src/lib/utils/sync/TLLocalSyncClient.ts

@@ -68,6 +68,7 @@ export class TLLocalSyncClient {
 	private disposables = new Set<() => void>()
 	private diffQueue: Array<RecordsDiff<UnknownRecord> | typeof UPDATE_INSTANCE_STATE> = []
 	private didDispose = false
+	private didLoad = false
 	private shouldDoFullDBWrite = true
 	private isReloading = false
 	readonly persistenceKey: string
@@ -143,6 +144,28 @@ export class TLLocalSyncClient {
 			)
 		)
 
+		if (typeof window !== 'undefined') {
+			// Persists are throttled, so without this the last PERSIST_THROTTLE_MS of edits are lost
+			// whenever the tab is closed or reloaded. `pagehide` is the last reliable event before
+			// unload on desktop; on mobile the page can be discarded without it firing, so we also
+			// flush when the tab is hidden.
+			const flush = () => {
+				// Before the initial load completes a full write would overwrite the saved
+				// document with an empty store.
+				if (!this.didLoad) return
+				this.persistIfNeeded()
+			}
+			const onVisibilityChange = () => {
+				if (document.visibilityState === 'hidden') flush()
+			}
+			window.addEventListener('pagehide', flush)
+			document.addEventListener('visibilitychange', onVisibilityChange)
+			this.disposables.add(() => {
+				window.removeEventListener('pagehide', flush)
+				document.removeEventListener('visibilitychange', onVisibilityChange)
+			})
+		}
+
 		this.connect(onLoad, onLoadError)
 
 		this.documentTypes = new Set(
@@ -249,6 +272,7 @@ export class TLLocalSyncClient {
 			this.disposables.add(() => {
 				this.channel.close()
 			})
+			this.didLoad = true
 			onLoad(this)
 		} catch (e: any) {
 			this.debug('error loading data from store', e)

package/src/lib/utils/sync/alerts.ts

@@ -12,7 +12,7 @@ Keep seeing this message?
 /** @internal */
 export function showCantReadFromIndexDbAlert() {
 	window.alert(
-		`Oops! We could not access your browser's storage—and the app won't work correctly without that. We now need to reload the page and try again.
+		`Oops! We could not access your browser's storage—and the app won't work correctly without that. Reload the page to try again.
 
 Keep seeing this message?
 • If you're using tldraw in a private or "incognito" window, try loading tldraw in a regular window or in a different browser.`

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.4.0-next.ebc95cf01337'
+export const version = '5.4.0'
 export const publishDates = {
 	major: '2026-05-06T16:28:18.473Z',
-	minor: '2026-08-13T15:10:11.500Z',
-	patch: '2026-08-13T15:10:11.500Z',
+	minor: '2026-09-02T11:04:02.901Z',
+	patch: '2026-09-02T11:04:02.901Z',
 }

package/src/lib/primitives/geometry/Polyline.test.ts

@@ -1,5 +0,0 @@
-describe('Polyline2d', () => {
-	it('should be tested', () => {
-		expect(true).toBe(true)
-	})
-})