feat(editor): introduce canvas OverlayUtil system (tldraw#8633)

In order to replace tldraw's growing tangle of per-feature canvas React
components (selection foreground, shape handles, brush rectangles, snap
indicators, scribbles, collaborator cursors, arrow hints, and shape
indicators) with a single declarative API that renders to a shared
canvas layer, this PR introduces the **OverlayUtil** system.
OverlayUtils subclass a common base class that declares when an overlay
is active, produces overlay instances from editor state, optionally
contributes hit-test geometry + cursor behavior, and draws into a 2D
context.


https://github.com/user-attachments/assets/c7174d07-b3a8-44f1-b504-f35a38faade4

Built as a clean, narrative-quality reimplementation of tldraw#8626 (same end
state, commits reordered and regrouped so a reviewer can read the story
end-to-end). The original branch is
[`ui-widgets-clean`](https://github.com/tldraw/tldraw/tree/ui-widgets-clean).

### Concepts

| Term | Type | Meaning |
| ---- | ---- | ------- |
| `OverlayUtil` | abstract class | Subclass to describe a kind of canvas
overlay (predicate, overlay generator, hit test, cursor, render) |
| `TLOverlay` | interface | A single live overlay instance — `{ id,
type, props }`, where `id` is globally unique across utils |
| `OverlayManager` | class | Lives on `editor.overlays`; registers
utils, resolves active overlays, hit-tests, tracks `hoveredOverlayId` |
| `TLAnyOverlayUtilConstructor` | type | What you pass in `overlayUtils`
on `<Tldraw>` / the Editor |
| `defaultOverlayUtils` | const | The tldraw package's built-in set
(shape indicator, selection foreground, handles, brush, zoom brush,
snaps, scribble, collaborator cursor / brush / hint / scribble, arrow
hints / binding hints) |

### Editor API

| Method / property | Description |
| ----------------- | ----------- |
| `editor.overlays` | The `OverlayManager` instance |
| `editor.overlays.getActiveOverlayEntries()` | All currently-active
overlays, grouped by util, for render / hit test |
| `editor.overlays.getOverlayAtPoint(point)` | Hit-test in draw order
with vertex-handle priority |
| `editor.overlays.hoveredOverlayId` | Atom tracking which overlay the
pointer is currently over |
| `editor.getVisibleCollaborators()` | Replaces the old
`useActivePeerIds$` hook with a reactive, editor-owned version |
| `editor.getVisibleCollaboratorsOnCurrentPage()` | Same, scoped to
current page; used by the minimap and collab overlays |
| `TLPointerEventTarget` | Gains an `{ target: 'overlay', overlay }`
variant so tools can dispatch on overlay hits |
| `TLTheme.colors` | New keys: `snap`, `selectionStroke`,
`selectionFill`, `brushFill`, `brushStroke`, `selectedContrast`, `laser`
|

### Example

Register a custom overlay by subclassing `OverlayUtil` and passing it in
`overlayUtils`:

```ts
class PointerRingOverlayUtil extends OverlayUtil<{ type: 'pointer_ring'; id: string; props: {} }> {
  static override type = 'pointer_ring'
  override isActive() { return true }
  override getOverlays() { return [{ id: 'pointer_ring:main', type: 'pointer_ring', props: {} }] }
  override render(ctx: CanvasRenderingContext2D) {
    const { x, y } = this.editor.inputs.currentScreenPoint
    ctx.strokeStyle = this.editor.getTheme().selectionStroke
    ctx.beginPath(); ctx.arc(x, y, 20, 0, Math.PI * 2); ctx.stroke()
  }
}

<Tldraw overlayUtils={[PointerRingOverlayUtil]} />
```

Replace a built-in by matching its `type`:

```ts
class DashedBrushOverlayUtil extends BrushOverlayUtil {
  override render(ctx: CanvasRenderingContext2D, overlay: TLBrushOverlay) {
    ctx.setLineDash([4, 4])
    super.render(ctx, overlay)
  }
}

<Tldraw overlayUtils={[DashedBrushOverlayUtil]} />
```

### New examples

- `editor-api/custom-overlay` — minimal new OverlayUtil (pointer ring).
- `editor-api/hovered-overlay` — reading
`editor.overlays.hoveredOverlayId` from React.
- `editor-api/replace-brush-overlay` — swapping a built-in util by
`type`.
- `ui/overlay-theme-colors` — the new TLTheme overlay color keys in
action.

### Change type

- [x] `api`

### Test plan

1. Run `yarn dev` and confirm selection handles, brush, scribbles, snap
lines, collaborator cursors, arrow hints, and shape indicators render
and respond identically to main.
2. Enter crop mode — crop handles should work via the overlay path.
3. Drag a line vertex and a nearby virtual handle — vertex wins.
4. Open a multiplayer room; remote cursors, selections, and scribbles
should fade in/out via the shared visibility clock.
5. Toggle dark mode — all overlay colors update via TLTheme.

- [x] Unit tests
- [x] End to end tests

### Release notes

- Introduce the `OverlayUtil` system for canvas UI (selection
foreground, handles, brush, snaps, scribbles, collaborator overlays,
shape indicators, arrow hints, arrow binding hints). Pass `overlayUtils`
on `<Tldraw>` / `TldrawEditor` to customize.
- Breaking! The following legacy `EditorComponents` slots are removed:
`Brush`, `ZoomBrush`, `Scribble`, `SnapIndicator`, `Handle`, `Handles`,
`SelectionForeground`, `ShapeIndicator`, `ShapeIndicators`,
`CollaboratorBrush`, `CollaboratorCursor`, `CollaboratorHint`,
`CollaboratorScribble`, `CollaboratorShapeIndicator`, `Cursor`,
`Overlays`, `ShapeIndicatorErrorFallback`. Migrate by subclassing the
equivalent `OverlayUtil`.
- Breaking! The `options.useCanvasIndicators` flag is removed — shape
indicators are always canvas.
- Breaking! `ShapeUtil.useLegacyIndicator()` is removed.
- Add `Editor.getVisibleCollaborators()` /
`getVisibleCollaboratorsOnCurrentPage()` with a shared visibility clock;
`usePeerIds` now reads from them. Replaces `useActivePeerIds$`.
- Add seven `TLTheme` color keys (`snap`, `selectionStroke`,
`selectionFill`, `brushFill`, `brushStroke`, `selectedContrast`,
`laser`).
- Rewrite the minimap in Canvas 2D (dropped the WebGL pipeline).
- Add selectable UI color themes on tldraw.com under user settings.

### API changes

- Added `OverlayUtil`, `OverlayManager`, `TLOverlay`, `TLOverlayEntry`,
`TLOverlayUtilConstructor`, `TLAnyOverlayUtilConstructor`,
`ShapeIndicatorOverlayUtil`.
- Added tldraw overlay utils: `ArrowBindingHintOverlayUtil`,
`ArrowHintOverlayUtil`, `BrushOverlayUtil`,
`CollaboratorBrushOverlayUtil`, `CollaboratorCursorOverlayUtil`,
`CollaboratorHintOverlayUtil`, `CollaboratorScribbleOverlayUtil`,
`ScribbleOverlayUtil`, `SelectionForegroundOverlayUtil`,
`ShapeHandleOverlayUtil`, `SnapIndicatorOverlayUtil`,
`ZoomBrushOverlayUtil`, plus `defaultOverlayUtils`.
- Added `Editor.overlays`, `Editor.getVisibleCollaborators`,
`Editor.getVisibleCollaboratorsOnCurrentPage`; added `overlayUtils`
option on `TLEditorOptions` / `TldrawEditorBaseProps` / `<Tldraw>`.
- Added `TLPointerEventTarget` variant `{ target: 'overlay', overlay }`.
- Added `TLTheme.colors.snap` / `.selectionStroke` / `.selectionFill` /
`.brushFill` / `.brushStroke` / `.selectedContrast` / `.laser`.
- Breaking! Removed legacy canvas components: `DefaultBrush`,
`DefaultCollaboratorHint`, `DefaultCursor` (slot removed; file kept
internal), `DefaultHandle`, `DefaultHandles`, `DefaultScribble`,
`DefaultSelectionForeground`, `DefaultShapeIndicator`,
`DefaultShapeIndicators`, `DefaultShapeIndicatorErrorFallback`,
`DefaultSnapIndicator`, `CanvasShapeIndicators`, `LiveCollaborators`,
and tldraw's `TldrawCropHandles`, `TldrawHandles`, `TldrawOverlays`,
`TldrawArrowHints`, `TldrawScribble`, `TldrawSelectionForeground`,
`TldrawShapeIndicators`.
- Breaking! Removed `EditorComponents` slots listed in Release notes.
- Breaking! Removed `ShapeUtil.useLegacyIndicator` and
`TldrawOptions.useCanvasIndicators`.
- Breaking! Removed `useActivePeerIds$` (use
`editor.getVisibleCollaborators` instead).

### Code changes

| Section         | LOC change |
| --------------- | ---------- |
| Core code       | +3507 / -3567 |
| Tests           | +2420 / -526 |
| Automated files | +531 / -286 |
| Documentation   | +931 / -601 |
| Apps            | +2117 / -105 |
| Templates       | +503 / -430 |
| Config/tooling  | +72 / -13 |

Relates to tldraw#8626

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: steveruizok <23072548+steveruizok@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

.gitignore

@@ -132,3 +132,4 @@ opencode.json
 .claude/skills/pr-walkthrough/video/dist
 .claude/skills/pr-walkthrough/video/public/audio-*
 .claude/skills/pr-walkthrough/video/public/manifest.json
+todo.md

apps/docs/content/docs/collaboration.mdx

@@ -58,7 +58,7 @@ Collaboration involves three concerns:
 
 - **Synchronizing data** — Getting document changes in and out of the [store](/sdk-features/store). See [Persistence](/docs/persistence) for the basics, or [Collaboration](/sdk-features/collaboration) for building custom sync.
 - **User presence** — Sharing cursor positions, selections, and viewports with other users. See [Collaboration](/sdk-features/collaboration) for presence APIs and [Cursors](/sdk-features/cursors) for customizing how collaborator cursors appear.
-- **Collaboration UI** — The visual elements that show other users on the canvas. See [UI components](/sdk-features/ui-components) for overriding components like `CollaboratorCursor`, `CollaboratorBrush`, and `SharePanel`.
+- **Collaboration UI** — The visual elements that show other users on the canvas. See [UI components](/sdk-features/ui-components) for overriding components like `CollaboratorCursor` and `SharePanel`. Collaborator brushes, scribbles, and hints are rendered via the [OverlayUtil](?) system.
 
 ## Related
 

apps/docs/content/docs/handles.mdx

@@ -236,9 +236,9 @@ class SpeechBubbleUtil extends ShapeUtil<SpeechBubbleShape> {
 		)
 	}
 
-	indicator(shape: SpeechBubbleShape) {
+	getIndicatorPath(shape: SpeechBubbleShape) {
 		const geometry = this.getGeometry(shape)
-		return <path d={geometry.getSvgPathData()} />
+		return new Path2D(geometry.getSvgPathData())
 	}
 }
 ```

apps/docs/content/docs/indicators.mdx

@@ -18,7 +18,7 @@ Indicators are the outlines that appear around shapes when they're selected or h
 
 When you select a shape in tldraw, an indicator appears as a stroke around the shape's geometry. Indicators are separate from the shape's visual appearance so they can be styled consistently across all shape types.
 
-Each [ShapeUtil](?) defines how its indicator should be drawn by implementing the required `indicator` method:
+Each [ShapeUtil](?) defines how its indicator should be drawn by implementing the required `getIndicatorPath` method:
 
 ```tsx
 import { HTMLContainer, Rectangle2d, ShapeUtil } from 'tldraw'
@@ -42,13 +42,15 @@ class CardShapeUtil extends ShapeUtil<CardShape> {
 		return <HTMLContainer>Hello</HTMLContainer>
 	}
 
-	indicator(shape: CardShape) {
-		return <rect width={shape.props.w} height={shape.props.h} />
+	getIndicatorPath(shape: CardShape) {
+		const path = new Path2D()
+		path.rect(0, 0, shape.props.w, shape.props.h)
+		return path
 	}
 }
 ```
 
-The `indicator` method returns SVG elements that describe the shape's outline. The editor automatically positions and styles these elements based on selection state.
+The `getIndicatorPath` method returns paths in the shape's local coordinate space. The editor automatically positions and styles these paths based on selection state.
 
 ## When indicators appear
 
@@ -62,48 +64,21 @@ By default, indicators appear in these situations:
 
 Indicators are hidden during certain interactions, like when changing styles or during tool operations that would make indicators distracting.
 
-## Rendering approaches
-
-tldraw supports two ways to render indicators: SVG-based and canvas-based.
-
-### SVG indicators (default)
-
-The default approach uses React to render indicators as SVG elements. This is simpler to implement. It works well for most shapes:
-
-```tsx
-class MyShapeUtil extends ShapeUtil<MyShape> {
-	indicator(shape: MyShape) {
-		return <rect width={shape.props.w} height={shape.props.h} rx={5} />
-	}
-}
-```
-
-SVG indicators support any valid SVG elements. The editor wraps them in a styled `<g>` element that applies the indicator color.
-
-### Canvas indicators
+## Defining paths
 
-Canvas-based rendering improves performance for complex shapes. Override `useLegacyIndicator` to return `false` and implement `getIndicatorPath`:
+For most shapes, return a `Path2D`:
 
 ```tsx
 class MyShapeUtil extends ShapeUtil<MyShape> {
-	override useLegacyIndicator() {
-		return false
-	}
-
 	override getIndicatorPath(shape: MyShape): Path2D | undefined {
 		const path = new Path2D()
 		path.roundRect(0, 0, shape.props.w, shape.props.h, 5)
 		return path
 	}
-
-	indicator(shape: MyShape) {
-		// Required method. Used only when useLegacyIndicator returns true (the default).
-		return <rect width={shape.props.w} height={shape.props.h} rx={5} />
-	}
 }
 ```
 
-Canvas indicators are drawn on a single canvas layer. This is more efficient when many shapes are selected. Most built-in shapes use canvas indicators.
+Indicators are drawn on a single canvas layer, which is efficient when many shapes are selected.
 
 ### Complex canvas indicators
 
@@ -125,109 +100,12 @@ override getIndicatorPath(shape: MyShape): TLIndicatorPath | undefined {
 
 	return {
 		path: bodyPath,
-		clipPath: labelClipPath,        // Areas to exclude from the main path
-		additionalPaths: [arrowheadPath] // Extra paths to stroke
+		clipPath: labelClipPath, // Areas to exclude from the main path
+		additionalPaths: [arrowheadPath], // Extra paths to stroke
 	}
 }
 ```
 
-## Customizing indicator display
-
-Override the indicator components to control when and how indicators appear.
-
-### Show all indicators
-
-To show indicators for every shape on the canvas:
-
-```tsx
-import { DefaultShapeIndicators, TLComponents, Tldraw } from 'tldraw'
-
-const components: TLComponents = {
-	ShapeIndicators: () => {
-		return <DefaultShapeIndicators showAll />
-	},
-}
-
-export default function App() {
-	return <Tldraw components={components} />
-}
-```
-
-### Hide all indicators
-
-To hide indicators entirely:
-
-```tsx
-const components: TLComponents = {
-	ShapeIndicators: () => {
-		return <DefaultShapeIndicators hideAll />
-	},
-}
-```
-
-### Custom indicator logic
-
-For complete control over which shapes show indicators, use the `OnTheCanvas` component:
-
-```tsx
-import { TLComponents, Tldraw, useEditor, useEditorComponents, useValue } from 'tldraw'
-
-const components: TLComponents = {
-	OnTheCanvas: () => {
-		const editor = useEditor()
-
-		const renderingShapes = useValue(
-			'rendering shapes',
-			() =>
-				editor.getRenderingShapes().filter((info) => {
-					// Custom filter logic here
-					const shape = editor.getShape(info.id)
-					return shape?.type === 'geo' // Only show indicators for geo shapes
-				}),
-			[editor]
-		)
-
-		const { ShapeIndicator } = useEditorComponents()
-		if (!ShapeIndicator) return null
-
-		return (
-			<div style={{ position: 'absolute', top: 0, left: 0, zIndex: 9999 }}>
-				{renderingShapes.map(({ id }) => (
-					<ShapeIndicator key={id + '_indicator'} shapeId={id} />
-				))}
-			</div>
-		)
-	},
-}
-```
-
-### Custom indicator styling
-
-To change the color or appearance of indicators:
-
-```tsx
-import { DefaultShapeIndicator, TLComponents, TLShapeIndicatorProps } from 'tldraw'
-
-const CustomShapeIndicator = (props: TLShapeIndicatorProps) => {
-	return <DefaultShapeIndicator {...props} color="red" opacity={0.5} />
-}
-
-const components: TLComponents = {
-	ShapeIndicator: CustomShapeIndicator,
-}
-```
-
-The [DefaultShapeIndicator](?) component accepts these props:
-
-| Prop      | Type      | Description                                        |
-| --------- | --------- | -------------------------------------------------- |
-| shapeId   | TLShapeId | The shape to show an indicator for                 |
-| userId    | string    | The collaborator's user ID (for multiplayer)       |
-| color     | string    | Stroke color (default: `var(--tl-color-selected)`) |
-| opacity   | number    | Opacity from 0 to 1                                |
-| className | string    | Additional CSS class                               |
-| hidden    | boolean   | Whether to hide this indicator                     |
-
 ## Collaborator indicators
 
 In multiplayer sessions, indicators show other users' selections. These appear with the collaborator's assigned color and slightly reduced opacity. The canvas indicator system handles collaborator indicators automatically.

apps/docs/content/docs/shapes.mdx

@@ -71,8 +71,10 @@ class CardShapeUtil extends ShapeUtil<CardShape> {
 		return <HTMLContainer>Hello</HTMLContainer>
 	}
 
-	indicator(shape: CardShape) {
-		return <rect width={shape.props.w} height={shape.props.h} />
+	getIndicatorPath(shape: CardShape) {
+		const path = new Path2D()
+		path.rect(0, 0, shape.props.w, shape.props.h)
+		return path
 	}
 }
 ```

apps/docs/content/getting-started/installation.mdx

@@ -192,8 +192,7 @@ const components: TLComponents = {
 	Background: YourCustomBackground,
 	Cursor: YourCustomCursor,
 	Grid: YourCustomGrid,
-	SelectionForeground: YourCustomSelectionForeground,
-	SnapIndicator: YourCustomSnapIndicator,
+	SelectionBackground: YourCustomSelectionBackground,
 
 	// UI components
 	Toolbar: YourCustomToolbar,
@@ -205,6 +204,8 @@ const components: TLComponents = {
 <Tldraw components={components} />
 ```
 
+Canvas overlay elements like the selection foreground, brush, snap indicators, and scribble are rendered via the [OverlayUtil](?) system rather than React components. You can customize them by extending the built-in overlay utils and passing them via the `overlayUtils` prop.
+
 See the [TLEditorComponents](?) and [TLUiComponents](?) type definitions for the complete list of customizable components.
 
 ## Versioning

apps/docs/content/releases/next.mdx

@@ -8,7 +8,7 @@ status: published
 last_version: v4.5.10
 ---
 
-This release adds a first-class theme system with display values for customizing default shapes, extensible asset types via a new `AssetUtil` system, shape attribution with a new `TLUserStore` provider and extensible user records, clipboard hooks for intercepting copy, cut, and paste, custom record types to the store, a new `@tldraw/mermaid` package for converting Mermaid diagrams to native shapes, WebSocket hibernation support for tlsync, a new `@tldraw/editor-controller` package for scripting and automation, RTL language support in the UI, cross-window embedding support, arbitrary iframe embed pasting, a paste-as-plain-text keyboard shortcut, and smarter export trimming. It also includes various other improvements and bug fixes.
+This release adds a first-class theme system with display values for customizing default shapes, a new canvas overlay system that replaces React component overrides with Canvas 2D rendering, extensible asset types via a new `AssetUtil` system, shape attribution with a new `TLUserStore` provider and extensible user records, clipboard hooks for intercepting copy, cut, and paste, custom record types to the store, a new `@tldraw/mermaid` package for converting Mermaid diagrams to native shapes, WebSocket hibernation support for tlsync, a new `@tldraw/editor-controller` package for scripting and automation, RTL language support in the UI, cross-window embedding support, arbitrary iframe embed pasting, a paste-as-plain-text keyboard shortcut, and smarter export trimming. It also includes various other improvements and bug fixes.
 
 ## What's new
 
@@ -229,6 +229,45 @@ A new `Cmd+Shift+V` / `Ctrl+Shift+V` shortcut pastes clipboard content as plain
 
 Note: `Cmd+Shift+V` previously toggled paste-at-cursor positioning. Since the "Paste at cursor" preference now covers that use case, this shortcut has been repurposed for plain text paste. Users who relied on `Cmd+Shift+V` for paste-at-cursor should use the preference toggle instead.
 
+### 💥 Canvas overlay system ([overlay utils](/sdk-features/overlay-utils))
+
+Canvas overlay UI — the selection foreground, brush rectangles, snap indicators, shape indicators, shape handles, scribbles, arrow hints, and collaborator presence visuals — is now rendered via a new `OverlayUtil` system instead of React components. Overlays draw directly to a `<canvas>` element using the Canvas 2D API, with optional hit-test geometry for pointer interactions.
+
+Pass custom overlay utils through the `overlayUtils` prop on `<Tldraw>` or `<TldrawEditor>`. Custom utils are merged with the defaults; if your util has the same `type` as a built-in, it replaces it:
+
+```tsx
+import { Tldraw, BrushOverlayUtil, type TLBrushOverlay } from 'tldraw'
+
+class BlueBrushOverlayUtil extends BrushOverlayUtil {
+	override render(ctx: CanvasRenderingContext2D, overlays: TLBrushOverlay[]): void {
+		const overlay = overlays[0]
+		if (!overlay) return
+		const { x, y, w, h } = overlay.props
+		ctx.fillStyle = 'rgba(0, 0, 255, 0.1)'
+		ctx.fillRect(x, y, w, h)
+	}
+}
+
+;<Tldraw overlayUtils={[BlueBrushOverlayUtil]} />
+```
+
+<details>
+<summary>Migration guide</summary>
+
+The following `TLEditorComponents` entries have been removed: `Brush`, `CollaboratorBrush`, `CollaboratorCursor`, `CollaboratorHint`, `CollaboratorScribble`, `CollaboratorShapeIndicator`, `Cursor`, `Handle`, `Handles`, `Overlays`, `Scribble`, `SelectionForeground`, `ShapeIndicator`, `ShapeIndicatorErrorFallback`, `ShapeIndicators`, `SnapIndicator`, and `ZoomBrush`. Their corresponding default implementations (`DefaultBrush`, `DefaultCollaboratorHint`, `DefaultCursor`, `DefaultHandle`, `DefaultHandles`, `DefaultScribble`, `DefaultSelectionForeground`, `DefaultShapeIndicator`, `DefaultShapeIndicators`, `DefaultSnapIndicator`) and prop types (`TLBrushProps`, `TLCollaboratorHintProps`, `TLCursorProps`, `TLHandleProps`, `TLHandlesProps`, `TLScribbleProps`, `TLSelectionForegroundProps`, `TLShapeIndicatorProps`, `TLShapeIndicatorErrorFallbackComponent`, `TLShapeIndicatorsProps`, `TLSnapIndicatorProps`) have also been removed.
+
+If you were overriding these via the `components` prop, create a custom `OverlayUtil` subclass instead and pass it via `overlayUtils`. See the [overlay utils documentation](/sdk-features/overlay-utils) for details.
+
+The following `tldraw` canvas helpers have also been removed: `TldrawArrowHints`, `TldrawCropHandles`, `TldrawCropHandlesProps`, `TldrawHandles`, `TldrawOverlays`, `TldrawScribble`, `TldrawSelectionForeground`, and `TldrawShapeIndicators`.
+
+Custom shape utils must now implement `getIndicatorPath()`. `indicator()` is deprecated and no longer rendered, and `useLegacyIndicator()` has been removed. Return a `Path2D` (or `TLIndicatorPath` for clipped / multi-path indicators) from `getIndicatorPath()` instead.
+
+`TldrawOptions.useCanvasIndicators` has been removed. Shape indicators now always render through `ShapeIndicatorOverlayUtil`; replace that overlay util if you need custom indicator visibility or styling.
+
+Custom themes must include the overlay UI colors `snap`, `selectionStroke`, `selectionFill`, `brushFill`, `brushStroke`, `selectedContrast`, and `laser`.
+
+</details>
+
 ### Cross-window embedding support ([#8196](https://github.com/tldraw/tldraw/pull/8196))
 
 Tldraw now works correctly when embedded in iframes, Electron pop-out windows, and Obsidian plugins where the global `document` and `window` differ from the ones tldraw is mounted in. All bare `document` and `window` references have been replaced with container-aware alternatives.
@@ -267,6 +306,13 @@ New helpers `getOwnerDocument()` and `getOwnerWindow()` are exported from `@tldr
 - Add `TLUserStore` interface with `getCurrentUser()` and `resolve()` for connecting tldraw to auth systems. Add unified `TLUser` record type, `UserRecordType`, `createUserId`, `isUserId`, `userIdValidator`, and `createUserRecordType()` for extensible user schemas. Add `user` parameter to `createTLSchema()`. Add `Editor.getAttributionUser()`, `Editor.getAttributionUserId()`, and `Editor.getAttributionDisplayName()`. Add `textFirstEditedBy` prop to `TLNoteShapeProps`. ([#8147](https://github.com/tldraw/tldraw/pull/8147))
 - Add `AssetUtil` base class with `configure()`, `getDefaultProps()`, `getSupportedMimeTypes()`, `getAssetFromFile()`, and `createShape()`. Add `assetUtils` prop to `<Tldraw>`. Add `Editor.getAssetUtil()`, `Editor.hasAssetUtil()`, and `Editor.getAssetUtilForMimeType()`. Add `TLGlobalAssetPropsMap` for type-safe custom asset registration. Add `createAssetRecordType()`, `defaultAssetSchemas`, and `assets` parameter to `createTLSchema()`. ([#8031](https://github.com/tldraw/tldraw/pull/8031))
 - Add `Cmd+Shift+V` / `Ctrl+Shift+V` shortcut to paste clipboard content as plain text. `Cmd+Shift+V` no longer toggles paste-at-cursor positioning. ([#8347](https://github.com/tldraw/tldraw/pull/8347))
+- 💥 Remove `Brush`, `CollaboratorBrush`, `CollaboratorCursor`, `CollaboratorHint`, `CollaboratorScribble`, `CollaboratorShapeIndicator`, `Cursor`, `Handle`, `Handles`, `Overlays`, `Scribble`, `SelectionForeground`, `ShapeIndicator`, `ShapeIndicatorErrorFallback`, `ShapeIndicators`, `SnapIndicator`, and `ZoomBrush` from `TLEditorComponents`. Remove their default implementations and prop types. These are now rendered via the `OverlayUtil` system.
+- 💥 Remove `TldrawArrowHints`, `TldrawCropHandles`, `TldrawCropHandlesProps`, `TldrawHandles`, `TldrawOverlays`, `TldrawScribble`, `TldrawSelectionForeground`, and `TldrawShapeIndicators` from `tldraw`.
+- 💥 Change shape indicators from SVG to canvas paths: `ShapeUtil.getIndicatorPath()` is now abstract, `ShapeUtil.indicator()` is deprecated and no longer rendered, and `ShapeUtil.useLegacyIndicator()` has been removed.
+- 💥 Remove `TldrawOptions.useCanvasIndicators`.
+- 💥 Add `snap`, `selectionStroke`, `selectionFill`, `brushFill`, `brushStroke`, `selectedContrast`, and `laser` to the required `TLThemeDefaultColors` / `TLThemeUiColorKeys` UI color keys.
+- Add `OverlayUtil` base class, `OverlayManager`, `TLOverlay`, `TLOverlayEntry`, `TLOverlayUtilConstructor`, and `TLAnyOverlayUtilConstructor` to `@tldraw/editor`. Add `overlayUtils` prop to `<Tldraw>` and `<TldrawEditor>`. Add `Editor.overlays` (`OverlayManager`) with `getOverlayUtil()`, `getOverlayUtilsInZOrder()`, `getActiveOverlayEntries()`, `getCurrentOverlays()`, `getOverlayGeometry()`, `getOverlayAtPoint()`, `getHoveredOverlayId()`, `getHoveredOverlay()`, and `setHoveredOverlay()`.
+- Add `ShapeIndicatorOverlayUtil`, `BrushOverlayUtil`, `ZoomBrushOverlayUtil`, `ScribbleOverlayUtil`, `CollaboratorBrushOverlayUtil`, `CollaboratorCursorOverlayUtil`, `CollaboratorScribbleOverlayUtil`, `CollaboratorHintOverlayUtil`, `ShapeHandleOverlayUtil`, `SelectionForegroundOverlayUtil`, `SnapIndicatorOverlayUtil`, `ArrowHintOverlayUtil`, `ArrowBindingHintOverlayUtil`, their overlay types, and `defaultOverlayUtils` to `tldraw`.
 - Add `Vec.IsFinite()` static method for checking whether a vector has finite coordinates. ([#8176](https://github.com/tldraw/tldraw/pull/8176))
 
 ## Improvements

apps/docs/content/sdk-features/culling.mdx

@@ -97,8 +97,10 @@ class MyShapeUtil extends ShapeUtil<MyShape> {
 		return <div style={{ width: shape.props.w, height: shape.props.h }} />
 	}
 
-	indicator(shape: MyShape) {
-		return <rect width={shape.props.w} height={shape.props.h} />
+	getIndicatorPath(shape: MyShape) {
+		const path = new Path2D()
+		path.rect(0, 0, shape.props.w, shape.props.h)
+		return path
 	}
 }
 ```

apps/docs/content/sdk-features/cursors.mdx

@@ -152,7 +152,7 @@ editor.user.updateUserPreferences({ color: '#FF802B' })
 
 ### Rendering collaborator cursors
 
-Remote cursors render through the `CollaboratorCursor` component. The default implementation ([DefaultCursor](?)) displays:
+Remote cursors render through the `CollaboratorCursor` component. The default implementation (`DefaultCursor`) displays:
 
 - The cursor icon in the user's color
 - The user's name as a label below the cursor

apps/docs/content/sdk-features/drag-and-drop.mdx

@@ -259,8 +259,10 @@ class SlotContainerShapeUtil extends ShapeUtil<SlotContainerShape> {
 		)
 	}
 
-	indicator(shape: SlotContainerShape) {
-		return <rect width={shape.props.slots * 100} height={100} />
+	getIndicatorPath(shape: SlotContainerShape) {
+		const path = new Path2D()
+		path.rect(0, 0, shape.props.slots * 100, 100)
+		return path
 	}
 }
 ```