@tldraw/editor 4.6.0-canary.7e9dd241bb89 → 4.6.0-canary.7ea68e5d3c36

package/dist-cjs/index.d.ts

@@ -1,5 +1,6 @@
 import { Atom } from '@tldraw/state';
 import { AtomSet } from '@tldraw/store';
+import { Awaitable } from '@tldraw/utils';
 import { BoxModel } from '@tldraw/tlschema';
 import { ComponentType } from 'react';
 import { Computed } from '@tldraw/state';
@@ -18,11 +19,8 @@ import { JsonObject } from '@tldraw/utils';
 import { JSX } from 'react/jsx-runtime';
 import { LegacyMigrations } from '@tldraw/store';
 import { MigrationSequence } from '@tldraw/store';
-import { NamedExoticComponent } from 'react';
 import { Node as Node_2 } from '@tiptap/pm/model';
 import { PerformanceTracker } from '@tldraw/utils';
-import { PointerEvent as PointerEvent_2 } from 'react';
-import { PointerEventHandler } from 'react';
 import * as React_2 from 'react';
 import { default as React_3 } from 'react';
 import { ReactElement } from 'react';
@@ -56,9 +54,12 @@ import { TLCamera } from '@tldraw/tlschema';
 import { TLCreateShapePartial } from '@tldraw/tlschema';
 import { TLCursor } from '@tldraw/tlschema';
 import { TLCursorType } from '@tldraw/tlschema';
+import { TLDefaultColor } from '@tldraw/tlschema';
+import { TLDefaultColorStyle } from '@tldraw/tlschema';
 import { TLDefaultDashStyle } from '@tldraw/tlschema';
 import { TLDefaultHorizontalAlignStyle } from '@tldraw/tlschema';
 import { TLDocument } from '@tldraw/tlschema';
+import { TLFontFace } from '@tldraw/tlschema';
 import { TLGroupShape } from '@tldraw/tlschema';
 import { TLHandle } from '@tldraw/tlschema';
 import { TLImageAsset } from '@tldraw/tlschema';
@@ -80,8 +81,15 @@ import { TLStore } from '@tldraw/tlschema';
 import { TLStoreProps } from '@tldraw/tlschema';
 import { TLStoreSchema } from '@tldraw/tlschema';
 import { TLStoreSnapshot } from '@tldraw/tlschema';
+import { TLTheme } from '@tldraw/tlschema';
+import { TLThemeColors } from '@tldraw/tlschema';
+import { TLThemeId } from '@tldraw/tlschema';
+import { TLThemes } from '@tldraw/tlschema';
+import { TLUnknownAsset } from '@tldraw/tlschema';
 import { TLUnknownBinding } from '@tldraw/tlschema';
 import { TLUnknownShape } from '@tldraw/tlschema';
+import { TLUser } from '@tldraw/tlschema';
+import { TLUserStore } from '@tldraw/tlschema';
 import { TLVideoAsset } from '@tldraw/tlschema';
 import { UnknownRecord } from '@tldraw/store';
 import { VecModel } from '@tldraw/tlschema';
@@ -144,6 +152,51 @@ export declare class Arc2d extends Geometry2d {
  */
 export declare function areAnglesCompatible(a: number, b: number): boolean;
 
+/**
+ * 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 declare abstract class AssetUtil<Asset extends TLAsset = TLAsset> {
+    editor: Editor;
+    /** 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;
+    constructor(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 | MigrationSequence | TLPropsMigrations;
+    /**
+     * 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[];
+    /**
+     * Check whether this asset type accepts a given MIME type.
+     */
+    acceptsMimeType(mimeType: string): boolean;
+    /**
+     * Create an asset from a file. Return null if this asset type can't handle the file.
+     */
+    getAssetFromFile(_file: File, _assetId: TLAssetId): Promise<Asset | null>;
+}
+
 /** @public */
 export declare function average(A: VecLike, B: VecLike): string;
 
@@ -164,6 +217,64 @@ export declare abstract class BaseBoxShapeUtil<Shape extends TLBaseBoxShape> ext
     getInterpolatedProps(startShape: Shape, endShape: Shape, t: number): Shape['props'];
 }
 
+/**
+ * A base class for frame-like shapes — containers that clip their children,
+ * require full-brush selection, block erasure from inside, and support
+ * drag-and-drop reparenting.
+ *
+ * Extending this class is the easiest way to create a custom frame-like shape.
+ * It provides sensible defaults for all frame-like behaviors:
+ *
+ * - `isFrameLike()` returns `true`
+ * - `providesBackgroundForChildren()` returns `true`
+ * - `canReceiveNewChildrenOfType()` returns `true` unless the container is locked
+ * - `canRemoveChildrenOfType()` returns `true` unless the container is locked
+ * - `getClipPath()` returns the shape geometry's vertices
+ * - `onDragShapesIn()` reparents shapes into the frame (with index restoration)
+ * - `onDragShapesOut()` reparents shapes back to the page
+ *
+ * All methods can be overridden for custom behavior.
+ *
+ * @example
+ * ```ts
+ * class MyContainerUtil extends BaseFrameLikeShapeUtil<MyContainerShape> {
+ *   static override type = 'my-container' as const
+ *   static override props = myContainerShapeProps
+ *
+ *   override getDefaultProps() {
+ *     return { w: 300, h: 200 }
+ *   }
+ *
+ *   override component(shape: MyContainerShape) {
+ *     return <SVGContainer>...</SVGContainer>
+ *   }
+ *
+ *   override getIndicatorPath(shape: MyContainerShape) {
+ *     const path = new Path2D()
+ *     path.rect(0, 0, shape.props.w, shape.props.h)
+ *     return path
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export declare abstract class BaseFrameLikeShapeUtil<Shape extends TLBaseBoxShape> extends BaseBoxShapeUtil<Shape> {
+    isFrameLike(_shape: Shape): boolean;
+    providesBackgroundForChildren(): boolean;
+    canReceiveNewChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
+    canRemoveChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
+    getClipPath(shape: Shape): undefined | Vec[];
+    onDragShapesIn(shape: Shape, draggingShapes: TLShape[], { initialParentIds, initialIndices }: TLDragShapesInInfo): void;
+    onDragShapesOut(shape: Shape, draggingShapes: TLShape[], info: TLDragShapesOutInfo): void;
+}
+
+/** @public */
+export declare interface BatchMeasurementRequest {
+    html: string;
+    opts: TLMeasureTextOpts;
+}
+
 /**
  * Options passed to {@link BindingUtil.onBeforeChange} and {@link BindingUtil.onAfterChange},
  * describing the data associated with a binding being changed.
@@ -657,6 +768,49 @@ export declare class ClickManager {
  */
 export declare function clockwiseAngleDist(a0: number, a1: number): number;
 
+/**
+ * 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 declare class CollaboratorsManager {
+    private readonly editor;
+    constructor(editor: Editor);
+    /**
+     * 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;
+    private _getCollaboratorsQuery;
+    /**
+     * Returns a list of presence records for all peer collaborators.
+     * This will return the latest presence record for each connected user.
+     */
+    getCollaborators(): TLInstancePresence[];
+    /**
+     * 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.
+     */
+    getCollaboratorsOnCurrentPage(): TLInstancePresence[];
+    /**
+     * 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.
+     */
+    getVisibleCollaborators(): TLInstancePresence[];
+    /**
+     * Returns a list of presence records for peer collaborators who should currently be
+     * shown in the UI, filtered to those on the current page.
+     */
+    getVisibleCollaboratorsOnCurrentPage(): TLInstancePresence[];
+}
+
 /**
  * @public
  * @react
@@ -711,6 +865,12 @@ export declare function createDeepLinkString(deepLink: TLDeepLink): string;
  */
 export declare function createSessionStateSnapshotSignal(store: TLStore): Signal<null | TLSessionStateSnapshot>;
 
+/** @public */
+export declare function createTLCurrentUser(opts?: {
+    setUserPreferences?: ((userPreferences: TLUserPreferences) => void) | undefined;
+    userPreferences?: Signal<TLUserPreferences, unknown> | undefined;
+}): TLCurrentUser;
+
 /**
  * A helper for creating a TLStore schema from either an object with shapeUtils, bindingUtils, and
  * migrations, or a schema.
@@ -728,13 +888,7 @@ export declare function createTLSchemaFromUtils(opts: TLStoreSchemaOptions): Sto
  *
  * @public
  */
-export declare function createTLStore({ initialData, defaultName, id, assets, onMount, collaboration, ...rest }?: TLStoreOptions): TLStore;
-
-/** @public */
-export declare function createTLUser(opts?: {
-    setUserPreferences?: ((userPreferences: TLUserPreferences) => void) | undefined;
-    userPreferences?: Signal<TLUserPreferences, unknown> | undefined;
-}): TLUser;
+export declare function createTLStore({ initialData, defaultName, id, assets, users, onMount, collaboration, themes, ...rest }?: TLStoreOptions): TLStore;
 
 /** @public */
 export declare class CubicBezier2d extends Polyline2d {
@@ -809,54 +963,31 @@ export declare interface DebugFlagDefaults<T> {
 
 /* Excluded from this release type: DEFAULT_CAMERA_OPTIONS */
 
-/** @public @react */
-export declare function DefaultBackground(): JSX.Element;
+/**
+ * The default theme definition containing color palettes for both light and dark modes.
+ *
+ * @public
+ */
+export declare const DEFAULT_THEME: TLTheme;
 
 /** @public @react */
-export declare const DefaultBrush: ({ brush, color, opacity, className }: TLBrushProps) => JSX.Element;
+export declare function DefaultBackground(): JSX.Element;
 
 /** @public @react */
 export declare function DefaultCanvas({ className }: TLCanvasComponentProps): JSX.Element;
 
-/** @public @react */
-export declare function DefaultCollaboratorHint({ className, zoom, point, color, viewport, opacity }: TLCollaboratorHintProps): JSX.Element;
-
-/** @public @react */
-export declare const DefaultCursor: NamedExoticComponent<TLCursorProps>;
-
 /** @public @react */
 export declare const DefaultErrorFallback: TLErrorFallbackComponent;
 
 /** @public @react */
 export declare function DefaultGrid({ x, y, z, size }: TLGridProps): JSX.Element;
 
-/** @public @react */
-export declare function DefaultHandle({ handle, isCoarse, className, zoom }: TLHandleProps): JSX.Element;
-
-/** @public @react */
-export declare const DefaultHandles: ({ children }: TLHandlesProps) => JSX.Element;
-
-/** @public @react */
-export declare function DefaultScribble({ scribble, zoom, color, opacity, className }: TLScribbleProps): JSX.Element | null;
-
 /** @public @react */
 export declare function DefaultSelectionBackground({ bounds, rotation }: TLSelectionBackgroundProps): JSX.Element;
 
-/** @public @react */
-export declare function DefaultSelectionForeground({ bounds, rotation }: TLSelectionForegroundProps): JSX.Element;
-
-/** @public @react */
-export declare const DefaultShapeIndicator: NamedExoticComponent<TLShapeIndicatorProps>;
-
-/** @public @react */
-export declare const DefaultShapeIndicators: NamedExoticComponent<TLShapeIndicatorsProps>;
-
 /** @public @react */
 export declare const DefaultShapeWrapper: ForwardRefExoticComponent<TLShapeWrapperProps & RefAttributes<HTMLDivElement>>;
 
-/** @public @react */
-export declare function DefaultSnapIndicator({ className, line, zoom }: TLSnapIndicatorProps): JSX.Element;
-
 /** @public @react */
 export declare function DefaultSpinner(props: React.SVGProps<SVGSVGElement>): JSX.Element;
 
@@ -923,7 +1054,11 @@ export declare const defaultTldrawOptions: {
     readonly maxShapesPerPage: 4000;
     readonly multiClickDurationMs: 200;
     readonly nonce: undefined;
+    readonly onBeforeCopyToClipboard: undefined;
+    readonly onBeforePasteFromClipboard: undefined;
+    readonly onClipboardPasteRaw: undefined;
     readonly quickZoomPreservesScreenBounds: true;
+    readonly rightClickPanning: true;
     readonly snapThreshold: 8;
     readonly spacebarPanning: true;
     readonly temporaryAssetPreviewLifetimeMs: 180000;
@@ -953,6 +1088,9 @@ export declare const defaultUserPreferences: Readonly<{
     name: "";
 }>;
 
+/** @public */
+export declare const defaultUserStore: TLUserStore;
+
 /**
  * Convert degrees to radians.
  *
@@ -1028,7 +1166,7 @@ export declare class EdgeScrollManager {
 /** @public */
 export declare class Editor extends EventEmitter<TLEventMap> {
     readonly id: string;
-    constructor({ store, user, shapeUtils, bindingUtils, tools, getContainer, cameraOptions, initialState, autoFocus, inferDarkMode, options: _options, textOptions: _textOptions, getShapeVisibility, fontAssetUrls }: TLEditorOptions);
+    constructor({ store, user, shapeUtils, bindingUtils, assetUtils: assetUtilConstructors, overlayUtils: overlayUtilConstructors, tools, getContainer, cameraOptions, initialState, autoFocus, options: _options, textOptions: _textOptions, getShapeVisibility, colorScheme, fontAssetUrls, themes, initialTheme }: TLEditorOptions);
     private readonly _getShapeVisibility?;
     private getIsShapeHiddenCache;
     isShapeHidden(shapeOrId: TLShape | TLShapeId): boolean;
@@ -1091,7 +1229,13 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      * @public
      */
     readonly snaps: SnapManager;
-    private readonly _spatialIndex;
+    /**
+     * A manager for performance measurement hooks.
+     *
+     * @public
+     */
+    readonly performance: PerformanceManager;
+    /* Excluded from this release type: _spatialIndex */
     /**
      * A manager for the any asynchronous events and making sure they're
      * cleaned up upon disposal.
@@ -1104,12 +1248,19 @@ export declare class Editor extends EventEmitter<TLEventMap> {
         setInterval: (handler: TimerHandler, timeout?: number | undefined, ...args: any[]) => number;
         setTimeout: (handler: TimerHandler, timeout?: number | undefined, ...args: any[]) => number;
     };
+    /**
+     * A manager for remote peer collaborators connected to this editor.
+     *
+     * @public
+     */
+    readonly collaborators: CollaboratorsManager;
     /**
      * A manager for the user and their preferences.
      *
      * @public
      */
     readonly user: UserPreferencesManager;
+    /* Excluded from this release type: _themeManager */
     /**
      * A helper for measuring text.
      *
@@ -1128,6 +1279,12 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      * @public
      */
     readonly scribbles: ScribbleManager;
+    /**
+     * A manager for canvas overlay UI elements (selection handles, shape handles, etc.).
+     *
+     * @public
+     */
+    readonly overlays: OverlayManager;
     /**
      * A manager for side effects and correct state enforcement. See {@link @tldraw/store#StoreSideEffects} for details.
      *
@@ -1160,6 +1317,83 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      * @public
      */
     dispose(): void;
+    /**
+     * Get the current color mode (`'light'` or `'dark'`), based on the user's dark mode preference.
+     *
+     * @public
+     */
+    getColorMode(): 'dark' | 'light';
+    /**
+     * Set the color mode. Note that this is a convenience method that passes the mode to
+     * `user.updateUserPreferences`, which is the source of truth for the user's color mode preference.
+     *
+     * @public
+     */
+    setColorMode(mode: 'dark' | 'light'): this;
+    /**
+     * Get the id of the current theme.
+     *
+     * @public
+     */
+    getCurrentThemeId(): TLThemeId;
+    /**
+     * Get the current theme definition.
+     *
+     * @public
+     */
+    getCurrentTheme(): TLTheme;
+    /**
+     * Set the current theme by id.
+     *
+     * @public
+     */
+    setCurrentTheme(id: TLThemeId): this;
+    /**
+     * Get all registered theme definitions.
+     *
+     * @public
+     */
+    getThemes(): TLThemes;
+    /**
+     * Get a single theme definition by id.
+     *
+     * @public
+     */
+    getTheme(id: TLThemeId): TLTheme | undefined;
+    /**
+     * Replace all theme definitions, or update them via a callback that receives a deep copy.
+     * The `'default'` theme must always be present in the result.
+     *
+     * @example
+     * ```ts
+     * // Replace all themes
+     * editor.updateThemes({ default: myDefaultTheme, ocean: myOceanTheme })
+     *
+     * // Update via callback
+     * editor.updateThemes((themes) => {
+     *   delete themes.ocean
+     *   return themes
+     * })
+     * ```
+     *
+     * @public
+     */
+    updateThemes(themes: ((themes: TLThemes) => TLThemes) | TLThemes): this;
+    /**
+     * Register or update a single theme definition. The theme is keyed by its `id` property.
+     *
+     * @example
+     * ```ts
+     * // Override a property on the default theme
+     * editor.updateTheme({ ...editor.getTheme('default')!, fontSize: 24 })
+     *
+     * // Register a new theme
+     * editor.updateTheme({ id: 'ocean', ...myOceanTheme })
+     * ```
+     *
+     * @public
+     */
+    updateTheme(theme: TLTheme): this;
     /**
      * A map of shape utility classes (TLShapeUtils) by shape type.
      *
@@ -1168,6 +1402,7 @@ export declare class Editor extends EventEmitter<TLEventMap> {
     shapeUtils: {
         readonly [K in string]?: ShapeUtil<TLShape>;
     };
+    /* Excluded from this release type: _shapeUtilsByAssetType */
     styleProps: {
         [key: string]: Map<StyleProp<any>, string>;
     };
@@ -1199,6 +1434,15 @@ export declare class Editor extends EventEmitter<TLEventMap> {
     hasShapeUtil(shape: TLShape | TLShapePartial<TLShape>): boolean;
     hasShapeUtil(type: TLShape['type']): boolean;
     hasShapeUtil<T extends ShapeUtil>(type: T extends ShapeUtil<infer R> ? R['type'] : string): boolean;
+    /**
+     * Get the shape util that handles the given asset type.
+     * Returns the shape util whose {@link ShapeUtil.handledAssetTypes} includes
+     * the given asset type, or undefined if none matches.
+     *
+     * @param assetType - The asset type string.
+     * @public
+     */
+    getShapeUtilForAssetType(assetType: string): ShapeUtil | undefined;
     /**
      * A map of shape utility classes (TLShapeUtils) by shape type.
      *
@@ -1229,6 +1473,40 @@ export declare class Editor extends EventEmitter<TLEventMap> {
         type: S['type'];
     } | S): BindingUtil<S>;
     getBindingUtil<T extends BindingUtil>(type: T extends BindingUtil<infer R> ? R['type'] : string): T;
+    /**
+     * A map of asset utility classes by asset type.
+     *
+     * @public
+     */
+    assetUtils: {
+        readonly [K in string]?: AssetUtil<TLAsset>;
+    };
+    /**
+     * Get an asset util from an asset or asset type.
+     *
+     * @param arg - An asset, asset type string, or object with type.
+     *
+     * @public
+     */
+    getAssetUtil<S extends TLAsset>(asset: {
+        type: S['type'];
+    } | S): AssetUtil<S>;
+    getAssetUtil(type: string): AssetUtil;
+    /**
+     * Returns true if the editor has an asset util for the given asset type.
+     *
+     * @public
+     */
+    hasAssetUtil(arg: {
+        type: string;
+    } | string): boolean;
+    /**
+     * Get the asset util that accepts the given MIME type.
+     * Returns null if no registered asset util accepts the MIME type.
+     *
+     * @public
+     */
+    getAssetUtilForMimeType(mimeType: string): AssetUtil | null;
     /**
      * A manager for the editor's history.
      *
@@ -1485,6 +1763,11 @@ export declare class Editor extends EventEmitter<TLEventMap> {
     /**
      * Set the cursor.
      *
+     * No-op when the partial wouldn't change the current cursor — `setCursor`
+     * is called from pointer-move hot paths (see `updateHoveredOverlayId`,
+     * various tool states) and skipping redundant writes avoids needlessly
+     * dirtying instance state.
+     *
      * @param cursor - The cursor to set.
      * @public
      */
@@ -2244,11 +2527,12 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      * @public
      */
     pageToViewport(point: VecLike): Vec;
-    private _getCollaboratorsQuery;
     /**
      * Returns a list of presence records for all peer collaborators.
      * This will return the latest presence record for each connected user.
      *
+     * Convenience wrapper for {@link CollaboratorsManager.getCollaborators}.
+     *
      * @public
      */
     getCollaborators(): TLInstancePresence[];
@@ -2256,9 +2540,58 @@ export declare class Editor extends EventEmitter<TLEventMap> {
      * 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.
      *
+     * Convenience wrapper for {@link CollaboratorsManager.getCollaboratorsOnCurrentPage}.
+     *
      * @public
      */
     getCollaboratorsOnCurrentPage(): TLInstancePresence[];
+    /**
+     * Returns a list of presence records for peer collaborators who should currently be
+     * shown in the UI. Filters {@link Editor.getCollaborators} by activity state
+     * (active / idle / inactive) and visibility rules such as following and highlighted
+     * users. Re-evaluates on the collaborator visibility clock, so callers don't need to
+     * drive their own activity timer.
+     *
+     * Convenience wrapper for {@link CollaboratorsManager.getVisibleCollaborators}.
+     *
+     * @public
+     */
+    getVisibleCollaborators(): TLInstancePresence[];
+    /**
+     * Returns a list of presence records for peer collaborators who should currently be
+     * shown in the UI, filtered to those on the current page.
+     *
+     * Convenience wrapper for {@link CollaboratorsManager.getVisibleCollaboratorsOnCurrentPage}.
+     *
+     * @public
+     */
+    getVisibleCollaboratorsOnCurrentPage(): TLInstancePresence[];
+    /**
+     * Get the current user's ID for attribution purposes.
+     * Also ensures a `user:` record exists in the store for the current user.
+     * Returns `null` when the user store has no current user.
+     *
+     * @public
+     */
+    getAttributionUserId(): null | string;
+    /* Excluded from this release type: _ensureUserRecord */
+    /**
+     * Resolve a display name for a user ID. Asks the
+     * {@link @tldraw/tlschema#TLUserStore} first (the app's source of truth),
+     * falling back to the `user:` record in the store.
+     *
+     * @public
+     */
+    getAttributionDisplayName(userId: null | string): null | string;
+    /**
+     * Resolve a user record by ID. Asks the
+     * {@link @tldraw/tlschema#TLUserStore} first (the app's source of truth),
+     * falling back to the `user:` record in the store.
+     *
+     * @public
+     */
+    getAttributionUser(userId: null | string): null | TLUser;
+    /* Excluded from this release type: _getReferencedUserIds */
     private _isLockedOnFollowingUser;
     /**
      * Start viewport-following a user.
@@ -2893,6 +3226,20 @@ export declare class Editor extends EventEmitter<TLEventMap> {
         type: T['type'];
     }>;
     isShapeOfType<T extends TLShape = TLShape>(shapeId: TLShapeId, type: T['type']): boolean;
+    /**
+     * Get whether a shape behaves like a frame — a container that has child
+     * shapes, requires full-brush selection, blocks erasure from inside, etc.
+     *
+     * @example
+     * ```ts
+     * const isFrameLike = editor.isShapeFrameLike(someShape)
+     * ```
+     *
+     * @param shape - The shape (or shape id) to test.
+     *
+     * @public
+     */
+    isShapeFrameLike(shape: TLShape | TLShapeId): boolean;
     /**
      * Get a shape by its id.
      *
@@ -4353,6 +4700,35 @@ export declare interface Geometry2dOptions extends TransformedGeometry2dOptions
  */
 export declare function getArcMeasure(A: number, B: number, sweepFlag: number, largeArcFlag: number): number;
 
+/**
+ * Resolves a color style value to its actual CSS color string for a given theme and variant.
+ * If the color is not a default theme color, returns the color value as-is.
+ *
+ * @param colors - The color palette for the current color mode (e.g. `theme.colors[colorMode]`)
+ * @param color - The color style value to resolve
+ * @param variant - Which variant of the color to return (solid, fill, pattern, etc.)
+ * @returns The CSS color string for the specified color and variant
+ *
+ * @example
+ * ```ts
+ * import { getColorValue } from 'tldraw'
+ *
+ * const colors = editor.getCurrentTheme().colors[editor.getColorMode()]
+ *
+ * // Get the solid variant of red
+ * const redSolid = getColorValue(colors, 'red', 'solid') // '#e03131'
+ *
+ * // Get the fill variant of blue
+ * const blueFill = getColorValue(colors, 'blue', 'fill') // '#4465e9'
+ *
+ * // Custom color passes through unchanged
+ * const customColor = getColorValue(colors, '#ff0000', 'solid') // '#ff0000'
+ * ```
+ *
+ * @public
+ */
+export declare function getColorValue(colors: TLThemeColors, color: string | TLDefaultColorStyle, variant: keyof TLDefaultColor): string;
+
 /** @public */
 export declare function getCursor(cursor: TLCursorType, rotation?: number, color?: string): string;
 
@@ -4397,6 +4773,16 @@ export declare function getFreshUserPreferences(): TLUserPreferences;
  */
 export declare function getIncrementedName(name: string, others: string[]): string;
 
+/**
+ * Get the resolved display values for an overlay, merging the base values with any overrides.
+ *
+ * @public
+ */
+export declare function getOverlayDisplayValues<Overlay extends TLOverlay, DisplayValues extends object>(util: {
+    editor: Editor;
+    options: OverlayOptionsWithDisplayValues<Overlay, DisplayValues>;
+}, overlay: Overlay, colorMode?: 'dark' | 'light'): DisplayValues;
+
 /* Excluded from this release type: getOwnerDocument */
 
 /* Excluded from this release type: getOwnerWindow */
@@ -4523,14 +4909,14 @@ export declare class GroupShapeUtil extends ShapeUtil<TLGroupShape> {
     static type: "group";
     static props: RecordProps<TLGroupShape>;
     static migrations: TLPropsMigrations;
-    hideSelectionBoundsFg(): boolean;
+    hideSelectionBoundsFg(shape: TLGroupShape): boolean;
     canBind(): boolean;
     canResize(): boolean;
     canResizeChildren(): boolean;
     getDefaultProps(): TLGroupShape['props'];
     getGeometry(shape: TLGroupShape): Geometry2d;
     component(shape: TLGroupShape): JSX.Element | null;
-    indicator(shape: TLGroupShape): JSX.Element;
+    getIndicatorPath(shape: TLGroupShape): Path2D;
     onChildrenChange(group: TLGroupShape): void;
 }
 
@@ -4809,6 +5195,12 @@ export declare class InputsManager {
     get isPointing(): boolean;
     set isPointing(isPointing: boolean);
     /* Excluded from this release type: setIsPointing */
+    private _isRightPointing;
+    /**
+     * Whether the user is right-click pointing (before drag threshold).
+     */
+    getIsRightPointing(): boolean;
+    /* Excluded from this release type: setIsRightPointing */
     private _isPinching;
     /**
      * Whether the user is pinching.
@@ -5152,19 +5544,286 @@ export declare function openWindow(url: string, target?: string, allowReferrer?:
 /** @public */
 export declare type OptionalKeys<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
 
-/**
- * Parses a string created by {@link createDeepLinkString} back into a deep link descriptor.
- *
- * @param deepLinkString - the deep link string
- * @returns a deep link descriptor
- *
- * @public
- */
-export declare function parseDeepLinkString(deepLinkString: string): TLDeepLink;
+/** @public */
+export declare class OverlayManager {
+    readonly editor: Editor;
+    constructor(editor: Editor);
+    /* Excluded from this release type: _overlayUtils */
+    /* Excluded from this release type: registerUtil */
+    /**
+     * Get an overlay util by type string, overlay instance, or by passing
+     * a util class as a generic parameter for type-safe lookup.
+     *
+     * @example
+     * ```ts
+     * const util = editor.overlays.getOverlayUtil('brush')
+     * const util = editor.overlays.getOverlayUtil<BrushOverlayUtil>('brush')
+     * const util = editor.overlays.getOverlayUtil(myOverlay)
+     * ```
+     *
+     * @public
+     */
+    getOverlayUtil<T extends OverlayUtil>(type: T extends OverlayUtil<infer O> ? O['type'] : string): T;
+    getOverlayUtil<O extends TLOverlay>(overlay: O): OverlayUtil<O>;
+    /**
+     * Returns all registered overlay utils in paint order (ascending zIndex).
+     * Utils with the same zIndex preserve their registration order.
+     *
+     * @public
+     */
+    getOverlayUtilsInZOrder(): OverlayUtil[];
+    /**
+     * Reactive list of active overlay utils paired with the overlays they
+     * produced for the current editor state, in paint order (ascending
+     * zIndex). Both the hit-test and render paths read from this single
+     * cached scan instead of each re-deriving the active set. Active utils
+     * are included even when their `getOverlays()` returns an empty array,
+     * since `render()` may still draw non-interactive UI (e.g. the selection
+     * bounding box during brushing).
+     *
+     * @public
+     */
+    getActiveOverlayEntries(): TLOverlayEntry[];
+    /**
+     * Reactively computed list of all currently active overlays, in paint order.
+     * @public
+     */
+    getCurrentOverlays(): TLOverlay[];
+    private _geometryCache;
+    /**
+     * Get hit-test geometry for an overlay, cached by overlay identity. Lets
+     * hit-testing on a pointermove storm skip the per-overlay geometry
+     * allocation that {@link OverlayUtil.getGeometry} would otherwise do on
+     * every call.
+     *
+     * @public
+     */
+    getOverlayGeometry(overlay: TLOverlay): Geometry2d | null;
+    /**
+     * The currently hovered overlay id.
+     * @public
+     */
+    private _hoveredOverlayId;
+    getHoveredOverlayId(): null | string;
+    getHoveredOverlay(): null | TLOverlay;
+    setHoveredOverlay(id: null | string): void;
+    /**
+     * Hit test all active overlays at a given page point.
+     * Returns the topmost overlay whose geometry contains the point, or null.
+     * Utils are walked from highest zIndex to lowest so the overlay painted on
+     * top also wins the hit test. Within a util, overlays are walked in
+     * array order: the first overlay whose geometry contains the point wins,
+     * so utils should place highest-priority overlays first in `getOverlays`.
+     * Interactive overlays (those with geometry) are checked; non-interactive are skipped.
+     *
+     * @param point - Point in page coordinates
+     * @param margin - Hit test margin
+     * @public
+     */
+    getOverlayAtPoint(point: VecLike, margin?: number): null | TLOverlay;
+}
+
+/** @public */
+export declare interface OverlayOptionsWithDisplayValues<Overlay extends TLOverlay, DisplayValues extends object> {
+    getDefaultDisplayValues(editor: Editor, overlay: Overlay, theme: TLTheme, colorMode: 'dark' | 'light'): DisplayValues;
+    getCustomDisplayValues(editor: Editor, overlay: Overlay, theme: TLTheme, colorMode: 'dark' | 'light'): Partial<DisplayValues>;
+}
+
+/**
+ * Base class for overlay utilities. Overlays are ephemeral UI elements rendered
+ * on top of the canvas (selection handles, rotation corners, shape handles, etc.).
+ *
+ * Each OverlayUtil defines a type of overlay and knows how to:
+ * - Determine when its overlays should be active (predicate)
+ * - Produce overlay instances from current editor state
+ * - Provide hit-test geometry for interactive overlays
+ * - Provide cursor style on hover
+ * - Render into a canvas 2D context
+ *
+ * @public
+ */
+export declare abstract class OverlayUtil<T extends TLOverlay = TLOverlay> {
+    editor: Editor;
+    constructor(editor: Editor);
+    static type: string;
+    /**
+     * Options for this overlay util. Override this to provide customization options.
+     * Use {@link OverlayUtil.configure} to customize existing overlay utils.
+     *
+     * `zIndex` controls paint and hit-test order across utils — higher numbers
+     * paint on top and are hit-tested first. Ties resolve by registration order.
+     * Defaults to `0`; built-in utils use larger integers (100, 200, …) with
+     * gaps so custom utils can slot between.
+     *
+     * @public
+     */
+    options: {
+        zIndex?: number;
+    };
+    /**
+     * Create a new overlay util class with the given options merged in.
+     *
+     * @example
+     * ```ts
+     * const MyBrush = BrushOverlayUtil.configure({ fill: 'rgba(0,0,255,0.1)' })
+     * ```
+     *
+     * @public
+     */
+    static configure<T extends TLOverlayUtilConstructor<any>>(this: T, options: T extends new (...args: any[]) => {
+        options: infer Options;
+    } ? Partial<Options> : never): T;
+    /**
+     * Whether this overlay util's overlays should currently be active.
+     * Checked reactively to determine which overlays exist at any given time.
+     */
+    abstract isActive(): boolean;
+    /**
+     * Returns the overlay instances that currently exist.
+     * Called only when `isActive()` returns true.
+     */
+    abstract getOverlays(): T[];
+    /**
+     * Returns hit-test geometry for an overlay instance, in page coordinates.
+     * Return null for non-interactive overlays (e.g. snap indicators, scribbles).
+     */
+    getGeometry(_overlay: T): Geometry2d | null;
+    /**
+     * Returns the cursor type to show when hovering this overlay.
+     */
+    getCursor(_overlay: T): TLCursorType | undefined;
+    /**
+     * Called when the user points down on this overlay, before the default
+     * routing runs. Acts as an interrupt: define it to take over the event.
+     *
+     * Return `false` to continue with the default behavior (e.g. the
+     * built-in rotate/resize handle transitions or shape-handle dispatch).
+     * Return `true` — or nothing at all — to skip the default. In other
+     * words, once you override this method you own the event unless you
+     * explicitly opt back in by returning `false`.
+     */
+    onPointerDown?(overlay: T, info: TLPointerEventInfo): boolean | void;
+    /**
+     * Render all active overlays into the canvas context.
+     * The context is already transformed to page space (camera transform applied).
+     * Called reactively when overlays or editor state changes.
+     */
+    render(_ctx: CanvasRenderingContext2D, _overlays: T[]): void;
+    /**
+     * Optional: render all active overlays into the minimap canvas.
+     * The context is already transformed to page space (minimap camera applied),
+     * so overlays can use the same page-space coordinates as in {@link OverlayUtil.render}.
+     *
+     * `zoom` is the minimap's screen-pixels-per-page-unit, analogous to
+     * `editor.getCamera().z`; use `1 / zoom` for one-minimap-pixel line widths.
+     *
+     * Most overlays should leave this blank — only overlays that are meaningful
+     * at minimap scale (e.g. brushes, collaborator cursors) should opt in.
+     */
+    renderMinimap(_ctx: CanvasRenderingContext2D, _overlays: T[], _zoom: number): void;
+}
+
+/**
+ * Parses a string created by {@link createDeepLinkString} back into a deep link descriptor.
+ *
+ * @param deepLinkString - the deep link string
+ * @returns a deep link descriptor
+ *
+ * @public
+ */
+export declare function parseDeepLinkString(deepLinkString: string): TLDeepLink;
 
 /** @public */
 export declare type PerfectDashTerminal = 'none' | 'outset' | 'skip';
 
+/**
+ * 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 declare class PerformanceApiAdapter {
+    private cleanups;
+    constructor(perfManager: PerformanceManager);
+    /** Remove all listeners and stop piping events. @public */
+    dispose(): void;
+}
+
+/**
+ * Manages performance event subscriptions for the editor. Available as `editor.performance`.
+ *
+ * Listeners are lazy — internal editor hooks (frame, shape events) are only attached while
+ * at least one subscriber exists, so there is zero overhead when unused.
+ *
+ * @example
+ * ```ts
+ * const unsub = editor.performance.on('interaction-end', (event) => {
+ *   console.log(`${event.name}: ${event.fps.toFixed(1)} fps, p95=${event.p95FrameTime.toFixed(1)}ms`)
+ * })
+ * ```
+ *
+ * @public
+ */
+export declare class PerformanceManager {
+    /* Excluded from this release type: emitter */
+    private editor;
+    private activeInteraction;
+    private activeCamera;
+    private frameCleanup;
+    private shapeCreatedCleanup;
+    private shapeEditedCleanup;
+    private shapeDeletedCleanup;
+    private loafObserver;
+    constructor(editor: Editor);
+    /**
+     * Subscribe to a performance event. Returns an unsubscribe function.
+     *
+     * @example
+     * ```ts
+     * const unsub = editor.performance.on('interaction-end', (event) => {
+     *   sendToAnalytics({ name: event.name, fps: event.fps, p95: event.p95FrameTime })
+     * })
+     * // later: unsub()
+     * ```
+     *
+     * @public
+     */
+    on<K extends keyof TLPerfEventMap>(event: K, fn: (...args: TLPerfEventMap[K]) => void): () => void;
+    /**
+     * Subscribe to a performance event once. The listener is removed after the first invocation.
+     * Returns an unsubscribe function for early removal.
+     *
+     * @public
+     */
+    once<K extends keyof TLPerfEventMap>(event: K, fn: (...args: TLPerfEventMap[K]) => void): () => void;
+    /* Excluded from this release type: dispose */
+    /* Excluded from this release type: _notifyInteractionStart */
+    /* Excluded from this release type: _notifyInteractionEnd */
+    /* Excluded from this release type: _notifyCameraOperation */
+    /* Excluded from this release type: _notifyUndoRedo */
+    private _startCameraSession;
+    private _endCameraSession;
+    private _onFrame;
+    private _onShapesCreated;
+    private _onShapesEdited;
+    private _onShapesDeleted;
+    private _startLoafObserver;
+    private _stopLoafObserver;
+    private _needsFrameListener;
+    private _needsLoafObserver;
+    private _maybeAttachLazyListeners;
+    private _maybeDetachLazyListeners;
+}
+
 /**
  * Find the approximate perimeter of an ellipse.
  *
@@ -5359,6 +6018,16 @@ export declare function resizeScaled(shape: TLBaseShape<any, {
     y: number;
 };
 
+/**
+ * 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 declare function resolveThemes(themes?: Partial<TLThemes>): TLThemes;
+
 /** @public */
 export declare type RichTextFontVisitor = (node: TiptapNode, state: RichTextFontVisitorState, addFont: (font: TLFontFace) => void) => RichTextFontVisitorState;
 
@@ -5586,6 +6255,32 @@ export declare function setRuntimeOverrides(input: Partial<typeof runtime>): voi
 /** @public */
 export declare function setUserPreferences(user: TLUserPreferences): void;
 
+/**
+ * Overlay util for shape indicators — the selection / hover / hint outlines drawn
+ * under the selection foreground. Paints local indicators in the theme's
+ * selection color.
+ *
+ * Remote collaborator selection indicators are drawn by a separate overlay util
+ * (e.g. `CollaboratorShapeIndicatorOverlayUtil` from `tldraw`) that runs at a
+ * lower z-index so peer selections appear under the local indicators.
+ *
+ * Non-interactive: contributes no hit-test geometry.
+ *
+ * @public
+ */
+export declare class ShapeIndicatorOverlayUtil extends OverlayUtil<TLShapeIndicatorOverlay> {
+    static type: string;
+    options: {
+        hintedLineWidth: number;
+        lineWidth: number;
+        zIndex: number;
+    };
+    private _instanceFlags$;
+    isActive(): boolean;
+    getOverlays(): TLShapeIndicatorOverlay[];
+    render(ctx: CanvasRenderingContext2D, overlays: TLShapeIndicatorOverlay[]): void;
+}
+
 /** @public */
 export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
     editor: Editor;
@@ -5640,12 +6335,32 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
      * @public
      */
     static type: string;
+    /**
+     * The asset types that this shape can be created from.
+     * When a file is dropped on the canvas, the editor finds the shape util
+     * whose `handledAssetTypes` includes the asset's type and calls
+     * {@link ShapeUtil.createShapeForAsset} to produce the shape.
+     *
+     * @public
+     */
+    static handledAssetTypes?: readonly string[];
     /**
      * Get the default props for a shape.
      *
      * @public
      */
     abstract getDefaultProps(): Shape['props'];
+    /**
+     * Create a shape partial for placing an asset on the canvas.
+     * Only called for shapes whose constructor declares matching
+     * {@link ShapeUtil.handledAssetTypes | `handledAssetTypes`}.
+     *
+     * @param asset - The asset to create a shape for.
+     * @param position - Where to place the shape.
+     * @returns A shape partial, or null if this shape can't be created for the asset.
+     * @public
+     */
+    createShapeForAsset?(asset: TLAsset, position: VecModel): null | TLShapePartial;
     /**
      * Get the shape's geometry.
      *
@@ -5662,37 +6377,30 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
      */
     abstract component(shape: Shape): any;
     /**
-     * Get JSX describing the shape's indicator (as an SVG element).
+     * Get a Path2D (or a richer object with clip/additional paths) for rendering the
+     * shape's indicator on the canvas. Shapes that return `undefined` will not render
+     * an indicator.
      *
-     * @param shape - The shape.
-     * @public
-     */
-    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.
+     * For complex indicators that need clipping (e.g., arrows with labels), return an
+     * object with `path`, `clipPath`, and `additionalPaths` properties.
      *
-     * @returns `true` to use SVG indicators (default), `false` to use canvas indicators.
+     * @param shape - The shape.
+     * @returns A Path2D to stroke, or an object with clipping info, or undefined to skip.
      * @public
      */
-    useLegacyIndicator(): boolean;
+    abstract getIndicatorPath(shape: Shape): TLIndicatorPath | undefined;
     /**
-     * Get a Path2D for rendering the shape's indicator on the canvas.
+     * Get JSX describing the shape's indicator (as an SVG element).
      *
-     * 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.
+     * @deprecated SVG indicators are no longer rendered. Override
+     * {@link ShapeUtil.getIndicatorPath} instead. This stub is retained so legacy
+     * subclasses that still call `super.indicator()` keep type-checking; new shapes
+     * should not implement it.
      *
      * @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;
+    indicator(_shape: Shape): any;
     /**
      * Get the font faces that should be rendered in the document in order for this shape to render
      * correctly.
@@ -5726,7 +6434,7 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
      *
      * @public
      */
-    canBind(_opts: TLShapeUtilCanBindOpts): boolean;
+    canBind(opts: TLShapeUtilCanBindOpts): boolean;
     /**
      * Whether the shape can be double clicked to edit.
      *
@@ -5860,6 +6568,14 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
      * @public
      */
     isAspectRatioLocked(shape: Shape): boolean;
+    /**
+     * Whether the shape behaves like a frame — a container that has child shapes,
+     * requires full-brush selection, blocks erasure from inside, etc.
+     *
+     * @param shape - The shape.
+     * @public
+     */
+    isFrameLike(_shape: Shape): boolean;
     /**
      * By default, the bounds of an image export are the bounds of all the shapes it contains, plus
      * some padding. If an export includes a shape where `isExportBoundsContainer` is true, then the
@@ -5901,13 +6617,28 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
      */
     getHandles?(shape: Shape): TLHandle[];
     /**
-     * Get whether the shape can receive children of a given type.
+     * Get whether the shape can receive children of a given type. Used by the drag and drop system
+     * to decide whether {@link ShapeUtil.onDragShapesIn} should fire when a shape of the given type
+     * is dragged over this one.
      *
      * @param shape - The shape.
      * @param type - The shape type.
      * @public
      */
-    canReceiveNewChildrenOfType(shape: Shape, _type: TLShape['type']): boolean;
+    canReceiveNewChildrenOfType(shape: Shape, type: TLShape['type']): boolean;
+    /**
+     * Get whether children of a given type can be removed from this shape. Used by the drag and
+     * drop system to decide whether {@link ShapeUtil.onDragShapesOut} should fire when a child of
+     * the given type is dragged out of this shape, and by `kickoutOccludedShapes` to decide
+     * whether to auto-reparent a child of the given type when it has moved outside this shape's
+     * geometry. Returning `false` therefore "pins" matching children — they stay parented to this
+     * shape even when dragged or moved outside it. Defaults to `true`.
+     *
+     * @param shape - The shape.
+     * @param type - The shape type.
+     * @public
+     */
+    canRemoveChildrenOfType(shape: Shape, type: TLShape['type']): boolean;
     /**
      * Get the shape as an SVG object.
      *
@@ -5947,6 +6678,14 @@ export declare abstract class ShapeUtil<Shape extends TLShape = TLShape> {
      */
     getHandleSnapGeometry(shape: Shape): HandleSnapGeometry;
     getText(shape: Shape): string | undefined;
+    /**
+     * Return user IDs referenced in shape-specific props.
+     * Used when copying shapes to include referenced users on the clipboard.
+     * Override this if your shape stores user IDs in custom props.
+     *
+     * @public
+     */
+    getReferencedUserIds(shape: Shape): string[];
     getAriaDescriptor(shape: Shape): string | undefined;
     /**
      * A callback called just before a shape is created. This method provides a last chance to modify
@@ -6342,6 +7081,8 @@ export declare abstract class StateNode implements Partial<TLEventHandlers> {
     static children?: () => TLStateNodeConstructor[];
     static isLockable: boolean;
     static useCoalescedEvents: boolean;
+    /** Set to `true` in subclasses to emit interaction-start/end performance events when this state is entered/exited. */
+    static trackPerformance: boolean;
     id: string;
     type: 'branch' | 'leaf' | 'root';
     shapeType?: string;
@@ -6441,6 +7182,19 @@ export declare const stopEventPropagation: (e: any) => any;
 
 /* Excluded from this release type: StoreName */
 
+/**
+ * Combine every batchable shape indicator into a single page-space `Path2D` and
+ * emit one stroke call. Shapes whose indicator needs an evenodd clip (e.g.
+ * arrows with labels or complex arrowheads) can't be batched — they still
+ * stroke individually inside a save/restore with `ctx.clip` applied.
+ *
+ * Shared by {@link ShapeIndicatorOverlayUtil} and any overlay util that paints
+ * shape indicators (e.g. collaborator selections).
+ *
+ * @public
+ */
+export declare function strokeShapeIndicators(editor: Editor, ctx: CanvasRenderingContext2D, shapeIds: TLShapeId[]): void;
+
 /** @public */
 export declare function suffixSafeId(id: SafeId, suffix: string): SafeId;
 
@@ -6476,6 +7230,10 @@ export declare interface SvgExportContext {
      * Whether the export should be in dark mode.
      */
     readonly isDarkMode: boolean;
+    /**
+     * The color mode to use for this export.
+     */
+    readonly colorMode: 'dark' | 'light';
     /**
      * The scale of the export - how much CSS pixels will be scaled up/down by.
      */
@@ -6507,15 +7265,18 @@ export declare const TAB_ID: string;
 export declare class TextManager {
     editor: Editor;
     private elm;
+    private poolElms;
     constructor(editor: Editor);
+    private createMeasurementEl;
+    private resetElementStyles;
     private setElementStyles;
+    private getMeasureStyles;
     dispose(): void;
-    measureText(textToMeasure: string, opts: TLMeasureTextOpts): BoxModel & {
-        scrollWidth: number;
-    };
-    measureHtml(html: string, opts: TLMeasureTextOpts): BoxModel & {
-        scrollWidth: number;
-    };
+    private ensurePoolSize;
+    private getPoolItem;
+    measureHtmlBatch(requests: BatchMeasurementRequest[]): TLMeasuredTextSize[];
+    measureText(textToMeasure: string, opts: TLMeasureTextOpts): TLMeasuredTextSize;
+    measureHtml(html: string, opts: TLMeasureTextOpts): TLMeasuredTextSize;
     /**
      * Given an html element, measure the position of each span of unbroken
      * word/white-space characters within any text nodes it contains.
@@ -6543,6 +7304,47 @@ export declare class TextManager {
     }[];
 }
 
+/**
+ * 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 declare class ThemeManager {
+    private readonly editor;
+    private readonly _themes;
+    private readonly _currentThemeId;
+    constructor(editor: Editor, options: {
+        initial: TLThemeId;
+        themes: TLThemes;
+    });
+    /** Get the current color mode based on the user's dark mode preference. */
+    getColorMode(): 'dark' | 'light';
+    /** Get all registered theme definitions. */
+    getThemes(): TLThemes;
+    /** Get a single theme definition by id. */
+    getTheme(id: TLThemeId): TLTheme | undefined;
+    /** Get the id of the current theme. */
+    getCurrentThemeId(): TLThemeId;
+    getCurrentTheme(): TLTheme;
+    /** Set the current theme by id. The theme must have been previously registered. */
+    setCurrentTheme(id: TLThemeId): void;
+    /** Replace all theme definitions, or update them via a callback that receives a deep copy. */
+    updateThemes(themes: ((themes: TLThemes) => TLThemes) | TLThemes): void;
+    /** Register or update a named theme definition. */
+    updateTheme(theme: TLTheme): void;
+    /** Clean up any resources held by the manager. */
+    dispose(): void;
+}
+
 /* Excluded from this release type: TickManager */
 
 /**
@@ -6561,12 +7363,26 @@ export declare type TiptapNode = Node_2;
 /** @public */
 export declare type TLAdjacentDirection = 'down' | 'left' | 'next' | 'prev' | 'right' | 'up';
 
+/** @public */
+export declare type TLAnyAssetUtilConstructor = TLAssetUtilConstructor<any>;
+
 /** @public */
 export declare type TLAnyBindingUtilConstructor = TLBindingUtilConstructor<any>;
 
+/** @public */
+export declare type TLAnyOverlayUtilConstructor = TLOverlayUtilConstructor<any>;
+
 /** @public */
 export declare type TLAnyShapeUtilConstructor = TLShapeUtilConstructor<any>;
 
+/** @public */
+export declare interface TLAssetUtilConstructor<T extends TLAsset = TLAsset, U extends AssetUtil<T> = AssetUtil<T>> {
+    new (editor: Editor): U;
+    type: T['type'];
+    props?: RecordProps<T>;
+    migrations?: LegacyMigrations | MigrationSequence | TLPropsMigrations;
+}
+
 /** @public */
 export declare type TLBaseBoxShape = ExtractShapeByProps<{
     h: number;
@@ -6599,15 +7415,6 @@ export declare interface TLBindingUtilConstructor<T extends TLBinding, U extends
     migrations?: TLPropsMigrations;
 }
 
-/** @public */
-export declare interface TLBrushProps {
-    userId?: string;
-    brush: BoxModel;
-    color?: string;
-    opacity?: number;
-    className?: string;
-}
-
 /** @public */
 export declare interface TLCameraConstraints {
     /** The bounds (in page space) of the constrained space */
@@ -6656,6 +7463,29 @@ export declare interface TLCameraConstraints {
     };
 }
 
+/**
+ * Emitted when a camera operation ends (after a 50ms debounce), with aggregated frame time stats.
+ * @public
+ */
+export declare 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;
+}
+
 /** @public */
 export declare interface TLCameraMoveOptions {
     /** Whether to move the camera immediately, rather than on the next tick. */
@@ -6694,6 +7524,17 @@ export declare interface TLCameraOptions {
     constraints?: TLCameraConstraints;
 }
 
+/**
+ * Emitted when a camera operation (pan or zoom) begins.
+ * @public
+ */
+export declare interface TLCameraStartPerfEvent {
+    /** Whether this is a pan or zoom operation. */
+    type: 'panning' | 'zooming';
+    /** `performance.now()` when the camera session started. */
+    timestamp: number;
+}
+
 /** @public */
 export declare type TLCancelEvent = (info: TLCancelEventInfo) => void;
 
@@ -6727,15 +7568,38 @@ export declare type TLCLickEventName = 'double_click' | 'quadruple_click' | 'tri
 /** @public */
 export declare type TLClickState = 'idle' | 'overflow' | 'pendingDouble' | 'pendingOverflow' | 'pendingQuadruple' | 'pendingTriple';
 
-/** @public */
-export declare interface TLCollaboratorHintProps {
-    userId: string;
-    className?: string;
-    point: VecModel;
-    viewport: Box;
-    zoom: number;
-    opacity?: number;
-    color: string;
+/**
+ * Raw clipboard paste payload, before tldraw parses clipboard contents into {@link TLExternalContent}.
+ *
+ * - `native-event`: from the `paste` event — `clipboardData` is available synchronously (unlike async
+ *   `navigator.clipboard.read()`).
+ * - `clipboard-read`: from an explicit `navigator.clipboard.read()` call — only `ClipboardItem[]`
+ *   exists
+ *   (no `DataTransfer`).
+ *
+ * @public
+ */
+export declare type TLClipboardPasteRawInfo = {
+    readonly clipboardData: DataTransfer | null;
+    readonly editor: Editor;
+    readonly event: ClipboardEvent;
+    readonly point: undefined | VecLike;
+    readonly source: 'native-event';
+} | {
+    readonly clipboardItems: readonly ClipboardItem[];
+    readonly editor: Editor;
+    readonly point: undefined | VecLike;
+    readonly source: 'clipboard-read';
+};
+
+/**
+ * Identifies how a clipboard write was triggered (copy vs cut, keyboard vs menu).
+ *
+ * @public
+ */
+export declare interface TLClipboardWriteInfo {
+    readonly operation: 'copy' | 'cut';
+    readonly source: 'menu' | 'native';
 }
 
 /** @public */
@@ -6754,6 +7618,7 @@ export declare interface TLContent {
     rootShapeIds: TLShapeId[];
     assets: TLAsset[];
     schema: SerializedSchema;
+    users?: TLUser[];
 }
 
 /**
@@ -6776,14 +7641,9 @@ export declare interface TLCropInfo<T extends TLShape> {
 }
 
 /** @public */
-export declare interface TLCursorProps {
-    userId: string;
-    className?: string;
-    point: null | VecModel;
-    zoom: number;
-    color?: string;
-    name: null | string;
-    chatMessage: string;
+export declare interface TLCurrentUser {
+    readonly userPreferences: Signal<TLUserPreferences>;
+    readonly setUserPreferences: (userPreferences: TLUserPreferences) => void;
 }
 
 /** @public */
@@ -6875,6 +7735,14 @@ export declare interface TldrawEditorBaseProps {
      * An array of binding utils to use in the editor.
      */
     bindingUtils?: readonly TLAnyBindingUtilConstructor[];
+    /**
+     * An array of asset utils to use in the editor.
+     */
+    assetUtils?: readonly TLAnyAssetUtilConstructor[];
+    /**
+     * An array of overlay utils to use in the editor for canvas overlay UI elements.
+     */
+    overlayUtils?: readonly TLAnyOverlayUtilConstructor[];
     /**
      * An array of tools to add to the editor's state chart.
      */
@@ -6902,11 +7770,23 @@ export declare interface TldrawEditorBaseProps {
     /**
      * The user interacting with the editor.
      */
-    user?: TLUser;
+    user?: TLCurrentUser;
+    /**
+     * 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.
+     */
+    colorScheme?: 'dark' | 'light' | 'system';
+    /**
+     * Named themes for the editor.
+     */
+    themes?: Partial<TLThemes>;
     /**
-     * Whether to infer dark mode from the user's OS. Defaults to false.
+     * The id of the initially active theme. Defaults to `'default'`.
      */
-    inferDarkMode?: boolean;
+    initialTheme?: TLThemeId;
     /**
      * Camera options for the editor.
      *
@@ -7124,6 +8004,12 @@ export declare interface TldrawOptions {
      * When false, the spacebar will not pan the camera.
      */
     readonly spacebarPanning: boolean;
+    /**
+     * Whether to allow right-click + drag to pan the camera. When true, right-click + drag pans the
+     * camera and a static right-click opens the context menu at the release position. When false,
+     * right-click opens the context menu on press (no drag-to-pan).
+     */
+    readonly rightClickPanning: boolean;
     /**
      * The default padding (in pixels) used when zooming to fit content in the viewport.
      * This affects methods like `zoomToFit()`, `zoomToSelection()`, and `zoomToBounds()`.
@@ -7166,6 +8052,72 @@ export declare interface TldrawOptions {
      * viewport's page dimensions regardless of overview zoom changes.
      */
     readonly quickZoomPreservesScreenBounds: boolean;
+    /**
+     * Called before content is written to the clipboard during a copy or cut operation.
+     * Receives the serialized content (shapes, bindings, assets) and can filter or transform
+     * it before it reaches the clipboard.
+     *
+     * Return a modified `TLContent` object to change what is copied or cut. Return `false` to
+     * cancel the clipboard write (for cut, the selected shapes are not removed). Return `void`
+     * (or `undefined`) to pass through unchanged. You may return a `Promise` of those values if
+     * the hook is async.
+     *
+     * @example
+     * ```tsx
+     * // Filter out "locked" shapes from copy
+     * onBeforeCopyToClipboard({ content, operation }) {
+     *     return {
+     *         ...content,
+     *         shapes: content.shapes.filter(s => !s.meta.locked),
+     *         rootShapeIds: content.rootShapeIds.filter(id =>
+     *             content.shapes.find(s => s.id === id && !s.meta.locked)
+     *         ),
+     *     }
+     * }
+     * ```
+     */
+    onBeforeCopyToClipboard?(info: {
+        content: TLContent;
+        editor: Editor;
+    } & TLClipboardWriteInfo): Awaitable<false | TLContent | void>;
+    /**
+     * Called before pasted content is processed and shapes are created. Receives the parsed
+     * external content from the clipboard and can filter, transform, or cancel it.
+     *
+     * Return `false` to cancel the paste. Return a modified content object to transform it.
+     * Return `void` (or `undefined`) to pass through unchanged. You may return a `Promise` of
+     * those values if the hook is async.
+     *
+     * This only fires for clipboard paste operations (keyboard shortcuts and menu actions),
+     * not for file drops or programmatic `putExternalContent` calls.
+     *
+     * @example
+     * ```tsx
+     * // Block pasting of image files
+     * onBeforePasteFromClipboard({ content }) {
+     *     if (content.type === 'files') {
+     *         const nonImages = content.files.filter(f => !f.type.startsWith('image/'))
+     *         if (nonImages.length === 0) return false
+     *         return { ...content, files: nonImages }
+     *     }
+     * }
+     * ```
+     */
+    onBeforePasteFromClipboard?(info: {
+        content: TLExternalContent<unknown>;
+        editor: Editor;
+        point?: VecLike;
+        source: 'clipboard-read' | 'native-event';
+    }): Awaitable<false | TLExternalContent<unknown> | void>;
+    /**
+     * Called first for keyboard and menu paste, **before** tldraw handles or parses clipboard data
+     * (and before {@link TldrawOptions.onBeforePasteFromClipboard}).
+     *
+     * Return `false` to cancel tldraw's default paste handling for this gesture (same convention as
+     * {@link TldrawOptions.onBeforePasteFromClipboard}). Use this when you handle paste yourself from
+     * raw clipboard data, or to block the gesture entirely. Return `void` (or `undefined`) to continue.
+     */
+    onClipboardPasteRaw?(info: TLClipboardPasteRawInfo): false | void;
     /**
      * Called when content is dropped on the canvas. Provides the page position
      * where the drop occurred and the underlying drag event object.
@@ -7187,34 +8139,17 @@ export declare interface TLDropShapesOverInfo {
 /** @public */
 export declare interface TLEditorComponents {
     Background?: ComponentType | null;
-    Brush?: ComponentType<TLBrushProps> | null;
     Canvas?: ComponentType<TLCanvasComponentProps> | null;
-    CollaboratorBrush?: ComponentType<TLBrushProps> | null;
-    CollaboratorCursor?: ComponentType<TLCursorProps> | null;
-    CollaboratorHint?: ComponentType<TLCollaboratorHintProps> | null;
-    CollaboratorScribble?: ComponentType<TLScribbleProps> | null;
-    CollaboratorShapeIndicator?: ComponentType<TLShapeIndicatorProps> | null;
-    Cursor?: ComponentType<TLCursorProps> | null;
     Grid?: ComponentType<TLGridProps> | null;
-    Handle?: ComponentType<TLHandleProps> | null;
-    Handles?: ComponentType<TLHandlesProps> | null;
     InFrontOfTheCanvas?: ComponentType | null;
     LoadingScreen?: ComponentType | null;
     OnTheCanvas?: ComponentType | null;
-    Overlays?: ComponentType | null;
-    Scribble?: ComponentType<TLScribbleProps> | null;
     SelectionBackground?: ComponentType<TLSelectionBackgroundProps> | null;
-    SelectionForeground?: ComponentType<TLSelectionForegroundProps> | null;
-    ShapeIndicator?: ComponentType<TLShapeIndicatorProps> | null;
-    ShapeIndicators?: ComponentType | null;
     ShapeWrapper?: ComponentType<TLShapeWrapperProps & RefAttributes<HTMLDivElement>> | null;
-    SnapIndicator?: ComponentType<TLSnapIndicatorProps> | null;
     Spinner?: ComponentType<React.SVGProps<SVGSVGElement>> | null;
     SvgDefs?: ComponentType | null;
-    ZoomBrush?: ComponentType<TLBrushProps> | null;
     ErrorFallback?: TLErrorFallbackComponent;
     ShapeErrorFallback?: TLShapeErrorFallbackComponent;
-    ShapeIndicatorErrorFallback?: TLShapeIndicatorErrorFallbackComponent;
 }
 
 /** @public */
@@ -7233,18 +8168,22 @@ export declare interface TLEditorOptions {
      */
     bindingUtils: readonly TLAnyBindingUtilConstructor[];
     /**
-     * An array of tools to use in the editor. These will be used to handle events and manage user interactions in the editor.
+     * An array of asset utils to use in the editor. These will be used to handle asset-type-specific behavior.
      */
-    tools: readonly TLStateNodeConstructor[];
+    assetUtils?: readonly TLAnyAssetUtilConstructor[];
     /**
-     * Should return a containing html element which has all the styles applied to the editor. If not
-     * given, the body element will be used.
+     * An array of overlay utils to use in the editor. These define canvas overlay UI elements
+     * like selection handles, rotation corners, shape handles, etc.
      */
-    getContainer(): HTMLElement;
+    overlayUtils?: readonly TLAnyOverlayUtilConstructor[];
+    /**
+     * An array of tools to use in the editor. These will be used to handle events and manage user interactions in the editor.
+     */
+    tools: readonly TLStateNodeConstructor[];
     /**
      * A user defined externally to replace the default user.
      */
-    user?: TLUser;
+    user?: TLCurrentUser;
     /**
      * The editor's initial active tool (or other state node id).
      */
@@ -7253,27 +8192,15 @@ export declare interface TLEditorOptions {
      * Whether to automatically focus the editor when it mounts.
      */
     autoFocus?: boolean;
-    /**
-     * Whether to infer dark mode from the user's system preferences. Defaults to false.
-     */
-    inferDarkMode?: boolean;
-    /**
-     * Options for the editor's camera.
-     *
-     * @deprecated Use `options.cameraOptions` instead. This will be removed in a future release.
-     */
-    cameraOptions?: Partial<TLCameraOptions>;
-    options?: Partial<TldrawOptions>;
-    /**
-     * Text options for the editor.
-     *
-     * @deprecated Use `options.text` instead. This prop will be removed in a future release.
-     */
-    textOptions?: TLTextOptions;
     licenseKey?: string;
     fontAssetUrls?: {
         [key: string]: string | undefined;
     };
+    /**
+     * Should return a containing html element which has all the styles applied to the editor. If not
+     * given, the body element will be used.
+     */
+    getContainer(): HTMLElement;
     /**
      * Provides a way to hide shapes.
      *
@@ -7290,6 +8217,40 @@ export declare interface TLEditorOptions {
      * @param editor - The editor instance.
      */
     getShapeVisibility?(shape: TLShape, editor: Editor): 'hidden' | 'inherit' | 'visible' | null | undefined;
+    /**
+     * Named theme definitions for the editor. Each theme contains shared
+     * properties (font size, line height, stroke width) and color palettes
+     * for both light and dark modes.
+     */
+    themes?: Partial<TLThemes>;
+    /**
+     * The id of the initially active theme. Defaults to `'default'`.
+     */
+    initialTheme?: TLThemeId;
+    /**
+     * The editor's color scheme preference, controls the default color mode. Defaults to `'light'`.
+     *
+     * - `'light'` - Always use light mode.
+     * - `'dark'` - Always use dark mode.
+     * - `'system'` - Follow the OS color scheme preference.
+     */
+    colorScheme?: 'dark' | 'light' | 'system';
+    /**
+     * Additional configuration options for the tldraw editor.
+     */
+    options?: Partial<TldrawOptions>;
+    /**
+     * Options for the editor's camera.
+     *
+     * @deprecated Use `options.cameraOptions` instead. This will be removed in a future release.
+     */
+    cameraOptions?: Partial<TLCameraOptions>;
+    /**
+     * Text options for the editor.
+     *
+     * @deprecated Use `options.text` instead. This prop will be removed in a future release.
+     */
+    textOptions?: TLTextOptions;
 }
 
 /**
@@ -7348,6 +8309,7 @@ export declare const tlenv: {
  */
 export declare const tlenvReactive: Atom<    {
 isCoarsePointer: boolean;
+supportsP3ColorSpace: boolean;
 }, unknown>;
 
 /** @public */
@@ -7476,6 +8438,7 @@ export declare interface TLFileReplaceExternalContent extends TLBaseExternalCont
     type: 'file-replace';
     file: File;
     shapeId: TLShapeId;
+    /** @deprecated This field is no longer used by the default handler. It may be removed in a future version. */
     isImage: boolean;
 }
 
@@ -7487,69 +8450,18 @@ export declare interface TLFilesExternalContent extends TLBaseExternalContent {
 }
 
 /**
- * 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}.
+ * Emitted every animation frame when at least one `'frame'` listener is registered.
  * @public
  */
-export declare 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;
-}
-
-/**
- * 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 declare 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;
+export declare 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;
 }
 
 /** Additional options for the {@link ShapeUtil.getGeometry} method.
@@ -7630,20 +8542,6 @@ export declare interface TLHandleDragInfo<T extends TLShape> {
     initial?: T | undefined;
 }
 
-/** @public */
-export declare interface TLHandleProps {
-    shapeId: TLShapeId;
-    handle: TLHandle;
-    zoom: number;
-    isCoarse: boolean;
-    className?: string;
-}
-
-/** @public */
-export declare interface TLHandlesProps {
-    children: ReactNode;
-}
-
 /** @public */
 export declare interface TLHistoryBatchOptions {
     /**
@@ -7694,6 +8592,38 @@ export declare type TLIndicatorPath = {
     path: Path2D;
 } | Path2D;
 
+/**
+ * Emitted when an interaction state is exited, with aggregated frame time stats.
+ * @public
+ */
+export declare 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 an interaction state (e.g. translating, resizing) is entered.
+ * @public
+ */
+export declare 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;
+}
+
 /** @public */
 export declare type TLInterruptEvent = (info: TLInterruptEventInfo) => void;
 
@@ -7743,6 +8673,11 @@ export declare interface TLLoadSnapshotOptions {
     forceOverwriteSessionState?: boolean;
 }
 
+/** @public */
+export declare type TLMeasuredTextSize = BoxModel & {
+    scrollWidth: number;
+};
+
 /** @public */
 export declare interface TLMeasureTextOpts {
     fontStyle: string;
@@ -7936,6 +8871,130 @@ export declare const tlmenus: {
  */
 export declare type TLOnMountHandler = (editor: Editor) => (() => undefined | void) | undefined | void;
 
+/** @public */
+export declare interface TLOverlay<Props = Record<string, unknown>> {
+    /**
+     * Globally unique id for this overlay instance across all overlay utils.
+     * Hit-test and hover lookup key on `id` alone, so utils must namespace their
+     * ids (e.g. `'selection_fg:top_left'`, `'handle:<shapeId>:<handleId>'`) to
+     * avoid colliding with overlays from other utils.
+     */
+    id: string;
+    /** The overlay util type that owns this instance */
+    type: string;
+    /** Arbitrary props for the overlay (handle id, corner name, etc.) */
+    props: Props;
+}
+
+/**
+ * An active overlay util paired with the overlays it produced for the current
+ * editor state. Returned by {@link OverlayManager.getActiveOverlayEntries} so
+ * hit-test, render, and debug paths share a single scan per reactive tick.
+ *
+ * @public
+ */
+export declare interface TLOverlayEntry {
+    util: OverlayUtil;
+    overlays: TLOverlay[];
+}
+
+/** @public */
+export declare interface TLOverlayUtilConstructor<U extends OverlayUtil = OverlayUtil> {
+    new (editor: Editor): U;
+    type: string;
+    configure<T extends TLOverlayUtilConstructor<any>>(this: T, options: T extends new (...args: any[]) => {
+        options: infer Options;
+    } ? Partial<Options> : never): T;
+}
+
+/**
+ * Map of all performance event names to their payload types.
+ * Used with {@link PerformanceManager.on} and {@link PerformanceManager.once}.
+ * @public
+ */
+export declare 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];
+}
+
+/**
+ * Common frame time statistics shared by interaction and camera end events.
+ * @public
+ */
+export declare 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[];
+}
+
+/**
+ * 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 declare 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 declare 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;
+}
+
 /** @public */
 export declare type TLPinchEvent = (info: TLPinchEventInfo) => void;
 
@@ -7975,6 +9034,10 @@ export declare type TLPointerEventTarget = {
     handle?: TLSelectionHandle;
     shape?: undefined;
     target: 'selection';
+} | {
+    overlay: TLOverlay;
+    shape?: undefined;
+    target: 'overlay';
 } | {
     shape: TLShape;
     target: 'shape';
@@ -8045,28 +9108,12 @@ export declare type TLResizeShapeOptions = Partial<{
 
 /* Excluded from this release type: TLRotationSnapshot */
 
-/** @public */
-export declare interface TLScribbleProps {
-    userId?: string;
-    scribble: TLScribble;
-    zoom: number;
-    color?: string;
-    opacity?: number;
-    className?: string;
-}
-
 /** @public */
 export declare interface TLSelectionBackgroundProps {
     bounds: Box;
     rotation: number;
 }
 
-/** @public */
-export declare interface TLSelectionForegroundProps {
-    bounds: Box;
-    rotation: number;
-}
-
 /** @public */
 export declare type TLSelectionHandle = RotateCorner | SelectionCorner | SelectionEdge;
 
@@ -8101,26 +9148,26 @@ export declare type TLShapeErrorFallbackComponent = ComponentType<{
 }>;
 
 /** @public */
-export declare type TLShapeIndicatorErrorFallbackComponent = ComponentType<{
-    error: unknown;
-}>;
-
-/** @public */
-export declare interface TLShapeIndicatorProps {
-    userId?: string;
-    shapeId: TLShapeId;
-    color?: string | undefined;
-    opacity?: number;
-    className?: string;
-    hidden?: boolean;
+export declare interface TLShapeIndicatorOverlay extends TLOverlay {
+    props: {
+        hintingShapeIds: TLShapeId[];
+        idsToDisplay: TLShapeId[];
+    };
 }
 
-/** @public */
-export declare interface TLShapeIndicatorsProps {
-    /** Whether to hide all of the indicators */
-    hideAll?: boolean;
-    /** Whether to show all of the indicators */
-    showAll?: boolean;
+/**
+ * Emitted when shapes are created, updated, or deleted.
+ * @public
+ */
+export declare interface TLShapeOperationPerfEvent {
+    /** The operation type. */
+    operation: 'create' | 'delete' | 'update';
+    /** 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;
 }
 
 /**
@@ -8180,6 +9227,7 @@ export declare interface TLShapeUtilConstructor<T extends TLShape, U extends Sha
     type: T['type'];
     props?: RecordProps<T>;
     migrations?: LegacyMigrations | MigrationSequence | TLPropsMigrations;
+    handledAssetTypes?: readonly string[];
 }
 
 /** @public */
@@ -8192,13 +9240,6 @@ export declare interface TLShapeWrapperProps extends React.HTMLAttributes<HTMLDi
     children: ReactNode;
 }
 
-/** @public */
-export declare interface TLSnapIndicatorProps {
-    className?: string;
-    line: SnapIndicator;
-    zoom: number;
-}
-
 /** @public */
 export declare interface TLStateNodeConstructor {
     new (editor: Editor, parent?: StateNode): StateNode;
@@ -8207,6 +9248,7 @@ export declare interface TLStateNodeConstructor {
     children?(): TLStateNodeConstructor[];
     isLockable: boolean;
     useCoalescedEvents: boolean;
+    trackPerformance: boolean;
 }
 
 /** @public */
@@ -8219,6 +9261,14 @@ export declare interface TLStoreBaseOptions {
     defaultName?: string;
     /** 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;
     /** Called when the store is connected to an {@link @tldraw/editor#Editor}. */
     onMount?(editor: Editor): (() => void) | void;
 }
@@ -8238,6 +9288,7 @@ export declare type TLStoreOptions = TLStoreBaseOptions & {
 
 /** @public */
 export declare type TLStoreSchemaOptions = {
+    assetUtils?: readonly TLAnyAssetUtilConstructor[];
     bindingUtils?: readonly TLAnyBindingUtilConstructor[];
     migrations?: readonly MigrationSequence[];
     records?: Record<string, CustomRecordInfo>;
@@ -8375,6 +9426,19 @@ export declare interface TLTldrawExternalContentSource {
     data: TLContent;
 }
 
+/**
+ * Emitted after an undo or redo operation.
+ * @public
+ */
+export declare interface TLUndoRedoPerfEvent {
+    /** Whether this was an undo or redo. */
+    type: 'redo' | 'undo';
+    /** Number of undo steps remaining. */
+    undoDepth: number;
+    /** Number of redo steps remaining. */
+    redoDepth: number;
+}
+
 /** @public */
 export declare interface TLUpdatePointerOptions {
     /** Whether to update the pointer immediately, rather than on the next tick. */
@@ -8406,12 +9470,6 @@ export declare interface TLUrlExternalContent extends TLBaseExternalContent {
     url: string;
 }
 
-/** @public */
-export declare interface TLUser {
-    readonly userPreferences: Signal<TLUserPreferences>;
-    readonly setUserPreferences: (userPreferences: TLUserPreferences) => void;
-}
-
 /**
  * A user of tldraw
  *
@@ -8512,6 +9570,9 @@ export declare function uniq<T>(array: {
     readonly length: number;
 } | null | undefined): T[];
 
+/** @public */
+export declare function useColorMode(): 'dark' | 'light';
+
 /** @public */
 export declare function useContainer(): HTMLElement;
 
@@ -8550,9 +9611,6 @@ export declare function useGlobalMenuIsOpen(id: string, onChange?: (isOpen: bool
 /** @public */
 export declare function useIsCropping(shapeId: TLShapeId): boolean;
 
-/** @public */
-export declare function useIsDarkMode(): boolean;
-
 /** @public */
 export declare function useIsEditing(shapeId: TLShapeId): boolean;
 
@@ -8570,6 +9628,10 @@ export declare function usePassThroughMouseOverEvents(ref: RefObject<HTMLElement
 export declare function usePassThroughWheelEvents(ref: RefObject<HTMLElement | null>): void;
 
 /**
+ * Reactive list of peer user IDs for collaborators currently shown in the UI.
+ * Mirrors {@link Editor.getVisibleCollaborators} — peers fade out as they
+ * transition to idle/inactive, without requiring a manual re-render.
+ *
  * @returns The list of peer UserIDs
  * @public
  */
@@ -8590,11 +9652,11 @@ export declare function usePresence(userId: string): null | TLInstancePresence;
 /** @public */
 export declare class UserPreferencesManager {
     private readonly user;
-    private readonly inferDarkMode;
+    private readonly colorScheme;
     systemColorScheme: Atom<"dark" | "light", unknown>;
     disposables: Set<() => void>;
     dispose(): void;
-    constructor(user: TLUser, inferDarkMode: boolean);
+    constructor(user: TLCurrentUser, colorScheme: 'dark' | 'light' | 'system');
     updateUserPreferences(userPreferences: Partial<TLUserPreferences>): void;
     getUserPreferences(): {
         animationSpeed: number;
@@ -8635,13 +9697,6 @@ export declare class UserPreferencesManager {
 /** @public */
 export declare const userTypeValidator: T.Validator<TLUserPreferences>;
 
-/** @public */
-export declare function useSelectionEvents(handle: TLSelectionHandle): {
-    onPointerDown: PointerEventHandler<Element>;
-    onPointerMove: (e: PointerEvent_2<Element>) => void;
-    onPointerUp: PointerEventHandler<Element>;
-};
-
 /* Excluded from this release type: useShallowArrayIdentity */
 
 /* Excluded from this release type: useShallowObjectIdentity */
@@ -8665,10 +9720,10 @@ export declare function useSvgExportContext(): null | SvgExportContext;
 /**
  * @public
  */
-export declare function useTldrawUser(opts: {
+export declare function useTldrawCurrentUser(opts: {
     setUserPreferences?: (userPreferences: TLUserPreferences) => void;
     userPreferences?: Signal<TLUserPreferences> | TLUserPreferences;
-}): TLUser;
+}): TLCurrentUser;
 
 /** @public */
 export declare function useTLSchemaFromUtils(opts: TLStoreSchemaOptions): StoreSchema<TLRecord, TLStoreProps>;