@tldraw/editor 4.6.0-canary.ba8f2c41e1ba → 4.6.0-canary.bda13b9dbf8f

package/dist-cjs/index.d.ts

@@ -19,7 +19,6 @@ 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';
@@ -220,6 +219,56 @@ 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
+ * - `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;
+    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;
@@ -719,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
@@ -881,51 +973,21 @@ export declare const DEFAULT_THEME: TLTheme;
 /** @public @react */
 export declare function DefaultBackground(): JSX.Element;
 
-/** @public @react */
-export declare const DefaultBrush: ({ brush, color, opacity, className }: TLBrushProps) => 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;
 
@@ -1005,7 +1067,6 @@ export declare const defaultTldrawOptions: {
     readonly tooltipDelayMs: 700;
     readonly uiCoarseDragDistanceSquared: 625;
     readonly uiDragDistanceSquared: 16;
-    readonly useCanvasIndicators: true;
     readonly zoomToFitPadding: 128;
 };
 
@@ -1105,7 +1166,7 @@ export declare class EdgeScrollManager {
 /** @public */
 export declare class Editor extends EventEmitter<TLEventMap> {
     readonly id: string;
-    constructor({ store, user, shapeUtils, bindingUtils, assetUtils: assetUtilConstructors, tools, getContainer, cameraOptions, initialState, autoFocus, options: _options, textOptions: _textOptions, getShapeVisibility, colorScheme, fontAssetUrls, themes, initialTheme }: 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;
@@ -1187,6 +1248,12 @@ 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.
      *
@@ -1212,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.
      *
@@ -1690,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
      */
@@ -2449,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[];
@@ -2461,9 +2540,32 @@ 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.
@@ -3124,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.
      *
@@ -4790,7 +4906,7 @@ export declare class GroupShapeUtil extends ShapeUtil<TLGroupShape> {
     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;
 }
 
@@ -5418,6 +5534,179 @@ 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>>;
 
+/** @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;
+}
+
+/**
+ * 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.
  *
@@ -5950,6 +6239,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;
@@ -6046,37 +6361,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).
-     *
-     * @param shape - The shape.
-     * @public
-     */
-    abstract indicator(shape: Shape): any;
-    /**
-     * Whether to use the legacy React-based indicator rendering.
+     * 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.
      *
-     * 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.
-     *
-     * 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}.
+     * Get JSX describing the shape's indicator (as an SVG element).
      *
-     * 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.
@@ -6244,6 +6552,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
@@ -6835,6 +7151,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;
 
@@ -7009,6 +7338,9 @@ 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>;
 
@@ -7052,15 +7384,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 */
@@ -7248,17 +7571,6 @@ export declare interface TLClipboardWriteInfo {
     readonly source: 'menu' | 'native';
 }
 
-/** @public */
-export declare interface TLCollaboratorHintProps {
-    userId: string;
-    className?: string;
-    point: VecModel;
-    viewport: Box;
-    zoom: number;
-    opacity?: number;
-    color: string;
-}
-
 /** @public */
 export declare type TLCompleteEvent = (info: TLCompleteEventInfo) => void;
 
@@ -7303,17 +7615,6 @@ export declare interface TLCurrentUser {
     readonly setUserPreferences: (userPreferences: TLUserPreferences) => void;
 }
 
-/** @public */
-export declare interface TLCursorProps {
-    userId: string;
-    className?: string;
-    point: null | VecModel;
-    zoom: number;
-    color?: string;
-    name: null | string;
-    chatMessage: string;
-}
-
 /** @public */
 export declare type TLDeepLink = {
     bounds: BoxModel;
@@ -7407,6 +7708,10 @@ export declare interface TldrawEditorBaseProps {
      * 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.
      */
@@ -7716,12 +8021,6 @@ export declare interface TldrawOptions {
      * viewport's page dimensions regardless of overview zoom changes.
      */
     readonly quickZoomPreservesScreenBounds: boolean;
-    /**
-     * Whether to use 2D canvas rendering for shape indicators. When true (default),
-     * shapes that support it will render indicators on a 2D canvas for better
-     * performance. When false, all indicators use legacy SVG rendering.
-     */
-    readonly useCanvasIndicators: 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
@@ -7809,34 +8108,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 */
@@ -7858,6 +8140,11 @@ export declare interface TLEditorOptions {
      * An array of asset utils to use in the editor. These will be used to handle asset-type-specific behavior.
      */
     assetUtils?: readonly TLAnyAssetUtilConstructor[];
+    /**
+     * An array of overlay utils to use in the editor. These define canvas overlay UI elements
+     * like selection handles, rotation corners, shape handles, etc.
+     */
+    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.
      */
@@ -8224,20 +8511,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 {
     /**
@@ -8567,6 +8840,42 @@ 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}.
@@ -8694,6 +9003,10 @@ export declare type TLPointerEventTarget = {
     handle?: TLSelectionHandle;
     shape?: undefined;
     target: 'selection';
+} | {
+    overlay: TLOverlay;
+    shape?: undefined;
+    target: 'overlay';
 } | {
     shape: TLShape;
     target: 'shape';
@@ -8764,28 +9077,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;
 
@@ -8820,26 +9117,11 @@ 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;
-}
-
-/** @public */
-export declare interface TLShapeIndicatorsProps {
-    /** Whether to hide all of the indicators */
-    hideAll?: boolean;
-    /** Whether to show all of the indicators */
-    showAll?: boolean;
+export declare interface TLShapeIndicatorOverlay extends TLOverlay {
+    props: {
+        hintingShapeIds: TLShapeId[];
+        idsToDisplay: TLShapeId[];
+    };
 }
 
 /**
@@ -8927,13 +9209,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;
@@ -9322,6 +9597,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
  */