@tldraw/editor 3.15.1 → 3.16.0-canary.03ed24d72068

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/editor",
   "description": "tldraw infinite canvas SDK (editor).",
-  "version": "3.15.1",
+  "version": "3.16.0-canary.03ed24d72068",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
@@ -49,12 +49,12 @@
     "@tiptap/core": "^2.9.1",
     "@tiptap/pm": "^2.9.1",
     "@tiptap/react": "^2.9.1",
-    "@tldraw/state": "3.15.1",
-    "@tldraw/state-react": "3.15.1",
-    "@tldraw/store": "3.15.1",
-    "@tldraw/tlschema": "3.15.1",
-    "@tldraw/utils": "3.15.1",
-    "@tldraw/validate": "3.15.1",
+    "@tldraw/state": "3.16.0-canary.03ed24d72068",
+    "@tldraw/state-react": "3.16.0-canary.03ed24d72068",
+    "@tldraw/store": "3.16.0-canary.03ed24d72068",
+    "@tldraw/tlschema": "3.16.0-canary.03ed24d72068",
+    "@tldraw/utils": "3.16.0-canary.03ed24d72068",
+    "@tldraw/validate": "3.16.0-canary.03ed24d72068",
     "@types/core-js": "^2.5.8",
     "@use-gesture/react": "^10.3.1",
     "classnames": "^2.5.1",

package/src/index.ts

@@ -67,6 +67,10 @@ export {
 	DefaultShapeIndicators,
 	type TLShapeIndicatorsProps,
 } from './lib/components/default-components/DefaultShapeIndicators'
+export {
+	DefaultShapeWrapper,
+	type TLShapeWrapperProps,
+} from './lib/components/default-components/DefaultShapeWrapper'
 export {
 	DefaultSnapIndicator,
 	type TLSnapIndicatorProps,
@@ -261,9 +265,11 @@ export {
 	type TLCameraMoveOptions,
 	type TLCameraOptions,
 	type TLExportType,
+	type TLGetShapeAtPointOptions,
 	type TLImageExportOptions,
 	type TLSvgExportOptions,
 	type TLSvgOptions,
+	type TLUpdatePointerOptions,
 } from './lib/editor/types/misc-types'
 export {
 	type TLAdjacentDirection,
@@ -445,6 +451,7 @@ export {
 	setPointerCapture,
 	stopEventPropagation,
 } from './lib/utils/dom'
+export { EditorAtom } from './lib/utils/EditorAtom'
 export { getIncrementedName } from './lib/utils/getIncrementedName'
 export { getPointerInfo } from './lib/utils/getPointerInfo'
 export { getSvgPathFromPoints } from './lib/utils/getSvgPathFromPoints'

package/src/lib/TldrawEditor.tsx

@@ -1,9 +1,9 @@
 import { MigrationSequence, Store } from '@tldraw/store'
 import { TLShape, TLStore, TLStoreSnapshot } from '@tldraw/tlschema'
-import { Required, annotateError } from '@tldraw/utils'
+import { annotateError, Required } from '@tldraw/utils'
 import React, {
-	ReactNode,
 	memo,
+	ReactNode,
 	useCallback,
 	useEffect,
 	useLayoutEffect,
@@ -15,13 +15,13 @@ import React, {
 
 import classNames from 'classnames'
 import { version } from '../version'
-import { OptionalErrorBoundary } from './components/ErrorBoundary'
 import { DefaultErrorFallback } from './components/default-components/DefaultErrorFallback'
-import { TLEditorSnapshot } from './config/TLEditorSnapshot'
+import { OptionalErrorBoundary } from './components/ErrorBoundary'
 import { TLStoreBaseOptions } from './config/createTLStore'
-import { TLUser, createTLUser } from './config/createTLUser'
+import { createTLUser, TLUser } from './config/createTLUser'
 import { TLAnyBindingUtilConstructor } from './config/defaultBindings'
 import { TLAnyShapeUtilConstructor } from './config/defaultShapes'
+import { TLEditorSnapshot } from './config/TLEditorSnapshot'
 import { Editor } from './editor/Editor'
 import { TLStateNodeConstructor } from './editor/tools/StateNode'
 import { TLCameraOptions } from './editor/types/misc-types'
@@ -39,6 +39,7 @@ import { useForceUpdate } from './hooks/useForceUpdate'
 import { useShallowObjectIdentity } from './hooks/useIdentity'
 import { useLocalStore } from './hooks/useLocalStore'
 import { useRefState } from './hooks/useRefState'
+import { useStateAttribute } from './hooks/useStateAttribute'
 import { useZoomCss } from './hooks/useZoomCss'
 import { LicenseProvider } from './license/LicenseProvider'
 import { Watermark } from './license/Watermark'
@@ -646,6 +647,7 @@ function Layout({ children, onMount }: { children: ReactNode; onMount?: TLOnMoun
 	useCursor()
 	useDarkMode()
 	useForceUpdate()
+	useStateAttribute()
 	useOnMount((editor) => {
 		const teardownStore = editor.store.props.onMount(editor)
 		const teardownCallback = onMount?.(editor)

package/src/lib/components/MenuClickCapture.tsx

@@ -50,12 +50,6 @@ export function MenuClickCapture() {
 			// Do nothing unless we're pointing
 			if (!rPointerState.current.isDown) return
 
-			// If we're already dragging, pass on the event as it is
-			if (rPointerState.current.isDragging) {
-				canvasEvents.onPointerMove?.(e)
-				return
-			}
-
 			if (
 				// We're pointing, but are we dragging?
 				Vec.Dist2(rPointerState.current.start, new Vec(e.clientX, e.clientY)) >
@@ -75,8 +69,6 @@ export function MenuClickCapture() {
 					clientY: y,
 					button: 0,
 				})
-				// call the pointer move with the current pointer position
-				canvasEvents.onPointerMove?.(e)
 			}
 		},
 		[canvasEvents, editor]

package/src/lib/components/Shape.tsx

@@ -40,7 +40,7 @@ export const Shape = memo(function Shape({
 }) {
 	const editor = useEditor()
 
-	const { ShapeErrorFallback } = useEditorComponents()
+	const { ShapeErrorFallback, ShapeWrapper } = useEditorComponents()
 
 	const containerRef = useRef<HTMLDivElement>(null)
 	const bgContainerRef = useRef<HTMLDivElement>(null)
@@ -145,37 +145,22 @@ export const Shape = memo(function Shape({
 		[editor]
 	)
 
-	if (!shape) return null
-
-	const isFilledShape = 'fill' in shape.props && shape.props.fill !== 'none'
+	if (!shape || !ShapeWrapper) return null
 
 	return (
 		<>
 			{util.backgroundComponent && (
-				<div
-					ref={bgContainerRef}
-					className="tl-shape tl-shape-background"
-					data-shape-type={shape.type}
-					data-shape-id={shape.id}
-					draggable={false}
-				>
+				<ShapeWrapper ref={bgContainerRef} shape={shape} isBackground={true}>
 					<OptionalErrorBoundary fallback={ShapeErrorFallback} onError={annotateError}>
 						<InnerShapeBackground shape={shape} util={util} />
 					</OptionalErrorBoundary>
-				</div>
+				</ShapeWrapper>
 			)}
-			<div
-				ref={containerRef}
-				className="tl-shape"
-				data-shape-type={shape.type}
-				data-shape-is-filled={isFilledShape}
-				data-shape-id={shape.id}
-				draggable={false}
-			>
+			<ShapeWrapper ref={containerRef} shape={shape} isBackground={false}>
 				<OptionalErrorBoundary fallback={ShapeErrorFallback as any} onError={annotateError}>
 					<InnerShape shape={shape} util={util} />
 				</OptionalErrorBoundary>
-			</div>
+			</ShapeWrapper>
 		</>
 	)
 })

package/src/lib/components/default-components/DefaultCollaboratorHint.tsx

@@ -44,7 +44,7 @@ export function DefaultCollaboratorHint({
 				href={`#${cursorHintId}`}
 				color={color}
 				strokeWidth={3}
-				stroke="var(--color-background)"
+				stroke="var(--tl-color-background)"
 			/>
 			<use href={`#${cursorHintId}`} color={color} opacity={opacity} />
 		</svg>

package/src/lib/components/default-components/DefaultScribble.tsx

@@ -21,7 +21,7 @@ export function DefaultScribble({ scribble, zoom, color, opacity, className }: T
 			<path
 				className="tl-scribble"
 				d={getSvgPathFromPoints(scribble.points, false)}
-				stroke={color ?? `var(--color-${scribble.color})`}
+				stroke={color ?? `var(--tl-color-${scribble.color})`}
 				fill="none"
 				strokeWidth={8 / zoom}
 				opacity={opacity ?? scribble.opacity}

package/src/lib/components/default-components/DefaultShapeIndicator.tsx

@@ -87,7 +87,11 @@ export const DefaultShapeIndicator = memo(function DefaultShapeIndicator({
 
 	return (
 		<svg ref={rIndicator} className={classNames('tl-overlays__item', className)} aria-hidden="true">
-			<g className="tl-shape-indicator" stroke={color ?? 'var(--color-selected)'} opacity={opacity}>
+			<g
+				className="tl-shape-indicator"
+				stroke={color ?? 'var(--tl-color-selected)'}
+				opacity={opacity}
+			>
 				<InnerIndicator editor={editor} id={shapeId} />
 			</g>
 		</svg>

package/src/lib/components/default-components/DefaultShapeWrapper.tsx

@@ -0,0 +1,35 @@
+import { TLShape } from '@tldraw/tlschema'
+import classNames from 'classnames'
+import { forwardRef, ReactNode } from 'react'
+
+/** @public */
+export interface TLShapeWrapperProps extends React.HTMLAttributes<HTMLDivElement> {
+	/** The shape being rendered. */
+	shape: TLShape
+	/** Whether this is the shapes regular, or background component. */
+	isBackground: boolean
+	/** The shape's rendered component. */
+	children: ReactNode
+}
+
+/** @public @react */
+export const DefaultShapeWrapper = forwardRef(function DefaultShapeWrapper(
+	{ children, shape, isBackground, ...props }: TLShapeWrapperProps,
+	ref: React.Ref<HTMLDivElement>
+) {
+	const isFilledShape = 'fill' in shape.props && shape.props.fill !== 'none'
+
+	return (
+		<div
+			ref={ref}
+			data-shape-type={shape.type}
+			data-shape-is-filled={isBackground ? undefined : isFilledShape}
+			data-shape-id={shape.id}
+			draggable={false}
+			{...props}
+			className={classNames('tl-shape', isBackground && 'tl-shape-background', props.className)}
+		>
+			{children}
+		</div>
+	)
+})

package/src/lib/config/TLUserPreferences.ts

@@ -24,6 +24,7 @@ export interface TLUserPreferences {
 	isWrapMode?: boolean | null
 	isDynamicSizeMode?: boolean | null
 	isPasteAtCursorMode?: boolean | null
+	showUiLabels?: boolean | null
 }
 
 interface UserDataSnapshot {
@@ -52,6 +53,7 @@ export const userTypeValidator: T.Validator<TLUserPreferences> = T.object<TLUser
 	isWrapMode: T.boolean.nullable().optional(),
 	isDynamicSizeMode: T.boolean.nullable().optional(),
 	isPasteAtCursorMode: T.boolean.nullable().optional(),
+	showUiLabels: T.boolean.nullable().optional(),
 })
 
 const Versions = {
@@ -64,6 +66,7 @@ const Versions = {
 	AllowSystemColorScheme: 7,
 	AddPasteAtCursor: 8,
 	AddKeyboardShortcuts: 9,
+	AddShowUiLabels: 10,
 } as const
 
 const CURRENT_VERSION = Math.max(...Object.values(Versions))
@@ -102,6 +105,9 @@ function migrateSnapshot(data: { version: number; user: any }) {
 	if (data.version < Versions.AddKeyboardShortcuts) {
 		data.user.areKeyboardShortcutsEnabled = true
 	}
+	if (data.version < Versions.AddShowUiLabels) {
+		data.user.showUiLabels = false
+	}
 
 	// finally
 	data.version = CURRENT_VERSION
@@ -150,6 +156,7 @@ export const defaultUserPreferences = Object.freeze({
 	isWrapMode: false,
 	isDynamicSizeMode: false,
 	isPasteAtCursorMode: false,
+	showUiLabels: false,
 	colorScheme: 'light',
 }) satisfies Readonly<Omit<TLUserPreferences, 'id'>>
 

package/src/lib/editor/Editor.ts

@@ -176,8 +176,10 @@ import {
 	RequiredKeys,
 	TLCameraMoveOptions,
 	TLCameraOptions,
+	TLGetShapeAtPointOptions,
 	TLImageExportOptions,
 	TLSvgExportOptions,
+	TLUpdatePointerOptions,
 } from './types/misc-types'
 import { TLAdjacentDirection, TLResizeHandle } from './types/selection-types'
 
@@ -3072,7 +3074,6 @@ export class Editor extends EventEmitter<TLEventMap> {
 			// Dispatch a new pointer move because the pointer's page will have changed
 			// (its screen position will compute to a new page position given the new camera position)
 			const { currentScreenPoint, currentPagePoint } = this.inputs
-			const { screenBounds } = this.store.unsafeGetWithoutCapture(TLINSTANCE_ID)!
 
 			// compare the next page point (derived from the current camera) to the current page point
 			if (
@@ -3080,27 +3081,10 @@ export class Editor extends EventEmitter<TLEventMap> {
 				currentScreenPoint.y / z - y !== currentPagePoint.y
 			) {
 				// If it's changed, dispatch a pointer event
-				const event: TLPointerEventInfo = {
-					type: 'pointer',
-					target: 'canvas',
-					name: 'pointer_move',
-					// weird but true: we need to put the screen point back into client space
-					point: Vec.AddXY(currentScreenPoint, screenBounds.x, screenBounds.y),
+				this.updatePointer({
+					immediate: opts?.immediate,
 					pointerId: INTERNAL_POINTER_IDS.CAMERA_MOVE,
-					ctrlKey: this.inputs.ctrlKey,
-					altKey: this.inputs.altKey,
-					shiftKey: this.inputs.shiftKey,
-					metaKey: this.inputs.metaKey,
-					accelKey: isAccelKey(this.inputs),
-					button: 0,
-					isPen: this.getInstanceState().isPenMode ?? false,
-				}
-
-				if (opts?.immediate) {
-					this._flushEventForTick(event)
-				} else {
-					this.dispatch(event)
-				}
+				})
 			}
 
 			this._tickCameraState()
@@ -4421,21 +4405,28 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 */
 	deletePage(page: TLPageId | TLPage): this {
 		const id = typeof page === 'string' ? page : page.id
-		this.run(() => {
-			if (this.getIsReadonly()) return
-			const pages = this.getPages()
-			if (pages.length === 1) return
+		this.run(
+			() => {
+				if (this.getIsReadonly()) return
+				const pages = this.getPages()
+				if (pages.length === 1) return
 
-			const deletedPage = this.getPage(id)
-			if (!deletedPage) return
+				const deletedPage = this.getPage(id)
+				if (!deletedPage) return
 
-			if (id === this.getCurrentPageId()) {
-				const index = pages.findIndex((page) => page.id === id)
-				const next = pages[index - 1] ?? pages[index + 1]
-				this.setCurrentPage(next.id)
-			}
-			this.store.remove([deletedPage.id])
-		})
+				if (id === this.getCurrentPageId()) {
+					const index = pages.findIndex((page) => page.id === id)
+					const next = pages[index - 1] ?? pages[index + 1]
+					this.setCurrentPage(next.id)
+				}
+
+				const shapes = this.getSortedChildIdsForParent(deletedPage.id)
+				this.deleteShapes(shapes)
+
+				this.store.remove([deletedPage.id])
+			},
+			{ ignoreShapeLock: true }
+		)
 		return this
 	}
 
@@ -5164,20 +5155,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 *
 	 * @returns The shape at the given point, or undefined if there is no shape at the point.
 	 */
-	getShapeAtPoint(
-		point: VecLike,
-		opts = {} as {
-			renderingOnly?: boolean
-			margin?: number
-			hitInside?: boolean
-			hitLocked?: boolean
-			// TODO: we probably need to rename this, we don't quite _always_
-			// respect this esp. in the part below that does "Check labels first"
-			hitLabels?: boolean
-			hitFrameInside?: boolean
-			filter?(shape: TLShape): boolean
-		}
-	): TLShape | undefined {
+	getShapeAtPoint(point: VecLike, opts: TLGetShapeAtPointOptions = {}): TLShape | undefined {
 		const zoomLevel = this.getZoomLevel()
 		const viewportPageBounds = this.getViewportPageBounds()
 		const {
@@ -5189,6 +5167,8 @@ export class Editor extends EventEmitter<TLEventMap> {
 			hitFrameInside = false,
 		} = opts
 
+		const [innerMargin, outerMargin] = Array.isArray(margin) ? margin : [margin, margin]
+
 		let inHollowSmallestArea = Infinity
 		let inHollowSmallestAreaHit: TLShape | null = null
 
@@ -5208,7 +5188,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 				return false
 			const pageMask = this.getShapeMask(shape)
 			if (pageMask && !pointInPolygon(point, pageMask)) return false
-			if (filter) return filter(shape)
+			if (filter && !filter(shape)) return false
 			return true
 		})
 
@@ -5222,8 +5202,8 @@ export class Editor extends EventEmitter<TLEventMap> {
 			// Check labels first
 			if (
 				this.isShapeOfType<TLFrameShape>(shape, 'frame') ||
-				(this.isShapeOfType<TLArrowShape>(shape, 'arrow') && shape.props.text.trim()) ||
 				((this.isShapeOfType<TLNoteShape>(shape, 'note') ||
+					this.isShapeOfType<TLArrowShape>(shape, 'arrow') ||
 					(this.isShapeOfType<TLGeoShape>(shape, 'geo') && shape.props.fill === 'none')) &&
 					this.getShapeUtil(shape).getText(shape)?.trim())
 			) {
@@ -5234,13 +5214,18 @@ export class Editor extends EventEmitter<TLEventMap> {
 				}
 			}
 
-			if (this.isShapeOfType(shape, 'frame')) {
+			if (this.isShapeOfType<TLFrameShape>(shape, 'frame')) {
 				// On the rare case that we've hit a frame (not its label), test again hitInside to be forced true;
 				// this prevents clicks from passing through the body of a frame to shapes behind it.
 
 				// If the hit is within the frame's outer margin, then select the frame
-				const distance = geometry.distanceToPoint(pointInShapeSpace, hitInside)
-				if (Math.abs(distance) <= margin) {
+				const distance = geometry.distanceToPoint(pointInShapeSpace, hitFrameInside)
+				if (
+					hitFrameInside
+						? (distance > 0 && distance <= outerMargin) ||
+							(distance <= 0 && distance > -innerMargin)
+						: distance > 0 && distance <= outerMargin
+				) {
 					return inMarginClosestToEdgeHit || shape
 				}
 
@@ -5279,11 +5264,11 @@ export class Editor extends EventEmitter<TLEventMap> {
 				// If the margin is zero and the geometry has a very small width or height,
 				// then check the actual distance. This is to prevent a bug where straight
 				// lines would never pass the broad phase (point-in-bounds) check.
-				if (margin === 0 && (geometry.bounds.w < 1 || geometry.bounds.h < 1)) {
+				if (outerMargin === 0 && (geometry.bounds.w < 1 || geometry.bounds.h < 1)) {
 					distance = geometry.distanceToPoint(pointInShapeSpace, hitInside)
 				} else {
 					// Broad phase
-					if (geometry.bounds.containsPoint(pointInShapeSpace, margin)) {
+					if (geometry.bounds.containsPoint(pointInShapeSpace, outerMargin)) {
 						// Narrow phase (actual distance)
 						distance = geometry.distanceToPoint(pointInShapeSpace, hitInside)
 					} else {
@@ -5298,7 +5283,8 @@ export class Editor extends EventEmitter<TLEventMap> {
 				// the shape or negative if inside of the shape. If the distance
 				// is greater than the margin, then it's a miss. Otherwise...
 
-				if (distance <= margin) {
+				// Are we close to the shape's edge?
+				if (distance <= outerMargin || (hitInside && distance <= 0 && distance > -innerMargin)) {
 					if (geometry.isFilled || (isGroup && geometry.children[0].isFilled)) {
 						// If the shape is filled, then it's a hit. Remember, we're
 						// starting from the TOP-MOST shape in z-index order, so any
@@ -5308,11 +5294,21 @@ export class Editor extends EventEmitter<TLEventMap> {
 						// If the shape is bigger than the viewport, then skip it.
 						if (this.getShapePageBounds(shape)!.contains(viewportPageBounds)) continue
 
-						// For hollow shapes...
-						if (Math.abs(distance) < margin) {
-							// We want to preference shapes where we're inside of the
-							// shape margin; and we would want to hit the shape with the
-							// edge closest to the point.
+						// If we're close to the edge of the shape, and if it's the closest edge among
+						// all the edges that we've gotten close to so far, then we will want to hit the
+						// shape unless we hit something else or closer in later iterations.
+						if (
+							hitInside
+								? // On hitInside, the distance will be negative for hits inside
+									// If the distance is positive, check against the outer margin
+									(distance > 0 && distance <= outerMargin) ||
+									// If the distance is negative, check against the inner margin
+									(distance <= 0 && distance > -innerMargin)
+								: // If hitInside is false, then sadly _we do not know_ whether the
+									// point is inside or outside of the shape, so we check against
+									// the max of the two margins
+									Math.abs(distance) <= Math.max(innerMargin, outerMargin)
+						) {
 							if (Math.abs(distance) < inMarginClosestToEdgeDistance) {
 								inMarginClosestToEdgeDistance = Math.abs(distance)
 								inMarginClosestToEdgeHit = shape
@@ -5334,6 +5330,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 			} else {
 				// For open shapes (e.g. lines or draw shapes) always use the margin.
 				// If the distance is less than the margin, return the shape as the hit.
+				// Use the editor's configurable hit test margin.
 				if (distance < this.options.hitTestMargin / zoomLevel) {
 					return shape
 				}
@@ -7390,7 +7387,6 @@ export class Editor extends EventEmitter<TLEventMap> {
 			if (
 				!this.getShapeUtil(shape).canBeLaidOut?.(shape, {
 					type: 'stretch',
-					shapes: shapesToStretchFirstPass,
 				})
 			) {
 				continue
@@ -7861,25 +7857,32 @@ export class Editor extends EventEmitter<TLEventMap> {
 				) {
 					let parentId: TLParentId = this.getFocusedGroupId()
 
-					for (let i = currentPageShapesSorted.length - 1; i >= 0; i--) {
-						const parent = currentPageShapesSorted[i]
-						const util = this.getShapeUtil(parent)
-						if (
-							util.canReceiveNewChildrenOfType(parent, partial.type) &&
-							!this.isShapeHidden(parent) &&
-							this.isPointInShape(
-								parent,
-								// If no parent is provided, then we can treat the
-								// shape's provided x/y as being in the page's space.
-								{ x: partial.x ?? 0, y: partial.y ?? 0 },
-								{
-									margin: 0,
-									hitInside: true,
-								}
-							)
-						) {
-							parentId = parent.id
-							break
+					const isPositioned = partial.x !== undefined && partial.y !== undefined
+
+					// If the shape has been explicitly positioned, we'll try to find a parent at
+					// that position. If not, we'll assume the user isn't deliberately placing the
+					// shape and the positioning will be handled later by another system.
+					if (isPositioned) {
+						for (let i = currentPageShapesSorted.length - 1; i >= 0; i--) {
+							const parent = currentPageShapesSorted[i]
+							const util = this.getShapeUtil(parent)
+							if (
+								util.canReceiveNewChildrenOfType(parent, partial.type) &&
+								!this.isShapeHidden(parent) &&
+								this.isPointInShape(
+									parent,
+									// If no parent is provided, then we can treat the
+									// shape's provided x/y as being in the page's space.
+									{ x: partial.x ?? 0, y: partial.y ?? 0 },
+									{
+										margin: 0,
+										hitInside: true,
+									}
+								)
+							) {
+								parentId = parent.id
+								break
+							}
 						}
 					}
 
@@ -9673,6 +9676,52 @@ export class Editor extends EventEmitter<TLEventMap> {
 		return this
 	}
 
+	/**
+	 * Dispatch a pointer move event in the current position of the pointer. This is useful when
+	 * external circumstances have changed (e.g. the camera moved or a shape was moved) and you want
+	 * the current interaction to respond to that change.
+	 *
+	 * @example
+	 * ```ts
+	 * editor.updatePointer()
+	 * ```
+	 *
+	 * @param options - The options for updating the pointer.
+	 * @returns The editor instance.
+	 * @public
+	 */
+	updatePointer(options?: TLUpdatePointerOptions): this {
+		const event: TLPointerEventInfo = {
+			type: 'pointer',
+			target: 'canvas',
+			name: 'pointer_move',
+			point:
+				options?.point ??
+				// weird but true: what `inputs` calls screen-space is actually viewport space. so
+				// we need to convert back into true screen space first. we should fix this...
+				Vec.Add(
+					this.inputs.currentScreenPoint,
+					this.store.unsafeGetWithoutCapture(TLINSTANCE_ID)!.screenBounds
+				),
+			pointerId: options?.pointerId ?? 0,
+			button: options?.button ?? 0,
+			isPen: options?.isPen ?? this.inputs.isPen,
+			shiftKey: options?.shiftKey ?? this.inputs.shiftKey,
+			altKey: options?.altKey ?? this.inputs.altKey,
+			ctrlKey: options?.ctrlKey ?? this.inputs.ctrlKey,
+			metaKey: options?.metaKey ?? this.inputs.metaKey,
+			accelKey: options?.accelKey ?? isAccelKey(this.inputs),
+		}
+
+		if (options?.immediate) {
+			this._flushEventForTick(event)
+		} else {
+			this.dispatch(event)
+		}
+
+		return this
+	}
+
 	/**
 	 * Puts the editor into focused mode.
 	 *

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

@@ -25,6 +25,7 @@ describe('UserPreferencesManager', () => {
 		locale: 'en',
 		animationSpeed: 1,
 		areKeyboardShortcutsEnabled: true,
+		showUiLabels: false,
 		edgeScrollSpeed: 1,
 		colorScheme: 'light',
 		isSnapMode: false,
@@ -231,6 +232,7 @@ describe('UserPreferencesManager', () => {
 				color: mockUserPreferences.color,
 				animationSpeed: mockUserPreferences.animationSpeed,
 				areKeyboardShortcutsEnabled: mockUserPreferences.areKeyboardShortcutsEnabled,
+				showUiLabels: mockUserPreferences.showUiLabels,
 				isSnapMode: mockUserPreferences.isSnapMode,
 				colorScheme: mockUserPreferences.colorScheme,
 				isDarkMode: false, // light mode
@@ -379,6 +381,17 @@ describe('UserPreferencesManager', () => {
 			})
 		})
 
+		describe('getShowUiLabels', () => {
+			it('should return user show ui labels setting', () => {
+				expect(userPreferencesManager.getShowUiLabels()).toBe(mockUserPreferences.showUiLabels)
+			})
+
+			it('should return default show ui labels when null', () => {
+				userPreferencesAtom.set({ ...mockUserPreferences, showUiLabels: null })
+				expect(userPreferencesManager.getShowUiLabels()).toBe(defaultUserPreferences.showUiLabels)
+			})
+		})
+
 		describe('getEdgeScrollSpeed', () => {
 			it('should return user edge scroll speed', () => {
 				expect(userPreferencesManager.getEdgeScrollSpeed()).toBe(

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

@@ -49,6 +49,7 @@ export class UserPreferencesManager {
 			isDarkMode: this.getIsDarkMode(),
 			isWrapMode: this.getIsWrapMode(),
 			isDynamicResizeMode: this.getIsDynamicResizeMode(),
+			showUiLabels: this.getShowUiLabels(),
 		}
 	}
 
@@ -119,4 +120,8 @@ export class UserPreferencesManager {
 			defaultUserPreferences.isPasteAtCursorMode
 		)
 	}
+
+	@computed getShowUiLabels() {
+		return this.user.userPreferences.get().showUiLabels ?? defaultUserPreferences.showUiLabels
+	}
 }