@tldraw/editor 4.6.0-next.5a871ec02ff3 → 4.6.0-next.6594d48ace27

package/src/lib/editor/assets/AssetUtil.ts

@@ -0,0 +1,85 @@
+import { LegacyMigrations, MigrationSequence } from '@tldraw/store'
+import {
+	RecordProps,
+	TLAsset,
+	TLAssetId,
+	TLPropsMigrations,
+	TLUnknownAsset,
+} from '@tldraw/tlschema'
+import type { Editor } from '../Editor'
+
+/** @public */
+export interface TLAssetUtilConstructor<
+	T extends TLAsset = TLAsset,
+	U extends AssetUtil<T> = AssetUtil<T>,
+> {
+	new (editor: Editor): U
+	type: T['type']
+	props?: RecordProps<T>
+	migrations?: LegacyMigrations | TLPropsMigrations | MigrationSequence
+}
+
+/**
+ * Abstract base class for defining asset-type-specific behavior.
+ *
+ * Each asset type (image, video, bookmark, etc.) has a corresponding AssetUtil that handles
+ * type-specific operations like determining supported MIME types and creating assets from files.
+ *
+ * @public
+ */
+export abstract class AssetUtil<Asset extends TLAsset = TLAsset> {
+	/** Configure this asset util's {@link AssetUtil.options | `options`}. */
+	static configure<T extends TLAssetUtilConstructor<any, any>>(
+		this: T,
+		options: T extends new (...args: any[]) => { options: infer Options } ? Partial<Options> : never
+	): T {
+		// @ts-expect-error -- typescript has no idea what's going on here but it's fine
+		return class extends this {
+			// @ts-expect-error
+			options = { ...this.options, ...options }
+		}
+	}
+
+	constructor(public editor: Editor) {}
+
+	/**
+	 * Options for this asset util. Override this to provide customization options for your asset.
+	 * Use {@link AssetUtil.configure} to customize existing asset utils.
+	 */
+	options = {}
+
+	static props?: RecordProps<TLUnknownAsset>
+	static migrations?: LegacyMigrations | TLPropsMigrations | MigrationSequence
+
+	/**
+	 * The type of the asset util, which should match the asset's type.
+	 */
+	static type: string
+
+	/**
+	 * Get the default props for an asset of this type.
+	 */
+	abstract getDefaultProps(): Asset['props']
+
+	/**
+	 * Get the MIME types that this asset type supports.
+	 * Return an empty array if this asset type doesn't support files (e.g. bookmarks).
+	 */
+	getSupportedMimeTypes(): readonly string[] {
+		return []
+	}
+
+	/**
+	 * Check whether this asset type accepts a given MIME type.
+	 */
+	acceptsMimeType(mimeType: string): boolean {
+		return this.getSupportedMimeTypes().includes(mimeType)
+	}
+
+	/**
+	 * Create an asset from a file. Return null if this asset type can't handle the file.
+	 */
+	async getAssetFromFile(_file: File, _assetId: TLAssetId): Promise<Asset | null> {
+		return null
+	}
+}

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

@@ -87,7 +87,7 @@ export class ClickManager {
 	 *
 	 * @public
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get clickState() {
 		return this._clickState
 	}

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

@@ -0,0 +1,98 @@
+import { EMPTY_ARRAY, atom, computed } from '@tldraw/state'
+import { TLInstancePresence } from '@tldraw/tlschema'
+import { maxBy } from '@tldraw/utils'
+import {
+	getCollaboratorStateFromElapsedTime,
+	shouldShowCollaborator,
+} from '../../../utils/collaboratorState'
+import type { Editor } from '../../Editor'
+
+/**
+ * Tracks remote peers and exposes the collaborator-related queries used by the
+ * editor and its overlays. Encapsulates the visibility clock that periodically
+ * re-evaluates which collaborators should be visible based on activity.
+ *
+ * Accessed via {@link Editor.collaborators}.
+ *
+ * @public
+ */
+export class CollaboratorsManager {
+	constructor(private readonly editor: Editor) {
+		// Editor disposes `editor.timers` on its own teardown, so the interval is
+		// automatically cleared when the editor is disposed.
+		editor.timers.setInterval(() => {
+			this._visibilityClock.set(Date.now())
+		}, editor.options.collaboratorCheckIntervalMs)
+	}
+
+	/**
+	 * Drives reactive re-evaluation of {@link CollaboratorsManager.getVisibleCollaborators}.
+	 * Ticked on a fixed interval so callers don't need to manage their own activity timers.
+	 */
+	private readonly _visibilityClock = atom('collaboratorVisibilityClock', Date.now())
+
+	@computed
+	private _getCollaboratorsQuery() {
+		return this.editor.store.query.records('instance_presence', () => ({
+			userId: { neq: this.editor.user.getId() },
+		}))
+	}
+
+	/**
+	 * Returns a list of presence records for all peer collaborators.
+	 * This will return the latest presence record for each connected user.
+	 */
+	@computed
+	getCollaborators(): TLInstancePresence[] {
+		const allPresenceRecords = this._getCollaboratorsQuery().get()
+		if (!allPresenceRecords.length) return EMPTY_ARRAY
+		const userIds = [...new Set(allPresenceRecords.map((c) => c.userId))].sort()
+		return userIds.map((id) => {
+			const latestPresence = maxBy(
+				allPresenceRecords.filter((c) => c.userId === id),
+				(p) => p.lastActivityTimestamp ?? 0
+			)
+			return latestPresence!
+		})
+	}
+
+	/**
+	 * Returns a list of presence records for all peer collaborators on the current page.
+	 * This will return the latest presence record for each connected user.
+	 */
+	@computed
+	getCollaboratorsOnCurrentPage(): TLInstancePresence[] {
+		const currentPageId = this.editor.getCurrentPageId()
+		return this.getCollaborators().filter((c) => c.currentPageId === currentPageId)
+	}
+
+	/**
+	 * Returns a list of presence records for peer collaborators who should currently be
+	 * shown in the UI. Filters {@link CollaboratorsManager.getCollaborators} by activity
+	 * state (active / idle / inactive) and visibility rules such as following and
+	 * highlighted users. Re-evaluates on the visibility clock, so callers don't need to
+	 * drive their own activity timer.
+	 */
+	@computed
+	getVisibleCollaborators(): TLInstancePresence[] {
+		this._visibilityClock.get()
+		const now = Date.now()
+		return this.getCollaborators().filter((presence) => {
+			// Treat a missing `lastActivityTimestamp` as "active right now" (elapsed = 0)
+			// so newly-joined peers aren't immediately classified as idle/inactive.
+			const elapsed = Math.max(0, now - (presence.lastActivityTimestamp ?? now))
+			const state = getCollaboratorStateFromElapsedTime(this.editor, elapsed)
+			return shouldShowCollaborator(this.editor, presence, state)
+		})
+	}
+
+	/**
+	 * Returns a list of presence records for peer collaborators who should currently be
+	 * shown in the UI, filtered to those on the current page.
+	 */
+	@computed
+	getVisibleCollaboratorsOnCurrentPage(): TLInstancePresence[] {
+		const currentPageId = this.editor.getCurrentPageId()
+		return this.getVisibleCollaborators().filter((c) => c.currentPageId === currentPageId)
+	}
+}

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

@@ -1,5 +1,5 @@
-import { Vec } from '../../../primitives/Vec'
 import { EASINGS } from '../../../primitives/easings'
+import { Vec } from '../../../primitives/Vec'
 import type { Editor } from '../../Editor'
 
 /** @public */

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

@@ -1,8 +1,15 @@
-import { TLParentId, TLShape, TLShapeId, createShapeId, toRichText } from '@tldraw/tlschema'
+import {
+	TLFontFace,
+	TLParentId,
+	TLShape,
+	TLShapeId,
+	createShapeId,
+	toRichText,
+} from '@tldraw/tlschema'
 import { IndexKey } from '@tldraw/utils'
 import { Mock, Mocked, vi } from 'vitest'
 import { Editor } from '../../Editor'
-import { FontManager, TLFontFace } from './FontManager'
+import { FontManager } from './FontManager'
 
 // Mock the Editor class
 vi.mock('../../Editor')

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

@@ -1,6 +1,6 @@
 import { computed, EMPTY_ARRAY, transact } from '@tldraw/state'
 import { AtomMap } from '@tldraw/store'
-import { TLShape, TLShapeId } from '@tldraw/tlschema'
+import { TLFontFace, TLShape, TLShapeId } from '@tldraw/tlschema'
 import {
 	areArraysShallowEqual,
 	compact,
@@ -10,72 +10,6 @@ import {
 } from '@tldraw/utils'
 import type { Editor } from '../../Editor'
 
-/**
- * Represents the `src` property of a {@link TLFontFace}.
- * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src | `src`} for details of the properties here.
- * @public
- */
-export interface TLFontFaceSource {
-	/**
-	 * A URL from which to load the font. If the value here is a key in
-	 * {@link tldraw#TLEditorAssetUrls.fonts}, the value from there will be used instead.
-	 */
-	url: string
-	format?: string
-	tech?: string
-}
-
-/**
- * A font face that can be used in the editor. The properties of this are largely the same as the
- * ones in the
- * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face | css `@font-face` rule}.
- * @public
- */
-export interface TLFontFace {
-	/**
-	 * How this font can be referred to in CSS.
-	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-family | `font-family`}.
-	 */
-	readonly family: string
-	/**
-	 * The source of the font. This
-	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/src | `src`}.
-	 */
-	readonly src: TLFontFaceSource
-	/**
-	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/ascent-override | `ascent-override`}.
-	 */
-	readonly ascentOverride?: string
-	/**
-	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/descent-override | `descent-override`}.
-	 */
-	readonly descentOverride?: string
-	/**
-	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-stretch | `font-stretch`}.
-	 */
-	readonly stretch?: string
-	/**
-	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-style | `font-style`}.
-	 */
-	readonly style?: string
-	/**
-	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-weight | `font-weight`}.
-	 */
-	readonly weight?: string
-	/**
-	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/font-feature-settings | `font-feature-settings`}.
-	 */
-	readonly featureSettings?: string
-	/**
-	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/line-gap-override | `line-gap-override`}.
-	 */
-	readonly lineGapOverride?: string
-	/**
-	 * See {@link https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face/unicode-range | `unicode-range`}.
-	 */
-	readonly unicodeRange?: string
-}
-
 interface FontState {
 	readonly state: 'loading' | 'ready' | 'error'
 	readonly instance: FontFace

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

@@ -21,7 +21,7 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getOriginPagePoint()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get originPagePoint() {
 		return this.getOriginPagePoint()
 	}
@@ -36,7 +36,7 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getOriginScreenPoint()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get originScreenPoint() {
 		return this.getOriginScreenPoint()
 	}
@@ -51,7 +51,7 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getPreviousPagePoint()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get previousPagePoint() {
 		return this.getPreviousPagePoint()
 	}
@@ -66,7 +66,7 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getPreviousScreenPoint()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get previousScreenPoint() {
 		return this.getPreviousScreenPoint()
 	}
@@ -81,7 +81,7 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getCurrentPagePoint()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get currentPagePoint() {
 		return this.getCurrentPagePoint()
 	}
@@ -96,7 +96,7 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getCurrentScreenPoint()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get currentScreenPoint() {
 		return this.getCurrentScreenPoint()
 	}
@@ -111,7 +111,7 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getPointerVelocity()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get pointerVelocity() {
 		return this.getPointerVelocity()
 	}
@@ -147,11 +147,11 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getIsPen()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get isPen() {
 		return this.getIsPen()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set isPen(isPen: boolean) {
 		this.setIsPen(isPen)
 	}
@@ -172,11 +172,11 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getShiftKey()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get shiftKey() {
 		return this.getShiftKey()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set shiftKey(shiftKey: boolean) {
 		this.setShiftKey(shiftKey)
 	}
@@ -198,11 +198,11 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getMetaKey()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get metaKey() {
 		return this.getMetaKey()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set metaKey(metaKey: boolean) {
 		this.setMetaKey(metaKey)
 	}
@@ -224,11 +224,11 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getCtrlKey()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get ctrlKey() {
 		return this.getCtrlKey()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set ctrlKey(ctrlKey: boolean) {
 		this.setCtrlKey(ctrlKey)
 	}
@@ -250,11 +250,11 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getAltKey()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get altKey() {
 		return this.getAltKey()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set altKey(altKey: boolean) {
 		this.setAltKey(altKey)
 	}
@@ -275,7 +275,7 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getAccelKey()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get accelKey() {
 		return this.getAccelKey()
 	}
@@ -290,11 +290,11 @@ export class InputsManager {
 	/**
 	 * Soon to be deprecated, use `getIsDragging()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get isDragging() {
 		return this.getIsDragging()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set isDragging(isDragging: boolean) {
 		this.setIsDragging(isDragging)
 	}
@@ -315,11 +315,11 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getIsPointing()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get isPointing() {
 		return this.getIsPointing()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set isPointing(isPointing: boolean) {
 		this.setIsPointing(isPointing)
 	}
@@ -331,6 +331,18 @@ export class InputsManager {
 		this._isPointing.set(isPointing)
 	}
 
+	private _isRightPointing = atom<boolean>('isRightPointing', false)
+	/**
+	 * Whether the user is right-click pointing (before drag threshold).
+	 */
+	getIsRightPointing() {
+		return this._isRightPointing.get()
+	}
+	/** @internal */
+	setIsRightPointing(isRightPointing: boolean) {
+		this._isRightPointing.set(isRightPointing)
+	}
+
 	private _isPinching = atom<boolean>('isPinching', false)
 	/**
 	 * Whether the user is pinching.
@@ -341,11 +353,11 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getIsPinching()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get isPinching() {
 		return this.getIsPinching()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set isPinching(isPinching: boolean) {
 		this.setIsPinching(isPinching)
 	}
@@ -367,11 +379,11 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getIsEditing()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get isEditing() {
 		return this.getIsEditing()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set isEditing(isEditing: boolean) {
 		this.setIsEditing(isEditing)
 	}
@@ -392,11 +404,11 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getIsPanning()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get isPanning() {
 		return this.getIsPanning()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set isPanning(isPanning: boolean) {
 		this.setIsPanning(isPanning)
 	}
@@ -418,11 +430,11 @@ export class InputsManager {
 	/**
 	 * @deprecated Use `getIsSpacebarPanning()` instead.
 	 */
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	get isSpacebarPanning() {
 		return this.getIsSpacebarPanning()
 	}
-	// eslint-disable-next-line no-restricted-syntax
+	// eslint-disable-next-line tldraw/no-setter-getter
 	set isSpacebarPanning(isSpacebarPanning: boolean) {
 		this.setIsSpacebarPanning(isSpacebarPanning)
 	}

package/src/lib/editor/managers/PerformanceManager/PerformanceApiAdapter.ts

@@ -0,0 +1,82 @@
+import type { PerformanceManager } from './PerformanceManager'
+
+/** Wrap performance.mark with try/catch — `detail` option may throw in Safari/Firefox. */
+function safeMark(name: string, detail?: Record<string, unknown>) {
+	try {
+		performance.mark(name, detail ? { detail } : undefined)
+	} catch {
+		performance.mark(name)
+	}
+}
+
+/**
+ * Optional adapter that pipes PerformanceManager events into browser
+ * `performance.mark()` / `performance.measure()` for DevTools integration.
+ *
+ * Tree-shakeable — only included if imported.
+ *
+ * @example
+ * ```ts
+ * const adapter = new PerformanceApiAdapter(editor.performance)
+ * // ... later
+ * adapter.dispose()
+ * ```
+ *
+ * @public
+ */
+export class PerformanceApiAdapter {
+	private cleanups: (() => void)[] = []
+
+	constructor(perfManager: PerformanceManager) {
+		this.cleanups.push(
+			perfManager.on('interaction-start', (event) => {
+				safeMark(`tldraw:interaction:${event.name}:start`, { path: event.path })
+			})
+		)
+
+		this.cleanups.push(
+			perfManager.on('interaction-end', (event) => {
+				const startMark = `tldraw:interaction:${event.name}:start`
+				const endMark = `tldraw:interaction:${event.name}:end`
+				safeMark(endMark, {
+					path: event.path,
+					fps: event.fps,
+					frameCount: event.frameCount,
+					shapeCount: event.shapeCount,
+				})
+				try {
+					performance.measure(`tldraw:interaction:${event.name}`, startMark, endMark)
+				} catch {
+					// start mark may not exist if adapter attached mid-interaction
+				}
+			})
+		)
+
+		this.cleanups.push(
+			perfManager.on('camera-start', (event) => {
+				safeMark(`tldraw:camera:${event.type}:start`)
+			})
+		)
+
+		this.cleanups.push(
+			perfManager.on('camera-end', (event) => {
+				const startMark = `tldraw:camera:${event.type}:start`
+				const endMark = `tldraw:camera:${event.type}:end`
+				safeMark(endMark, { fps: event.fps, shapeCount: event.shapeCount })
+				try {
+					performance.measure(`tldraw:camera:${event.type}`, startMark, endMark)
+				} catch {
+					// start mark may not exist
+				}
+			})
+		)
+	}
+
+	/** Remove all listeners and stop piping events. @public */
+	dispose() {
+		for (const cleanup of this.cleanups) {
+			cleanup()
+		}
+		this.cleanups.length = 0
+	}
+}