@tldraw/editor 3.15.0-next.f1dfcef63951 → 3.15.1

package/src/lib/editor/managers/TextManager/TextManager.ts

@@ -1,4 +1,5 @@
 import { BoxModel, TLDefaultHorizontalAlignStyle } from '@tldraw/tlschema'
+import { objectMapKeys } from '@tldraw/utils'
 import { Editor } from '../../Editor'
 
 const fixNewLines = /\r?\n|\r/g
@@ -60,10 +61,18 @@ export interface TLMeasureTextSpanOpts {
 
 const spaceCharacterRegex = /\s/
 
+const initialDefaultStyles = Object.freeze({
+	'overflow-wrap': 'break-word',
+	'word-break': 'auto',
+	width: null,
+	height: null,
+	'max-width': null,
+	'min-width': null,
+})
+
 /** @public */
 export class TextManager {
 	private elm: HTMLDivElement
-	private defaultStyles: Record<string, string | null>
 
 	constructor(public editor: Editor) {
 		const elm = document.createElement('div')
@@ -73,31 +82,34 @@ export class TextManager {
 		elm.tabIndex = -1
 		this.editor.getContainer().appendChild(elm)
 
-		// we need to save the default styles so that we can restore them when we're done
-		// these must be the css names, not the js names for the styles
-		this.defaultStyles = {
-			'overflow-wrap': 'break-word',
-			'word-break': 'auto',
-			width: null,
-			height: null,
-			'max-width': null,
-			'min-width': null,
+		this.elm = elm
+
+		for (const key of objectMapKeys(initialDefaultStyles)) {
+			elm.style.setProperty(key, initialDefaultStyles[key])
 		}
+	}
 
-		this.elm = elm
+	private setElementStyles(styles: Record<string, string | undefined>) {
+		const stylesToReinstate = {} as any
+		for (const key of objectMapKeys(styles)) {
+			if (typeof styles[key] === 'string') {
+				const oldValue = this.elm.style.getPropertyValue(key)
+				if (oldValue === styles[key]) continue
+				stylesToReinstate[key] = oldValue
+				this.elm.style.setProperty(key, styles[key])
+			}
+		}
+		return () => {
+			for (const key of objectMapKeys(stylesToReinstate)) {
+				this.elm.style.setProperty(key, stylesToReinstate[key])
+			}
+		}
 	}
 
 	dispose() {
 		return this.elm.remove()
 	}
 
-	private resetElmStyles() {
-		const { elm, defaultStyles } = this
-		for (const key in defaultStyles) {
-			elm.style.setProperty(key, defaultStyles[key])
-		}
-	}
-
 	measureText(textToMeasure: string, opts: TLMeasureTextOpts): BoxModel & { scrollWidth: number } {
 		const div = document.createElement('div')
 		div.textContent = normalizeTextForDom(textToMeasure)
@@ -107,54 +119,36 @@ export class TextManager {
 	measureHtml(html: string, opts: TLMeasureTextOpts): BoxModel & { scrollWidth: number } {
 		const { elm } = this
 
-		if (opts.otherStyles) {
-			for (const key in opts.otherStyles) {
-				if (!this.defaultStyles[key]) {
-					// we need to save the original style so that we can restore it when we're done
-					this.defaultStyles[key] = elm.style.getPropertyValue(key)
-				}
-			}
+		const newStyles = {
+			'font-family': opts.fontFamily,
+			'font-style': opts.fontStyle,
+			'font-weight': opts.fontWeight,
+			'font-size': opts.fontSize + 'px',
+			'line-height': opts.lineHeight.toString(),
+			padding: opts.padding,
+			'max-width': opts.maxWidth ? opts.maxWidth + 'px' : undefined,
+			'min-width': opts.minWidth ? opts.minWidth + 'px' : undefined,
+			'overflow-wrap': opts.disableOverflowWrapBreaking ? 'normal' : undefined,
+			...opts.otherStyles,
 		}
 
-		elm.innerHTML = html
+		const restoreStyles = this.setElementStyles(newStyles)
 
-		// Apply the default styles to the element (for all styles here or that were ever seen in opts.otherStyles)
-		this.resetElmStyles()
+		try {
+			elm.innerHTML = html
 
-		elm.style.setProperty('font-family', opts.fontFamily)
-		elm.style.setProperty('font-style', opts.fontStyle)
-		elm.style.setProperty('font-weight', opts.fontWeight)
-		elm.style.setProperty('font-size', opts.fontSize + 'px')
-		elm.style.setProperty('line-height', opts.lineHeight.toString())
-		elm.style.setProperty('padding', opts.padding)
+			const scrollWidth = opts.measureScrollWidth ? elm.scrollWidth : 0
+			const rect = elm.getBoundingClientRect()
 
-		if (opts.maxWidth) {
-			elm.style.setProperty('max-width', opts.maxWidth + 'px')
-		}
-
-		if (opts.minWidth) {
-			elm.style.setProperty('min-width', opts.minWidth + 'px')
-		}
-
-		if (opts.disableOverflowWrapBreaking) {
-			elm.style.setProperty('overflow-wrap', 'normal')
-		}
-
-		if (opts.otherStyles) {
-			for (const [key, value] of Object.entries(opts.otherStyles)) {
-				elm.style.setProperty(key, value)
+			return {
+				x: 0,
+				y: 0,
+				w: rect.width,
+				h: rect.height,
+				scrollWidth,
 			}
-		}
-
-		const scrollWidth = opts.measureScrollWidth ? elm.scrollWidth : 0
-		const rect = elm.getBoundingClientRect()
-
-		return {
-			x: 0,
-			y: 0,
-			w: rect.width,
-			h: rect.height,
-			scrollWidth,
+		} finally {
+			restoreStyles()
 		}
 	}
 
@@ -274,82 +268,68 @@ export class TextManager {
 
 		const { elm } = this
 
-		if (opts.otherStyles) {
-			for (const key in opts.otherStyles) {
-				if (!this.defaultStyles[key]) {
-					// we need to save the original style so that we can restore it when we're done
-					this.defaultStyles[key] = elm.style.getPropertyValue(key)
-				}
-			}
-		}
-
-		this.resetElmStyles()
-
-		elm.style.setProperty('font-family', opts.fontFamily)
-		elm.style.setProperty('font-style', opts.fontStyle)
-		elm.style.setProperty('font-weight', opts.fontWeight)
-		elm.style.setProperty('font-size', opts.fontSize + 'px')
-		elm.style.setProperty('line-height', opts.lineHeight.toString())
-
-		const elementWidth = Math.ceil(opts.width - opts.padding * 2)
-		elm.style.setProperty('width', `${elementWidth}px`)
-		elm.style.setProperty('height', 'min-content')
-		elm.style.setProperty('text-align', textAlignmentsForLtr[opts.textAlign])
-
 		const shouldTruncateToFirstLine =
 			opts.overflow === 'truncate-ellipsis' || opts.overflow === 'truncate-clip'
-
-		if (shouldTruncateToFirstLine) {
-			elm.style.setProperty('overflow-wrap', 'anywhere')
-			elm.style.setProperty('word-break', 'break-all')
-		}
-
-		if (opts.otherStyles) {
-			for (const [key, value] of Object.entries(opts.otherStyles)) {
-				elm.style.setProperty(key, value)
-			}
+		const elementWidth = Math.ceil(opts.width - opts.padding * 2)
+		const newStyles = {
+			'font-family': opts.fontFamily,
+			'font-style': opts.fontStyle,
+			'font-weight': opts.fontWeight,
+			'font-size': opts.fontSize + 'px',
+			'line-height': opts.lineHeight.toString(),
+			width: `${elementWidth}px`,
+			height: 'min-content',
+			'text-align': textAlignmentsForLtr[opts.textAlign],
+			'overflow-wrap': shouldTruncateToFirstLine ? 'anywhere' : undefined,
+			'word-break': shouldTruncateToFirstLine ? 'break-all' : undefined,
+			...opts.otherStyles,
 		}
+		const restoreStyles = this.setElementStyles(newStyles)
 
-		const normalizedText = normalizeTextForDom(textToMeasure)
-
-		// Render the text into the measurement element:
-		elm.textContent = normalizedText
-
-		// actually measure the text:
-		const { spans, didTruncate } = this.measureElementTextNodeSpans(elm, {
-			shouldTruncateToFirstLine,
-		})
+		try {
+			const normalizedText = normalizeTextForDom(textToMeasure)
 
-		if (opts.overflow === 'truncate-ellipsis' && didTruncate) {
-			// we need to measure the ellipsis to know how much space it takes up
-			elm.textContent = '…'
-			const ellipsisWidth = Math.ceil(this.measureElementTextNodeSpans(elm).spans[0].box.w)
-
-			// then, we need to subtract that space from the width we have and measure again:
-			elm.style.setProperty('width', `${elementWidth - ellipsisWidth}px`)
+			// Render the text into the measurement element:
 			elm.textContent = normalizedText
-			const truncatedSpans = this.measureElementTextNodeSpans(elm, {
-				shouldTruncateToFirstLine: true,
-			}).spans
-
-			// Finally, we add in our ellipsis at the end of the last span. We
-			// have to do this after measuring, not before, because adding the
-			// ellipsis changes how whitespace might be getting collapsed by the
-			// browser.
-			const lastSpan = truncatedSpans[truncatedSpans.length - 1]!
-			truncatedSpans.push({
-				text: '…',
-				box: {
-					x: Math.min(lastSpan.box.x + lastSpan.box.w, opts.width - opts.padding - ellipsisWidth),
-					y: lastSpan.box.y,
-					w: ellipsisWidth,
-					h: lastSpan.box.h,
-				},
+
+			// actually measure the text:
+			const { spans, didTruncate } = this.measureElementTextNodeSpans(elm, {
+				shouldTruncateToFirstLine,
 			})
 
-			return truncatedSpans
-		}
+			if (opts.overflow === 'truncate-ellipsis' && didTruncate) {
+				// we need to measure the ellipsis to know how much space it takes up
+				elm.textContent = '…'
+				const ellipsisWidth = Math.ceil(this.measureElementTextNodeSpans(elm).spans[0].box.w)
+
+				// then, we need to subtract that space from the width we have and measure again:
+				elm.style.setProperty('width', `${elementWidth - ellipsisWidth}px`)
+				elm.textContent = normalizedText
+				const truncatedSpans = this.measureElementTextNodeSpans(elm, {
+					shouldTruncateToFirstLine: true,
+				}).spans
+
+				// Finally, we add in our ellipsis at the end of the last span. We
+				// have to do this after measuring, not before, because adding the
+				// ellipsis changes how whitespace might be getting collapsed by the
+				// browser.
+				const lastSpan = truncatedSpans[truncatedSpans.length - 1]!
+				truncatedSpans.push({
+					text: '…',
+					box: {
+						x: Math.min(lastSpan.box.x + lastSpan.box.w, opts.width - opts.padding - ellipsisWidth),
+						y: lastSpan.box.y,
+						w: ellipsisWidth,
+						h: lastSpan.box.h,
+					},
+				})
+
+				return truncatedSpans
+			}
 
-		return spans
+			return spans
+		} finally {
+			restoreStyles()
+		}
 	}
 }

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

@@ -24,6 +24,7 @@ describe('UserPreferencesManager', () => {
 		color: '#FF802B',
 		locale: 'en',
 		animationSpeed: 1,
+		areKeyboardShortcutsEnabled: true,
 		edgeScrollSpeed: 1,
 		colorScheme: 'light',
 		isSnapMode: false,
@@ -229,6 +230,7 @@ describe('UserPreferencesManager', () => {
 				locale: mockUserPreferences.locale,
 				color: mockUserPreferences.color,
 				animationSpeed: mockUserPreferences.animationSpeed,
+				areKeyboardShortcutsEnabled: mockUserPreferences.areKeyboardShortcutsEnabled,
 				isSnapMode: mockUserPreferences.isSnapMode,
 				colorScheme: mockUserPreferences.colorScheme,
 				isDarkMode: false, // light mode
@@ -362,6 +364,21 @@ describe('UserPreferencesManager', () => {
 			})
 		})
 
+		describe('getAreKeyboardShortcutsEnabled', () => {
+			it('should return user keyboard shortcuts', () => {
+				expect(userPreferencesManager.getAreKeyboardShortcutsEnabled()).toBe(
+					mockUserPreferences.areKeyboardShortcutsEnabled
+				)
+			})
+
+			it('should return default keyboard shortcuts when null', () => {
+				userPreferencesAtom.set({ ...mockUserPreferences, areKeyboardShortcutsEnabled: null })
+				expect(userPreferencesManager.getAreKeyboardShortcutsEnabled()).toBe(
+					defaultUserPreferences.areKeyboardShortcutsEnabled
+				)
+			})
+		})
+
 		describe('getEdgeScrollSpeed', () => {
 			it('should return user edge scroll speed', () => {
 				expect(userPreferencesManager.getEdgeScrollSpeed()).toBe(
@@ -483,6 +500,7 @@ describe('UserPreferencesManager', () => {
 				color: null,
 				locale: null,
 				animationSpeed: null,
+				areKeyboardShortcutsEnabled: null,
 				edgeScrollSpeed: null,
 				isSnapMode: null,
 				isWrapMode: null,
@@ -496,6 +514,9 @@ describe('UserPreferencesManager', () => {
 			expect(userPreferencesManager.getColor()).toBe(defaultUserPreferences.color)
 			expect(userPreferencesManager.getLocale()).toBe(defaultUserPreferences.locale)
 			expect(userPreferencesManager.getAnimationSpeed()).toBe(defaultUserPreferences.animationSpeed)
+			expect(userPreferencesManager.getAreKeyboardShortcutsEnabled()).toBe(
+				defaultUserPreferences.areKeyboardShortcutsEnabled
+			)
 			expect(userPreferencesManager.getEdgeScrollSpeed()).toBe(
 				defaultUserPreferences.edgeScrollSpeed
 			)

package/src/lib/editor/managers/UserPreferencesManager/UserPreferencesManager.ts

@@ -43,6 +43,7 @@ export class UserPreferencesManager {
 			locale: this.getLocale(),
 			color: this.getColor(),
 			animationSpeed: this.getAnimationSpeed(),
+			areKeyboardShortcutsEnabled: this.getAreKeyboardShortcutsEnabled(),
 			isSnapMode: this.getIsSnapMode(),
 			colorScheme: this.user.userPreferences.get().colorScheme,
 			isDarkMode: this.getIsDarkMode(),
@@ -75,6 +76,13 @@ export class UserPreferencesManager {
 		return this.user.userPreferences.get().animationSpeed ?? defaultUserPreferences.animationSpeed
 	}
 
+	@computed getAreKeyboardShortcutsEnabled() {
+		return (
+			this.user.userPreferences.get().areKeyboardShortcutsEnabled ??
+			defaultUserPreferences.areKeyboardShortcutsEnabled
+		)
+	}
+
 	@computed getId() {
 		return this.user.userPreferences.get().id
 	}

package/src/lib/editor/tools/StateNode.test.ts

@@ -0,0 +1,285 @@
+import { createTLStore } from '../../config/createTLStore'
+import { Editor } from '../Editor'
+import { StateNode } from './StateNode'
+
+describe('StateNode.addChild', () => {
+	// Test state node classes for addChild tests
+	class ParentState extends StateNode {
+		static override id = 'parent'
+		static override initial = 'child1'
+		static override children() {
+			return [ChildState1]
+		}
+	}
+
+	class ChildState1 extends StateNode {
+		static override id = 'child1'
+	}
+
+	class ChildState2 extends StateNode {
+		static override id = 'child2'
+	}
+
+	class ChildState3 extends StateNode {
+		static override id = 'child3'
+	}
+
+	class LeafState extends StateNode {
+		static override id = 'leaf'
+	}
+
+	class RootState extends StateNode {
+		static override id = 'root'
+		static override initial = 'child1'
+		static override children() {
+			return [ChildState1]
+		}
+	}
+
+	class RootStateWithoutChildren extends StateNode {
+		static override id = 'rootWithoutChildren'
+	}
+
+	let editor: Editor
+
+	beforeEach(() => {
+		editor = new Editor({
+			initialState: 'parent',
+			shapeUtils: [],
+			bindingUtils: [],
+			tools: [
+				ParentState,
+				ChildState1,
+				ChildState2,
+				ChildState3,
+				LeafState,
+				RootState,
+				RootStateWithoutChildren,
+			],
+			store: createTLStore({ shapeUtils: [], bindingUtils: [] }),
+			getContainer: () => document.body,
+		})
+	})
+
+	it('should add a child to a branch state node', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		// Initially should have one child
+		expect(Object.keys(parentState.children!)).toHaveLength(1)
+		expect(parentState.children!['child1']).toBeDefined()
+
+		// Add a new child
+		parentState.addChild(ChildState2)
+
+		// Should now have two children
+		expect(Object.keys(parentState.children!)).toHaveLength(2)
+		expect(parentState.children!['child1']).toBeDefined()
+		expect(parentState.children!['child2']).toBeDefined()
+		expect(parentState.children!['child2']).toBeInstanceOf(ChildState2)
+	})
+
+	it('should add a child to a root state node', () => {
+		const rootState = editor.root.children!['root'] as RootState
+
+		// Initially should have one child
+		expect(Object.keys(rootState.children!)).toHaveLength(1)
+		expect(rootState.children!['child1']).toBeDefined()
+
+		// Add a new child
+		rootState.addChild(ChildState2)
+
+		// Should now have two children
+		expect(Object.keys(rootState.children!)).toHaveLength(2)
+		expect(rootState.children!['child1']).toBeDefined()
+		expect(rootState.children!['child2']).toBeDefined()
+		expect(rootState.children!['child2']).toBeInstanceOf(ChildState2)
+	})
+
+	it('should throw an error when trying to add a child to a leaf state node', () => {
+		const leafState = editor.root.children!['leaf'] as LeafState
+
+		// Leaf state should not have children
+		expect(leafState.children).toBeUndefined()
+
+		// Should throw an error when trying to add a child
+		expect(() => {
+			leafState.addChild(ChildState2)
+		}).toThrow('StateNode.addChild: cannot add child to a leaf node')
+	})
+
+	it('should return the parent state node for chaining', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		const result = parentState.addChild(ChildState2)
+
+		expect(result).toBe(parentState)
+	})
+
+	it('should create the child with the correct editor and parent', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		parentState.addChild(ChildState2)
+		const childState = parentState.children!['child2'] as ChildState2
+
+		expect(childState.editor).toBe(editor)
+		expect(childState.parent).toBe(parentState)
+	})
+
+	it('should allow adding multiple children', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		// Add multiple children
+		parentState.addChild(ChildState2).addChild(ChildState3)
+
+		// Should have three children
+		expect(Object.keys(parentState.children!)).toHaveLength(3)
+		expect(parentState.children!['child1']).toBeDefined()
+		expect(parentState.children!['child2']).toBeDefined()
+		expect(parentState.children!['child3']).toBeDefined()
+		expect(parentState.children!['child2']).toBeInstanceOf(ChildState2)
+		expect(parentState.children!['child3']).toBeInstanceOf(ChildState3)
+	})
+
+	it('should allow transitioning to added children', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		// Add a new child
+		parentState.addChild(ChildState2)
+
+		// Should be able to transition to the new child
+		expect(() => {
+			parentState.transition('child2')
+		}).not.toThrow()
+
+		// The current state should be the new child
+		expect(parentState.getCurrent()?.id).toBe('child2')
+	})
+
+	it('should maintain existing children when adding new ones', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+		const originalChild = parentState.children!['child1']
+
+		// Add a new child
+		parentState.addChild(ChildState2)
+
+		// Original child should still exist and be the same instance
+		expect(parentState.children!['child1']).toBe(originalChild)
+		expect(parentState.children!['child1']).toBeInstanceOf(ChildState1)
+	})
+
+	it('should initialize children object for root nodes without static children', () => {
+		// Create a StateNode directly as a root node (no parent)
+		const mockEditor = {} as Editor
+		const rootStateWithoutChildren = new RootStateWithoutChildren(mockEditor, undefined)
+
+		// Root state without static children should not have children initially
+		expect(rootStateWithoutChildren.children).toBeUndefined()
+
+		// Adding a child should initialize the children object
+		rootStateWithoutChildren.addChild(ChildState2)
+
+		// Should now have children object with the added child
+		expect(rootStateWithoutChildren.children).toBeDefined()
+		expect(Object.keys(rootStateWithoutChildren.children!)).toHaveLength(1)
+		expect(rootStateWithoutChildren.children!['child2']).toBeDefined()
+		expect(rootStateWithoutChildren.children!['child2']).toBeInstanceOf(ChildState2)
+	})
+
+	it('should throw an error when trying to add a child with a duplicate ID', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		// Initially should have one child
+		expect(Object.keys(parentState.children!)).toHaveLength(1)
+		expect(parentState.children!['child1']).toBeDefined()
+
+		// Should throw an error when trying to add a child with the same ID
+		expect(() => {
+			parentState.addChild(ChildState1)
+		}).toThrow("StateNode.addChild: a child with id 'child1' already exists")
+
+		// Should still have only one child
+		expect(Object.keys(parentState.children!)).toHaveLength(1)
+		expect(parentState.children!['child1']).toBeDefined()
+	})
+
+	it('should throw an error when trying to add a child with a duplicate ID to a root state', () => {
+		const rootState = editor.root.children!['root'] as RootState
+
+		// Initially should have one child
+		expect(Object.keys(rootState.children!)).toHaveLength(1)
+		expect(rootState.children!['child1']).toBeDefined()
+
+		// Should throw an error when trying to add a child with the same ID
+		expect(() => {
+			rootState.addChild(ChildState1)
+		}).toThrow("StateNode.addChild: a child with id 'child1' already exists")
+
+		// Should still have only one child
+		expect(Object.keys(rootState.children!)).toHaveLength(1)
+		expect(rootState.children!['child1']).toBeDefined()
+	})
+
+	it('should throw an error when trying to add a child with a duplicate ID to a root state without static children', () => {
+		// Create a StateNode directly as a root node (no parent)
+		const mockEditor = {} as Editor
+		const rootStateWithoutChildren = new RootStateWithoutChildren(mockEditor, undefined)
+
+		// Add a child first
+		rootStateWithoutChildren.addChild(ChildState1)
+
+		// Should throw an error when trying to add a child with the same ID
+		expect(() => {
+			rootStateWithoutChildren.addChild(ChildState1)
+		}).toThrow("StateNode.addChild: a child with id 'child1' already exists")
+
+		// Should still have only one child
+		expect(Object.keys(rootStateWithoutChildren.children!)).toHaveLength(1)
+		expect(rootStateWithoutChildren.children!['child1']).toBeDefined()
+	})
+})
+
+describe('current tool id mask', () => {
+	// Tool mask test classes
+	class ToolA extends StateNode {
+		static override id = 'A'
+	}
+
+	class ToolB extends StateNode {
+		static override id = 'B'
+	}
+
+	class ToolC extends StateNode {
+		static override id = 'C'
+
+		override onEnter() {
+			this.setCurrentToolIdMask('A')
+		}
+	}
+
+	let toolMaskEditor: Editor
+
+	beforeEach(() => {
+		toolMaskEditor = new Editor({
+			initialState: 'A',
+			shapeUtils: [],
+			bindingUtils: [],
+			tools: [ToolA, ToolB, ToolC],
+			store: createTLStore({ shapeUtils: [], bindingUtils: [] }),
+			getContainer: () => document.body,
+		})
+	})
+
+	it('starts with the correct tool id', () => {
+		expect(toolMaskEditor.getCurrentToolId()).toBe('A')
+	})
+
+	it('updates the current tool id', () => {
+		toolMaskEditor.setCurrentTool('B')
+		expect(toolMaskEditor.getCurrentToolId()).toBe('B')
+	})
+
+	it('masks the current tool id', () => {
+		toolMaskEditor.setCurrentTool('C')
+		expect(toolMaskEditor.getCurrentToolId()).toBe('A')
+	})
+})

package/src/lib/editor/tools/StateNode.ts

@@ -62,7 +62,7 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 
 		this.parent = parent ?? ({} as any)
 
-		if (this.parent) {
+		if (parent) {
 			if (children && initial) {
 				this.type = 'branch'
 				this.initial = initial
@@ -238,6 +238,32 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 		this._currentToolIdMask.set(id)
 	}
 
+	/**
+	 * Add a child node to this state node.
+	 *
+	 * @public
+	 */
+	addChild(childConstructor: TLStateNodeConstructor): this {
+		if (this.type === 'leaf') {
+			throw new Error('StateNode.addChild: cannot add child to a leaf node')
+		}
+
+		// Initialize children if it's undefined (for root nodes without static children)
+		if (!this.children) {
+			this.children = {}
+		}
+
+		const child = new childConstructor(this.editor, this)
+
+		// Check if a child with this ID already exists
+		if (this.children[child.id]) {
+			throw new Error(`StateNode.addChild: a child with id '${child.id}' already exists`)
+		}
+
+		this.children[child.id] = child
+		return this
+	}
+
 	onWheel?(info: TLWheelEventInfo): void
 	onPointerDown?(info: TLPointerEventInfo): void
 	onPointerMove?(info: TLPointerEventInfo): void