@tldraw/editor 4.6.0-next.30b99cd52fc8 → 4.6.0-next.35cf541abcf9

package/src/lib/TldrawEditor.tsx

@@ -1,5 +1,14 @@
 import { MigrationSequence, Store } from '@tldraw/store'
-import { TLShape, TLStore, TLStoreSnapshot } from '@tldraw/tlschema'
+import {
+	TLShape,
+	TLStore,
+	TLStoreSnapshot,
+	TLTheme,
+	TLThemeId,
+	TLThemes,
+	registerColorsFromThemes,
+	registerFontsFromThemes,
+} from '@tldraw/tlschema'
 import { annotateError, Required } from '@tldraw/utils'
 import classNames from 'classnames'
 import React, {
@@ -18,10 +27,12 @@ import { DefaultErrorFallback } from './components/default-components/DefaultErr
 import { OptionalErrorBoundary } from './components/ErrorBoundary'
 import { createTLCurrentUser, TLCurrentUser } from './config/createTLCurrentUser'
 import { TLStoreBaseOptions } from './config/createTLStore'
+import { TLAnyAssetUtilConstructor } from './config/defaultAssets'
 import { TLAnyBindingUtilConstructor } from './config/defaultBindings'
 import { TLAnyShapeUtilConstructor } from './config/defaultShapes'
 import { TLEditorSnapshot } from './config/TLEditorSnapshot'
 import { Editor } from './editor/Editor'
+import { resolveThemes } from './editor/managers/ThemeManager/ThemeManager'
 import { TLStateNodeConstructor } from './editor/tools/StateNode'
 import { TLCameraOptions } from './editor/types/misc-types'
 import { useEditorComponents } from './hooks/EditorComponentsContext'
@@ -121,6 +132,11 @@ export interface TldrawEditorBaseProps {
 	 */
 	bindingUtils?: readonly TLAnyBindingUtilConstructor[]
 
+	/**
+	 * An array of asset utils to use in the editor.
+	 */
+	assetUtils?: readonly TLAnyAssetUtilConstructor[]
+
 	/**
 	 * An array of tools to add to the editor's state chart.
 	 */
@@ -157,9 +173,23 @@ export interface TldrawEditorBaseProps {
 	user?: TLCurrentUser
 
 	/**
-	 * Whether to infer dark mode from the user's OS. Defaults to false.
+	 * The editor's color scheme. Defaults to `'light'`.
+	 *
+	 * - `'light'` - Always use light mode.
+	 * - `'dark'` - Always use dark mode.
+	 * - `'system'` - Follow the OS color scheme preference.
 	 */
-	inferDarkMode?: boolean
+	colorScheme?: 'light' | 'dark' | 'system'
+
+	/**
+	 * Named themes for the editor.
+	 */
+	themes?: Partial<TLThemes>
+
+	/**
+	 * The id of the initially active theme. Defaults to `'default'`.
+	 */
+	initialTheme?: TLThemeId
 
 	/**
 	 * Camera options for the editor.
@@ -242,6 +272,7 @@ declare global {
 
 const EMPTY_SHAPE_UTILS_ARRAY = [] as const
 const EMPTY_BINDING_UTILS_ARRAY = [] as const
+const EMPTY_ASSET_UTILS_ARRAY = [] as const
 const EMPTY_TOOLS_ARRAY = [] as const
 /** @internal */
 export const TL_CONTAINER_CLASS = 'tl-container'
@@ -259,6 +290,13 @@ export const TldrawEditor = memo(function TldrawEditor({
 	deepLinks: _deepLinks,
 	...rest
 }: TldrawEditorProps) {
+	// Register custom colors and fonts before effects run. For external stores,
+	// users should also pass themes to createTLStore so they are
+	// registered before data is loaded into the store.
+	const resolvedThemes = resolveThemes(rest.themes)
+	registerColorsFromThemes(resolvedThemes)
+	registerFontsFromThemes(resolvedThemes)
+
 	const [container, setContainer] = useState<HTMLElement | null>(null)
 	const user = useMemo(() => _user ?? createTLCurrentUser(), [_user])
 
@@ -285,6 +323,7 @@ export const TldrawEditor = memo(function TldrawEditor({
 		...rest,
 		shapeUtils: rest.shapeUtils ?? EMPTY_SHAPE_UTILS_ARRAY,
 		bindingUtils: rest.bindingUtils ?? EMPTY_BINDING_UTILS_ARRAY,
+		assetUtils: rest.assetUtils ?? EMPTY_ASSET_UTILS_ARRAY,
 		tools: rest.tools ?? EMPTY_TOOLS_ARRAY,
 		components,
 		options: useShallowObjectIdentity(mergedOptions),
@@ -332,7 +371,7 @@ export const TldrawEditor = memo(function TldrawEditor({
 function TldrawEditorWithOwnStore(
 	props: Required<
 		TldrawEditorProps & { store: undefined; user: TLCurrentUser },
-		'shapeUtils' | 'bindingUtils' | 'tools'
+		'shapeUtils' | 'bindingUtils' | 'assetUtils' | 'tools'
 	>
 ) {
 	const {
@@ -341,17 +380,20 @@ function TldrawEditorWithOwnStore(
 		initialData,
 		shapeUtils,
 		bindingUtils,
+		assetUtils,
 		persistenceKey,
 		sessionId,
 		user,
 		assets,
 		users,
 		migrations,
+		themes,
 	} = props
 
 	const syncedStore = useLocalStore({
 		shapeUtils,
 		bindingUtils,
+		assetUtils,
 		initialData,
 		persistenceKey,
 		sessionId,
@@ -360,6 +402,7 @@ function TldrawEditorWithOwnStore(
 		assets,
 		users,
 		migrations,
+		themes,
 	})
 
 	return <TldrawEditorWithLoadingStore {...props} store={syncedStore} user={user} />
@@ -371,7 +414,7 @@ const TldrawEditorWithLoadingStore = memo(function TldrawEditorBeforeLoading({
 	...rest
 }: Required<
 	TldrawEditorProps & { store: TLStoreWithStatus; user: TLCurrentUser },
-	'shapeUtils' | 'bindingUtils' | 'tools'
+	'shapeUtils' | 'bindingUtils' | 'assetUtils' | 'tools'
 >) {
 	const container = useContainer()
 
@@ -417,22 +460,25 @@ function TldrawEditorWithReadyStore({
 	tools,
 	shapeUtils,
 	bindingUtils,
+	assetUtils,
 	user,
 	initialState,
 	autoFocus = true,
-	inferDarkMode,
 	// eslint-disable-next-line @typescript-eslint/no-deprecated
 	cameraOptions,
 	options,
 	licenseKey,
 	getShapeVisibility,
+	colorScheme,
 	assetUrls,
+	themes,
+	initialTheme,
 }: Required<
 	TldrawEditorProps & {
 		store: TLStore
 		user: TLCurrentUser
 	},
-	'shapeUtils' | 'bindingUtils' | 'tools'
+	'shapeUtils' | 'bindingUtils' | 'assetUtils' | 'tools'
 >) {
 	const { ErrorFallback } = useEditorComponents()
 	const container = useContainer()
@@ -448,44 +494,58 @@ function TldrawEditorWithReadyStore({
 	const editorOptionsRef = useRef({
 		// for these, it's because they're only used when the editor first mounts:
 		autoFocus: autoFocus && !noAutoFocus(),
-		inferDarkMode,
 		initialState,
+		colorScheme,
 
 		// for these, it's because we keep them up to date in a separate effect:
 		cameraOptions,
 		deepLinks,
+		themes,
+		initialTheme,
 	})
 
 	useLayoutEffect(() => {
 		editorOptionsRef.current = {
 			autoFocus: autoFocus && !noAutoFocus(),
-			inferDarkMode,
 			initialState,
+			colorScheme,
 			cameraOptions,
 			deepLinks,
+			themes,
+			initialTheme,
 		}
-	}, [autoFocus, inferDarkMode, initialState, cameraOptions, deepLinks])
+	}, [autoFocus, initialState, colorScheme, cameraOptions, deepLinks, themes, initialTheme])
 
 	useLayoutEffect(
 		() => {
-			const { autoFocus, inferDarkMode, initialState, cameraOptions, deepLinks } =
-				editorOptionsRef.current
+			const {
+				autoFocus,
+				initialState,
+				colorScheme: initColorScheme,
+				cameraOptions,
+				deepLinks,
+				themes,
+				initialTheme,
+			} = editorOptionsRef.current
 			const editor = new Editor({
 				store,
 				shapeUtils,
 				bindingUtils,
+				assetUtils,
 				tools,
 				getContainer: () => container,
 				user,
 				initialState,
 				// we should check for some kind of query parameter that turns off autofocus
 				autoFocus,
-				inferDarkMode,
 				cameraOptions,
 				options,
 				licenseKey,
 				getShapeVisibility,
+				colorScheme: initColorScheme,
 				fontAssetUrls: assetUrls?.fonts,
+				themes: themes,
+				initialTheme: initialTheme,
 			})
 
 			editor.updateViewportScreenBounds(canvasRef.current ?? container)
@@ -510,7 +570,9 @@ function TldrawEditorWithReadyStore({
 		},
 		// if any of these change, we need to recreate the editor.
 		[
+			assetUtils,
 			bindingUtils,
+			colorScheme,
 			container,
 			options,
 			shapeUtils,
@@ -539,6 +601,21 @@ function TldrawEditorWithReadyStore({
 		}
 	}, [editor, cameraOptions, options?.camera])
 
+	// keep the editor up to date with the latest theme definitions
+	useLayoutEffect(() => {
+		if (editor && themes) {
+			for (const def of Object.values(themes) as TLTheme[]) {
+				editor.updateTheme(def)
+			}
+		}
+	}, [editor, themes])
+
+	useLayoutEffect(() => {
+		if (editor && initialTheme) {
+			editor.setCurrentTheme(initialTheme)
+		}
+	}, [editor, initialTheme])
+
 	const crashingError = useSyncExternalStore(
 		useCallback(
 			(onStoreChange) => {

package/src/lib/components/LiveCollaborators.tsx

@@ -123,8 +123,14 @@ const Collaborator = track(function Collaborator({
 					.filter((id) => {
 						// Skip hidden shapes
 						if (editor.isShapeHidden(id)) return false
-						// Only render SVG indicators for shapes that use legacy indicators
-						// Canvas-based indicators are handled by CanvasShapeIndicators
+						// When canvas indicators are disabled, render SVG indicators for
+						// every selected shape. Otherwise shapes that opt into the canvas
+						// path via useLegacyIndicator() === false would never get a
+						// collaborator indicator drawn.
+						if (!editor.options.useCanvasIndicators) return true
+						// Otherwise, only render SVG indicators for shapes that opt in to
+						// the legacy path — canvas-based indicators are handled by
+						// CanvasShapeIndicators.
 						const shape = editor.getShape(id)
 						if (!shape) return false
 						const util = editor.getShapeUtil(shape)

package/src/lib/components/MenuClickCapture.tsx

@@ -1,8 +1,10 @@
 import { useValue } from '@tldraw/state-react'
-import { PointerEvent, useCallback, useRef, useState } from 'react'
+import { type PointerEvent, useCallback, useEffect, useRef, useState } from 'react'
+import { flushSync } from 'react-dom'
 import { useCanvasEvents } from '../hooks/useCanvasEvents'
 import { useEditor } from '../hooks/useEditor'
 import { Vec } from '../primitives/Vec'
+import { releasePointerCapture, setPointerCapture } from '../utils/dom'
 import { getPointerInfo } from '../utils/getPointerInfo'
 
 /**
@@ -13,99 +15,173 @@ import { getPointerInfo } from '../utils/getPointerInfo'
 export function MenuClickCapture() {
 	const editor = useEditor()
 
-	// Whether any menus are open
 	const isMenuOpen = useValue('is menu open', () => editor.menus.hasAnyOpenMenus(), [editor])
 
-	// Whether we're pointing or not—keep this component visible if we're pointing
+	// Keep this component mounted while the pointer is down so pointerup/move still
+	// land here after a synchronous clearOpenMenus() flips isMenuOpen to false.
 	const [isPointing, setIsPointing] = useState(false)
-
 	const showElement = isMenuOpen || isPointing
 
-	// Get the same events that we use on the canvas
 	const canvasEvents = useCanvasEvents()
 
-	// Keep track of the pointer state
 	const rPointerState = useRef({
 		isDown: false,
 		isDragging: false,
+		button: 0,
 		start: new Vec(),
 	})
 
+	// Swallow the native contextmenu that follows a right-click pointerdown. Without
+	// this, Radix's trigger catches the native event and opens a menu at the pointer-
+	// DOWN position — then our own synthetic contextmenu (fired on pointerup) opens it
+	// again at the release position, producing a visible flash.
+	const rCancelContextMenuSwallow = useRef<null | (() => void)>(null)
+	useEffect(
+		() => () => {
+			rCancelContextMenuSwallow.current?.()
+			rCancelContextMenuSwallow.current = null
+		},
+		[]
+	)
+	const swallowNextNativeContextMenu = useCallback(() => {
+		rCancelContextMenuSwallow.current?.()
+		const doc = editor.getContainerDocument()
+		const onContextMenu = (event: MouseEvent) => {
+			// Skip our own synthetic contextmenu — only swallow the real browser one
+			if (!event.isTrusted) return
+			rCancelContextMenuSwallow.current?.()
+			rCancelContextMenuSwallow.current = null
+			event.preventDefault()
+			event.stopImmediatePropagation()
+		}
+		const cancel = () => doc.removeEventListener('contextmenu', onContextMenu, true)
+		rCancelContextMenuSwallow.current = cancel
+		doc.addEventListener('contextmenu', onContextMenu, true)
+		// Drop the listener on the next tick if it never fires (e.g. pointer moved off-screen)
+		doc.defaultView?.setTimeout(() => {
+			if (rCancelContextMenuSwallow.current === cancel) {
+				cancel()
+				rCancelContextMenuSwallow.current = null
+			}
+		}, 0)
+	}, [editor])
+
 	const handlePointerDown = useCallback(
 		(e: PointerEvent) => {
-			if (e.button === 0) {
-				setIsPointing(true)
-				rPointerState.current = {
-					isDown: true,
-					isDragging: false,
-					start: new Vec(e.clientX, e.clientY),
+			if (e.button !== 0 && e.button !== 2) return
+
+			flushSync(() => setIsPointing(true))
+			setPointerCapture(e.currentTarget, e)
+			rPointerState.current = {
+				isDown: true,
+				isDragging: false,
+				button: e.button,
+				start: new Vec(e.clientX, e.clientY),
+			}
+
+			if (e.button === 2) {
+				if (!editor.options.rightClickPanning) {
+					// Right-click panning off: close the open menu and swallow the native
+					// contextmenu that would otherwise briefly open a new one (causing a flash).
+					swallowNextNativeContextMenu()
+					editor.menus.clearOpenMenus()
+					return
 				}
-				rDidAPointerDownAndDragWhileMenuWasOpen.current = false
+				// Forward right-click pointerdown through the canvas's own handler so
+				// pointer capture is also set on the canvas (load-bearing: without this
+				// the context menu briefly flashes closed during consecutive right-clicks).
+				// We don't clearOpenMenus() — Radix's DismissableLayer closes the menu
+				// via outside-click detection, keeping its internal state in sync.
+				const canvas =
+					editor.getContainer().querySelector<HTMLDivElement>('.tl-canvas') ?? e.currentTarget
+				canvasEvents.onPointerDown?.({ ...e, currentTarget: canvas })
+				swallowNextNativeContextMenu()
+				return
 			}
+
 			editor.menus.clearOpenMenus()
 		},
-		[editor]
+		[canvasEvents, editor, swallowNextNativeContextMenu]
 	)
 
-	const rDidAPointerDownAndDragWhileMenuWasOpen = useRef(false)
-
 	const handlePointerMove = useCallback(
 		(e: PointerEvent) => {
-			// Do nothing unless we're pointing
-			if (!rPointerState.current.isDown) return
-
-			// call the onPointerDown with the original pointer position
-			const { x, y } = rPointerState.current.start
+			const state = rPointerState.current
+			if (!state.isDown) return
 
-			if (!rDidAPointerDownAndDragWhileMenuWasOpen.current) {
+			// Left-click: wait for the drag threshold before forwarding anything, then
+			// replay pointerdown at the original start so the editor records the
+			// correct drag origin. Right-click forwards moves immediately (pointerdown
+			// was already dispatched in handlePointerDown).
+			if (state.button !== 2 && !state.isDragging) {
 				if (
-					// We're pointing, but are we dragging?
-					Vec.Dist2(rPointerState.current.start, new Vec(e.clientX, e.clientY)) >
+					Vec.Dist2(state.start, new Vec(e.clientX, e.clientY)) <=
 					editor.options.dragDistanceSquared
 				) {
-					rDidAPointerDownAndDragWhileMenuWasOpen.current = true
-					// Wehaddaeventitsadrag
-					rPointerState.current = {
-						...rPointerState.current,
-						isDown: true,
-						isDragging: true,
-					}
-					canvasEvents.onPointerDown?.({
-						...e,
-						clientX: x,
-						clientY: y,
-						button: 0,
-					})
+					return
 				}
-			}
-
-			if (rDidAPointerDownAndDragWhileMenuWasOpen.current) {
+				state.isDragging = true
 				editor.dispatch({
 					type: 'pointer',
 					target: 'canvas',
-					name: 'pointer_move',
-					...getPointerInfo(editor, e),
+					name: 'pointer_down',
+					...getPointerInfo(editor, { ...e, clientX: state.start.x, clientY: state.start.y }),
 				})
 			}
+
+			editor.dispatch({
+				type: 'pointer',
+				target: 'canvas',
+				name: 'pointer_move',
+				...getPointerInfo(editor, e),
+			})
 		},
-		[canvasEvents, editor]
+		[editor]
 	)
 
 	const handlePointerUp = useCallback(
 		(e: PointerEvent) => {
-			// Run the pointer up
-			canvasEvents.onPointerUp?.(e)
-			// Then turn off pointing
+			const isStaticRightClick = e.button === 2 && !rPointerState.current.isDragging
+
+			editor.dispatch({
+				type: 'pointer',
+				target: 'canvas',
+				name: 'pointer_up',
+				...getPointerInfo(editor, e),
+			})
+
+			if (isStaticRightClick && editor.options.rightClickPanning) {
+				// Dispatch contextmenu on the canvas's parent (Radix's trigger) so the
+				// menu opens at the release position. Bypassing the canvas avoids its
+				// own onContextMenu handler, which preventDefaults non-synthesized events.
+				const canvas = editor.getContainer().querySelector<HTMLDivElement>('.tl-canvas')
+				const trigger = canvas?.parentElement ?? e.currentTarget
+				editor.timers.requestAnimationFrame(() => {
+					trigger.dispatchEvent(
+						new PointerEvent('contextmenu', {
+							bubbles: true,
+							clientX: e.clientX,
+							clientY: e.clientY,
+							button: 2,
+							buttons: 0,
+							pointerId: e.pointerId,
+							pointerType: e.pointerType,
+							isPrimary: e.isPrimary,
+						})
+					)
+				})
+			}
+
+			releasePointerCapture(e.currentTarget, e)
 			setIsPointing(false)
-			// Reset the pointer state
 			rPointerState.current = {
 				isDown: false,
 				isDragging: false,
+				button: 0,
 				start: new Vec(e.clientX, e.clientY),
 			}
-			rDidAPointerDownAndDragWhileMenuWasOpen.current = false
 		},
-		[canvasEvents]
+		[editor]
 	)
 
 	return (
@@ -117,6 +193,10 @@ export function MenuClickCapture() {
 				onPointerDown={handlePointerDown}
 				onPointerMove={handlePointerMove}
 				onPointerUp={handlePointerUp}
+				onContextMenu={(e) => {
+					e.preventDefault()
+					e.stopPropagation()
+				}}
 			/>
 		)
 	)

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

@@ -6,8 +6,8 @@ import { memo, useEffect, useRef } from 'react'
 import { Editor } from '../../editor/Editor'
 import { TLIndicatorPath } from '../../editor/shapes/ShapeUtil'
 import { getComputedStyle } from '../../exports/domUtils'
+import { useColorMode } from '../../hooks/useColorMode'
 import { useEditor } from '../../hooks/useEditor'
-import { useIsDarkMode } from '../../hooks/useIsDarkMode'
 import { useActivePeerIds$ } from '../../hooks/usePeerIds'
 
 interface CollaboratorIndicatorData {
@@ -129,18 +129,29 @@ function renderIndicatorPath(ctx: CanvasRenderingContext2D, indicatorPath: TLInd
 /** @internal @react */
 export const CanvasShapeIndicators = memo(function CanvasShapeIndicators() {
 	const editor = useEditor()
+
+	// Skip canvas indicator rendering when the option is disabled (e.g. A/B test)
+	if (!editor.options.useCanvasIndicators) {
+		return null
+	}
+
+	return <CanvasShapeIndicatorsInner />
+})
+
+const CanvasShapeIndicatorsInner = memo(function CanvasShapeIndicatorsInner() {
+	const editor = useEditor()
 	const canvasRef = useRef<HTMLCanvasElement>(null)
 
 	// Cache the selected color to avoid getComputedStyle on every render
 	const rSelectedColor = useRef<string | null>(null)
-	const isDarkMode = useIsDarkMode()
+	const colorMode = useColorMode()
 
 	useEffect(() => {
 		const timer = editor.timers.setTimeout(() => {
 			rSelectedColor.current = null
 		}, 0)
 		return () => clearTimeout(timer)
-	}, [isDarkMode, editor])
+	}, [colorMode, editor])
 
 	// Get active peer IDs (already handles time-based state transitions)
 	const activePeerIds$ = useActivePeerIds$()

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

@@ -465,8 +465,11 @@ function HintedShapeIndicator() {
 	const ids = useValue(
 		'hinting shape ids without canvas indicator',
 		() => {
+			const hintingIds = dedupe(editor.getHintingShapeIds())
+			// When canvas indicators are disabled, render all hints via SVG
+			if (!editor.options.useCanvasIndicators) return hintingIds
 			// Filter to only shapes that use legacy SVG indicators
-			return dedupe(editor.getHintingShapeIds()).filter((id) => {
+			return hintingIds.filter((id) => {
 				const shape = editor.getShape(id)
 				if (!shape) return false
 				const util = editor.getShapeUtil(shape)
@@ -530,7 +533,8 @@ function DebugSvgCopy({ id, mode }: { id: TLShapeId; mode: 'img' | 'iframe' }) {
 			const renderId = Math.random()
 			latest = renderId
 
-			const isSingleFrame = editor.isShapeOfType(id, 'frame')
+			const shape = editor.getShape(id)
+			const isSingleFrame = !!shape && editor.isShapeFrameLike(shape)
 			const padding = isSingleFrame ? 0 : 10
 			let bounds = editor.getShapePageBounds(id)
 			if (!bounds) return

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

@@ -34,8 +34,8 @@ const InnerIndicator = memo(({ editor, id }: { editor: Editor; id: TLShapeId })
 
 	const util = editor.getShapeUtil(shape)
 
-	// If the shape uses canvas indicators, it will be rendered by CanvasShapeIndicators
-	if (!util.useLegacyIndicator()) return null
+	// If canvas indicators are enabled and the shape uses them, it will be rendered by CanvasShapeIndicators
+	if (editor.options.useCanvasIndicators && !util.useLegacyIndicator()) return null
 
 	return (
 		<OptionalErrorBoundary

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

@@ -91,9 +91,11 @@ export const DefaultShapeIndicators = memo(function DefaultShapeIndicators({
 	const { ShapeIndicator } = useEditorComponents()
 
 	// Filter out shapes that have canvas indicator support - only render shapes that use legacy SVG indicators
+	// When useCanvasIndicators is disabled, render all shapes via SVG
 	const shapesToRender = useValue(
 		'shapes to render for svg indicators',
 		() => {
+			if (!editor.options.useCanvasIndicators) return renderingShapes
 			return renderingShapes.filter(({ id }) => {
 				const shape = editor.getShape(id)
 				if (!shape) return false

package/src/lib/config/createTLStore.ts

@@ -8,15 +8,20 @@ import {
 	TLStore,
 	TLStoreProps,
 	TLStoreSnapshot,
+	TLThemes,
 	TLUser,
 	TLUserStore,
 	UserRecordType,
 	createCachedUserResolve,
 	createTLSchema,
 	createUserId,
+	registerColorsFromThemes,
+	registerFontsFromThemes,
 } from '@tldraw/tlschema'
 import { FileHelpers, assert } from '@tldraw/utils'
 import { Editor } from '../editor/Editor'
+import { resolveThemes } from '../editor/managers/ThemeManager/ThemeManager'
+import { TLAnyAssetUtilConstructor, checkAssets } from './defaultAssets'
 import { TLAnyBindingUtilConstructor, checkBindings } from './defaultBindings'
 import { TLAnyShapeUtilConstructor, checkShapesAndAddCore } from './defaultShapes'
 import { TLEditorSnapshot, loadSnapshot } from './TLEditorSnapshot'
@@ -36,6 +41,13 @@ export interface TLStoreBaseOptions {
 	/** How should this store upload & resolve assets? */
 	assets?: TLAssetStore
 
+	/**
+	 * Named theme definitions. When provided, custom color names are automatically
+	 * registered before the store is constructed so persisted data with those
+	 * colors passes validation on load.
+	 */
+	themes?: Partial<TLThemes>
+
 	/** How should this store resolve users for attribution? */
 	users?: TLUserStore
 
@@ -50,8 +62,9 @@ export type TLStoreSchemaOptions =
 	  }
 	| {
 			shapeUtils?: readonly TLAnyShapeUtilConstructor[]
-			migrations?: readonly MigrationSequence[]
 			bindingUtils?: readonly TLAnyBindingUtilConstructor[]
+			assetUtils?: readonly TLAnyAssetUtilConstructor[]
+			migrations?: readonly MigrationSequence[]
 			records?: Record<string, CustomRecordInfo>
 	  }
 
@@ -114,6 +127,10 @@ export function createTLSchemaFromUtils(
 			'bindingUtils' in opts && opts.bindingUtils
 				? utilsToMap(checkBindings(opts.bindingUtils))
 				: undefined,
+		assets:
+			'assetUtils' in opts && opts.assetUtils
+				? utilsToMap(checkAssets(opts.assetUtils))
+				: undefined,
 		records: 'records' in opts ? opts.records : undefined,
 		migrations: 'migrations' in opts ? opts.migrations : undefined,
 	})
@@ -134,8 +151,12 @@ export function createTLStore({
 	users = defaultUserStore,
 	onMount,
 	collaboration,
+	themes,
 	...rest
 }: TLStoreOptions = {}): TLStore {
+	const resolvedThemes = resolveThemes(themes)
+	registerColorsFromThemes(resolvedThemes)
+	registerFontsFromThemes(resolvedThemes)
 	const schema = createTLSchemaFromUtils(rest)
 
 	const store = new Store({