fix(memory): clean up module-level state leaks after editor unmount (tldraw#8604)

In order to prevent `Editor`, `Store`, and sync client instances from
being retained after unmount, this PR cleans up several module-level
caches, globals, and debounced functions that hold references.
Particularly impactful for apps that mount/unmount editors frequently
(iOS WebViews hit memory limits). Closes tldraw#8440.

**`debounce.cancel()`** — sets `state = undefined` so `latestArgs` (and
any captured Editor) are released on cancel. Previously only cleared the
timeout.

**`window.tlsync`** — cleared in `close()` for both `TLLocalSyncClient`
and `TLSyncClient`. Guarded with `=== this` to avoid clearing a newer
client's reference.

**Bookmark debounce** — replaced module-level `debounce(editor, shape)`
with per-editor instances via `WeakMap<Editor, ...>` (same pattern as
the `updateHoveredShapeId` fix in tldraw#8439). Debouncer is GC'd with the
editor.

**`LruCache`** — new `@tldraw/utils` class (~20 LOC) using `Map`
insertion-order for O(1) LRU eviction. `fetchCache` (cap 200) and
`alphaCache` (cap 500) now use `LruCache` instead of unbounded `Map`s,
preventing unbounded growth while keeping hot entries warm.

### Change type

- [x] `bugfix`

### Test plan

1. Mount/unmount editor multiple times
2. Take heap snapshots, confirm Editor instances are GC'd
3. Verify bookmark URL unfurling still works after editor remount
4. Verify image alpha hit-testing works with many unique images

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

### Release notes

- Fixed memory leaks from module-level state retaining editor references
after unmount
- Added `LruCache` utility class for bounded caches with
least-recently-used eviction

### API changes

- Added `LruCache<K, V>` class to `@tldraw/utils` with `get`, `set`,
`has`, and `size`

### Code changes

| Section         | LOC change |
| --------------- | ---------- |
| Core code       | +60 / -8   |
| Tests           | +89 / -0   |
| Automated files | +13 / -0   |

Author: MitjaBezensek

packages/editor/src/lib/exports/fetchCache.ts

@@ -1,9 +1,7 @@
-import { FileHelpers, assert, fetch } from '@tldraw/utils'
+import { FileHelpers, LruCache, assert, fetch } from '@tldraw/utils'
 
-// TODO(alex): currently, this cache will grow unbounded. we should come up with a better strategy
-// for clearing items from the cache over time.
 export function fetchCache<T>(cb: (response: Response) => Promise<T>, init?: RequestInit) {
-	const cache = new Map<string, Promise<T | null>>()
+	const cache = new LruCache<string, Promise<T | null>>(100)
 
 	return async function fetchCached(url: string): Promise<T | null> {
 		const existing = cache.get(url)

packages/editor/src/lib/utils/sync/TLLocalSyncClient.ts

@@ -262,6 +262,9 @@ export class TLLocalSyncClient {
 		this.debug('closing')
 		this.didDispose = true
 		this.disposables.forEach((d) => d())
+		if (typeof window !== 'undefined' && (window as any).tlsync === this) {
+			delete (window as any).tlsync
+		}
 	}
 
 	private isPersisting = false

packages/sync-core/src/lib/TLSyncClient.ts

@@ -826,6 +826,9 @@ export class TLSyncClient<R extends UnknownRecord, S extends Store<R> = Store<R>
 		this.disposables.forEach((dispose) => dispose())
 		this.sendUnsentChanges.cancel?.()
 		this.scheduleRebase.cancel?.()
+		if (typeof window !== 'undefined' && (window as any).tlsync === this) {
+			delete (window as any).tlsync
+		}
 	}
 
 	private lastPushedPresenceState: R | null = null

packages/tldraw/src/lib/shapes/bookmark/bookmarks.ts

@@ -84,7 +84,7 @@ export function updateBookmarkAssetOnUrlChange(editor: Editor, shape: TLBookmark
 	}
 }
 
-const createBookmarkAssetOnUrlChange = debounce(async (editor: Editor, shape: TLBookmarkShape) => {
+async function _createBookmarkAssetOnUrlChange(editor: Editor, shape: TLBookmarkShape) {
 	if (editor.isDisposed) return
 
 	const { url } = shape.props
@@ -111,7 +111,21 @@ const createBookmarkAssetOnUrlChange = debounce(async (editor: Editor, shape: TL
 			},
 		])
 	})
-}, 500)
+}
+
+const bookmarkDebouncers = new WeakMap<
+	Editor,
+	ReturnType<typeof debounce<[Editor, TLBookmarkShape], void>>
+>()
+
+function createBookmarkAssetOnUrlChange(editor: Editor, shape: TLBookmarkShape) {
+	let fn = bookmarkDebouncers.get(editor)
+	if (!fn) {
+		fn = debounce(_createBookmarkAssetOnUrlChange, 500)
+		bookmarkDebouncers.set(editor, fn)
+	}
+	fn(editor, shape)
+}
 
 /**
  * Creates a bookmark shape from a URL with unfurled metadata.

packages/tldraw/src/lib/shapes/image/ImageAlphaCache.ts

@@ -1,4 +1,4 @@
-import { Image, VecLike } from '@tldraw/editor'
+import { Image, LruCache, VecLike } from '@tldraw/editor'
 
 /** Mime types of image formats that support transparency / alpha channel. */
 export const TRANSPARENT_IMAGE_MIMETYPES: readonly string[] = [
@@ -65,7 +65,7 @@ export function isImagePointTransparent(
 
 const MAX_SIZE = 256
 
-const alphaCache = new Map<string, AlphaData>()
+const alphaCache = new LruCache<string, AlphaData>(100)
 const pending = new Set<string>()
 let offscreenCanvas: OffscreenCanvas | null = null
 

packages/utils/api-report.api.md

@@ -264,6 +264,19 @@ export function lerp(a: number, b: number, t: number): number;
 // @public
 export function lns(str: string): string;
 
+// @public
+export class LruCache<K, V> {
+    constructor(maxSize: number);
+    // (undocumented)
+    get(key: K): undefined | V;
+    // (undocumented)
+    has(key: K): boolean;
+    // (undocumented)
+    set(key: K, value: V): void;
+    // (undocumented)
+    get size(): number;
+}
+
 // @public
 export type MakeUndefinedOptional<T extends object> = Expand<{
     [P in {

packages/utils/src/index.ts

@@ -35,6 +35,7 @@ export { noop, omitFromStackTrace } from './lib/function'
 export { getHashForBuffer, getHashForObject, getHashForString, lns } from './lib/hash'
 export { mockUniqueId, restoreUniqueId, uniqueId } from './lib/id'
 export { getFirstFromIterable } from './lib/iterable'
+export { LruCache } from './lib/LruCache'
 export type { JsonArray, JsonObject, JsonPrimitive, JsonValue } from './lib/json-value'
 export {
 	DEFAULT_SUPPORT_VIDEO_TYPES,

packages/utils/src/lib/LruCache.test.ts

@@ -0,0 +1,89 @@
+import { LruCache } from './LruCache'
+
+describe('LruCache', () => {
+	it('stores and retrieves values', () => {
+		const cache = new LruCache<string, number>(3)
+		cache.set('a', 1)
+		cache.set('b', 2)
+		expect(cache.get('a')).toBe(1)
+		expect(cache.get('b')).toBe(2)
+		expect(cache.get('c')).toBeUndefined()
+	})
+
+	it('reports size', () => {
+		const cache = new LruCache<string, number>(5)
+		expect(cache.size).toBe(0)
+		cache.set('a', 1)
+		expect(cache.size).toBe(1)
+		cache.set('b', 2)
+		expect(cache.size).toBe(2)
+	})
+
+	it('has() checks existence without promoting', () => {
+		const cache = new LruCache<string, number>(2)
+		cache.set('a', 1)
+		cache.set('b', 2)
+		expect(cache.has('a')).toBe(true)
+		expect(cache.has('z')).toBe(false)
+
+		// 'a' was not promoted by has(), so adding 'c' should evict 'a'
+		cache.set('c', 3)
+		expect(cache.has('a')).toBe(false)
+	})
+
+	it('evicts the oldest entry when exceeding capacity', () => {
+		const cache = new LruCache<string, number>(2)
+		cache.set('a', 1)
+		cache.set('b', 2)
+		cache.set('c', 3) // should evict 'a'
+
+		expect(cache.get('a')).toBeUndefined()
+		expect(cache.get('b')).toBe(2)
+		expect(cache.get('c')).toBe(3)
+		expect(cache.size).toBe(2)
+	})
+
+	it('get() promotes entry so it is not evicted next', () => {
+		const cache = new LruCache<string, number>(2)
+		cache.set('a', 1)
+		cache.set('b', 2)
+
+		// Access 'a' to promote it; now 'b' is oldest
+		cache.get('a')
+		cache.set('c', 3) // should evict 'b', not 'a'
+
+		expect(cache.get('b')).toBeUndefined()
+		expect(cache.get('a')).toBe(1)
+		expect(cache.get('c')).toBe(3)
+	})
+
+	it('set() on existing key updates value and promotes it', () => {
+		const cache = new LruCache<string, number>(2)
+		cache.set('a', 1)
+		cache.set('b', 2)
+
+		// Update 'a' — promotes it, 'b' becomes oldest
+		cache.set('a', 10)
+		expect(cache.get('a')).toBe(10)
+
+		cache.set('c', 3) // should evict 'b'
+		expect(cache.get('b')).toBeUndefined()
+		expect(cache.get('a')).toBe(10)
+		expect(cache.size).toBe(2)
+	})
+
+	it('evicts entries in insertion order across many inserts', () => {
+		const cache = new LruCache<number, number>(3)
+		for (let i = 0; i < 10; i++) {
+			cache.set(i, i * 10)
+		}
+		// Only the last 3 should remain
+		expect(cache.size).toBe(3)
+		expect(cache.get(7)).toBe(70)
+		expect(cache.get(8)).toBe(80)
+		expect(cache.get(9)).toBe(90)
+		for (let i = 0; i < 7; i++) {
+			expect(cache.has(i)).toBe(false)
+		}
+	})
+})

packages/utils/src/lib/LruCache.ts

@@ -0,0 +1,32 @@
+/** Simple LRU cache backed by a Map's insertion-order iteration. @public */
+export class LruCache<K, V> {
+	private map = new Map<K, V>()
+	constructor(private maxSize: number) {}
+
+	get(key: K): V | undefined {
+		if (!this.map.has(key)) return undefined
+		const value = this.map.get(key)!
+		// Move to most-recent position
+		this.map.delete(key)
+		this.map.set(key, value)
+		return value
+	}
+
+	set(key: K, value: V): void {
+		if (this.map.has(key)) this.map.delete(key)
+		this.map.set(key, value)
+		if (this.map.size > this.maxSize) {
+			// Evict oldest entry
+			this.map.delete(this.map.keys().next().value!)
+		}
+	}
+
+	has(key: K): boolean {
+		return this.map.has(key)
+	}
+
+	// eslint-disable-next-line tldraw/no-setter-getter
+	get size(): number {
+		return this.map.size
+	}
+}

packages/utils/src/lib/debounce.ts

@@ -79,6 +79,7 @@ export function debounce<T extends unknown[], U>(
 	fn.cancel = () => {
 		if (!state) return
 		clearTimeout(state.timeout)
+		state = undefined
 	}
 	return fn
 }