@tldraw/editor 3.14.0-canary.e0ab6f4c80f9 → 3.14.0-canary.e7ebd007cb8c

package/src/lib/editor/managers/{HistoryManager.ts → HistoryManager/HistoryManager.ts}

@@ -9,8 +9,7 @@ import {
 	squashRecordDiffsMutable,
 } from '@tldraw/store'
 import { exhaustiveSwitchError, noop } from '@tldraw/utils'
-import { TLHistoryBatchOptions, TLHistoryEntry } from '../types/history-types'
-import { stack } from './Stack'
+import { TLHistoryBatchOptions, TLHistoryEntry } from '../../types/history-types'
 
 enum HistoryRecorderState {
 	Recording = 'recording',
@@ -349,3 +348,75 @@ class PendingDiff<R extends UnknownRecord> {
 		return { diff: this.diff, isEmpty: this.isEmpty() }
 	}
 }
+
+import { EMPTY_ARRAY } from '@tldraw/state'
+
+export type Stack<T> = StackItem<T> | EmptyStackItem<T>
+
+export function stack<T>(items?: Array<T>): Stack<T> {
+	if (items) {
+		let result = EMPTY_STACK_ITEM as Stack<T>
+		while (items.length) {
+			result = result.push(items.pop()!)
+		}
+		return result
+	}
+	return EMPTY_STACK_ITEM as any
+}
+
+class EmptyStackItem<T> implements Iterable<T> {
+	readonly length = 0
+	readonly head = null
+	readonly tail: Stack<T> = this
+
+	push(head: T): Stack<T> {
+		return new StackItem<T>(head, this)
+	}
+
+	toArray() {
+		return EMPTY_ARRAY
+	}
+
+	[Symbol.iterator]() {
+		return {
+			next() {
+				return { value: undefined, done: true as const }
+			},
+		}
+	}
+}
+
+const EMPTY_STACK_ITEM = new EmptyStackItem()
+
+class StackItem<T> implements Iterable<T> {
+	length: number
+	constructor(
+		public readonly head: T,
+		public readonly tail: Stack<T>
+	) {
+		this.length = tail.length + 1
+	}
+
+	push(head: T): Stack<T> {
+		return new StackItem(head, this)
+	}
+
+	toArray() {
+		return Array.from(this)
+	}
+
+	[Symbol.iterator]() {
+		let stack = this as Stack<T>
+		return {
+			next() {
+				if (stack.length) {
+					const value = stack.head!
+					stack = stack.tail
+					return { value, done: false as const }
+				} else {
+					return { value: undefined, done: true as const }
+				}
+			},
+		}
+	}
+}

package/src/lib/editor/managers/ScribbleManager/ScribbleManager.test.ts

@@ -0,0 +1,624 @@
+import { TLScribble } from '@tldraw/tlschema'
+import { Editor } from '../../Editor'
+import { ScribbleItem, ScribbleManager } from './ScribbleManager'
+
+// Mock the Editor class
+jest.mock('../../Editor')
+jest.mock('@tldraw/utils', () => ({
+	uniqueId: jest.fn(() => 'test-id'),
+}))
+
+describe('ScribbleManager', () => {
+	let editor: jest.Mocked<Editor>
+	let scribbleManager: ScribbleManager
+	let mockUniqueId: jest.Mock
+
+	beforeEach(() => {
+		editor = {
+			updateInstanceState: jest.fn(),
+			run: jest.fn((fn) => fn()),
+		} as any
+
+		const { uniqueId } = jest.requireMock('@tldraw/utils')
+		mockUniqueId = uniqueId
+		mockUniqueId.mockReturnValue('test-id')
+
+		scribbleManager = new ScribbleManager(editor)
+	})
+
+	afterEach(() => {
+		jest.clearAllMocks()
+	})
+
+	describe('constructor and initialization', () => {
+		it('should initialize with empty scribble items and paused state', () => {
+			expect(scribbleManager.scribbleItems.size).toBe(0)
+			expect(scribbleManager.state).toBe('paused')
+		})
+
+		it('should store reference to editor', () => {
+			expect((scribbleManager as any).editor).toBe(editor)
+		})
+	})
+
+	describe('addScribble', () => {
+		it('should add a new scribble with default values', () => {
+			const result = scribbleManager.addScribble({})
+
+			expect(result).toBeDefined()
+			expect(result.id).toBe('test-id')
+			expect(result.scribble).toMatchObject({
+				id: 'test-id',
+				size: 20,
+				color: 'accent',
+				opacity: 0.8,
+				delay: 0,
+				points: [],
+				shrink: 0.1,
+				taper: true,
+				state: 'starting',
+			})
+			expect(result.timeoutMs).toBe(0)
+			expect(result.delayRemaining).toBe(0)
+			expect(result.prev).toBeNull()
+			expect(result.next).toBeNull()
+		})
+
+		it('should add a scribble with custom properties', () => {
+			const customScribble: Partial<TLScribble> = {
+				size: 30,
+				color: 'black',
+				opacity: 0.5,
+				delay: 1000,
+				shrink: 0.2,
+				taper: false,
+			}
+
+			const result = scribbleManager.addScribble(customScribble)
+
+			expect(result.scribble).toMatchObject({
+				...customScribble,
+				id: 'test-id',
+				points: [],
+				state: 'starting',
+			})
+			expect(result.delayRemaining).toBe(1000)
+		})
+
+		it('should add scribble with custom id', () => {
+			const customId = 'custom-scribble-id'
+			const result = scribbleManager.addScribble({}, customId)
+
+			expect(result.id).toBe(customId)
+			expect(result.scribble.id).toBe(customId)
+			expect(scribbleManager.scribbleItems.has(customId)).toBe(true)
+		})
+
+		it('should store scribble in scribbleItems map', () => {
+			const result = scribbleManager.addScribble({})
+
+			expect(scribbleManager.scribbleItems.size).toBe(1)
+			expect(scribbleManager.scribbleItems.get('test-id')).toBe(result)
+		})
+
+		it('should handle multiple scribbles', () => {
+			mockUniqueId.mockReturnValueOnce('id1').mockReturnValueOnce('id2').mockReturnValueOnce('id3')
+
+			const scribble1 = scribbleManager.addScribble({ color: 'black' })
+			const scribble2 = scribbleManager.addScribble({ color: 'white' })
+			const scribble3 = scribbleManager.addScribble({ color: 'accent' })
+
+			expect(scribbleManager.scribbleItems.size).toBe(3)
+			expect(scribble1.scribble.color).toBe('black')
+			expect(scribble2.scribble.color).toBe('white')
+			expect(scribble3.scribble.color).toBe('accent')
+		})
+	})
+
+	describe('reset', () => {
+		it('should clear all scribble items and update instance state', () => {
+			mockUniqueId.mockReturnValueOnce('id1').mockReturnValueOnce('id2')
+			scribbleManager.addScribble({})
+			scribbleManager.addScribble({})
+			expect(scribbleManager.scribbleItems.size).toBe(2)
+
+			scribbleManager.reset()
+
+			expect(scribbleManager.scribbleItems.size).toBe(0)
+			expect(editor.updateInstanceState).toHaveBeenCalledWith({ scribbles: [] })
+		})
+
+		it('should work when no scribbles exist', () => {
+			expect(() => scribbleManager.reset()).not.toThrow()
+			expect(scribbleManager.scribbleItems.size).toBe(0)
+			expect(editor.updateInstanceState).toHaveBeenCalledWith({ scribbles: [] })
+		})
+	})
+
+	describe('stop', () => {
+		it('should stop an existing scribble', () => {
+			const item = scribbleManager.addScribble({ delay: 1000 })
+			item.delayRemaining = 500
+
+			const result = scribbleManager.stop(item.id)
+
+			expect(result).toBe(item)
+			expect(result.scribble.state).toBe('stopping')
+			expect(result.delayRemaining).toBe(200) // min(500, 200)
+		})
+
+		it('should cap delay at 200ms when stopping', () => {
+			const item = scribbleManager.addScribble({ delay: 50 })
+			item.delayRemaining = 50
+
+			scribbleManager.stop(item.id)
+
+			expect(item.delayRemaining).toBe(50) // min(50, 200)
+		})
+
+		it('should throw error for non-existent scribble', () => {
+			expect(() => scribbleManager.stop('non-existent-id')).toThrow(
+				'Scribble with id non-existent-id not found'
+			)
+		})
+
+		it('should handle stopping multiple scribbles', () => {
+			mockUniqueId.mockReturnValueOnce('id1').mockReturnValueOnce('id2')
+
+			const item1 = scribbleManager.addScribble({})
+			const item2 = scribbleManager.addScribble({})
+
+			scribbleManager.stop('id1')
+			scribbleManager.stop('id2')
+
+			expect(item1.scribble.state).toBe('stopping')
+			expect(item2.scribble.state).toBe('stopping')
+		})
+	})
+
+	describe('addPoint', () => {
+		it('should add point to existing scribble', () => {
+			const item = scribbleManager.addScribble({})
+
+			const result = scribbleManager.addPoint(item.id, 10, 20, 0.7)
+
+			expect(result).toBe(item)
+			expect(result.next).toEqual({ x: 10, y: 20, z: 0.7 })
+		})
+
+		it('should use default z value of 0.5', () => {
+			const item = scribbleManager.addScribble({})
+
+			scribbleManager.addPoint(item.id, 10, 20)
+
+			expect(item.next).toEqual({ x: 10, y: 20, z: 0.5 })
+		})
+
+		it('should only set next if distance from prev is >= 1', () => {
+			const item = scribbleManager.addScribble({})
+			item.prev = { x: 10, y: 20, z: 0.5 }
+
+			// Distance < 1 (should not set next)
+			scribbleManager.addPoint(item.id, 10.5, 20.3)
+			expect(item.next).toBeNull()
+
+			// Distance >= 1 (should set next)
+			scribbleManager.addPoint(item.id, 11, 21)
+			expect(item.next).toEqual({ x: 11, y: 21, z: 0.5 })
+		})
+
+		it('should set next when prev is null', () => {
+			const item = scribbleManager.addScribble({})
+			expect(item.prev).toBeNull()
+
+			scribbleManager.addPoint(item.id, 5, 5)
+
+			expect(item.next).toEqual({ x: 5, y: 5, z: 0.5 })
+		})
+
+		it('should throw error for non-existent scribble', () => {
+			expect(() => scribbleManager.addPoint('non-existent-id', 10, 20)).toThrow(
+				'Scribble with id non-existent-id not found'
+			)
+		})
+
+		it('should handle multiple points', () => {
+			const item = scribbleManager.addScribble({})
+
+			scribbleManager.addPoint(item.id, 0, 0)
+			expect(item.next).toEqual({ x: 0, y: 0, z: 0.5 })
+
+			item.prev = item.next
+			scribbleManager.addPoint(item.id, 10, 10)
+			expect(item.next).toEqual({ x: 10, y: 10, z: 0.5 })
+		})
+	})
+
+	describe('tick', () => {
+		it('should return early when no scribble items exist', () => {
+			scribbleManager.tick(16)
+
+			expect(editor.run).not.toHaveBeenCalled()
+		})
+
+		it('should wrap tick operations in editor.run', () => {
+			scribbleManager.addScribble({})
+
+			scribbleManager.tick(16)
+
+			expect(editor.run).toHaveBeenCalledWith(expect.any(Function))
+		})
+
+		describe('starting state behavior', () => {
+			it('should add points to scribble in starting state', () => {
+				const item = scribbleManager.addScribble({})
+				item.next = { x: 10, y: 20, z: 0.5 }
+
+				scribbleManager.tick(16)
+
+				expect(item.prev).toEqual({ x: 10, y: 20, z: 0.5 })
+				expect(item.scribble.points).toHaveLength(1)
+				expect(item.scribble.points[0]).toEqual({ x: 10, y: 20, z: 0.5 })
+			})
+
+			it('should not add point if next equals prev', () => {
+				const item = scribbleManager.addScribble({})
+				const point = { x: 10, y: 20, z: 0.5 }
+				item.next = point
+				item.prev = point
+
+				scribbleManager.tick(16)
+
+				expect(item.scribble.points).toHaveLength(0)
+			})
+
+			it('should transition to active after 8 points', () => {
+				const item = scribbleManager.addScribble({})
+
+				// Add 9 points to trigger transition
+				for (let i = 0; i < 9; i++) {
+					item.next = { x: i, y: i, z: 0.5 }
+					item.prev = null // Reset prev to ensure point is added
+					scribbleManager.tick(16)
+				}
+
+				expect(item.scribble.state).toBe('active')
+				expect(item.scribble.points).toHaveLength(9)
+			})
+		})
+
+		describe('active state behavior', () => {
+			let item: ScribbleItem
+
+			beforeEach(() => {
+				item = scribbleManager.addScribble({})
+				item.scribble.state = 'active'
+			})
+
+			it('should add new points when next differs from prev', () => {
+				item.next = { x: 10, y: 20, z: 0.5 }
+				item.prev = { x: 0, y: 0, z: 0.5 }
+
+				scribbleManager.tick(16)
+
+				expect(item.prev).toEqual({ x: 10, y: 20, z: 0.5 })
+				expect(item.scribble.points).toContainEqual({ x: 10, y: 20, z: 0.5 })
+			})
+
+			it('should shrink from start when delay is finished and points > 8', () => {
+				// Set up scribble with > 8 points and no delay
+				for (let i = 0; i < 10; i++) {
+					item.scribble.points.push({ x: i, y: i, z: 0.5 })
+				}
+				item.delayRemaining = 0
+				item.next = { x: 50, y: 50, z: 0.5 }
+
+				scribbleManager.tick(16)
+
+				expect(item.scribble.points).toHaveLength(10) // Added one, removed one
+				expect(item.scribble.points[0]).toEqual({ x: 1, y: 1, z: 0.5 }) // First was removed
+			})
+
+			it('should shrink when not moving and timeout reached', () => {
+				item.scribble.points.push({ x: 1, y: 1, z: 0.5 })
+				item.scribble.points.push({ x: 2, y: 2, z: 0.5 })
+				item.timeoutMs = 16 // Will reset to 0, triggering shrink
+
+				scribbleManager.tick(16)
+
+				expect(item.scribble.points).toHaveLength(1)
+				expect(item.scribble.points[0]).toEqual({ x: 2, y: 2, z: 0.5 })
+			})
+
+			it('should reset delay when down to single point while stationary', () => {
+				item.scribble.points.push({ x: 1, y: 1, z: 0.5 })
+				item.scribble.delay = 500
+				item.delayRemaining = 0
+				item.timeoutMs = 16
+
+				scribbleManager.tick(16)
+
+				expect(item.delayRemaining).toBe(500)
+			})
+
+			it('should update timeout correctly', () => {
+				item.timeoutMs = 10
+
+				scribbleManager.tick(5)
+				expect(item.timeoutMs).toBe(15)
+
+				scribbleManager.tick(2)
+				expect(item.timeoutMs).toBe(0) // Reset when >= 16 (15 + 2 = 17)
+			})
+
+			it('should reduce delay remaining', () => {
+				item.delayRemaining = 100
+
+				scribbleManager.tick(30)
+
+				expect(item.delayRemaining).toBeLessThan(100)
+			})
+
+			it('should not reduce delay below 0', () => {
+				item.delayRemaining = 10
+
+				scribbleManager.tick(30)
+
+				expect(item.delayRemaining).toBe(0)
+			})
+		})
+
+		describe('stopping state behavior', () => {
+			let item: ScribbleItem
+
+			beforeEach(() => {
+				item = scribbleManager.addScribble({})
+				item.scribble.state = 'stopping'
+			})
+
+			it('should remove points when delay is finished and timeout reached', () => {
+				item.scribble.points.push({ x: 1, y: 1, z: 0.5 })
+				item.scribble.points.push({ x: 2, y: 2, z: 0.5 })
+				item.delayRemaining = 0
+				item.timeoutMs = 16
+
+				scribbleManager.tick(16)
+
+				expect(item.scribble.points).toHaveLength(1)
+				expect(item.scribble.points[0]).toEqual({ x: 2, y: 2, z: 0.5 })
+			})
+
+			it('should shrink scribble size when shrink is enabled', () => {
+				item.scribble.points.push({ x: 1, y: 1, z: 0.5 })
+				item.scribble.points.push({ x: 2, y: 2, z: 0.5 })
+				item.scribble.size = 20
+				item.scribble.shrink = 0.1
+				item.delayRemaining = 0
+				item.timeoutMs = 16
+
+				scribbleManager.tick(16)
+
+				expect(item.scribble.size).toBe(18) // 20 * (1 - 0.1)
+			})
+
+			it('should not shrink size below 1', () => {
+				item.scribble.points.push({ x: 1, y: 1, z: 0.5 })
+				item.scribble.points.push({ x: 2, y: 2, z: 0.5 })
+				item.scribble.size = 1.5
+				item.scribble.shrink = 0.8
+				item.delayRemaining = 0
+				item.timeoutMs = 16
+
+				scribbleManager.tick(16)
+
+				expect(item.scribble.size).toBe(1) // Math.max(1, 1.5 * 0.2)
+			})
+
+			it('should remove scribble when down to one point', () => {
+				item.scribble.points.push({ x: 1, y: 1, z: 0.5 })
+				item.delayRemaining = 0
+				item.timeoutMs = 16
+
+				scribbleManager.tick(16)
+
+				expect(scribbleManager.scribbleItems.has(item.id)).toBe(false)
+			})
+
+			it('should not process when delay remaining > 0', () => {
+				item.scribble.points.push({ x: 1, y: 1, z: 0.5 })
+				item.scribble.points.push({ x: 2, y: 2, z: 0.5 })
+				item.delayRemaining = 100
+				item.timeoutMs = 16
+
+				scribbleManager.tick(16)
+
+				expect(item.scribble.points).toHaveLength(2) // No change
+			})
+
+			it('should not process when timeout < 16', () => {
+				item.scribble.points.push({ x: 1, y: 1, z: 0.5 })
+				item.scribble.points.push({ x: 2, y: 2, z: 0.5 })
+				item.delayRemaining = 0
+				item.timeoutMs = 10
+
+				scribbleManager.tick(5)
+
+				expect(item.scribble.points).toHaveLength(2) // No change
+				expect(item.timeoutMs).toBe(15)
+			})
+		})
+
+		describe('paused state behavior', () => {
+			it('should do nothing when scribble is paused', () => {
+				const item = scribbleManager.addScribble({})
+				item.scribble.state = 'paused'
+				item.scribble.points.push({ x: 1, y: 1, z: 0.5 })
+				const originalPoints = [...item.scribble.points]
+
+				scribbleManager.tick(16)
+
+				expect(item.scribble.points).toEqual(originalPoints)
+			})
+		})
+
+		describe('instance state updates', () => {
+			it('should update instance state with scribbles', () => {
+				mockUniqueId.mockReturnValueOnce('id1').mockReturnValueOnce('id2')
+				scribbleManager.addScribble({ color: 'black' })
+				scribbleManager.addScribble({ color: 'white' })
+
+				scribbleManager.tick(16)
+
+				expect(editor.updateInstanceState).toHaveBeenCalledWith({
+					scribbles: expect.arrayContaining([
+						expect.objectContaining({
+							color: 'black',
+							points: expect.any(Array),
+						}),
+						expect.objectContaining({
+							color: 'white',
+							points: expect.any(Array),
+						}),
+					]),
+				})
+			})
+
+			it('should create copies of scribbles for instance state', () => {
+				const item = scribbleManager.addScribble({})
+				item.scribble.points.push({ x: 1, y: 1, z: 0.5 })
+
+				scribbleManager.tick(16)
+
+				const call = editor.updateInstanceState.mock.calls[0][0]
+				const scribbleInState = call.scribbles![0]
+
+				// Modify the original
+				item.scribble.points.push({ x: 2, y: 2, z: 0.5 })
+
+				// State copy should be unaffected
+				expect(scribbleInState.points).toHaveLength(1)
+			})
+
+			it('should limit scribbles to 5 items', () => {
+				// Add 7 scribbles
+				const colors = ['accent', 'black', 'white', 'laser', 'muted-1', 'accent', 'black'] as const
+				for (let i = 0; i < 7; i++) {
+					mockUniqueId.mockReturnValueOnce(`id${i}`)
+					scribbleManager.addScribble({ color: colors[i] })
+				}
+
+				scribbleManager.tick(16)
+
+				const call = editor.updateInstanceState.mock.calls[0][0]
+				expect(call.scribbles).toHaveLength(5)
+			})
+		})
+	})
+
+	describe('edge cases and error handling', () => {
+		it('should handle Vec.Dist calculation edge cases', () => {
+			const item = scribbleManager.addScribble({})
+			item.prev = { x: 0, y: 0, z: 0 }
+
+			// Exactly distance 1
+			scribbleManager.addPoint(item.id, 1, 0)
+			expect(item.next).toEqual({ x: 1, y: 0, z: 0.5 })
+
+			// Reset and test just under distance 1
+			item.next = null
+			scribbleManager.addPoint(item.id, 0.9, 0)
+			expect(item.next).toBeNull()
+		})
+
+		it('should handle multiple scribbles in different states', () => {
+			mockUniqueId
+				.mockReturnValueOnce('starting')
+				.mockReturnValueOnce('active')
+				.mockReturnValueOnce('stopping')
+
+			const startingItem = scribbleManager.addScribble({})
+			const activeItem = scribbleManager.addScribble({})
+			const stoppingItem = scribbleManager.addScribble({})
+
+			activeItem.scribble.state = 'active'
+			stoppingItem.scribble.state = 'stopping'
+
+			startingItem.next = { x: 1, y: 1, z: 0.5 }
+			activeItem.next = { x: 2, y: 2, z: 0.5 }
+			stoppingItem.scribble.points.push({ x: 3, y: 3, z: 0.5 })
+			stoppingItem.delayRemaining = 0
+			stoppingItem.timeoutMs = 16
+
+			scribbleManager.tick(16)
+
+			expect(startingItem.scribble.points).toHaveLength(1)
+			expect(activeItem.scribble.points).toHaveLength(1)
+			expect(scribbleManager.scribbleItems.has('stopping')).toBe(false) // Removed
+		})
+
+		it('should handle tick with 0 elapsed time', () => {
+			const item = scribbleManager.addScribble({})
+			item.delayRemaining = 100
+
+			expect(() => scribbleManager.tick(0)).not.toThrow()
+			expect(item.delayRemaining).toBe(100) // Should remain unchanged
+		})
+
+		it('should handle negative elapsed time', () => {
+			const item = scribbleManager.addScribble({})
+			item.delayRemaining = 100
+
+			scribbleManager.tick(-50)
+
+			expect(item.delayRemaining).toBe(100) // Should remain unchanged or handle gracefully
+		})
+
+		it('should handle empty points array operations', () => {
+			const item = scribbleManager.addScribble({})
+			item.scribble.state = 'active'
+			item.timeoutMs = 16
+
+			expect(() => scribbleManager.tick(16)).not.toThrow()
+		})
+	})
+
+	describe('integration scenarios', () => {
+		it('should handle complete scribble lifecycle', () => {
+			const item = scribbleManager.addScribble({ delay: 100 })
+
+			// Starting state - add points
+			for (let i = 0; i < 10; i++) {
+				item.next = { x: i, y: i, z: 0.5 }
+				item.prev = null
+				scribbleManager.tick(16)
+			}
+
+			expect(item.scribble.state).toBe('active')
+			expect(item.scribble.points).toHaveLength(10)
+
+			// Stop the scribble
+			scribbleManager.stop(item.id)
+			expect(item.scribble.state).toBe('stopping')
+
+			// Process until removed
+			let iterations = 0
+			while (scribbleManager.scribbleItems.has(item.id) && iterations < 20) {
+				scribbleManager.tick(16)
+				iterations++
+			}
+
+			expect(scribbleManager.scribbleItems.has(item.id)).toBe(false)
+		})
+
+		it('should handle rapid point additions', () => {
+			const item = scribbleManager.addScribble({})
+
+			// Add many points rapidly
+			for (let i = 0; i < 100; i++) {
+				scribbleManager.addPoint(item.id, i * 2, i * 2) // Ensure distance > 1
+			}
+
+			expect(item.next).toEqual({ x: 198, y: 198, z: 0.5 })
+		})
+	})
+})

package/src/lib/editor/managers/{ScribbleManager.ts → ScribbleManager/ScribbleManager.ts}

@@ -1,7 +1,7 @@
 import { TLScribble, VecModel } from '@tldraw/tlschema'
 import { uniqueId } from '@tldraw/utils'
-import { Vec } from '../../primitives/Vec'
-import { Editor } from '../Editor'
+import { Vec } from '../../../primitives/Vec'
+import { Editor } from '../../Editor'
 
 /** @public */
 export interface ScribbleItem {