@tldraw/editor 4.4.0-next.84d68f44c848 → 4.4.0-next.bde73a32273d

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

@@ -31,6 +31,7 @@ describe('UserPreferencesManager', () => {
 		isDynamicSizeMode: false,
 		isPasteAtCursorMode: false,
 		inputMode: null,
+		isZoomDirectionInverted: false,
 		...overrides,
 	})
 
@@ -235,6 +236,7 @@ describe('UserPreferencesManager', () => {
 				isWrapMode: mockUserPreferences.isWrapMode,
 				isDynamicResizeMode: mockUserPreferences.isDynamicSizeMode,
 				inputMode: mockUserPreferences.inputMode,
+				isZoomDirectionInverted: mockUserPreferences.isZoomDirectionInverted,
 			})
 		})
 
@@ -475,6 +477,24 @@ describe('UserPreferencesManager', () => {
 				expect(userPreferencesManager.getInputMode()).toBe('mouse')
 			})
 		})
+
+		describe('getIsZoomDirectionInverted', () => {
+			it('should return user zoom direction inverted setting', () => {
+				expect(userPreferencesManager.getIsZoomDirectionInverted()).toBe(false)
+			})
+
+			it('should return default when null', () => {
+				userPreferencesAtom.set({ ...mockUserPreferences, isZoomDirectionInverted: null })
+				expect(userPreferencesManager.getIsZoomDirectionInverted()).toBe(
+					defaultUserPreferences.isZoomDirectionInverted
+				)
+			})
+
+			it('should return true when inverted', () => {
+				userPreferencesAtom.set({ ...mockUserPreferences, isZoomDirectionInverted: true })
+				expect(userPreferencesManager.getIsZoomDirectionInverted()).toBe(true)
+			})
+		})
 	})
 
 	describe('reactive behavior', () => {
@@ -536,6 +556,7 @@ describe('UserPreferencesManager', () => {
 				isWrapMode: null,
 				isDynamicSizeMode: null,
 				isPasteAtCursorMode: null,
+				isZoomDirectionInverted: null,
 			})
 
 			userPreferencesAtom.set(nullPrefs)
@@ -558,6 +579,9 @@ describe('UserPreferencesManager', () => {
 			expect(userPreferencesManager.getIsPasteAtCursorMode()).toBe(
 				defaultUserPreferences.isPasteAtCursorMode
 			)
+			expect(userPreferencesManager.getIsZoomDirectionInverted()).toBe(
+				defaultUserPreferences.isZoomDirectionInverted
+			)
 		})
 
 		it('should handle matchMedia with null response', () => {

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

@@ -51,6 +51,7 @@ export class UserPreferencesManager {
 			isDynamicResizeMode: this.getIsDynamicResizeMode(),
 			enhancedA11yMode: this.getEnhancedA11yMode(),
 			inputMode: this.getInputMode(),
+			isZoomDirectionInverted: this.getIsZoomDirectionInverted(),
 		}
 	}
 
@@ -131,4 +132,11 @@ export class UserPreferencesManager {
 	@computed getInputMode() {
 		return this.user.userPreferences.get().inputMode ?? defaultUserPreferences.inputMode
 	}
+
+	@computed getIsZoomDirectionInverted() {
+		return (
+			this.user.userPreferences.get().isZoomDirectionInverted ??
+			defaultUserPreferences.isZoomDirectionInverted
+		)
+	}
 }

package/src/lib/editor/shapes/ShapeUtil.ts

@@ -35,17 +35,31 @@ export interface TLShapeUtilConstructor<T extends TLShape, U extends ShapeUtil<T
 
 /**
  * Options passed to {@link ShapeUtil.canBind}. A binding that could be made. At least one of
- * `fromShapeType` or `toShapeType` will belong to this shape util.
+ * `fromShape` or `toShape` will belong to this shape util.
+ *
+ * The shapes may be full {@link @tldraw/tlschema#TLShape} objects when available, or just
+ * `{ type }` stubs when the shape hasn't been created yet (e.g. during arrow creation). Use
+ * `'id' in shape` to check whether the full shape is available.
  *
  * @public
  */
 export interface TLShapeUtilCanBindOpts<Shape extends TLShape = TLShape> {
-	/** The type of shape referenced by the `fromId` of the binding. */
-	fromShapeType: TLShape['type']
-	/** The type of shape referenced by the `toId` of the binding. */
-	toShapeType: TLShape['type']
+	/** The shape referenced by the `fromId` of the binding, or a `{ type }` stub if unavailable. */
+	fromShape: TLShape | { type: TLShape['type'] }
+	/** The shape referenced by the `toId` of the binding, or a `{ type }` stub if unavailable. */
+	toShape: TLShape | { type: TLShape['type'] }
 	/** The type of binding. */
 	bindingType: string
+	/**
+	 * The type of shape referenced by the `fromId` of the binding.
+	 * @deprecated Use `fromShape.type` instead.
+	 */
+	fromShapeType: TLShape['type']
+	/**
+	 * The type of shape referenced by the `toId` of the binding.
+	 * @deprecated Use `toShape.type` instead.
+	 */
+	toShapeType: TLShape['type']
 }
 
 /**
@@ -75,6 +89,19 @@ export interface TLShapeUtilCanvasSvgDef {
 	component: React.ComponentType
 }
 
+/**
+ * Return type for {@link ShapeUtil.getIndicatorPath}. Can be either a simple Path2D
+ * or an object with additional rendering info like clip paths for complex indicators.
+ * @public
+ */
+export type TLIndicatorPath =
+	| Path2D
+	| {
+			path: Path2D
+			clipPath?: Path2D
+			additionalPaths?: Path2D[]
+	  }
+
 /** @public */
 export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 	/** Configure this shape utils {@link ShapeUtil.options | `options`}. */
@@ -173,6 +200,37 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 	 */
 	abstract indicator(shape: Shape): any
 
+	/**
+	 * Whether to use the legacy React-based indicator rendering.
+	 *
+	 * Override this to return `false` if your shape implements {@link ShapeUtil.getIndicatorPath}
+	 * for canvas-based indicator rendering.
+	 *
+	 * @returns `true` to use SVG indicators (default), `false` to use canvas indicators.
+	 * @public
+	 */
+	useLegacyIndicator(): boolean {
+		return true
+	}
+
+	/**
+	 * Get a Path2D for rendering the shape's indicator on the canvas.
+	 *
+	 * When implemented, this is used instead of {@link ShapeUtil.indicator} for more
+	 * efficient canvas-based indicator rendering. Shapes that return `undefined` will
+	 * fall back to SVG-based rendering via {@link ShapeUtil.indicator}.
+	 *
+	 * For complex indicators that need clipping (e.g., arrows with labels), return an
+	 * object with `path`, `clipPath`, and `additionalPaths` properties.
+	 *
+	 * @param shape - The shape.
+	 * @returns A Path2D to stroke, or an object with clipping info, or undefined to use SVG fallback.
+	 * @public
+	 */
+	getIndicatorPath(shape: Shape): TLIndicatorPath | undefined {
+		return undefined
+	}
+
 	/**
 	 * Get the font faces that should be rendered in the document in order for this shape to render
 	 * correctly.

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

@@ -1,4 +1,3 @@
-import { TLKeyboardEventInfo } from '../types/event-types'
 import { StateNode } from './StateNode'
 
 export class RootState extends StateNode {
@@ -7,19 +6,4 @@ export class RootState extends StateNode {
 	static override children() {
 		return []
 	}
-
-	override onKeyDown(info: TLKeyboardEventInfo) {
-		// todo: move this logic up to the tldraw library, as the "zoom" tool only exists there
-		switch (info.code) {
-			case 'KeyZ': {
-				if (!(info.shiftKey || info.ctrlKey)) {
-					const currentTool = this.getCurrent()
-					if (currentTool && currentTool.getCurrent()?.id === 'idle' && this.children!['zoom']) {
-						this.editor.setCurrentTool('zoom', { ...info, onInteractionEnd: currentTool.id })
-					}
-				}
-				break
-			}
-		}
-	}
 }

package/src/lib/hooks/usePeerIds.ts

@@ -1,7 +1,20 @@
-import { useComputed, useValue } from '@tldraw/state-react'
+import { useAtom, useComputed, useValue } from '@tldraw/state-react'
+import { useEffect } from 'react'
+import {
+	getCollaboratorStateFromElapsedTime,
+	shouldShowCollaborator,
+} from '../utils/collaboratorState'
 import { uniq } from '../utils/uniq'
 import { useEditor } from './useEditor'
 
+function setsEqual<T>(a: Set<T>, b: Set<T>): boolean {
+	if (a.size !== b.size) return false
+	for (const item of a) {
+		if (!b.has(item)) return false
+	}
+	return true
+}
+
 // TODO: maybe move this to a computed property on the App class?
 /**
  * @returns The list of peer UserIDs
@@ -19,3 +32,42 @@ export function usePeerIds() {
 
 	return useValue($userIds)
 }
+
+/**
+ * Returns a computed signal of active peer user IDs that should be shown.
+ * Automatically re-evaluates on an interval to handle time-based state transitions
+ * (active -> idle -> inactive).
+ *
+ * @returns A computed signal containing a Set of active peer user IDs
+ * @internal
+ */
+export function useActivePeerIds$() {
+	const $time = useAtom('peerIdsTime', Date.now())
+	const editor = useEditor()
+	useEffect(() => {
+		const interval = editor.timers.setInterval(() => {
+			$time.set(Date.now())
+		}, editor.options.collaboratorCheckIntervalMs)
+
+		return () => clearInterval(interval)
+	}, [editor, $time])
+
+	return useComputed(
+		'activePeerIds',
+		() => {
+			const now = $time.get()
+			return new Set(
+				editor
+					.getCollaborators()
+					.filter((p) => {
+						const elapsed = Math.max(0, now - (p.lastActivityTimestamp ?? Infinity))
+						const state = getCollaboratorStateFromElapsedTime(editor, elapsed)
+						return shouldShowCollaborator(editor, p, state)
+					})
+					.map((p) => p.userId)
+			)
+		},
+		{ isEqual: setsEqual },
+		[editor]
+	)
+}

package/src/lib/hooks/useShapeCulling.tsx

@@ -0,0 +1,98 @@
+import { TLShapeId } from '@tldraw/tlschema'
+import { createContext, useCallback, useContext, useMemo, useRef } from 'react'
+import { setStyleProperty } from '../utils/dom'
+
+interface ShapeContainerEntry {
+	container: HTMLDivElement
+	bgContainer: HTMLDivElement | null
+	isCulled: boolean
+}
+
+interface ShapeCullingContextValue {
+	register(
+		id: TLShapeId,
+		container: HTMLDivElement,
+		bgContainer: HTMLDivElement | null,
+		isCulled: boolean
+	): void
+	unregister(id: TLShapeId): void
+	updateCulling(culledShapes: Set<TLShapeId>): void
+}
+
+const ShapeCullingContext = createContext<ShapeCullingContextValue | null>(null)
+
+/** @internal */
+export interface ShapeCullingProviderProps {
+	children: React.ReactNode
+}
+
+/**
+ * Provides centralized culling management for shape containers.
+ * This allows a single reactor to update all shape display states
+ * instead of each shape having its own subscription.
+ *
+ * @internal
+ */
+export function ShapeCullingProvider({ children }: ShapeCullingProviderProps) {
+	const containersRef = useRef(new Map<TLShapeId, ShapeContainerEntry>())
+
+	const register = useCallback(
+		(
+			id: TLShapeId,
+			container: HTMLDivElement,
+			bgContainer: HTMLDivElement | null,
+			isCulled: boolean
+		) => {
+			const display = isCulled ? 'none' : 'block'
+			setStyleProperty(container, 'display', display)
+			setStyleProperty(bgContainer, 'display', display)
+
+			containersRef.current.set(id, {
+				container,
+				bgContainer,
+				isCulled,
+			})
+		},
+		[]
+	)
+
+	const unregister = useCallback((id: TLShapeId) => {
+		containersRef.current.delete(id)
+	}, [])
+
+	const updateCulling = useCallback((culledShapes: Set<TLShapeId>) => {
+		for (const [id, entry] of containersRef.current) {
+			const shouldBeCulled = culledShapes.has(id)
+			if (shouldBeCulled !== entry.isCulled) {
+				const display = shouldBeCulled ? 'none' : 'block'
+				setStyleProperty(entry.container, 'display', display)
+				setStyleProperty(entry.bgContainer, 'display', display)
+				entry.isCulled = shouldBeCulled
+			}
+		}
+	}, [])
+
+	const value = useMemo(
+		() => ({
+			register,
+			unregister,
+			updateCulling,
+		}),
+		[register, unregister, updateCulling]
+	)
+
+	return <ShapeCullingContext.Provider value={value}>{children}</ShapeCullingContext.Provider>
+}
+
+/**
+ * Hook to access the shape culling context for container registration.
+ *
+ * @internal
+ */
+export function useShapeCulling(): ShapeCullingContextValue {
+	const context = useContext(ShapeCullingContext)
+	if (!context) {
+		throw new Error('useShapeCulling must be used within ShapeCullingProvider')
+	}
+	return context
+}

package/src/lib/license/LicenseManager.ts

@@ -431,25 +431,25 @@ export class LicenseManager {
 	private outputMessages(messages: string[], type: 'warning' | 'error' = 'error') {
 		if (this.isTest) return
 		if (this.verbose) {
-			this.outputDelimiter()
+			this.outputDelimiter(type)
 			for (const message of messages) {
-				const color = type === 'warning' ? 'orange' : 'crimson'
 				const bgColor = type === 'warning' ? 'orange' : 'crimson'
 				// eslint-disable-next-line no-console
 				console.log(
 					`%c${message}`,
-					`color: ${color}; background: ${bgColor}; padding: 2px; border-radius: 3px;`
+					`color: white; background: ${bgColor}; padding: 2px; border-radius: 3px;`
 				)
 			}
-			this.outputDelimiter()
+			this.outputDelimiter(type)
 		}
 	}
 
-	private outputDelimiter() {
+	private outputDelimiter(type: 'warning' | 'error' = 'error') {
+		const bgColor = type === 'warning' ? 'orange' : 'crimson'
 		// eslint-disable-next-line no-console
 		console.log(
 			'%c-------------------------------------------------------------------',
-			`color: white; background: crimson; padding: 2px; border-radius: 3px;`
+			`color: white; background: ${bgColor}; padding: 2px; border-radius: 3px;`
 		)
 	}
 

package/src/lib/options.ts

@@ -1,4 +1,8 @@
 import { ComponentType, Fragment } from 'react'
+import { DEFAULT_CAMERA_OPTIONS } from './constants'
+import { TLCameraOptions } from './editor/types/misc-types'
+import { TLDeepLinkOptions } from './utils/deepLinks'
+import { TLTextOptions } from './utils/richText'
 
 /**
  * Options for configuring tldraw. For defaults, see {@link defaultTldrawOptions}.
@@ -54,6 +58,12 @@ export interface TldrawOptions {
 	readonly flattenImageBoundsExpand: number
 	readonly flattenImageBoundsPadding: number
 	readonly laserDelayMs: number
+	/**
+	 * How long (in milliseconds) to fade all laser scribbles after the session ends.
+	 * The total points across all scribbles will be removed proportionally over this duration.
+	 * Defaults to 500ms (0.5 seconds).
+	 */
+	readonly laserFadeoutMs: number
 	readonly maxExportDelayMs: number
 	readonly tooltipDelayMs: number
 	/**
@@ -89,13 +99,13 @@ export interface TldrawOptions {
 	readonly branding?: string
 	/**
 	 * Whether to use debounced zoom level for certain rendering optimizations. When true,
-	 * `editor.getDebouncedZoomLevel()` returns a cached zoom value while the camera is moving,
+	 * `editor.getEfficientZoomLevel()` returns a cached zoom value while the camera is moving,
 	 * reducing re-renders. When false, it always returns the current zoom level.
 	 */
 	readonly debouncedZoom: boolean
 	/**
 	 * The number of shapes that must be on the page for the debounced zoom level to be used.
-	 * Defaults to 300 shapes.
+	 * Defaults to 500 shapes.
 	 */
 	readonly debouncedZoomThreshold: number
 	/**
@@ -114,6 +124,37 @@ export interface TldrawOptions {
 	 * The distance (in screen pixels) at which shapes snap to guides and other shapes.
 	 */
 	readonly snapThreshold: number
+	/**
+	 * Options for the editor's camera. These are the initial camera options.
+	 * Use {@link Editor.setCameraOptions} to update camera options at runtime.
+	 */
+	readonly camera: Partial<TLCameraOptions>
+	/**
+	 * Options for the editor's text rendering. These include TipTap configuration and
+	 * font handling. These are the initial text options and cannot be changed at runtime.
+	 */
+	readonly text: TLTextOptions
+	/**
+	 * Options for syncing the editor's camera state with the URL. Set to `true` to enable
+	 * with default options, or pass an options object to customize behavior.
+	 *
+	 * @example
+	 * ```tsx
+	 * // Enable with defaults
+	 * <Tldraw options={{ deepLinks: true }} />
+	 *
+	 * // Enable with custom options
+	 * <Tldraw options={{ deepLinks: { param: 'd', debounceMs: 500 } }} />
+	 * ```
+	 */
+	readonly deepLinks: true | TLDeepLinkOptions | undefined
+	/**
+	 * Whether the quick-zoom brush preserves its screen-pixel size when the user
+	 * zooms the overview. When true, zooming in shrinks the target viewport (higher
+	 * return zoom); zooming out expands it. When false, the brush keeps the original
+	 * viewport's page dimensions regardless of overview zoom changes.
+	 */
+	readonly quickZoomPreservesScreenBounds: boolean
 }
 
 /** @public */
@@ -157,6 +198,7 @@ export const defaultTldrawOptions = {
 	flattenImageBoundsExpand: 64,
 	flattenImageBoundsPadding: 16,
 	laserDelayMs: 1200,
+	laserFadeoutMs: 500,
 	maxExportDelayMs: 5000,
 	tooltipDelayMs: 700,
 	temporaryAssetPreviewLifetimeMs: 180000,
@@ -171,4 +213,8 @@ export const defaultTldrawOptions = {
 	spacebarPanning: true,
 	zoomToFitPadding: 128,
 	snapThreshold: 8,
+	camera: DEFAULT_CAMERA_OPTIONS,
+	text: {},
+	deepLinks: undefined,
+	quickZoomPreservesScreenBounds: true,
 } as const satisfies TldrawOptions

package/src/lib/utils/collaboratorState.ts

@@ -0,0 +1,54 @@
+import { TLInstancePresence } from '@tldraw/tlschema'
+import { Editor } from '../editor/Editor'
+
+/** The activity state of a collaborator */
+export type CollaboratorState = 'active' | 'idle' | 'inactive'
+
+/**
+ * Get the activity state of a collaborator based on elapsed time since their last activity.
+ *
+ * @param editor - The editor instance
+ * @param elapsed - Time in milliseconds since the collaborator's last activity
+ * @returns The collaborator's activity state
+ */
+export function getCollaboratorStateFromElapsedTime(
+	editor: Editor,
+	elapsed: number
+): CollaboratorState {
+	return elapsed > editor.options.collaboratorInactiveTimeoutMs
+		? 'inactive'
+		: elapsed > editor.options.collaboratorIdleTimeoutMs
+			? 'idle'
+			: 'active'
+}
+
+/**
+ * Determine whether a collaborator should be shown based on their activity state
+ * and the current instance state (following, highlighted users, etc.).
+ *
+ * @param editor - The editor instance
+ * @param presence - The collaborator's presence data
+ * @param state - The collaborator's activity state
+ * @returns Whether the collaborator should be shown
+ */
+export function shouldShowCollaborator(
+	editor: Editor,
+	presence: TLInstancePresence,
+	state: CollaboratorState
+): boolean {
+	const { followingUserId, highlightedUserIds } = editor.getInstanceState()
+
+	switch (state) {
+		case 'inactive':
+			// If they're inactive, only show if we're following them or they're highlighted
+			return followingUserId === presence.userId || highlightedUserIds.includes(presence.userId)
+		case 'idle':
+			// If they're idle and following us, hide them unless they have a chat message or are highlighted
+			if (presence.followingUserId === editor.user.getId()) {
+				return !!(presence.chatMessage || highlightedUserIds.includes(presence.userId))
+			}
+			return true
+		case 'active':
+			return true
+	}
+}

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 = '4.4.0-next.84d68f44c848'
+export const version = '4.4.0-next.bde73a32273d'
 export const publishDates = {
 	major: '2025-09-18T14:39:22.803Z',
-	minor: '2026-01-22T09:49:37.857Z',
-	patch: '2026-01-22T09:49:37.857Z',
+	minor: '2026-02-11T22:21:46.227Z',
+	patch: '2026-02-11T22:21:46.227Z',
 }