@tldraw/editor 4.6.0-next.20de11b7e238 → 4.6.0-next.241e87d4700a

package/src/lib/editor/managers/PerformanceManager/perf-types.ts

@@ -0,0 +1,196 @@
+/**
+ * Common frame time statistics shared by interaction and camera end events.
+ * @public
+ */
+export interface TLPerfFrameTimeStats {
+	/** Total duration of the session in ms. */
+	duration: number
+	/** Average frames per second during the session. */
+	fps: number
+	/** Total number of frames recorded. */
+	frameCount: number
+	/** Mean frame duration in ms. */
+	avgFrameTime: number
+	/** Median (p50) frame duration in ms. */
+	medianFrameTime: number
+	/** 95th percentile frame duration in ms. */
+	p95FrameTime: number
+	/** 99th percentile frame duration in ms. */
+	p99FrameTime: number
+	/** Shortest frame duration in ms. */
+	minFrameTime: number
+	/** Longest frame duration in ms. */
+	maxFrameTime: number
+	/** Raw frame durations for local analysis. Exclude when sending to analytics. */
+	frameTimes: number[]
+	/**
+	 * Long animation frames observed during this period (Chromium 123+).
+	 * Only present when the browser supports the Long Animation Frames API and
+	 * at least one long frame was observed.
+	 * Exclude when sending to analytics — entries are large and contain script URLs.
+	 */
+	longAnimationFrames?: TLPerfLongAnimationFrame[]
+}
+
+/**
+ * Emitted when an interaction state (e.g. translating, resizing) is entered.
+ * @public
+ */
+export interface TLInteractionStartPerfEvent {
+	/** The state node id (e.g. `'translating'`). */
+	name: string
+	/** Full tool path (e.g. `'select.translating'`). */
+	path: string
+	/** `performance.now()` when the interaction started. */
+	timestamp: number
+}
+
+/**
+ * Emitted when an interaction state is exited, with aggregated frame time stats.
+ * @public
+ */
+export interface TLInteractionEndPerfEvent extends TLPerfFrameTimeStats {
+	/** The state node id (e.g. `'translating'`). */
+	name: string
+	/** Full tool path (e.g. `'select.translating'`). */
+	path: string
+	/** Total shapes on the current page. */
+	shapeCount: number
+	/** Breakdown of selected shape types at interaction start (e.g. `{ geo: 2, draw: 1 }`). */
+	selectedShapeTypes: Record<string, number>
+	/** Camera zoom level (`camera.z`) at interaction end. */
+	zoomLevel: number
+	/** `performance.now()` when the interaction ended. */
+	timestamp: number
+}
+
+/**
+ * Emitted when a camera operation (pan or zoom) begins.
+ * @public
+ */
+export interface TLCameraStartPerfEvent {
+	/** Whether this is a pan or zoom operation. */
+	type: 'panning' | 'zooming'
+	/** `performance.now()` when the camera session started. */
+	timestamp: number
+}
+
+/**
+ * Emitted when a camera operation ends (after a 50ms debounce), with aggregated frame time stats.
+ * @public
+ */
+export interface TLCameraEndPerfEvent extends TLPerfFrameTimeStats {
+	/** Whether this was a pan or zoom operation. */
+	type: 'panning' | 'zooming'
+	/** Total shapes on the current page. */
+	shapeCount: number
+	/** Number of shapes visible (not culled) in the viewport. */
+	visibleShapeCount: number
+	/** Number of shapes culled (off-screen) from rendering. */
+	culledShapeCount: number
+	/** Viewport width in screen pixels. */
+	viewportWidth: number
+	/** Viewport height in screen pixels. */
+	viewportHeight: number
+	/** Camera zoom level (`camera.z`) at session end. */
+	zoomLevel: number
+	/** `performance.now()` when the camera session ended. */
+	timestamp: number
+}
+
+/**
+ * Emitted when shapes are created, updated, or deleted.
+ * @public
+ */
+export interface TLShapeOperationPerfEvent {
+	/** The operation type. */
+	operation: 'create' | 'update' | 'delete'
+	/** Number of shapes affected. */
+	count: number
+	/** Breakdown by shape type (e.g. `{ geo: 2, draw: 1 }`). */
+	shapeTypes: Record<string, number>
+	/** `performance.now()` when the operation occurred. */
+	timestamp: number
+}
+
+/**
+ * Emitted every animation frame when at least one `'frame'` listener is registered.
+ * @public
+ */
+export interface TLFramePerfEvent {
+	/** Time since the last frame in ms. */
+	elapsed: number
+	/** Total shapes on the current page. */
+	shapeCount: number
+	/** Number of shapes culled (off-screen) from rendering. */
+	culledShapeCount: number
+	/** Number of shapes visible (not culled) in the viewport. */
+	visibleShapeCount: number
+}
+
+/**
+ * Emitted after an undo or redo operation.
+ * @public
+ */
+export interface TLUndoRedoPerfEvent {
+	/** Whether this was an undo or redo. */
+	type: 'undo' | 'redo'
+	/** Number of undo steps remaining. */
+	undoDepth: number
+	/** Number of redo steps remaining. */
+	redoDepth: number
+}
+
+/**
+ * A long animation frame observed by the browser during an interaction.
+ * Available only in browsers that support the Long Animation Frames API (Chromium 123+).
+ * @public
+ */
+export interface TLPerfLongAnimationFrame {
+	/** Frame start time (relative to timeOrigin). */
+	startTime: number
+	/** Total frame duration in ms. */
+	duration: number
+	/** Time the main thread was blocked in ms. */
+	blockingDuration: number
+	/** Scripts that contributed to the long frame. */
+	scripts: TLPerfLongAnimationFrameScript[]
+}
+
+/** A script attribution entry from a long animation frame. @public */
+export interface TLPerfLongAnimationFrameScript {
+	/** The script source URL (may be empty for inline scripts). */
+	sourceURL: string
+	/** The function name or invoker description. */
+	invoker: string
+	/** Time spent in this script in ms. */
+	duration: number
+}
+
+/**
+ * Map of all performance event names to their payload types.
+ * Used with {@link PerformanceManager.on} and {@link PerformanceManager.once}.
+ * @public
+ */
+export interface TLPerfEventMap {
+	/** An interaction state was entered. */
+	'interaction-start': [TLInteractionStartPerfEvent]
+	/** An interaction state was exited, with aggregated frame time stats. */
+	'interaction-end': [TLInteractionEndPerfEvent]
+	/** A camera operation (pan/zoom) began. */
+	'camera-start': [TLCameraStartPerfEvent]
+	/** A camera operation ended (after debounce), with aggregated frame time stats. */
+	'camera-end': [TLCameraEndPerfEvent]
+	/** Shapes were created. */
+	'shapes-created': [TLShapeOperationPerfEvent]
+	/** Shapes were updated. */
+	'shapes-updated': [TLShapeOperationPerfEvent]
+	/** Shapes were deleted. */
+	'shapes-deleted': [TLShapeOperationPerfEvent]
+	/** An animation frame was rendered. Only fires when listeners are registered. */
+	frame: [TLFramePerfEvent]
+	/** An undo operation was performed. */
+	undo: [TLUndoRedoPerfEvent]
+	/** A redo operation was performed. */
+	redo: [TLUndoRedoPerfEvent]
+}

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

@@ -0,0 +1,116 @@
+import { Atom, atom, computed } from '@tldraw/state'
+import { TLTheme, TLThemeId, TLThemes } from '@tldraw/tlschema'
+import { structuredClone } from '@tldraw/utils'
+import type { Editor } from '../../Editor'
+import { DEFAULT_THEME } from './defaultThemes'
+
+/**
+ * Resolve a partial set of user-provided themes into a complete `TLThemes`
+ * record by merging with `DEFAULT_THEME`. The result is suitable for passing to
+ * `registerColorsFromThemes`, `registerFontsFromThemes`, and the
+ * `ThemeManager` constructor.
+ *
+ * @public
+ */
+export function resolveThemes(themes?: Partial<TLThemes>): TLThemes {
+	return { default: DEFAULT_THEME, ...themes } as TLThemes
+}
+
+/**
+ * Manages the editor's color themes.
+ *
+ * Stores named theme definitions (each containing light and dark color palettes
+ * alongside shared properties like font size). The current theme is resolved by
+ * combining the current theme name with the user's color mode preference.
+ *
+ * **Terminology:**
+ * - **Theme** (`TLTheme`): A named set of colors and typographic values for both light and dark modes.
+ * - **Color mode** (`'light' | 'dark'`): The resolved appearance mode, derived from the user's
+ *   `colorScheme` preference (`'light' | 'dark' | 'system'`). Access via `getColorMode()`.
+ *
+ * @public
+ */
+export class ThemeManager {
+	private readonly _themes: Atom<TLThemes>
+	private readonly _currentThemeId: Atom<TLThemeId>
+
+	constructor(
+		private readonly editor: Editor,
+		options: {
+			themes: TLThemes
+			initial: TLThemeId
+		}
+	) {
+		this._themes = atom('ThemeManager._definitions', options.themes)
+		this._currentThemeId = atom('ThemeManager._currentThemeName', options.initial)
+	}
+
+	/** Get the current color mode based on the user's dark mode preference. */
+	@computed getColorMode(): 'light' | 'dark' {
+		return this.editor.user.getIsDarkMode() ? 'dark' : 'light'
+	}
+
+	/** Get all registered theme definitions. */
+	getThemes(): TLThemes {
+		return this._themes.get()
+	}
+
+	/** Get a single theme definition by id. */
+	getTheme(id: TLThemeId): TLTheme | undefined {
+		return this._themes.get()[id]
+	}
+
+	/** Get the id of the current theme. */
+	getCurrentThemeId(): TLThemeId {
+		return this._currentThemeId.get()
+	}
+
+	getCurrentTheme(): TLTheme {
+		return this._themes.get()[this.getCurrentThemeId()]!
+	}
+
+	/** Set the current theme by id. The theme must have been previously registered. */
+	setCurrentTheme(id: TLThemeId): void {
+		if (process.env.NODE_ENV !== 'production') {
+			if (!(id in this._themes.get())) {
+				console.warn(
+					`Theme '${id}' not found. Available themes: ${Object.keys(this._themes.get()).join(', ')}`
+				)
+			}
+		}
+
+		this._currentThemeId.set(id)
+	}
+
+	/** Replace all theme definitions, or update them via a callback that receives a deep copy. */
+	updateThemes(themes: TLThemes | ((themes: TLThemes) => TLThemes)): void {
+		this._themes.update((prev) => {
+			const next = typeof themes === 'function' ? themes(structuredClone(prev)) : themes
+			if (process.env.NODE_ENV !== 'production') {
+				if (!('default' in next)) {
+					console.warn("The 'default' theme cannot be removed.")
+					return prev
+				}
+			}
+			// If the current theme was removed, fall back to 'default'
+			if (!(this._currentThemeId.get() in next)) {
+				this._currentThemeId.set('default')
+			}
+			return next
+		})
+	}
+
+	/** Register or update a named theme definition. */
+	updateTheme(theme: TLTheme): void {
+		this._themes.update((prev) => ({
+			...prev,
+			[theme.id]: theme,
+		}))
+	}
+
+	/** Clean up any resources held by the manager. */
+	dispose() {
+		// currently no subscriptions to tear down, but here for consistency
+		// with the manager pattern and for future use
+	}
+}